Collection

b.db.collection(name, opts?) returns a small adapter that maps Mongo-shape calls onto the framework's query-builder primitives:

b.db.collection("users").findOne({ email: "alice@x.com" }); → b.db.from("users").where({ email: "alice@x.com" }).first();

b.db.collection("users").update({ _id }, { $set: { name } }); → b.db.from("users").where({ _id }).updateOne({ name });

b.db.collection("users").update({ _id }, { $inc: { failed: 1 } }); → b.db.from("users").where({ _id }).increment("failed", 1);

Schemaless-document support — three opts compose to give a document-store-shaped collection on top of the relational schema:

b.db.collection("users", { overflow: "data", // unknown fields fold into this JSON-text column jsonColumns: ["roles", "metadata"], // listed columns auto-parsed on read, stringified on write sealedFields: { email: "emailHash" }, // registers cryptoField derivedHash so where({email}) rewrites });

Supported update operators: $set (assign — overflow-aware), $inc (atomic increment per real column — composes Query.increment; refused on overflow fields), $unset (set to NULL on real columns; remove the key from the overflow JSON).

Query operators: $eq / $ne / $gt / $gte / $lt / $lte / $in / $like. Overflow fields support $eq / $ne / $in only — range / LIKE require a real column with an index.

b.db.collection(name, opts?) #

{
  {
    overflow?:     string,                       // JSON-text column for unknown fields (off when absent)
    jsonColumns?:  string[],                     // auto-stringify on write, auto-parse on read
    sealedFields?: { [plain: string]: string },  // plain column → hash column; registers via b.cryptoField
    columns?:      string[],                     // explicit column whitelist (defaults to PRAGMA introspection)
  }
}

Returns a Mongo-style adapter for the named table. Each method dispatches to b.db.from(name) under the hood; sealed-column semantics, derived-hash translation, and audit emission carry through unchanged.

Pass opts to enable schemaless-document features:

- overflow: "data" — unknown insert/update fields fold into the named JSON-text column. find / findOne parse that column and merge its keys back onto the row. WHERE on an unknown field rewrites to JSON_EXTRACT(, '$.field') ($eq / $ne / $in only — range / LIKE require a real column with an index). - jsonColumns: ["roles", "metadata"] — listed columns are JSON.stringify'd on write and parsed via b.safeJson on read. - sealedFields: { email: "emailHash" } — co-locates a sealed- column / derived-hash declaration with the collection. The plaintext field is registered as sealed; the hash column is registered as a derivedHashes[hashCol] = { from: plain } mapping in b.cryptoField. Subsequent where({ email: "x" }) calls automatically rewrite to where({ emailHash: }) via the existing query-builder rewrite path. - columns: ["_id", "email", ...] — explicit column whitelist. If omitted, the framework introspects via PRAGMA table_info once at first use and caches.

var b = require("@blamejs/core");
await b.db.init({ dataDir: "/tmp/data", schema: [{
  name: "users",
  columns: {
    _id:       "TEXT PRIMARY KEY",
    email:     "TEXT",
    emailHash: "TEXT",
    roles:     "TEXT",
    data:      "TEXT",
  },
}] });
var users = b.db.collection("users", {
  overflow:     "data",
  jsonColumns:  ["roles"],
  sealedFields: { email: "emailHash" },
});
users.insert({ _id: "u1", email: "alice@x.com", roles: ["admin"], dept: "eng", joined: "2026-01-01" });
//   → roles is JSON-stringified; dept + joined fold into data; email seals + emailHash derives
users.findOne({ email: "alice@x.com" });
//   → { _id: "u1", email: "alice@x.com", roles: ["admin"], dept: "eng", joined: "2026-01-01" }
users.find({ dept: "eng" });
//   → JSON_EXTRACT(data, '$.dept') = 'eng'

Last updated 2026-08-08T16:39:49.652Z by seeder.