@thadeu/ndb 0.1.2 → 0.2.1

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,49 +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')
 
 // Atomic update by filter: filter first, then the write operators.
 // _v in the filter is an optimistic lock.
-const res = await calls.update({ call_id: 'c1', _v: row!._v }, { $set: { status: 'done' }, $unset: { duration: true } })
+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)
 
+// A string is an _id (POST /{_id}/update). The same guard rules apply.
+await calls.update('c1', { $inc: { duration: 1 } })
+
 // A guarded decrement: exactly one of two racing calls wins.
-await stock.update({ sku: 'a', qty: { $gte: 1 } }, { $inc: { qty: -1 } })
+await stock.update({ _id: 'a', qty: { $gte: 1 } }, { $inc: { qty: -1 } })
 
-// Every match (the filter needs the id or an indexed field), or create it.
+// 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({ call_id: 'c9' }, { $inc: { duration: 1 } }, { upsert: true })
+await calls.update('c9', { $inc: { duration: 1 } }, { upsert: true })
 
-// Delete by filter: { deleted }.
-await calls.delete({ call_id: 'c2' })
+// Delete by _id or by filter: { deleted }.
+await calls.delete('c2')
 await calls.delete({ status: 'failed' }, { many: true })
 ```
 
-- Operators: `$set`, `$unset`, `$inc`, `$push` (with `{ $each: [...] }`), `$pull`, `$min`, `$max`. Field names can be dot paths.
+- 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 the id or an indexed field in the filter. `upsert` creates the document from the equality fields of the filter.
+- `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 insert without the id when the schema names one fails with code `missing_id`.
+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({ sid: 's1' }, { $set: { 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))
@@ -142,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)
 ```
@@ -168,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`.
@@ -180,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)
 }
 ```
 
@@ -236,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)
@@ -280,7 +280,7 @@ Daemon errors are `NdbError` or a subclass. They have `code` (the daemon code) a
 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

@@ -35,7 +35,8 @@ __export(index_exports, {
   UniqueViolationError: () => UniqueViolationError,
   WatchLaggedError: () => WatchLaggedError,
   connect: () => connect,
-  makeError: () => makeError
+  makeError: () => makeError,
+  newId: () => newId
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -255,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 };
   }
 }
 
@@ -270,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;
@@ -296,47 +294,55 @@ var Model = class {
   create(docs, opts = {}) {
     return this.insert(docs, opts);
   }
-  // Atomic update by filter. The filter and the operators are sent as one
-  // body; the daemon matches and writes in one step on the newest state, so
+  // 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:
-  // { call_id: 'c1', _v: 7 }. Matching nothing is not an error: matched is 0.
-  async update(filter, ops, opts = {}) {
+  // { _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 body = mergeUpdate(filter, ops);
-    const query = writeQuery({ many: opts.many, upsert: opts.upsert, expire_in: opts.expireIn });
+    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("update") + query,
+      this.path(op) + query,
       body
     );
     return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
   }
-  // Deletes the documents that the filter matches: one, or every match with
-  // many (same rule as update).
-  async delete(filter, 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();
+    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) {
-    return this.setExpiry({ id, in: duration });
+    return this.setExpiry({ _id: id, in: duration });
   }
   expireAt(id, at) {
-    return this.setExpiry({ id, at: at.toISOString() });
+    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) {
@@ -348,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);
@@ -428,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),
@@ -653,6 +668,38 @@ 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,
@@ -670,5 +717,6 @@ function connect(addr, opts) {
   UniqueViolationError,
   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,12 +60,14 @@ 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;
 }
 type Duration = number | string;
@@ -75,6 +79,7 @@ type Filter<F extends Fields> = Where<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>;
@@ -125,7 +130,7 @@ interface WatchEvent<R> {
     consumer: string;
     pos: string;
     op: 'put' | 'del';
-    id: string;
+    _id: string;
     v: number;
     doc: R | undefined;
 }
@@ -169,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(filter: Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
-    delete(filter: Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    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>;
@@ -239,6 +243,8 @@ declare class Ndb {
 }
 declare function connect(addr?: string, opts?: ConnectOptions): Ndb;
 
+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;
@@ -267,5 +273,5 @@ declare class TtlError extends NdbError {
 }
 declare function makeError(code: ErrorCode, message: string, status?: number): NdbError;
 
-export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, InvalidUpdateError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, WatchLaggedError, connect, makeError };
+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,12 +60,14 @@ 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;
 }
 type Duration = number | string;
@@ -75,6 +79,7 @@ type Filter<F extends Fields> = Where<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>;
@@ -125,7 +130,7 @@ interface WatchEvent<R> {
     consumer: string;
     pos: string;
     op: 'put' | 'del';
-    id: string;
+    _id: string;
     v: number;
     doc: R | undefined;
 }
@@ -169,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(filter: Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
-    delete(filter: Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    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>;
@@ -239,6 +243,8 @@ declare class Ndb {
 }
 declare function connect(addr?: string, opts?: ConnectOptions): Ndb;
 
+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;
@@ -267,5 +273,5 @@ declare class TtlError extends NdbError {
 }
 declare function makeError(code: ErrorCode, message: string, status?: number): NdbError;
 
-export { CursorError, DuplicateIdError, HistoryTruncatedError, InvalidQueryError, InvalidUpdateError, Model, Ndb, NdbError, NotFoundError, Query, TtlError, UnauthorizedError, UniqueViolationError, WatchLaggedError, connect, makeError };
+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

@@ -214,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 };
   }
 }
 
@@ -229,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;
@@ -255,47 +252,55 @@ var Model = class {
   create(docs, opts = {}) {
     return this.insert(docs, opts);
   }
-  // Atomic update by filter. The filter and the operators are sent as one
-  // body; the daemon matches and writes in one step on the newest state, so
+  // 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:
-  // { call_id: 'c1', _v: 7 }. Matching nothing is not an error: matched is 0.
-  async update(filter, ops, opts = {}) {
+  // { _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 body = mergeUpdate(filter, ops);
-    const query = writeQuery({ many: opts.many, upsert: opts.upsert, expire_in: opts.expireIn });
+    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("update") + query,
+      this.path(op) + query,
       body
     );
     return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
   }
-  // Deletes the documents that the filter matches: one, or every match with
-  // many (same rule as update).
-  async delete(filter, 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();
+    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) {
-    return this.setExpiry({ id, in: duration });
+    return this.setExpiry({ _id: id, in: duration });
   }
   expireAt(id, at) {
-    return this.setExpiry({ id, at: at.toISOString() });
+    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) {
@@ -307,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);
@@ -387,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),
@@ -612,6 +626,38 @@ 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,
@@ -628,5 +674,6 @@ export {
   UniqueViolationError,
   WatchLaggedError,
   connect,
-  makeError
+  makeError,
+  newId
 };

package/package.json

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