@thadeu/ndb 0.1.1 → 0.2.0

package/README.md

@@ -51,10 +51,8 @@ await ndb.close()
 
 ```ts
 const calls = ndb.model('calls', {
-  id: 'call_id',
   time: 'at',
   fields: {
-    call_id: { type: 'string' },
     status: { type: 'string', index: true },
     caller: { type: 'string', unique: true },
     duration: { type: 'number', optional: true },
@@ -66,10 +64,10 @@ const calls = ndb.model('calls', {
 
 - Field types: `string`, `number`, `boolean`, `date` (a `Date`), `json` (any value).
 - Field options: `index`, `unique`, `optional`.
-- `id` is the id field. Without it the id is `_id`, made by the daemon.
+- `_id` is the primary key of every document. It is not a schema field: leave it out on insert and the daemon makes a UUIDv7 (or use `newId()`). For a natural key (email, SKU), keep `_id` and mark that field `unique`.
 - `time` is the collection time field. Used by zone maps and `$dateTrunc`.
 - The model declares its collection on first use (`ensure_collection`). You can call `await calls.ready()` to do it at once.
-- Types come from the schema. Rows have the schema fields and `_v`, the document version. A `date` field is a `Date` in rows. Input takes `Date` values and ISO strings in filters.
+- Types come from the schema. Rows have the schema fields, `_id` and `_v`, the document version. A `date` field is a `Date` in rows. Input takes `Date` values and ISO strings in filters.
 - `expires` is the `date` field that holds when a document expires. It turns on `expireIn`, `expire`, `persist` and `ttl` (below).
 - The client has no `ttl` catalog option and no blob API. Use the HTTP API for those.
 
@@ -78,51 +76,51 @@ const calls = ndb.model('calls', {
 ```ts
 // Insert one or many. All documents go in one transaction.
 const results = await calls.insert([
-  { call_id: 'c1', status: 'answered', caller: 'a', duration: 30, at: new Date() },
-  { call_id: 'c2', status: 'failed', caller: 'b', at: new Date() },
+  { _id: 'c1', status: 'answered', caller: 'a', duration: 30, at: new Date() },
+  { _id: 'c2', status: 'failed', caller: 'b', at: new Date() },
 ])
-// results: [{ id: 'c1', v: 1 }, ...]
+// results: [{ _id: 'c1', v: 1 }, ...]
 
-// Find by id. Returns null when missing.
-const row = await calls.find('c1')
+// Get by _id (GET /v1/c/calls/c1). Returns null when missing.
+const row = await calls.get('c1')
 
-// Update with optimistic locking.
-await calls.update('c1', { status: 'done' }, { ifVersion: row!._v })
+// Atomic update by filter: filter first, then the write operators.
+// _v in the filter is an optimistic lock.
+const res = await calls.update({ _id: 'c1', _v: row!._v }, { $set: { status: 'done' }, $unset: { duration: true } })
+// res: { matched, modified, doc } (doc is the new row with _v; absent for many)
 
-// Remove a field.
-await calls.update('c1', {}, { unset: ['duration'] })
+// A string is an _id (POST /{_id}/update). The same guard rules apply.
+await calls.update('c1', { $inc: { duration: 1 } })
 
-// Delete. ifVersion is optional here too.
-await calls.delete('c1', { ifVersion: 3 })
-```
-
-`update` returns `{ id, v }` with the new version. A stale `ifVersion` throws `VersionConflictError`:
+// A guarded decrement: exactly one of two racing calls wins.
+await stock.update({ _id: 'a', qty: { $gte: 1 } }, { $inc: { qty: -1 } })
 
-```ts
-import { VersionConflictError } from '@thadeu/ndb'
+// Every match (the filter needs _id or an indexed field), or create it.
+await calls.update({ status: 'failed' }, { $set: { status: 'retry' } }, { many: true })
+await calls.update('c9', { $inc: { duration: 1 } }, { upsert: true })
 
