@thadeu/ndb 0.3.2 → 0.4.0

package/README.md

@@ -111,6 +111,16 @@ await calls.delete({ status: 'failed' }, { many: true })
 
 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`.
 
+### Truncate and drop
+
+```ts
+await calls.truncate() // every document goes; the definition and indexes stay
+await calls.drop()     // the collection, its definition and its watch consumers go
+```
+
+- Both take the same time for 10 or 10 million documents. Watch consumers get one event with `op: 'truncate'` (`_id` is `''`), then the new changes.
+- After `drop()`, the next call on the model declares the collection again. A collection declared in `ndb.yml` comes back, empty, when the daemon restarts.
+
 ### Expiry (TTL like Redis)
 
 ```ts
@@ -236,7 +246,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' | 'truncate', _id, v, doc }
     await handle(ev)
 
     await calls.ack(ev)

package/dist/index.cjs

@@ -160,6 +160,12 @@ var Query = class _Query {
   where(w) {
     return this.with({ clauses: [...this.state.clauses, toWhere(w)] });
   }
+  // A where object built elsewhere, such as from a search form. It is not
+  // type-checked and is sent as is; the daemon validates it. It is ANDed
+  // with the other clauses.
+  whereRaw(w) {
+    return this.with({ clauses: [...this.state.clauses, w] });
+  }
   not(w) {
     return this.with({ clauses: [...this.state.clauses, { $not: toWhere(w) }] });
   }
@@ -256,7 +262,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 };
   }
 }
 
@@ -275,7 +281,13 @@ var Model = class {
     const base = `/v1/c/${encodeURIComponent(this.name)}`;
     return op ? `${base}/${op}` : base;
   }
