@thadeu/ndb 0.1.0 → 0.1.1

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
 
@@ -111,6 +112,28 @@ try {
 
 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
+const sessions = db.model('sessions', {
+  id: 'sid',
+  expires: 'exp',
+  fields: { sid: { type: 'string' }, 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' })
+
+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
+```
+
+- 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
 
 A query is lazy and immutable. It is also thenable: `await` runs it.
@@ -252,6 +275,7 @@ Daemon errors are `NdbError` or a subclass. They have `code` (the daemon code) a
 | `CursorError` | `cursor_invalid`, `cursor_mismatch`, `cursor_expired` |
 | `WatchLaggedError` | `watch_lagged` |
 | `HistoryTruncatedError` | `history_truncated` |
+| `TtlError` | `ttl_not_enabled`, `ttl_derived` |
 | `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

@@ -29,6 +29,7 @@ __export(index_exports, {
   NdbError: () => NdbError,
   NotFoundError: () => NotFoundError,
   Query: () => Query,
+  TtlError: () => TtlError,
   UnauthorizedError: () => UnauthorizedError,
   UniqueViolationError: () => UniqueViolationError,
   VersionConflictError: () => VersionConflictError,
@@ -67,6 +68,8 @@ var WatchLaggedError = class extends NdbError {
 };
 var HistoryTruncatedError = class extends NdbError {
 };
+var TtlError = class extends NdbError {
+};
 var subclasses = {
   unauthorized: UnauthorizedError,
   not_found: NotFoundError,
@@ -80,7 +83,9 @@ var subclasses = {
   cursor_mismatch: CursorError,
   cursor_expired: CursorError,
   watch_lagged: WatchLaggedError,
-  history_truncated: HistoryTruncatedError
+  history_truncated: HistoryTruncatedError,
+  ttl_not_enabled: TtlError,
+  ttl_derived: TtlError
 };
 function makeError(code, message, status = 0) {
   const Cls = subclasses[code] ?? NdbError;
@@ -274,26 +279,60 @@ 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);
   }
   async update(id, set, opts = {}) {
     await this.ready();
-    const update = { id, set, unset: opts.unset, if_version: opts.ifVersion };
+    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 });
   }
   async delete(id, opts = {}) {
     await this.ready();
     await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
   }
+  // 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 });
+  }
+  expireAt(id, at, opts = {}) {
+    return this.setExpiry({ id, at: at.toISOString(), if_version: opts.ifVersion });
+  }
+  // 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 });
+  }
+  // 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,6 +413,7 @@ 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)
     };
@@ -589,6 +629,7 @@ function connect(addr, opts) {
   NdbError,
   NotFoundError,
   Query,
+  TtlError,
   UnauthorizedError,
   UniqueViolationError,
   VersionConflictError,

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']];
@@ -68,8 +69,16 @@ interface WriteResult {
 interface WriteOptions {
     ifVersion?: number;
 }
+type Duration = number | string;
 interface UpdateOptions extends WriteOptions {
     unset?: string[];
+    expireIn?: Duration;
+}
+interface InsertOptions {
+    expireIn?: Duration;
+}
+interface ExpireResult extends WriteResult {
+    expiresAt: Date;
 }
 interface AggregateOptions {
     limit?: number;
@@ -139,10 +148,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[]>;
+    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>;
+    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 +215,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' | '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 class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -225,7 +239,9 @@ declare class WatchLaggedError extends NdbError {
 }
 declare class HistoryTruncatedError 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, 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 };

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']];
@@ -68,8 +69,16 @@ interface WriteResult {
 interface WriteOptions {
     ifVersion?: number;
 }
+type Duration = number | string;
 interface UpdateOptions extends WriteOptions {
     unset?: string[];
+    expireIn?: Duration;
+}
+interface InsertOptions {
+    expireIn?: Duration;
+}
+interface ExpireResult extends WriteResult {
+    expiresAt: Date;
 }
 interface AggregateOptions {
     limit?: number;
@@ -139,10 +148,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[]>;
+    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>;
+    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 +215,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' | '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 class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -225,7 +239,9 @@ declare class WatchLaggedError extends NdbError {
 }
 declare class HistoryTruncatedError 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, 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 };

package/dist/index.js

@@ -27,6 +27,8 @@ var WatchLaggedError = class extends NdbError {
 };
 var HistoryTruncatedError = class extends NdbError {
 };
+var TtlError = class extends NdbError {
+};
 var subclasses = {
   unauthorized: UnauthorizedError,
   not_found: NotFoundError,
@@ -40,7 +42,9 @@ var subclasses = {
   cursor_mismatch: CursorError,
   cursor_expired: CursorError,
   watch_lagged: WatchLaggedError,
-  history_truncated: HistoryTruncatedError
+  history_truncated: HistoryTruncatedError,
+  ttl_not_enabled: TtlError,
+  ttl_derived: TtlError
 };
 function makeError(code, message, status = 0) {
   const Cls = subclasses[code] ?? NdbError;
@@ -234,26 +238,60 @@ 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);
   }
   async update(id, set, opts = {}) {
     await this.ready();
-    const update = { id, set, unset: opts.unset, if_version: opts.ifVersion };
+    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 });
   }
   async delete(id, opts = {}) {
     await this.ready();
     await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
   }
+  // 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 });
+  }
+  expireAt(id, at, opts = {}) {
+    return this.setExpiry({ id, at: at.toISOString(), if_version: opts.ifVersion });
+  }
+  // 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 });
+  }
+  // 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,6 +372,7 @@ 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)
     };
@@ -548,6 +587,7 @@ export {
   NdbError,
   NotFoundError,
   Query,
+  TtlError,
   UnauthorizedError,
   UniqueViolationError,
   VersionConflictError,

package/package.json

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