-try {
-  await calls.update('c1', { status: 'x' }, { ifVersion: row!._v })
-} catch (err) {
-  if (err instanceof VersionConflictError) {
-    // Someone else wrote first. Read again and retry.
-  }
-}
+// Delete by _id or by filter: { deleted }.
+await calls.delete('c2')
+await calls.delete({ status: 'failed' }, { many: true })
 ```
 
-An insert with a duplicate id throws `DuplicateIdError`. A duplicate `unique` value throws `UniqueViolationError`. An insert without the id when the schema names one fails with code `missing_id`.
+- Operators: `$set`, `$setOnInsert` (like `$set`, but only when an upsert creates the document), `$unset`, `$inc`, `$push` (with `{ $each: [...] }`), `$pull`, `$min`, `$max`. Field names can be dot paths.
+- Nothing matched is not an error: `matched` is 0 (for example when `_v` is stale, so read again and retry). `modified` is 0 when the operators leave the document as it is.
+- `many` needs `_id` or an indexed field in the filter, and does not apply to an `_id` string. `upsert` creates the document from the equality fields of the filter (or with that `_id`).
+- A key of the operators without `$` throws `InvalidUpdateError` before anything is sent. The daemon contract errors (`unknown_operator`, `no_update`, `conflicting_update`, `invalid_field`, `unindexed_many`, `empty_filter`) are `InvalidUpdateError` too.
+
+An insert with a duplicate `_id` throws `DuplicateIdError`. A duplicate `unique` value throws `UniqueViolationError`. An empty or non-string `_id` fails with code `invalid_id`.
 
 ### Expiry (TTL like Redis)
 
 ```ts
 const sessions = db.model('sessions', {
-  id: 'sid',
   expires: 'exp',
-  fields: { sid: { type: 'string' }, exp: { type: 'date', optional: true } },
+  fields: { exp: { type: 'date', optional: true } },
 })
 
-await sessions.insert({ sid: 's1' }, { expireIn: '1h' }) // or 3600; all docs of the call
-await sessions.update('s1', { user: 'u' }, { expireIn: '30m' })
+await sessions.insert({ _id: 's1' }, { expireIn: '1h' }) // or 3600; all docs of the call
+await sessions.update('s1', { $set: { user: 'u' } }, { expireIn: '30m' })
 
 const { v, expiresAt } = await sessions.expire('s1', '30m') // EXPIRE
 await sessions.expireAt('s1', new Date(Date.now() + 3_600_000))
@@ -144,8 +142,8 @@ const rows = await calls
   .where({ caller: { $in: ['a', 'b'] } })
   .not({ caller: 'zzz' })
   .or({ duration: { $lt: 5 } }, { 'meta.agent.id': 7 })
-  .sort({ at: -1, call_id: 1 })
-  .fields('call_id', 'status')
+  .sort({ at: -1, _id: 1 })
+  .fields('_id', 'status')
   .limit(50)
   .skip(100)
 ```
@@ -170,11 +168,11 @@ const total = await calls.count()
 Offset pages get slower as `skip` grows. Use a cursor for deep pages.
 
 ```ts
-const q = calls.where({ status: 'answered' }).sort({ call_id: 1 }).limit(100)
+const q = calls.where({ status: 'answered' }).sort({ _id: 1 }).limit(100)
 const page = await q
 const token = q.nextCursor // '' on the last page
 
-const next = await calls.where({ status: 'answered' }).sort({ call_id: 1 }).limit(100).after(token)
+const next = await calls.where({ status: 'answered' }).sort({ _id: 1 }).limit(100).after(token)
 ```
 
 A token works only with the same `where` and `sort`. Another query shape throws `CursorError`.
@@ -182,8 +180,8 @@ A token works only with the same `where` and `sort`. Another query shape throws
 To walk every row, use `iterate()`. It follows the cursor, with `limit` as the batch size:
 
 ```ts
