@thadeu/ndb 0.4.0 → 1.0.0

package/dist/index.cjs

@@ -20,12 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Collection: () => Collection,
   CursorError: () => CursorError,
   DuplicateIdError: () => DuplicateIdError,
   HistoryTruncatedError: () => HistoryTruncatedError,
   InvalidQueryError: () => InvalidQueryError,
   InvalidUpdateError: () => InvalidUpdateError,
-  Model: () => Model,
   Ndb: () => Ndb,
   NdbError: () => NdbError,
   NotFoundError: () => NotFoundError,
@@ -150,20 +150,21 @@ function toWhere(v) {
 
 // src/query.ts
 var Query = class _Query {
-  constructor(model, state = { clauses: [] }) {
-    this.model = model;
+  constructor(coll, state = { clauses: [] }) {
+    this.coll = coll;
     this.state = state;
   }
-  model;
+  coll;
   state;
   nextCursor = "";
-  where(w) {
+  // Adds conditions, ANDed with the ones already there.
+  query(w) {
     return this.with({ clauses: [...this.state.clauses, toWhere(w)] });
   }
-  // A where object built elsewhere, such as from a search form. It is not
+  // A query built elsewhere, such as from a search form. It is not
   // type-checked and is sent as is; the daemon validates it. It is ANDed
   // with the other clauses.
-  whereRaw(w) {
+  rawQuery(w) {
     return this.with({ clauses: [...this.state.clauses, w] });
   }
   not(w) {
@@ -206,14 +207,15 @@ var Query = class _Query {
     }
     return null;
   }
+  // How many documents match (POST /{coll}/_count). limit, skip and sort do
+  // not change it.
   async count() {
-    await this.model.ready();
-    const body = { where: this.whereDoc(), count: true, limit: 1 };
-    const res = await this.model.db.transport.stream("POST", this.model.path("find"), body);
-    await res.body.dump();
-    return Number(res.header("x-ndb-total") ?? 0);
+    await this.coll.ready();
+    const out = await this.coll.db.transport.request("POST", this.coll.path("_count"), { query: this.whereDoc() });
+    return out.count;
   }
-  async *iterate() {
+  // Every row, following the cursor page by page (limit is the page size).
+  async *each() {
     let body = this.body();
     for (; ; ) {
       yield* this.rows(body);
@@ -224,16 +226,16 @@ var Query = class _Query {
     }
   }
   async *rows(body) {
-    await this.model.ready();
-    const res = await this.model.db.transport.stream("POST", this.model.path("find"), body);
+    await this.coll.ready();
+    const res = await this.coll.db.transport.stream("POST", this.coll.path("_search"), body);
     this.nextCursor = res.header("x-ndb-next") ?? "";
     for await (const raw of res.rows()) {
-      yield this.model.decode(raw);
+      yield this.coll.decode(raw);
     }
   }
   body() {
     const { fields, sort, limit, skip, after } = this.state;
-    return { where: this.whereDoc(), fields, sort, limit, skip, after, versions: true };
+    return { query: this.whereDoc(), fields, sort, limit, skip, after, versions: true };
   }
   whereDoc() {
     const merged = {};
@@ -248,7 +250,7 @@ var Query = class _Query {
     return merged;
   }
   with(patch) {
-    return new _Query(this.model, { ...this.state, ...patch });
+    return new _Query(this.coll, { ...this.state, ...patch });
   }
 };
 
@@ -262,12 +264,12 @@ async function* watchEvents(lines2, consumer) {
     if (line.error) {
       throw makeError(line.error.code, line.error.message);
     }
-    yield { consumer, pos: line.pos, op: line.op, _id: line._id ?? "", v: line.v, doc: line.doc };
+    yield { consumer, pos: line.pos, op: line.op, _id: line._id ?? "", _v: line._v, doc: line.doc };
   }
 }
 
-// src/model.ts
-var Model = class {
+// src/collection.ts
+var Collection = class {
   constructor(db, name, schema) {
     this.db = db;
     this.name = name;
@@ -277,12 +279,11 @@ var Model = class {
   name;
   schema;
   ensured;
-  path(op) {
-    const base = `/v1/c/${encodeURIComponent(this.name)}`;
-    return op ? `${base}/${op}` : base;
+  // The path of the collection, or of one of its actions ("_search").
+  path(action) {
+    const base = `/${encodeURIComponent(this.name)}`;
+    return action ? `${base}/${action}` : base;
   }
-  // A collection pattern ("logs-2026-*") reads many collections and declares
-  // none: its writes fail with pattern_read_only.
   get isPattern() {
     return this.name.includes("*");
   }
@@ -295,58 +296,72 @@ var Model = class {
     return this.ensured;
   }
   async insert(docs, opts = {}) {
-    await this.ready();
+    if (!Array.isArray(docs) && opts.expireIn === void 0) {
+      return this.send("POST", "_doc", docs);
+    }
     const list = Array.isArray(docs) ? docs : [docs];
-    const out = await this.db.transport.request("POST", this.path("insert"), {
-      insert: list,
-      expire_in: opts.expireIn
-    });
+    const out = await this.send("POST", "_bulk", { docs: list, expire_in: opts.expireIn });
+    return Array.isArray(docs) ? out.results : out.results[0];
+  }
+  // Writes a document by its _id: creates it when the _id is free, and
+  // merges its fields into the stored document when it exists (the other
+  // fields stay), like doc_as_upsert in Elasticsearch. No _id is an insert.
+  async upsert(doc, opts = {}) {
+    return (await this.upsertAll([doc], opts))[0];
+  }
+  // upsert for many documents in one transaction, all or nothing
+  // (POST /{coll}/_bulk with upsert).
+  async upsertAll(docs, opts = {}) {
+    const out = await this.send("POST", "_bulk", { docs, expire_in: opts.expireIn, upsert: true });
     return out.results;
   }
-  create(docs, opts = {}) {
-    return this.insert(docs, opts);
+  // Applies ops to the document with this _id, in one atomic step
+  // (POST /{coll}/_update/{id}). guard adds conditions on the same document,
+  // such as { _v: 7 }: matched is 0 when it fails. Matching nothing is not an
+  // error.
+  async update(id, ops, opts = {}) {
+    const out = await this.send("POST", docPath("_update", id), {
+      query: opts.guard === void 0 ? void 0 : toWhere(opts.guard),
+      update: checkOps(ops),
+      upsert: opts.upsert,
+      expire_in: opts.expireIn
+    });
+    return this.updated(out);
+  }
+  // The atomic update by query (POST /{coll}/_update_by_query): the daemon
+  // matches and writes in one step on the newest state, so concurrent updates
+  // never interleave. Without many it updates the first match; many updates
+  // every match and needs _id or an indexed field in the query.
+  async updateBy(query, ops, opts = {}) {
+    const out = await this.send("POST", "_update_by_query", {
+      query: toWhere(query),
+      update: checkOps(ops),
+      many: opts.many,
+      upsert: opts.upsert,
+      expire_in: opts.expireIn
+    });
+    return this.updated(out);
   }
-  // Atomic update. A string is an _id (POST /{_id}/update); an object is a
-  // filter (POST /update). The filter and the operators are sent as one body;
-  // the daemon matches and writes in one step on the newest state, so
-  // concurrent updates never interleave. A version guard is a filter:
-  // { _id: 'c1', _v: 7 }. Matching nothing is not an error: matched is 0.
-  // many does not apply to an _id.
-  async update(idOrFilter, ops, opts = {}) {
-    await this.ready();
-    const byId = typeof idOrFilter === "string";
-    const body = mergeUpdate(byId ? {} : idOrFilter, ops);
-    const query = writeQuery({ many: byId ? void 0 : opts.many, upsert: opts.upsert, expire_in: opts.expireIn });
-    const op = byId ? `${encodeURIComponent(idOrFilter)}/update` : "update";
-    const out = await this.db.transport.request(
-      "POST",
-      this.path(op) + query,
-      body
-    );
-    return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
+  // Deletes the document with this _id (DELETE /{coll}/_doc/{id}).
+  delete(id) {
+    return this.send("DELETE", docPath("_doc", id));
   }
-  // Deletes by _id (a string), or the documents that the filter matches: one,
-  // or every match with many (same rule as update).
-  async delete(idOrFilter, opts = {}) {
-    await this.ready();
-    if (typeof idOrFilter === "string") {
-      return this.db.transport.request("DELETE", this.path(encodeURIComponent(idOrFilter)));
-    }
-    const filter = idOrFilter;
-    return this.db.transport.request("POST", this.path("delete") + writeQuery({ many: opts.many }), toWhere(filter));
+  // Deletes the first document the query matches, or every match with many
+  // (POST /{coll}/_delete_by_query, same rule as updateBy).
+  deleteBy(query, opts = {}) {
+    return this.send("POST", "_delete_by_query", { query: toWhere(query), many: opts.many });
   }
-  // Removes every document of the collection and keeps its definition and
-  // indexes. The cost does not depend on the number of documents. Watch
-  // consumers get one event with op "truncate".
+  // Removes every document and keeps the definition and indexes. The cost
+  // does not depend on the number of documents. Watch consumers get one event
+  // with op "truncate".
   async truncate() {
-    await this.ready();
-    await this.db.transport.request("POST", this.path("truncate") + this.confirm());
+    await this.db.transport.request("POST", this.path("_truncate") + this.confirm());
   }
   // Removes the collection: its documents, its definition and the positions
-  // of its watch consumers. The next call on the model declares it again.
+  // of its watch consumers. The next call declares it again.
   async drop() {
-    await this.db.transport.request("DELETE", this.path() + this.confirm());
     this.ensured = void 0;
+    await this.db.transport.request("DELETE", this.path() + this.confirm());
   }
   confirm() {
     return `?confirm=${encodeURIComponent(this.name)}`;
@@ -355,99 +370,84 @@ var Model = class {
   // NotFoundError for a missing or expired document, and TtlError when the
   // schema has no expires field.
   expire(id, duration) {
-    return this.setExpiry({ _id: id, in: duration });
+    return this.setExpiry(id, { in: duration });
   }
   expireAt(id, at) {
-    return this.setExpiry({ _id: id, at: at.toISOString() });
+    return this.setExpiry(id, { at: at.toISOString() });
   }
   // Removes the expiry of a document (PERSIST in Redis).
-  async persist(id) {
-    await this.ready();
-    return this.db.transport.request("POST", this.path("persist"), { _id: id });
+  persist(id) {
+    return this.send("POST", docPath("_persist", id));
   }
   // The seconds left (rounded up), -1 when the document never expires, null
   // when it is missing or expired.
   async ttl(id) {
-    await this.ready();
-    try {
-      const out = await this.db.transport.request("GET", this.path(`${encodeURIComponent(id)}/ttl`));
-      return out.ttl;
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        return null;
-      }
-      throw err;
-    }
+    const out = await orNull(this.send("GET", docPath("_ttl", id)));
+    return out === null ? null : out.ttl;
   }
-  async setExpiry(body) {
-    await this.ready();
-    const out = await this.db.transport.request("POST", this.path("expire"), body);
-    return { _id: out._id, v: out.v, expiresAt: new Date(out.expires_at) };
+  async setExpiry(id, body) {
+    const out = await this.send("POST", docPath("_expire", id), body);
+    return { _id: out._id, _v: out._v, expiresAt: new Date(out.expires_at) };
   }
   // The document with this _id, or null.
   async get(id) {
-    await this.ready();
-    try {
-      const doc = await this.db.transport.request("GET", this.path(encodeURIComponent(id)));
-      return this.decode(doc);
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        return null;
-      }
-      throw err;
-    }
-  }
-  query() {
-    return new Query(this);
+    const doc = await orNull(this.send("GET", docPath("_doc", id)));
+    return doc === null ? null : this.decode(doc);
   }
-  where(w) {
-    return this.query().where(w);
+  // A search (POST /{coll}/_search). No query matches every document.
+  query(w) {
+    const q = new Query(this);
+    return w === void 0 ? q : q.query(w);
   }
-  whereRaw(w) {
-    return this.query().whereRaw(w);
+  // A query built elsewhere, such as from a search form: it is not
+  // type-checked and is sent as is; the daemon validates it.
+  rawQuery(w) {
+    return new Query(this).rawQuery(w);
   }
   not(w) {
-    return this.query().not(w);
+    return new Query(this).not(w);
   }
   or(...ws) {
-    return this.query().or(...ws);
+    return new Query(this).or(...ws);
   }
   sort(spec) {
-    return this.query().sort(spec);
+    return new Query(this).sort(spec);
   }
   limit(n) {
-    return this.query().limit(n);
+    return new Query(this).limit(n);
   }
   skip(n) {
-    return this.query().skip(n);
+    return new Query(this).skip(n);
   }
   page(n, size) {
-    return this.query().page(n, size);
+    return new Query(this).page(n, size);
   }
   after(token) {
-    return this.query().after(token);
+    return new Query(this).after(token);
   }
   fields(...names) {
-    return this.query().fields(...names);
+    return new Query(this).fields(...names);
   }
   all() {
-    return this.query().all();
+    return new Query(this).all();
   }
-  count() {
-    return this.query().count();
+  // How many documents match (POST /{coll}/_count).
+  count(w) {
+    return this.query(w).count();
   }
   first() {
-    return this.query().first();
+    return new Query(this).first();
   }
-  iterate() {
-    return this.query().iterate();
+  // Every row, page by page.
+  each() {
+    return new Query(this).each();
   }
-  // Runs a find with a whole body built elsewhere, such as from a search
-  // form: { where, sort, limit, after, count }. The body is sent as is (the
-  // daemon validates it); rows are decoded like the rows of where().
-  async find(body) {
+  // Runs a whole search body built elsewhere, such as from a search form:
+  // { query, sort, limit, after, count }. The body is sent as is (the daemon
+  // validates it); rows are decoded like the rows of query().
+  async search(body) {
     await this.ready();
-    const res = await this.db.transport.stream("POST", this.path("find"), { ...body, versions: true });
+    const res = await this.db.transport.stream("POST", this.path("_search"), { ...body, versions: true });
     const rows = [];
     for await (const raw of res.rows()) {
       rows.push(this.decode(raw));
@@ -456,7 +456,7 @@ var Model = class {
   }
   async aggregate(pipeline, opts = {}) {
     await this.ready();
-    const res = await this.db.transport.stream("POST", this.path("aggregate"), { pipeline, ...opts });
+    const res = await this.db.transport.stream("POST", this.path("_aggregate"), { pipeline, ...opts });
     const rows = [];
     for await (const row of res.rows()) {
       rows.push(row);
@@ -465,14 +465,30 @@ var Model = class {
   }
   async *watch(consumer, opts = {}) {
     await this.ready();
-    const body = { consumer, from: opts.from, limit: opts.limit, where: opts.where === void 0 ? void 0 : toWhere(opts.where) };
-    const res = await this.db.transport.stream("POST", this.path("watch"), body, opts.signal);
+    const body = { consumer, from: opts.from, limit: opts.limit, query: opts.query === void 0 ? void 0 : toWhere(opts.query) };
+    const res = await this.db.transport.stream("POST", this.path("_watch"), body, opts.signal);
     for await (const ev of watchEvents(res.rows(), consumer)) {
       yield { ...ev, doc: ev.doc && this.decode(ev.doc) };
     }
   }
   async ack(event) {
-    await this.db.transport.request("POST", this.path("ack"), { consumer: event.consumer, pos: event.pos });
+    await this.send("POST", "_ack", { consumer: event.consumer, pos: event.pos });
+  }
+  // Rows, indexes, files and bytes (GET /{coll}/_stats).
+  stats() {
+    return this.send("GET", "_stats");
+  }
+  // Seals the memtable and merges every segment now (POST /{coll}/_compact).
+  compact() {
+    return this.send("POST", "_compact");
+  }
+  // Adds a secondary index and builds it in the background. Returns the
+  // indexed fields.
+  async ensureIndex(field) {
+    return (await this.send("PUT", docPath("_indexes", field))).indexes;
+  }
+  async dropIndex(field) {
+    return (await this.send("DELETE", docPath("_indexes", field))).indexes;
   }
   decode(raw) {
     const out = { ...raw };
@@ -484,6 +500,15 @@ var Model = class {
     }
     return out;
   }
+  // Declares the collection on first use, then sends one request to
+  // /{coll}/{action}.
+  async send(method, action, body) {
+    await this.ready();
+    return this.db.transport.request(method, this.path(action), body);
+  }
+  updated(out) {
+    return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
+  }
   catalog() {
     const entries = Object.entries(this.schema.fields);
     return {
@@ -494,23 +519,26 @@ var Model = class {
     };
   }
 };
-function writeQuery(params) {
-  const q = new URLSearchParams();
-  for (const [name, value] of Object.entries(params)) {
-    if (value !== void 0 && value !== false) {
-      q.set(name, String(value));
-    }
-  }
-  const text = q.toString();
-  return text === "" ? "" : `?${text}`;
+function docPath(action, id) {
+  return `${action}/${encodeURIComponent(id)}`;
 }
-function mergeUpdate(filter, ops) {
+function checkOps(ops) {
   for (const key of Object.keys(ops)) {
     if (!key.startsWith("$")) {
       throw new InvalidUpdateError("invalid_update", `update operator "${key}" must start with $ (for example "$set")`);
     }
   }
-  return { ...toWhere(filter), ...ops };
+  return ops;
+}
+async function orNull(p) {
+  try {
+    return await p;
+  } catch (err) {
+    if (err instanceof NotFoundError) {
+      return null;
+    }
+    throw err;
+  }
 }
 
 // src/transport.ts
@@ -548,7 +576,7 @@ var notConnected = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOENT"]);
 var retryBaseMs = 50;
 var retryCapMs = 1e3;
 var defaultReadyTimeoutMs = 1e4;
-var readOps = /\/(find|count|aggregate|get|stats)$/;
+var readOps = /\/(_search|_count|_aggregate)$/;
 var Transport = class {
   client;
   token;
@@ -567,9 +595,9 @@ var Transport = class {
       throw new TypeError(`ndb: address "${target}" must be unix:///path or tcp://host:port`);
     }
   }
-  async stream(method, path, body, signal) {
+  async stream(method, path, body, signal, contentType) {
     const res = await this.withReadyRetry(method, path, signal, async () => {
-      const r = await this.send(method, path, body, signal);
+      const r = await this.send(method, path, body, signal, contentType);
       if (r.statusCode >= 300) {
         throw await apiError(r);
       }
@@ -583,8 +611,9 @@ var Transport = class {
       header: (name) => headerOf(res.headers, name)
     };
   }
-  async request(method, path, body) {
-    const res = await this.stream(method, path, body);
+  // contentType sends body as raw bytes (blobs) instead of JSON.
+  async request(method, path, body, contentType) {
+    const res = await this.stream(method, path, body, void 0, contentType);
     const text = await res.body.setEncoding("utf8").toArray();
     return text.length > 0 ? JSON.parse(text.join("")) : void 0;
   }
@@ -612,20 +641,22 @@ var Transport = class {
       }
     }
   }
-  headers() {
-    const headers = { "content-type": "application/json" };
+  // Rows come as NDJSON: the SDK reads them one by one (jsonRows).
+  headers(contentType = "application/json") {
+    const headers = { "content-type": contentType, accept: "application/x-ndjson" };
     if (this.token) {
       headers.authorization = `Bearer ${this.token}`;
     }
     return headers;
   }
-  async send(method, path, body, signal) {
+  async send(method, path, body, signal, contentType) {
+    const raw = contentType !== void 0;
     const opts = {
       method,
       path,
       signal,
-      headers: this.headers(),
-      body: body === void 0 ? void 0 : JSON.stringify(body)
+      headers: this.headers(contentType),
+      body: body === void 0 ? void 0 : raw ? body : JSON.stringify(body)
     };
     try {
       return await this.client.request(opts);
@@ -692,11 +723,37 @@ var Ndb = class {
   constructor(addr, opts) {
     this.transport = new Transport(addr, opts);
   }
-  model(name, schema) {
-    return new Model(this, name, schema);
+  // A collection of the daemon; see Collection. Nothing is sent until its
+  // first call.
+  collection(name, schema) {
+    return new Collection(this, name, schema);
   }
+  // Resolves when the daemon is ready (GET /_health).
   async health() {
-    await this.transport.request("GET", "/health");
+    await this.transport.request("GET", "/_health");
+  }
+  // The catalog: one definition per collection (GET /_collections).
+  async collections() {
+    return (await this.transport.request("GET", "/_collections")).collections;
+  }
+  // Every collection, totals, version and uptime (GET /_stats).
+  stats() {
+    return this.transport.request("GET", "/_stats");
+  }
+  // Disk use per collection and per part (GET /_size).
+  size() {
+    return this.transport.request("GET", "/_size");
+  }
+  // Stores bytes in the blob store (POST /_blobs) and returns the reference
+  // to put in a document field.
+  putBlob(data, contentType = "application/octet-stream") {
+    return this.transport.request("POST", "/_blobs", data, contentType);
+  }
+  // The bytes of a blob (GET /_blobs/{ref}).
+  async getBlob(blob) {
+    const ref = typeof blob === "string" ? blob : blob.$blob;
+    const res = await this.transport.stream("GET", `/_blobs/${encodeURIComponent(ref)}`);
+    return new Uint8Array(await res.body.arrayBuffer());
   }
   request(method, path, body) {
     return this.transport.request(method, path, body);
@@ -745,12 +802,12 @@ function seedCounter() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Collection,
   CursorError,
   DuplicateIdError,
   HistoryTruncatedError,
   InvalidQueryError,
   InvalidUpdateError,
-  Model,
   Ndb,
   NdbError,
   NotFoundError,