+  // A collection pattern ("logs-2026-*") reads many collections and declares
+  // none: its writes fail with pattern_read_only.
+  get isPattern() {
+    return this.name.includes("*");
+  }
   ready() {
+    if (this.isPattern) return Promise.resolve();
     this.ensured ??= this.db.transport.request("PUT", this.path(), this.catalog()).catch((err) => {
       this.ensured = void 0;
       throw err;
@@ -323,6 +335,22 @@ var Model = class {
     const filter = idOrFilter;
     return this.db.transport.request("POST", this.path("delete") + writeQuery({ many: opts.many }), toWhere(filter));
   }
+  // Removes every document of the collection and keeps its definition and
+  // indexes. The cost does not depend on the number of documents. Watch
+  // consumers get one event with op "truncate".
+  async truncate() {
+    await this.ready();
+    await this.db.transport.request("POST", this.path("truncate") + this.confirm());
+  }
+  // Removes the collection: its documents, its definition and the positions
+  // of its watch consumers. The next call on the model declares it again.
+  async drop() {
+    await this.db.transport.request("DELETE", this.path() + this.confirm());
+    this.ensured = void 0;
+  }
+  confirm() {
+    return `?confirm=${encodeURIComponent(this.name)}`;
+  }
   // 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.
@@ -375,6 +403,9 @@ var Model = class {
   where(w) {
     return this.query().where(w);
   }
+  whereRaw(w) {
+    return this.query().whereRaw(w);
+  }
   not(w) {
     return this.query().not(w);
   }
@@ -411,6 +442,18 @@ var Model = class {
   iterate() {
     return this.query().iterate();
   }
+  // Runs a find with a whole body built elsewhere, such as from a search
+  // form: { where, sort, limit, after, count }. The body is sent as is (the
+  // daemon validates it); rows are decoded like the rows of where().
+  async find(body) {
+    await this.ready();
+    const res = await this.db.transport.stream("POST", this.path("find"), { ...body, versions: true });
+    const rows = [];
+    for await (const raw of res.rows()) {
+      rows.push(this.decode(raw));
+    }
+    return { rows, next: res.header("x-ndb-next") ?? "", total: Number(res.header("x-ndb-total") ?? 0) };
+  }
   async aggregate(pipeline, opts = {}) {
     await this.ready();
     const res = await this.db.transport.stream("POST", this.path("aggregate"), { pipeline, ...opts });

package/dist/index.d.cts

@@ -39,6 +39,7 @@ type Input<F extends Fields> = {
 type Row<F extends Fields> = Doc<F> & {
     _id: string;
     _v: number;
+    _coll?: string;
 };
 interface Ops<V> {
     $eq?: V;
@@ -52,6 +53,7 @@ interface Ops<V> {
     $exists?: boolean;
     $regex?: string | RegExp;
     $options?: string;
+    $elemMatch?: Record<string, unknown>;
 }
 type Operand<V> = V extends Date ? Date | string : V;
 type RegexOperand<V> = V extends string ? RegExp : never;
@@ -115,6 +117,20 @@ interface AggregateOptions {
     after?: string;
     count?: boolean;
 }
+interface FindBody {
+    where?: Record<string, unknown>;
+    fields?: string[];
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    after?: string;
+    count?: boolean;
+}
+interface FindResult<R> {
+    rows: R[];
+    next: string;
+    total: number;
+}
 interface AggregateResult<R = Record<string, unknown>> {
     rows: R[];
     next: string;
@@ -129,7 +145,7 @@ interface WatchOptions<F extends Fields = Fields> {
 interface WatchEvent<R> {
     consumer: string;
     pos: string;
-    op: 'put' | 'del';
+    op: 'put' | 'del' | 'truncate';
     _id: string;
     v: number;
     doc: R | undefined;
@@ -149,6 +165,7 @@ declare class Query<F extends Fields, R = Row<F>> implements PromiseLike<R[]> {
     nextCursor: string;
     constructor(model: Model<F>, state?: State);
     where(w: Where<F>): Query<F, R>;
+    whereRaw(w: Record<string, unknown>): Query<F, R>;
     not(w: Where<F>): Query<F, R>;
     or(...ws: Where<F>[]): Query<F, R>;
     sort(spec: SortSpec<F>): Query<F, R>;
@@ -175,11 +192,15 @@ declare class Model<F extends Fields> {
     private ensured?;
     constructor(db: Ndb, name: string, schema: Schema<F>);
     path(op?: string): string;
+    get isPattern(): boolean;
     ready(): Promise<void>;
     insert(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     create(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     update(idOrFilter: string | Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
     delete(idOrFilter: string | Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    truncate(): Promise<void>;
+    drop(): Promise<void>;
+    private confirm;
     expire(id: string, duration: Duration): Promise<ExpireResult>;
     expireAt(id: string, at: Date): Promise<ExpireResult>;
     persist(id: string): Promise<WriteResult>;
@@ -188,6 +209,7 @@ declare class Model<F extends Fields> {
     get(id: string): Promise<Row<F> | null>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
+    whereRaw(w: Record<string, unknown>): Query<F>;
     not(w: Where<F>): Query<F>;
     or(...ws: Where<F>[]): Query<F>;
     sort(spec: SortSpec<F>): Query<F>;
@@ -200,6 +222,7 @@ declare class Model<F extends Fields> {
     count(): Promise<number>;
     first(): Promise<Row<F> | null>;
     iterate(): AsyncGenerator<Row<F>>;
+    find(body: FindBody): Promise<FindResult<Row<F>>>;
     aggregate<R = Record<string, unknown>>(pipeline: Record<string, unknown>[], opts?: AggregateOptions): Promise<AggregateResult<R>>;
     watch(consumer: string, opts?: WatchOptions<F>): AsyncGenerator<WatchEvent<Row<F>>>;
     ack(event: Pick<WatchEvent<unknown>, 'consumer' | 'pos'>): Promise<void>;
@@ -245,7 +268,7 @@ 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 & {});
+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' | 'confirm_required' | 'invalid_update' | 'http_status' | (string & {});
 declare class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -274,4 +297,4 @@ 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, 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 };
+export type { AggregateOptions, AggregateResult, ConnectOptions, DeleteOptions, DeleteResult, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Filter, FindBody, FindResult, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOps, UpdateOptions, UpdateResult, WatchEvent, WatchOptions, Where, WriteResult };

package/dist/index.d.ts

@@ -39,6 +39,7 @@ type Input<F extends Fields> = {
 type Row<F extends Fields> = Doc<F> & {
     _id: string;
     _v: number;
+    _coll?: string;
 };
 interface Ops<V> {
     $eq?: V;
@@ -52,6 +53,7 @@ interface Ops<V> {
     $exists?: boolean;
     $regex?: string | RegExp;
     $options?: string;
+    $elemMatch?: Record<string, unknown>;
 }
 type Operand<V> = V extends Date ? Date | string : V;
 type RegexOperand<V> = V extends string ? RegExp : never;
@@ -115,6 +117,20 @@ interface AggregateOptions {
     after?: string;
     count?: boolean;
 }
+interface FindBody {
+    where?: Record<string, unknown>;
+    fields?: string[];
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    after?: string;
+    count?: boolean;
+}
+interface FindResult<R> {
+    rows: R[];
+    next: string;
+    total: number;
+}
 interface AggregateResult<R = Record<string, unknown>> {
     rows: R[];
     next: string;
@@ -129,7 +145,7 @@ interface WatchOptions<F extends Fields = Fields> {
 interface WatchEvent<R> {
     consumer: string;
     pos: string;
-    op: 'put' | 'del';
+    op: 'put' | 'del' | 'truncate';
     _id: string;
     v: number;
     doc: R | undefined;
@@ -149,6 +165,7 @@ declare class Query<F extends Fields, R = Row<F>> implements PromiseLike<R[]> {
     nextCursor: string;
     constructor(model: Model<F>, state?: State);
     where(w: Where<F>): Query<F, R>;
+    whereRaw(w: Record<string, unknown>): Query<F, R>;
     not(w: Where<F>): Query<F, R>;
     or(...ws: Where<F>[]): Query<F, R>;
     sort(spec: SortSpec<F>): Query<F, R>;
@@ -175,11 +192,15 @@ declare class Model<F extends Fields> {
     private ensured?;
     constructor(db: Ndb, name: string, schema: Schema<F>);
     path(op?: string): string;
+    get isPattern(): boolean;
     ready(): Promise<void>;
     insert(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     create(docs: Input<F> | Input<F>[], opts?: InsertOptions): Promise<WriteResult[]>;
     update(idOrFilter: string | Filter<F>, ops: UpdateOps<F>, opts?: UpdateOptions): Promise<UpdateResult<F>>;
     delete(idOrFilter: string | Filter<F>, opts?: DeleteOptions): Promise<DeleteResult>;
+    truncate(): Promise<void>;
+    drop(): Promise<void>;
+    private confirm;
     expire(id: string, duration: Duration): Promise<ExpireResult>;
     expireAt(id: string, at: Date): Promise<ExpireResult>;
     persist(id: string): Promise<WriteResult>;
@@ -188,6 +209,7 @@ declare class Model<F extends Fields> {
     get(id: string): Promise<Row<F> | null>;
     query(): Query<F>;
     where(w: Where<F>): Query<F>;
+    whereRaw(w: Record<string, unknown>): Query<F>;
     not(w: Where<F>): Query<F>;
     or(...ws: Where<F>[]): Query<F>;
     sort(spec: SortSpec<F>): Query<F>;
@@ -200,6 +222,7 @@ declare class Model<F extends Fields> {
     count(): Promise<number>;
     first(): Promise<Row<F> | null>;
     iterate(): AsyncGenerator<Row<F>>;
+    find(body: FindBody): Promise<FindResult<Row<F>>>;
     aggregate<R = Record<string, unknown>>(pipeline: Record<string, unknown>[], opts?: AggregateOptions): Promise<AggregateResult<R>>;
     watch(consumer: string, opts?: WatchOptions<F>): AsyncGenerator<WatchEvent<Row<F>>>;
     ack(event: Pick<WatchEvent<unknown>, 'consumer' | 'pos'>): Promise<void>;
@@ -245,7 +268,7 @@ 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 & {});
+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' | 'confirm_required' | 'invalid_update' | 'http_status' | (string & {});
 declare class NdbError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -274,4 +297,4 @@ 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, 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 };
+export type { AggregateOptions, AggregateResult, ConnectOptions, DeleteOptions, DeleteResult, Doc, Duration, ErrorCode, ExpireResult, FieldDef, FieldType, Fields, Filter, FindBody, FindResult, Input, InsertOptions, Ops, Row, Schema, SortSpec, TypeMap, UpdateOps, UpdateOptions, UpdateResult, WatchEvent, WatchOptions, Where, WriteResult };

package/dist/index.js

@@ -118,6 +118,12 @@ var Query = class _Query {
   where(w) {
     return this.with({ clauses: [...this.state.clauses, toWhere(w)] });
   }
+  // A where object built elsewhere, such as from a search form. It is not
+  // type-checked and is sent as is; the daemon validates it. It is ANDed
+  // with the other clauses.
+  whereRaw(w) {
+    return this.with({ clauses: [...this.state.clauses, w] });
+  }
   not(w) {
     return this.with({ clauses: [...this.state.clauses, { $not: toWhere(w) }] });
   }
@@ -214,7 +220,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 };
   }
 }
 
@@ -233,7 +239,13 @@ var Model = class {
     const base = `/v1/c/${encodeURIComponent(this.name)}`;
     return op ? `${base}/${op}` : base;
   }
+  // A collection pattern ("logs-2026-*") reads many collections and declares
+  // none: its writes fail with pattern_read_only.
+  get isPattern() {
+    return this.name.includes("*");
+  }
   ready() {
+    if (this.isPattern) return Promise.resolve();
     this.ensured ??= this.db.transport.request("PUT", this.path(), this.catalog()).catch((err) => {
       this.ensured = void 0;
       throw err;
@@ -281,6 +293,22 @@ var Model = class {
     const filter = idOrFilter;
     return this.db.transport.request("POST", this.path("delete") + writeQuery({ many: opts.many }), toWhere(filter));
   }
+  // Removes every document of the collection and keeps its definition and
+  // indexes. The cost does not depend on the number of documents. Watch
+  // consumers get one event with op "truncate".
+  async truncate() {
+    await this.ready();
+    await this.db.transport.request("POST", this.path("truncate") + this.confirm());
+  }
+  // Removes the collection: its documents, its definition and the positions
+  // of its watch consumers. The next call on the model declares it again.
+  async drop() {
+    await this.db.transport.request("DELETE", this.path() + this.confirm());
+    this.ensured = void 0;
+  }
+  confirm() {
+    return `?confirm=${encodeURIComponent(this.name)}`;
+  }
   // 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.
@@ -333,6 +361,9 @@ var Model = class {
   where(w) {
     return this.query().where(w);
   }
+  whereRaw(w) {
+    return this.query().whereRaw(w);
+  }
   not(w) {
     return this.query().not(w);
   }
@@ -369,6 +400,18 @@ var Model = class {
   iterate() {
     return this.query().iterate();
   }
+  // Runs a find with a whole body built elsewhere, such as from a search
+  // form: { where, sort, limit, after, count }. The body is sent as is (the
+  // daemon validates it); rows are decoded like the rows of where().
+  async find(body) {
+    await this.ready();
+    const res = await this.db.transport.stream("POST", this.path("find"), { ...body, versions: true });
+    const rows = [];
+    for await (const raw of res.rows()) {
+      rows.push(this.decode(raw));
+    }
+    return { rows, next: res.header("x-ndb-next") ?? "", total: Number(res.header("x-ndb-total") ?? 0) };
+  }
   async aggregate(pipeline, opts = {}) {
     await this.ready();
     const res = await this.db.transport.stream("POST", this.path("aggregate"), { pipeline, ...opts });

package/package.json

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