-for await (const row of calls.where({ status: 'answered' }).sort({ call_id: 1 }).limit(500).iterate()) {
-  console.log(row.call_id)
+for await (const row of calls.where({ status: 'answered' }).sort({ _id: 1 }).limit(500).iterate()) {
+  console.log(row._id)
 }
 ```
 
@@ -238,7 +236,7 @@ const controller = new AbortController()
 
 try {
   for await (const ev of calls.watch('relay', { where: { status: 'answered' }, signal: controller.signal })) {
-    // ev: { consumer, pos, op: 'put' | 'del', id, v, doc }
+    // ev: { consumer, pos, op: 'put' | 'del', _id, v, doc }
     await handle(ev)
 
     await calls.ack(ev)
@@ -268,7 +266,6 @@ Daemon errors are `NdbError` or a subclass. They have `code` (the daemon code) a
 |---|---|
 | `UnauthorizedError` | `unauthorized` |
 | `NotFoundError` | `not_found`, `unknown_collection` |
-| `VersionConflictError` | `version_conflict` |
 | `DuplicateIdError` | `duplicate_id` |
 | `UniqueViolationError` | `unique_violation` |
 | `InvalidQueryError` | `invalid_query`, `invalid_pipeline` |
@@ -276,13 +273,14 @@ Daemon errors are `NdbError` or a subclass. They have `code` (the daemon code) a
 | `WatchLaggedError` | `watch_lagged` |
 | `HistoryTruncatedError` | `history_truncated` |
 | `TtlError` | `ttl_not_enabled`, `ttl_derived` |
+| `InvalidUpdateError` | `unknown_operator`, `no_update`, `conflicting_update`, `invalid_field`, `unindexed_many`, `empty_filter`, `invalid_update` |
 | `NdbError` | every other code: `not_ready`, `catalog_conflict`, `catalog_invalid`, `direct_collection`, `invalid_request`, `group_limit_exceeded`, `request_too_large`, `line_too_large`, `closed`, `invalid_position`, `http_status`, ... |
 
 ```ts
 import { NdbError } from '@thadeu/ndb'
 
 try {
-  await calls.find('c1')
+  await calls.get('c1')
 } catch (err) {
   if (err instanceof NdbError && err.code === 'not_ready') {
     // The daemon is still recovering, and readyTimeout ran out.

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   DuplicateIdError: () => DuplicateIdError,
   HistoryTruncatedError: () => HistoryTruncatedError,
   InvalidQueryError: () => InvalidQueryError,
+  InvalidUpdateError: () => InvalidUpdateError,
   Model: () => Model,
   Ndb: () => Ndb,
   NdbError: () => NdbError,
@@ -32,10 +33,10 @@ __export(index_exports, {
   TtlError: () => TtlError,
   UnauthorizedError: () => UnauthorizedError,
   UniqueViolationError: () => UniqueViolationError,
-  VersionConflictError: () => VersionConflictError,
   WatchLaggedError: () => WatchLaggedError,
   connect: () => connect,
-  makeError: () => makeError
+  makeError: () => makeError,
+  newId: () => newId
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -54,8 +55,6 @@ var UnauthorizedError = class extends NdbError {
 };
 var NotFoundError = class extends NdbError {
 };
-var VersionConflictError = class extends NdbError {
-};
 var DuplicateIdError = class extends NdbError {
 };
 var UniqueViolationError = class extends NdbError {
@@ -68,13 +67,14 @@ var WatchLaggedError = class extends NdbError {
 };
 var HistoryTruncatedError = class extends NdbError {
 };
+var InvalidUpdateError = class extends NdbError {
+};
 var TtlError = class extends NdbError {
 };
 var subclasses = {
   unauthorized: UnauthorizedError,
   not_found: NotFoundError,
   unknown_collection: NotFoundError,
-  version_conflict: VersionConflictError,
   duplicate_id: DuplicateIdError,
   unique_violation: UniqueViolationError,
   invalid_query: InvalidQueryError,
@@ -85,7 +85,13 @@ var subclasses = {
   watch_lagged: WatchLaggedError,
   history_truncated: HistoryTruncatedError,
   ttl_not_enabled: TtlError,
-  ttl_derived: TtlError
+  ttl_derived: TtlError,
+  unknown_operator: InvalidUpdateError,
+  no_update: InvalidUpdateError,
+  conflicting_update: InvalidUpdateError,
+  invalid_field: InvalidUpdateError,
+  unindexed_many: InvalidUpdateError,
+  empty_filter: InvalidUpdateError
 };
 function makeError(code, message, status = 0) {
   const Cls = subclasses[code] ?? NdbError;
@@ -250,7 +256,7 @@ 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 };
   }
 }
 
@@ -265,9 +271,6 @@ var Model = class {
   name;
   schema;
   ensured;
-  get idField() {
-    return this.schema.id ?? "_id";
-  }
   path(op) {
     const base = `/v1/c/${encodeURIComponent(this.name)}`;
     return op ? `${base}/${op}` : base;
@@ -291,35 +294,55 @@ var Model = class {
   create(docs, opts = {}) {
     return this.insert(docs, opts);
   }
-  async update(id, set, opts = {}) {
+  // 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 update = { id, set, unset: opts.unset, if_version: opts.ifVersion, expire_in: opts.expireIn };
-    return this.db.transport.request("POST", this.path("update"), { update });
+    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) };
   }
-  async delete(id, opts = {}) {
+  // 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();
-    await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
+    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));
   }
   // Makes a document expire, like EXPIRE in Redis: seconds or "30m". It throws
   // NotFoundError for a missing or expired document, and TtlError when the
   // schema has no expires field.
-  expire(id, duration, opts = {}) {
-    return this.setExpiry({ id, in: duration, if_version: opts.ifVersion });
+  expire(id, duration) {
+    return this.setExpiry({ _id: id, in: duration });
   }
-  expireAt(id, at, opts = {}) {
-    return this.setExpiry({ id, at: at.toISOString(), if_version: opts.ifVersion });
+  expireAt(id, at) {
+    return this.setExpiry({ _id: 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 });
+    return this.db.transport.request("POST", this.path("persist"), { _id: 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("ttl")}/${encodeURIComponent(id)}`);
+      const out = await this.db.transport.request("GET", this.path(`${encodeURIComponent(id)}/ttl`));
       return out.ttl;
     } catch (err) {
       if (err instanceof NotFoundError) {
@@ -331,10 +354,20 @@ var Model = class {
   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) };
+    return { _id: out._id, v: out.v, expiresAt: new Date(out.expires_at) };
   }
-  find(id) {
-    return this.query().where({ [this.idField]: id }).first();
+  // 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);
@@ -411,7 +444,6 @@ var Model = class {
   catalog() {
     const entries = Object.entries(this.schema.fields);
     return {
-      id: this.schema.id,
       time: this.schema.time,
       expires_field: this.schema.expires,
       indexes: entries.filter(([, d]) => d.index).map(([n]) => n),
@@ -419,6 +451,24 @@ 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 mergeUpdate(filter, 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 };
+}
 
 // src/transport.ts
 var import_undici = require("undici");
@@ -618,12 +668,45 @@ var Ndb = class {
 function connect(addr, opts) {
   return new Ndb(addr, opts);
 }
+
+// src/id.ts
+var lastMs = 0;
+var counter = 0;
+function newId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const now = Date.now();
+  if (now > lastMs) {
+    lastMs = now;
+    counter = seedCounter();
+  } else if (counter === 4095) {
+    lastMs += 1;
+    counter = seedCounter();
+  } else {
+    counter += 1;
+  }
+  const ms = BigInt(lastMs);
+  for (let i = 0; i < 6; i++) {
+    bytes[i] = Number(ms >> BigInt(8 * (5 - i)) & 0xffn);
+  }
+  bytes[6] = 112 | counter >> 8;
+  bytes[7] = counter & 255;
+  bytes[8] = 128 | bytes[8] & 63;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function seedCounter() {
+  const r = new Uint16Array(1);
+  crypto.getRandomValues(r);
+  return r[0] & 2047;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CursorError,
   DuplicateIdError,
   HistoryTruncatedError,
   InvalidQueryError,
+  InvalidUpdateError,
   Model,
   Ndb,
   NdbError,
@@ -632,8 +715,8 @@ function connect(addr, opts) {
   TtlError,
   UnauthorizedError,
   UniqueViolationError,
-  VersionConflictError,
   WatchLaggedError,
   connect,
-  makeError
+  makeError,
+  newId
 });

package/dist/index.d.cts

@@ -16,7 +16,6 @@ interface FieldDef {
 }
 type Fields = Record<string, FieldDef>;
 interface Schema<F extends Fields> {
-    id?: Extract<keyof F, string>;
     time?: Extract<keyof F, string>;
     expires?: Extract<keyof F, string>;
     fields: F;
@@ -34,8 +33,11 @@ type Doc<F extends Fields> = {
 };
 type Input<F extends Fields> = {
     [K in keyof F]?: ValueOf<F[K]>;
+} & {
+    _id?: string;
 };
 type Row<F extends Fields> = Doc<F> & {
+    _id: string;
     _v: number;
 };
 interface Ops<V> {
@@ -58,22 +60,49 @@ type JsonKeys<F extends Fields> = Extract<{
 }[keyof F], string>;
 type Where<F extends Fields> = {
     [K in keyof F]?: Operand<ValueOf<F[K]>> | Ops<Operand<ValueOf<F[K]>>> | RegexOperand<ValueOf<F[K]>>;
+} & {
+    _id?: string | Ops<string>;
 } & {
     [P in `${JsonKeys<F>}.${string}`]?: unknown;
 };
-type SortSpec<F extends Fields> = Partial<Record<Extract<keyof F, string>, 1 | -1>>;
+type SortSpec<F extends Fields> = Partial<Record<Extract<keyof F, string> | '_id', 1 | -1>>;
 interface WriteResult {
-    id: string;
+    _id: string;
     v: number;
 }
-interface WriteOptions {
-    ifVersion?: number;
-}
 type Duration = number | string;
-interface UpdateOptions extends WriteOptions {
-    unset?: string[];
+type Filter<F extends Fields> = Where<F> & {
+    _v?: number | Ops<number>;
+    $and?: Filter<F>[];
+    $or?: Filter<F>[];
+    $nor?: Filter<F>[];
+};
+interface UpdateOps<F extends Fields = Fields> {
+    $set?: Input<F> & Record<string, unknown>;
+    $setOnInsert?: Input<F> & Record<string, unknown>;
+    $unset?: Record<string, true | ''>;
+    $inc?: Record<string, number>;
+    $push?: Record<string, unknown>;
+    $pull?: Record<string, unknown>;
+    $min?: Record<string, number | string>;
+    $max?: Record<string, number | string>;
+}
+interface UpdateOptions {
+    many?: boolean;
+    upsert?: boolean;
     expireIn?: Duration;
 }
+interface DeleteOptions {
+    many?: boolean;
+}
+interface UpdateResult<F extends Fields = Fields> {
+    matched: number;
+    modified: number;
+    doc?: Row<F>;
+}
+interface DeleteResult {
+    deleted: number;
+}
 interface InsertOptions {
     expireIn?: Duration;
 }
@@ -101,7 +130,7 @@ interface WatchEvent<R> {
     consumer: string;
     pos: string;
     op: 'put' | 'del';
-    id: string;
+    _id: string;
     v: number;
     doc: R | undefined;
 }
@@ -145,19 +174,18 @@ declare class Model<F extends Fields> {
     readonly schema: Schema<F>;
     private ensured?;
     constructor(db: Ndb, name: string, schema: Schema<F>);
-    get idField(): string;
     path(op?: string): string;
     ready(): Promise<void>;
     insert(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     create(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
-    update(id: string, set: Input<F>, opts?: UpdateOptions): Promise<WriteResult>;
-    delete(id: string, opts?: WriteOptions): Promise<void>;
-    expire(id: string, duration: Duration, opts?: WriteOptions): Promise<ExpireResult>;
-    expireAt(id: string, at: Date, opts?: WriteOptions): Promise<ExpireResult>;
+    update(idOrFilter: string | Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
+    delete(idOrFilter: string | Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    expire(id: string, duration: Duration): Promise<ExpireResult>;
+    expireAt(id: string, at: Date): Promise<ExpireResult>;
     persist(id: string): Promise<WriteResult>;
     ttl(id: string): Promise<number | null>;
     private setExpiry;
-    find(id: string): Promise<Row<F> | null>;
+    get(id: string): Promise<Row<F> | null>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
     not(w: Where<F>): Query<F>;
@@ -215,7 +243,9 @@ declare class Ndb {
 }
 declare function connect(addr?: string, opts?: ConnectOptions): Ndb;
 
-type ErrorCode = 'unauthorized' | 'not_found' | 'version_conflict' | 'duplicate_id' | 'unique_violation' | 'catalog_conflict' | 'catalog_invalid' | 'unknown_collection' | 'direct_collection' | 'invalid_request' | 'invalid_query' | 'invalid_pipeline' | 'group_limit_exceeded' | 'cursor_invalid' | 'cursor_mismatch' | 'cursor_expired' | 'request_too_large' | 'line_too_large' | 'not_ready' | 'closed' | 'watch_lagged' | 'invalid_position' | 'history_truncated' | 'ttl_not_enabled' | 'ttl_derived' | 'http_status' | (string & {});
+declare function newId(): string;
+
+type ErrorCode = 'unauthorized' | 'not_found' | 'duplicate_id' | 'unique_violation' | 'catalog_conflict' | 'catalog_invalid' | 'unknown_collection' | 'direct_collection' | 'invalid_request' | 'invalid_query' | 'invalid_pipeline' | 'group_limit_exceeded' | 'cursor_invalid' | 'cursor_mismatch' | 'cursor_expired' | 'request_too_large' | 'line_too_large' | 'not_ready' | 'closed' | 'watch_lagged' | 'invalid_position' | 'history_truncated' | 'ttl_not_enabled' | 'ttl_derived' | 'unknown_operator' | 'no_update' | 'conflicting_update' | 'invalid_field' | 'unindexed_many' | 'empty_filter' | 'invalid_update' | 'http_status' | (string & {});
 declare class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -225,8 +255,6 @@ declare class UnauthorizedError extends NdbError {
 }
 declare class NotFoundError extends NdbError {
 }
-declare class VersionConflictError extends NdbError {
-}
 declare class DuplicateIdError extends NdbError {
 }
 declare class UniqueViolationError extends NdbError {
@@ -239,9 +267,11 @@ declare class WatchLaggedError extends NdbError {
 }
 declare class HistoryTruncatedError extends NdbError {
 }
+declare class InvalidUpdateError extends NdbError {
+}
 declare class TtlError extends NdbError {
 }
 declare function makeError(code: ErrorCode, message: string, status?: number): NdbError;
 
-export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, VersionConflictError, WatchLaggedError, connect, makeError };
-export type { AggregateOptions, AggregateResult, ConnectOptions, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOptions, WatchEvent, WatchOptions, Where, WriteOptions, WriteResult };
+export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, InvalidUpdateError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, WatchLaggedError, connect, makeError, newId };
+export type { AggregateOptions, AggregateResult, ConnectOptions, DeleteOptions, DeleteResult, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Filter, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOps, UpdateOptions, UpdateResult, WatchEvent, WatchOptions, Where, WriteResult };

package/dist/index.d.ts

@@ -16,7 +16,6 @@ interface FieldDef {
 }
 type Fields = Record<string, FieldDef>;
 interface Schema<F extends Fields> {
-    id?: Extract<keyof F, string>;
     time?: Extract<keyof F, string>;
     expires?: Extract<keyof F, string>;
     fields: F;
@@ -34,8 +33,11 @@ type Doc<F extends Fields> = {
 };
 type Input<F extends Fields> = {
     [K in keyof F]?: ValueOf<F[K]>;
+} & {
+    _id?: string;
 };
 type Row<F extends Fields> = Doc<F> & {
+    _id: string;
     _v: number;
 };
 interface Ops<V> {
@@ -58,22 +60,49 @@ type JsonKeys<F extends Fields> = Extract<{
 }[keyof F], string>;
 type Where<F extends Fields> = {
     [K in keyof F]?: Operand<ValueOf<F[K]>> | Ops<Operand<ValueOf<F[K]>>> | RegexOperand<ValueOf<F[K]>>;
+} & {
+    _id?: string | Ops<string>;
 } & {
     [P in `${JsonKeys<F>}.${string}`]?: unknown;
 };
-type SortSpec<F extends Fields> = Partial<Record<Extract<keyof F, string>, 1 | -1>>;
+type SortSpec<F extends Fields> = Partial<Record<Extract<keyof F, string> | '_id', 1 | -1>>;
 interface WriteResult {
-    id: string;
+    _id: string;
     v: number;
 }
-interface WriteOptions {
-    ifVersion?: number;
-}
 type Duration = number | string;
-interface UpdateOptions extends WriteOptions {
-    unset?: string[];
+type Filter<F extends Fields> = Where<F> & {
+    _v?: number | Ops<number>;
+    $and?: Filter<F>[];
+    $or?: Filter<F>[];
+    $nor?: Filter<F>[];
+};
+interface UpdateOps<F extends Fields = Fields> {
+    $set?: Input<F> & Record<string, unknown>;
+    $setOnInsert?: Input<F> & Record<string, unknown>;
+    $unset?: Record<string, true | ''>;
+    $inc?: Record<string, number>;
+    $push?: Record<string, unknown>;
+    $pull?: Record<string, unknown>;
+    $min?: Record<string, number | string>;
+    $max?: Record<string, number | string>;
+}
+interface UpdateOptions {
+    many?: boolean;
+    upsert?: boolean;
     expireIn?: Duration;
 }
+interface DeleteOptions {
+    many?: boolean;
+}
+interface UpdateResult<F extends Fields = Fields> {
+    matched: number;
+    modified: number;
+    doc?: Row<F>;
+}
+interface DeleteResult {
+    deleted: number;
+}
 interface InsertOptions {
     expireIn?: Duration;
 }
@@ -101,7 +130,7 @@ interface WatchEvent<R> {
     consumer: string;
     pos: string;
     op: 'put' | 'del';
-    id: string;
+    _id: string;
     v: number;
     doc: R | undefined;
 }
@@ -145,19 +174,18 @@ declare class Model<F extends Fields> {
     readonly schema: Schema<F>;
     private ensured?;
     constructor(db: Ndb, name: string, schema: Schema<F>);
-    get idField(): string;
     path(op?: string): string;
     ready(): Promise<void>;
     insert(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     create(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
-    update(id: string, set: Input<F>, opts?: UpdateOptions): Promise<WriteResult>;
-    delete(id: string, opts?: WriteOptions): Promise<void>;
-    expire(id: string, duration: Duration, opts?: WriteOptions): Promise<ExpireResult>;
-    expireAt(id: string, at: Date, opts?: WriteOptions): Promise<ExpireResult>;
+    update(idOrFilter: string | Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
+    delete(idOrFilter: string | Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    expire(id: string, duration: Duration): Promise<ExpireResult>;
+    expireAt(id: string, at: Date): Promise<ExpireResult>;
     persist(id: string): Promise<WriteResult>;
     ttl(id: string): Promise<number | null>;
     private setExpiry;
-    find(id: string): Promise<Row<F> | null>;
+    get(id: string): Promise<Row<F> | null>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
     not(w: Where<F>): Query<F>;
@@ -215,7 +243,9 @@ declare class Ndb {
 }
 declare function connect(addr?: string, opts?: ConnectOptions): Ndb;
 
-type ErrorCode = 'unauthorized' | 'not_found' | 'version_conflict' | 'duplicate_id' | 'unique_violation' | 'catalog_conflict' | 'catalog_invalid' | 'unknown_collection' | 'direct_collection' | 'invalid_request' | 'invalid_query' | 'invalid_pipeline' | 'group_limit_exceeded' | 'cursor_invalid' | 'cursor_mismatch' | 'cursor_expired' | 'request_too_large' | 'line_too_large' | 'not_ready' | 'closed' | 'watch_lagged' | 'invalid_position' | 'history_truncated' | 'ttl_not_enabled' | 'ttl_derived' | 'http_status' | (string & {});
+declare function newId(): string;
+
+type ErrorCode = 'unauthorized' | 'not_found' | 'duplicate_id' | 'unique_violation' | 'catalog_conflict' | 'catalog_invalid' | 'unknown_collection' | 'direct_collection' | 'invalid_request' | 'invalid_query' | 'invalid_pipeline' | 'group_limit_exceeded' | 'cursor_invalid' | 'cursor_mismatch' | 'cursor_expired' | 'request_too_large' | 'line_too_large' | 'not_ready' | 'closed' | 'watch_lagged' | 'invalid_position' | 'history_truncated' | 'ttl_not_enabled' | 'ttl_derived' | 'unknown_operator' | 'no_update' | 'conflicting_update' | 'invalid_field' | 'unindexed_many' | 'empty_filter' | 'invalid_update' | 'http_status' | (string & {});
 declare class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -225,8 +255,6 @@ declare class UnauthorizedError extends NdbError {
 }
 declare class NotFoundError extends NdbError {
 }
-declare class VersionConflictError extends NdbError {
-}
 declare class DuplicateIdError extends NdbError {
 }
 declare class UniqueViolationError extends NdbError {
@@ -239,9 +267,11 @@ declare class WatchLaggedError extends NdbError {
 }
 declare class HistoryTruncatedError extends NdbError {
 }
+declare class InvalidUpdateError extends NdbError {
+}
 declare class TtlError extends NdbError {
 }
 declare function makeError(code: ErrorCode, message: string, status?: number): NdbError;
 
-export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, VersionConflictError, WatchLaggedError, connect, makeError };
-export type { AggregateOptions, AggregateResult, ConnectOptions, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOptions, WatchEvent, WatchOptions, Where, WriteOptions, WriteResult };
+export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, InvalidUpdateError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, WatchLaggedError, connect, makeError, newId };
+export type { AggregateOptions, AggregateResult, ConnectOptions, DeleteOptions, DeleteResult, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Filter, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOps, UpdateOptions, UpdateResult, WatchEvent, WatchOptions, Where, WriteResult };

package/dist/index.js

@@ -13,8 +13,6 @@ var UnauthorizedError = class extends NdbError {
 };
 var NotFoundError = class extends NdbError {
 };
-var VersionConflictError = class extends NdbError {
-};
 var DuplicateIdError = class extends NdbError {
 };
 var UniqueViolationError = class extends NdbError {
@@ -27,13 +25,14 @@ var WatchLaggedError = class extends NdbError {
 };
 var HistoryTruncatedError = class extends NdbError {
 };
+var InvalidUpdateError = class extends NdbError {
+};
 var TtlError = class extends NdbError {
 };
 var subclasses = {
   unauthorized: UnauthorizedError,
   not_found: NotFoundError,
   unknown_collection: NotFoundError,
-  version_conflict: VersionConflictError,
   duplicate_id: DuplicateIdError,
   unique_violation: UniqueViolationError,
   invalid_query: InvalidQueryError,
@@ -44,7 +43,13 @@ var subclasses = {
   watch_lagged: WatchLaggedError,
   history_truncated: HistoryTruncatedError,
   ttl_not_enabled: TtlError,
-  ttl_derived: TtlError
+  ttl_derived: TtlError,
+  unknown_operator: InvalidUpdateError,
+  no_update: InvalidUpdateError,
+  conflicting_update: InvalidUpdateError,
+  invalid_field: InvalidUpdateError,
+  unindexed_many: InvalidUpdateError,
+  empty_filter: InvalidUpdateError
 };
 function makeError(code, message, status = 0) {
   const Cls = subclasses[code] ?? NdbError;
@@ -209,7 +214,7 @@ 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 };
   }
 }
 
@@ -224,9 +229,6 @@ var Model = class {
   name;
   schema;
   ensured;
-  get idField() {
-    return this.schema.id ?? "_id";
-  }
   path(op) {
     const base = `/v1/c/${encodeURIComponent(this.name)}`;
     return op ? `${base}/${op}` : base;
@@ -250,35 +252,55 @@ var Model = class {
   create(docs, opts = {}) {
     return this.insert(docs, opts);
   }
-  async update(id, set, opts = {}) {
+  // 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 update = { id, set, unset: opts.unset, if_version: opts.ifVersion, expire_in: opts.expireIn };
-    return this.db.transport.request("POST", this.path("update"), { update });
+    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) };
   }
-  async delete(id, opts = {}) {
+  // 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();
-    await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
+    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));
   }
   // Makes a document expire, like EXPIRE in Redis: seconds or "30m". It throws
   // NotFoundError for a missing or expired document, and TtlError when the
   // schema has no expires field.
-  expire(id, duration, opts = {}) {
-    return this.setExpiry({ id, in: duration, if_version: opts.ifVersion });
+  expire(id, duration) {
+    return this.setExpiry({ _id: id, in: duration });
   }
-  expireAt(id, at, opts = {}) {
-    return this.setExpiry({ id, at: at.toISOString(), if_version: opts.ifVersion });
+  expireAt(id, at) {
+    return this.setExpiry({ _id: 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 });
+    return this.db.transport.request("POST", this.path("persist"), { _id: 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("ttl")}/${encodeURIComponent(id)}`);
+      const out = await this.db.transport.request("GET", this.path(`${encodeURIComponent(id)}/ttl`));
       return out.ttl;
     } catch (err) {
       if (err instanceof NotFoundError) {
@@ -290,10 +312,20 @@ var Model = class {
   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) };
+    return { _id: out._id, v: out.v, expiresAt: new Date(out.expires_at) };
   }
-  find(id) {
-    return this.query().where({ [this.idField]: id }).first();
+  // 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);
@@ -370,7 +402,6 @@ var Model = class {
   catalog() {
     const entries = Object.entries(this.schema.fields);
     return {
-      id: this.schema.id,
       time: this.schema.time,
       expires_field: this.schema.expires,
       indexes: entries.filter(([, d]) => d.index).map(([n]) => n),
@@ -378,6 +409,24 @@ 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 mergeUpdate(filter, 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 };
+}
 
 // src/transport.ts
 import { Pool } from "undici";
@@ -577,11 +626,44 @@ var Ndb = class {
 function connect(addr, opts) {
   return new Ndb(addr, opts);
 }
+
+// src/id.ts
+var lastMs = 0;
+var counter = 0;
+function newId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const now = Date.now();
+  if (now > lastMs) {
+    lastMs = now;
+    counter = seedCounter();
+  } else if (counter === 4095) {
+    lastMs += 1;
+    counter = seedCounter();
+  } else {
+    counter += 1;
+  }
+  const ms = BigInt(lastMs);
+  for (let i = 0; i < 6; i++) {
+    bytes[i] = Number(ms >> BigInt(8 * (5 - i)) & 0xffn);
+  }
+  bytes[6] = 112 | counter >> 8;
+  bytes[7] = counter & 255;
+  bytes[8] = 128 | bytes[8] & 63;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function seedCounter() {
+  const r = new Uint16Array(1);
+  crypto.getRandomValues(r);
+  return r[0] & 2047;
+}
 export {
   CursorError,
   DuplicateIdError,
   HistoryTruncatedError,
   InvalidQueryError,
+  InvalidUpdateError,
   Model,
   Ndb,
   NdbError,
@@ -590,8 +672,8 @@ export {
   TtlError,
   UnauthorizedError,
   UniqueViolationError,
-  VersionConflictError,
   WatchLaggedError,
   connect,
-  makeError
+  makeError,
+  newId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thadeu/ndb",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript client for the ndb daemon",
   "keywords": [
     "ndb",