@thadeu/ndb 0.1.0 → 0.1.2

package/README.md

@@ -70,7 +70,8 @@ const calls = ndb.model('calls', {
 - `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.
-- The client has no `expires` or `ttl` option and no blob API. Use the HTTP API for those.
+- `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.
 
 ## Insert, find, update, delete
 
@@ -85,31 +86,51 @@ const results = await calls.insert([
 // Find by id. Returns null when missing.
 const row = await calls.find('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({ call_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 guarded decrement: exactly one of two racing calls wins.
+await stock.update({ sku: 'a', qty: { $gte: 1 } }, { $inc: { qty: -1 } })
 
-// Delete. ifVersion is optional here too.
-await calls.delete('c1', { ifVersion: 3 })
+// Every match (the filter needs the 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 })
+
+// Delete by filter: { deleted }.
+await calls.delete({ call_id: 'c2' })
+await calls.delete({ status: 'failed' }, { many: true })
 ```
 
-`update` returns `{ id, v }` with the new version. A stale `ifVersion` throws `VersionConflictError`:
+- Operators: `$set`, `$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.
+- 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`.
+
+### Expiry (TTL like Redis)
 
 ```ts
-import { VersionConflictError } from '@thadeu/ndb'
+const sessions = db.model('sessions', {
+  id: 'sid',
+  expires: 'exp',
+  fields: { sid: { type: 'string' }, exp: { type: 'date', optional: 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.
-  }
-}
+await sessions.insert({ sid: 's1' }, { expireIn: '1h' }) // or 3600; all docs of the call
+await sessions.update({ sid: '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))
+await sessions.ttl('s1') // seconds left, -1 = never expires, null = missing or expired
+await sessions.persist('s1') // PERSIST
 ```
 
-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`.
+- A duration is seconds or a string such as `"90m"`, `"1h30m"`, `"1d"`. `expireIn` wins over a value of the `expires` field in the same call.
+- `expire` and `persist` throw `NotFoundError` for a missing or expired document. `TtlError` (`ttl_not_enabled`, `ttl_derived`) means the schema has no `expires` field, or the expiry comes from `ttl` + `time`.
+- Disk space of expired documents returns after compaction, and fully only with `wal_retention`; see [Freeing disk](https://github.com/thadeu/ndb/blob/main/docs/dev/configuration.md#freeing-disk).
 
 ## Query
 
@@ -245,13 +266,14 @@ 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` |
 | `CursorError` | `cursor_invalid`, `cursor_mismatch`, `cursor_expired` |
 | `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

package/dist/index.cjs

@@ -24,14 +24,15 @@ __export(index_exports, {
   DuplicateIdError: () => DuplicateIdError,
   HistoryTruncatedError: () => HistoryTruncatedError,
   InvalidQueryError: () => InvalidQueryError,
+  InvalidUpdateError: () => InvalidUpdateError,
   Model: () => Model,
   Ndb: () => Ndb,
   NdbError: () => NdbError,
   NotFoundError: () => NotFoundError,
   Query: () => Query,
+  TtlError: () => TtlError,
   UnauthorizedError: () => UnauthorizedError,
   UniqueViolationError: () => UniqueViolationError,
-  VersionConflictError: () => VersionConflictError,
   WatchLaggedError: () => WatchLaggedError,
   connect: () => connect,
   makeError: () => makeError
@@ -53,8 +54,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 {
@@ -67,11 +66,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,
@@ -80,7 +82,15 @@ var subclasses = {
   cursor_mismatch: CursorError,
   cursor_expired: CursorError,
   watch_lagged: WatchLaggedError,
-  history_truncated: HistoryTruncatedError
+  history_truncated: HistoryTruncatedError,
+  ttl_not_enabled: 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;
@@ -274,25 +284,71 @@ var Model = class {
     });
     return this.ensured;
   }
-  async insert(docs) {
+  async insert(docs, opts = {}) {
     await this.ready();
     const list = Array.isArray(docs) ? docs : [docs];
     const out = await this.db.transport.request("POST", this.path("insert"), {
-      insert: list
+      insert: list,
+      expire_in: opts.expireIn
     });
     return out.results;
   }
-  create(docs) {
-    return this.insert(docs);
+  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
+  // 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 = {}) {
+    await this.ready();
+    const body = mergeUpdate(filter, ops);
+    const query = writeQuery({ many: opts.many, upsert: opts.upsert, expire_in: opts.expireIn });
+    const out = await this.db.transport.request(
+      "POST",
+      this.path("update") + query,
+      body
+    );
+    return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
   }
-  async update(id, set, opts = {}) {
+  // Deletes the documents that the filter matches: one, or every match with
+  // many (same rule as update).
+  async delete(filter, opts = {}) {
     await this.ready();
-    const update = { id, set, unset: opts.unset, if_version: opts.ifVersion };
-    return this.db.transport.request("POST", this.path("update"), { update });
+    return this.db.transport.request("POST", this.path("delete") + writeQuery({ many: opts.many }), toWhere(filter));
   }
-  async delete(id, opts = {}) {
+  // 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 });
+  }
+  expireAt(id, at) {
+    return this.setExpiry({ id, at: at.toISOString() });
+  }
+  // Removes the expiry of a document (PERSIST in Redis).
+  async persist(id) {
     await this.ready();
-    await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
+    return this.db.transport.request("POST", this.path("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("ttl")}/${encodeURIComponent(id)}`);
+      return out.ttl;
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  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) };
   }
   find(id) {
     return this.query().where({ [this.idField]: id }).first();
@@ -374,11 +430,30 @@ var Model = class {
     return {
       id: this.schema.id,
       time: this.schema.time,
+      expires_field: this.schema.expires,
       indexes: entries.filter(([, d]) => d.index).map(([n]) => n),
       unique: entries.filter(([, d]) => d.unique).map(([n]) => n)
     };
   }
 };
+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");
@@ -584,14 +659,15 @@ function connect(addr, opts) {
   DuplicateIdError,
   HistoryTruncatedError,
   InvalidQueryError,
+  InvalidUpdateError,
   Model,
   Ndb,
   NdbError,
   NotFoundError,
   Query,
+  TtlError,
   UnauthorizedError,
   UniqueViolationError,
-  VersionConflictError,
   WatchLaggedError,
   connect,
   makeError

package/dist/index.d.cts

@@ -18,6 +18,7 @@ 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;
 }
 type ValueOf<D extends FieldDef> = TypeMap[D['type']];
@@ -65,11 +66,43 @@ interface WriteResult {
     id: string;
     v: number;
 }
-interface WriteOptions {
-    ifVersion?: number;
+type Duration = number | 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>;
+    $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 UpdateOptions extends WriteOptions {
-    unset?: string[];
+interface InsertOptions {
+    expireIn?: Duration;
+}
+interface ExpireResult extends WriteResult {
+    expiresAt: Date;
 }
 interface AggregateOptions {
     limit?: number;
@@ -139,10 +172,15 @@ declare class Model<F extends Fields> {
     get idField(): string;
     path(op?: string): string;
     ready(): Promise<void>;
-    insert(docs: Input<F> | Input<F>[]): Promise<WriteResult[]>;
-    create(docs: Input<F> | Input<F>[]): Promise<WriteResult[]>;
-    update(id: string, set: Input<F>, opts?: UpdateOptions): Promise<WriteResult>;
-    delete(id: string, opts?: WriteOptions): 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>;
+    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>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
@@ -201,7 +239,7 @@ 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' | 'http_status' | (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;
@@ -211,8 +249,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 {
@@ -225,7 +261,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, UnauthorizedError, UniqueViolationError, VersionConflictError, WatchLaggedError, connect, makeError };
-export type { AggregateOptions, AggregateResult, ConnectOptions, Doc, ErrorCode, FieldDef, FieldType, Fields, Input, 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 };
+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

@@ -18,6 +18,7 @@ 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;
 }
 type ValueOf<D extends FieldDef> = TypeMap[D['type']];
@@ -65,11 +66,43 @@ interface WriteResult {
     id: string;
     v: number;
 }
-interface WriteOptions {
-    ifVersion?: number;
+type Duration = number | 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>;
+    $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 UpdateOptions extends WriteOptions {
-    unset?: string[];
+interface InsertOptions {
+    expireIn?: Duration;
+}
+interface ExpireResult extends WriteResult {
+    expiresAt: Date;
 }
 interface AggregateOptions {
     limit?: number;
@@ -139,10 +172,15 @@ declare class Model<F extends Fields> {
     get idField(): string;
     path(op?: string): string;
     ready(): Promise<void>;
-    insert(docs: Input<F> | Input<F>[]): Promise<WriteResult[]>;
-    create(docs: Input<F> | Input<F>[]): Promise<WriteResult[]>;
-    update(id: string, set: Input<F>, opts?: UpdateOptions): Promise<WriteResult>;
-    delete(id: string, opts?: WriteOptions): 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>;
+    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>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
@@ -201,7 +239,7 @@ 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' | 'http_status' | (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;
@@ -211,8 +249,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 {
@@ -225,7 +261,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, UnauthorizedError, UniqueViolationError, VersionConflictError, WatchLaggedError, connect, makeError };
-export type { AggregateOptions, AggregateResult, ConnectOptions, Doc, ErrorCode, FieldDef, FieldType, Fields, Input, 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 };
+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,11 +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,
@@ -40,7 +41,15 @@ var subclasses = {
   cursor_mismatch: CursorError,
   cursor_expired: CursorError,
   watch_lagged: WatchLaggedError,
-  history_truncated: HistoryTruncatedError
+  history_truncated: HistoryTruncatedError,
+  ttl_not_enabled: 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;
@@ -234,25 +243,71 @@ var Model = class {
     });
     return this.ensured;
   }
-  async insert(docs) {
+  async insert(docs, opts = {}) {
     await this.ready();
     const list = Array.isArray(docs) ? docs : [docs];
     const out = await this.db.transport.request("POST", this.path("insert"), {
-      insert: list
+      insert: list,
+      expire_in: opts.expireIn
     });
     return out.results;
   }
-  create(docs) {
-    return this.insert(docs);
+  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
+  // 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 = {}) {
+    await this.ready();
+    const body = mergeUpdate(filter, ops);
+    const query = writeQuery({ many: opts.many, upsert: opts.upsert, expire_in: opts.expireIn });
+    const out = await this.db.transport.request(
+      "POST",
+      this.path("update") + query,
+      body
+    );
+    return { matched: out.matched, modified: out.modified, doc: out.doc && this.decode(out.doc) };
   }
-  async update(id, set, opts = {}) {
+  // Deletes the documents that the filter matches: one, or every match with
+  // many (same rule as update).
+  async delete(filter, opts = {}) {
     await this.ready();
-    const update = { id, set, unset: opts.unset, if_version: opts.ifVersion };
-    return this.db.transport.request("POST", this.path("update"), { update });
+    return this.db.transport.request("POST", this.path("delete") + writeQuery({ many: opts.many }), toWhere(filter));
   }
-  async delete(id, opts = {}) {
+  // 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 });
+  }
+  expireAt(id, at) {
+    return this.setExpiry({ id, at: at.toISOString() });
+  }
+  // Removes the expiry of a document (PERSIST in Redis).
+  async persist(id) {
     await this.ready();
-    await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
+    return this.db.transport.request("POST", this.path("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("ttl")}/${encodeURIComponent(id)}`);
+      return out.ttl;
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  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) };
   }
   find(id) {
     return this.query().where({ [this.idField]: id }).first();
@@ -334,11 +389,30 @@ var Model = class {
     return {
       id: this.schema.id,
       time: this.schema.time,
+      expires_field: this.schema.expires,
       indexes: entries.filter(([, d]) => d.index).map(([n]) => n),
       unique: entries.filter(([, d]) => d.unique).map(([n]) => n)
     };
   }
 };
+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";
@@ -543,14 +617,15 @@ export {
   DuplicateIdError,
   HistoryTruncatedError,
   InvalidQueryError,
+  InvalidUpdateError,
   Model,
   Ndb,
   NdbError,
   NotFoundError,
   Query,
+  TtlError,
   UnauthorizedError,
   UniqueViolationError,
-  VersionConflictError,
   WatchLaggedError,
   connect,
   makeError

package/package.json

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