@loams/client 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 # The TypeScript SDK (`@loams/client`)
 
-> **Preview.** `0.1.0` tracks the Loams preview server and may change between previews; pin an exact version. Installed with `npm install @loams/client@preview`.
+> **Preview.** `0.1.1` tracks the Loams preview server and may change between previews; pin an exact version. Installed with `npm install @loams/client@preview`.
 
 Design §44 §7 and §10.2: the SDK is a `Loams` object with namespaced modules,
 generated from the `loams.options.v1` annotations on the protos, over the
@@ -29,7 +29,7 @@ generator inputs stay outside the workspace, next to `proto/`.
 npm i @loams/client        # and @loams/live for Live's stubs
 ```
 
-`0.1.0` tracks Loams 0.1.0; in 0.x the API may change between minor versions. <!-- verify after publish -->
+`0.1.1` tracks Loams 0.1.1; in 0.x the API may change between minor versions.
 
 ## Using it
 
@@ -67,6 +67,82 @@ The `/node` subpath exists so a bundler never follows `@connectrpc/connect-node`
 into a browser build it cannot satisfy; the conformance suite checks that
 statically.
 
+## Build an app
+
+The app-building layer (SDKP) adds builders, a collection handle and the
+runtime an app needs: a default namespace, deadlines, read-your-writes
+consistency tokens, chunked bulk writes and stream subscriptions.
+
+```ts
+import { Filter, Loams, Schema, Search, Sort, rrf } from '@loams/client';
+
+const loams = Loams.fromEnv();              // LOAMS_ENDPOINT, LOAMS_API_KEY, LOAMS_NAMESPACE
+// or: new Loams({ endpoint, auth: key, namespace: 'app', sessionConsistency: true })
+
+await loams.collections.create({
+  name: 'notes',
+  schema: new Schema().text('title').text('body').keyword('tags').i64('n')
+    .vector('embedding', 4).toJson(),
+});
+
+const notes = loams.collection('notes');    // calls with `collection` filled in
+await notes.upsert([
+  { id: 1, source: { title: 'Refunds', body: 'refund policy', tags: 'policy', n: 1 },
+    vectors: { embedding: [1, 0, 0, 0] } },
+]);
+
+const hits = await notes.search(
+  notes.query()
+    .text('refund', { fields: ['body'] })
+    .vector('embedding', [1, 0, 0, 0], { k: 10 })
+    .fuse(rrf(60))
+    .filter(Filter.and(Filter.eq('tags', 'policy'), Filter.range('n', { gte: 1 })))
+    .highlight('body')
+    .select({ include: ['title'] })
+    .limit(5),
+);
+
+for await (const hit of loams.search.queryAll(
+  Search.on('notes').text('refund').sort(Sort.score(), Sort.pk()).limit(100),
+)) { /* every hit, page by page */ }
+
+await notes.writeBatch(rows);               // 10 000 rows / 4 MiB a chunk, one key per chunk
+```
+
+- **Default namespace (R11).** `namespace` fills every request that has a
+  `namespace` field and leaves it empty; an explicit one wins, and neither is
+  `InvalidArgumentError` before any network call.
+- **Deadlines (R12).** Unary calls default to 30 s (`timeoutMs` on the client
+  or per call; `0` disables). Running out raises `DeadlineExceededError` with
+  reason `client_deadline_exceeded`, which is never retried. Streams have no
+  default deadline.
+- **Consistency tokens (R4).** `ConsistencyToken.parse/merge/toString`; with
+  `sessionConsistency: true` every token a response carries merges into
+  `loams.consistency`, and every read with a `consistency` field is sent
+  `at_least` the session.
+- **Bulk writes (R13).** `documents.writeBatch` sends one chunk at a time,
+  each with its own idempotency key, returns the merged token, and stops at
+  the first failed chunk with a `BatchError` (`chunksApplied`, `rowsApplied`).
+- **Subscriptions (R14).** `streams.subscribe({ stream, partition, fromOffset })`
+  is an async iterable over `Fetch` that exposes `offset` for resuming.
+
+The modules `loams.namespaces`, `loams.collections`, `loams.documents`,
+`loams.search`, `loams.vector` and `loams.graph` are generated from the protos'
+facade annotations, with the hand-written conveniences above added to them.
+`loams.sql` is generated from `loams.sql.v1` the same way: `sql.query` answers
+`columns` and `rows`, `sql.records(statement, [$1, …])` answers one object per
+row, and `sqlRecords(answer)` reads an answer already in hand. `sql.queryArrow`
+answers the result as Arrow IPC bytes (`arrowIpc`), which `apache-arrow`'s
+`tableFromIPC` reads; the SDK does not depend on it. `loams.streams` is
+generated from `loams.stream.v1`: `create`, `get`, `list` (and `listAll`),
+`produce` (pass `producerId` and `producerSeq` so a retry cannot append
+twice), `fetch`, `produceEvents` and `fetchEvents` (CloudEvents as a JSON
+batch), plus `streams.subscribe(...)` (R14), an async iterable over `fetch`
+whose `offset` is where to resume. `examples/notes/main.ts` is the whole app
+scenario as a program, type-checked in CI. The session's token is used only for
+collection and SQL reads: a graph's token names one graph (SDKP-17). Durable
+workflows use the Resonate SDK pointed at `LOAMS_ENDPOINT/durable/` (SDKP-1).
+
 ## What is generated and what is hand-written
 
 Design §44 §7.3 draws the line, and this SDK follows it exactly.

package/dist/app.d.ts

@@ -0,0 +1,149 @@
+import { type JsonObject, type JsonValue } from '@bufbuild/protobuf';
+import { type ListValue } from '@bufbuild/protobuf/wkt';
+import type { ModuleBinding } from './gen/facade.js';
+import { type DocId, type FilterJson } from './builders/filter.js';
+import { Search, type ConsistencyLevel, type FusionJson } from './builders/search.js';
+import { type BatchOptions, type BatchResult } from './runtime/batch.js';
+import type { CallOptions } from './runtime/call.js';
+import { type OffsetRecord, type Subscription, type SubscribeRequest } from './runtime/subscribe.js';
+/** A generated unary call, as the hand-written layer sees it. */
+export type UnaryCall = (request: any, options?: CallOptions) => Promise<any>;
+/** One document to write. */
+export interface DocumentInput {
+    id: DocId;
+    /** The document's `_source`. */
+    source?: JsonObject;
+    /** Dense vectors by name. */
+    vectors?: Record<string, readonly number[]>;
+    /** Sparse vectors by name. */
+    sparseVectors?: Record<string, {
+        indices: number[];
+        values: number[];
+    }>;
+}
+/** Where a document call goes: the collection, and the namespace when it is
+ * not the client's default. */
+export interface Target {
+    collection: string;
+    namespace?: string;
+}
+/** A document id as `DocumentId`'s proto3 JSON: `{"uint": "1"}`,
+ * `{"string": "a"}` or `{"uuid": "…"}`. */
+export declare function documentIdJson(id: DocId): JsonObject;
+/** The `WriteOp`s of the document conveniences, as proto3 JSON. */
+export declare const WriteOps: {
+    readonly upsert: (doc: DocumentInput) => JsonObject;
+    readonly delete: (id: DocId) => JsonObject;
+    readonly patch: (id: DocId, change: PatchChange) => JsonObject;
+};
+/** What a `patch` changes. */
+export interface PatchChange {
+    /** The keys to merge into `_source`. */
+    set?: JsonObject;
+    /** The top-level keys to remove. */
+    unset?: string[];
+    /** `merge_deep` (the default), `merge_top` or `replace`. */
+    mode?: 'merge_deep' | 'merge_top' | 'replace';
+    /** Vectors to set; `null` removes one. */
+    vectors?: Record<string, readonly number[] | null>;
+    /** The document to write when there is none to patch. */
+    upsert?: DocumentInput;
+}
+/** The scroll options of `scrollAll`. */
+export interface ScrollOptions extends CallOptions {
+    /** A typed filter (`ScrollDocumentsRequest.where`, a `Query`'s proto3 JSON). */
+    where?: FilterJson;
+    /** Documents per page. */
+    limit?: number;
+    select?: JsonObject;
+    /** How fresh each page must be. */
+    read?: ConsistencyLevel;
+}
+/** The document conveniences over `documents.write` and `documents.scroll`. */
+export declare function documentCalls(documents: {
+    write: UnaryCall;
+    scroll?: UnaryCall;
+}): {
+    /** Writes (creates or replaces) documents in one call. Answers the write's
+     * response, whose `token` is its consistency token. */
+    upsert(collection: string | Target, docs: DocumentInput[], options?: CallOptions): Promise<any>;
+    /** Removes documents by id in one call. */
+    delete(collection: string | Target, ids: DocId[], options?: CallOptions): Promise<any>;
+    /** Changes part of one document. */
+    patch(collection: string | Target, id: DocId, change: PatchChange, options?: CallOptions): Promise<any>;
+    /** A bulk upsert, chunked, one chunk in flight (R13). */
+    writeBatch(collection: string | Target, docs: Iterable<DocumentInput> | AsyncIterable<DocumentInput>, options?: BatchOptions & CallOptions): Promise<BatchResult>;
+    /** Every document, page by page, following `next` until it is unset. */
+    scrollAll(collection: string | Target, options?: ScrollOptions): AsyncGenerator<unknown, void, unknown>;
+};
+/** The options of the search shorthands. */
+export interface SearchShorthandOptions extends CallOptions {
+    namespace?: string;
+    filter?: FilterJson;
+    limit?: number;
+}
+/** The search conveniences over `search.query`. */
+export declare function searchCalls(search: {
+    query: UnaryCall;
+}): {
+    /** A text search: one field is a `match`, several a `multi_match`, none a
+     * `query_string`. */
+    text(collection: string, text: string, options?: SearchShorthandOptions & {
+        fields?: string[];
+    }): Promise<any>;
+    /** Text plus vector, fused (RRF by default). */
+    hybrid(collection: string, text: string, vector: readonly number[], options: SearchShorthandOptions & {
+        field: string;
+        fields?: string[];
+        fusion?: FusionJson;
+        k?: number;
+    }): Promise<any>;
+    /**
+     * Every hit, page after page, following `search_after` from the last hit's
+     * `sortValues` until a page comes back short. The sort must end in a
+     * primary-key tiebreaker (`Sort.pk()`), or two hits with equal sort values
+     * could straddle a page and be skipped or repeated; without one this
+     * refuses with `invalid_argument` before any call.
+     */
+    queryAll(builder: Search, options?: CallOptions): AsyncGenerator<{
+        sortValues?: unknown[];
+    }, void, unknown>;
+};
+/** The parts of a `sql.query` answer `sqlRecords` reads. */
+export interface SqlAnswer {
+    columns: readonly {
+        name: string;
+    }[];
+    rows: readonly ListValue[];
+}
+/**
+ * A `sql.query` answer's rows as one object per row, keyed by column name
+ * (SDKP §2.5). A value is its JSON: a 64-bit integer past 2^53 is the decimal
+ * string the server sent, so it stays exact. A column name that repeats keeps
+ * its last value, as a JavaScript object must.
+ */
+export declare function sqlRecords(answer: SqlAnswer): Record<string, JsonValue>[];
+/** The options of `sql.records`. */
+export interface SqlRecordsOptions extends CallOptions {
+    namespace?: string;
+    maxRows?: number;
+}
+/** The SQL conveniences over `sql.query`. */
+export declare function sqlCalls(sql: {
+    query: UnaryCall;
+}): {
+    /**
+     * One read-only statement with its `$1…$n` values, answered as records
+     * (`sqlRecords`). The values are JSON scalars; the server casts each to the
+     * type its placeholder was inferred as.
+     */
+    records(statement: string, params?: readonly JsonValue[], options?: SqlRecordsOptions): Promise<Record<string, JsonValue>[]>;
+};
+/** The stream conveniences over `streams.fetch`. */
+export declare function streamCalls(streams: {
+    fetch: UnaryCall;
+}): {
+    /** Every record from `fromOffset` on, as an async iterable (R14). */
+    subscribe<R extends OffsetRecord = OffsetRecord>(request: SubscribeRequest, options?: CallOptions): Subscription<R>;
+};
+export declare function attachAppCalls(modules: Record<string, unknown>, bindings: readonly ModuleBinding[]): void;

package/dist/app.js

@@ -0,0 +1,317 @@
+// The hand-written half of the app modules (SDKP §2.3–§2.5, §4).
+//
+// The generated facade gives one function per proto method. A developer
+// building an app wants a few more, each a thin loop or shorthand over those:
+//
+// - `documents.upsert`, `delete`, `patch` and `writeBatch` over `write`;
+// - `documents.scrollAll` over `scroll` (its cursor is a `DocumentId`, not an
+//   AIP-158 string, so the generic `listAll` does not fit it);
+// - `search.text`, `search.hybrid` and `search.queryAll` over `search.query`;
+// - `sql.records` over `sql.query`, and `sqlRecords` for an answer in hand;
+// - `streams.subscribe` over `streams.fetch`;
+// - `<call>All` for every paged call (`namespaces.listAll`,
+//   `collections.listAll`), over the generic paging iterator.
+//
+// `attachAppCalls` adds them to the module objects the facade built, and only
+// to modules that exist: an SDK whose facade has no `documents` module gets no
+// `documents.upsert`. Nothing here names an RPC path or a retry class; those
+// stay the generated bindings'.
+import { fromJson, toJson } from '@bufbuild/protobuf';
+import { ListValueSchema, ValueSchema } from '@bufbuild/protobuf/wkt';
+import { Code } from '@connectrpc/connect';
+import { WriteOpSchema } from './vendor/proto/gen/loams/collection/v1/document_pb.js';
+import { idValue } from './builders/filter.js';
+import { Search, consistencyJson, rrf } from './builders/search.js';
+import { writeBatch } from './runtime/batch.js';
+import { InvalidArgumentError } from './runtime/errors.js';
+import { paginate } from './runtime/pagination.js';
+import { subscribe } from './runtime/subscribe.js';
+/** A document id as `DocumentId`'s proto3 JSON: `{"uint": "1"}`,
+ * `{"string": "a"}` or `{"uuid": "…"}`. */
+export function documentIdJson(id) {
+    if (typeof id === 'string') {
+        return { string: id };
+    }
+    const value = idValue(id);
+    return typeof value === 'string' ? { string: value } : value;
+}
+function documentJson(doc) {
+    const out = { id: documentIdJson(doc.id) };
+    if (doc.source !== undefined) {
+        out.source = doc.source;
+    }
+    if (doc.vectors !== undefined) {
+        out.vectors = Object.fromEntries(Object.entries(doc.vectors).map(([name, values]) => [name, [...values]]));
+    }
+    if (doc.sparseVectors !== undefined) {
+        out.sparseVectors = doc.sparseVectors;
+    }
+    return out;
+}
+/** The `WriteOp`s of the document conveniences, as proto3 JSON. */
+export const WriteOps = {
+    upsert(doc) {
+        return { upsert: documentJson(doc) };
+    },
+    delete(id) {
+        return { delete: { id: documentIdJson(id) } };
+    },
+    patch(id, change) {
+        const patch = { id: documentIdJson(id) };
+        if (change.mode !== undefined) {
+            patch.mode = change.mode;
+        }
+        if (change.set !== undefined) {
+            patch.source = change.set;
+        }
+        if (change.unset !== undefined && change.unset.length > 0) {
+            patch.deleteKeys = [...change.unset];
+        }
+        if (change.vectors !== undefined) {
+            patch.vectors = change.vectors;
+        }
+        if (change.upsert !== undefined) {
+            patch.upsert = documentJson(change.upsert);
+        }
+        return { patch };
+    },
+};
+function opsRequest(target, ops) {
+    return {
+        ...(target.namespace === undefined ? {} : { namespace: target.namespace }),
+        collection: target.collection,
+        ops: ops.map((op) => fromJson(WriteOpSchema, op)),
+    };
+}
+function targetOf(collection) {
+    return typeof collection === 'string' ? { collection } : collection;
+}
+/** The document conveniences over `documents.write` and `documents.scroll`. */
+export function documentCalls(documents) {
+    return {
+        /** Writes (creates or replaces) documents in one call. Answers the write's
+         * response, whose `token` is its consistency token. */
+        upsert(collection, docs, options) {
+            return documents.write(opsRequest(targetOf(collection), docs.map(WriteOps.upsert)), options);
+        },
+        /** Removes documents by id in one call. */
+        delete(collection, ids, options) {
+            return documents.write(opsRequest(targetOf(collection), ids.map(WriteOps.delete)), options);
+        },
+        /** Changes part of one document. */
+        patch(collection, id, change, options) {
+            return documents.write(opsRequest(targetOf(collection), [WriteOps.patch(id, change)]), options);
+        },
+        /** A bulk upsert, chunked, one chunk in flight (R13). */
+        writeBatch(collection, docs, options = {}) {
+            const target = targetOf(collection);
+            return writeBatch((ops, callOptions) => documents.write(opsRequest(target, ops), callOptions), mapOps(docs), options);
+        },
+        /** Every document, page by page, following `next` until it is unset. */
+        async *scrollAll(collection, options = {}) {
+            if (documents.scroll === undefined) {
+                throw new InvalidArgumentError('this SDK build has no documents.scroll', {
+                    code: Code.Unimplemented,
+                });
+            }
+            const { where, limit, select, read, ...call } = options;
+            const target = targetOf(collection);
+            let after;
+            for (;;) {
+                const page = await documents.scroll({
+                    ...(target.namespace === undefined ? {} : { namespace: target.namespace }),
+                    collection: target.collection,
+                    // `where` is a `Query`'s proto3 JSON (SDKP-12), which is what a
+                    // `Filter` already is.
+                    ...(where === undefined ? {} : { where }),
+                    ...(limit === undefined ? {} : { limit }),
+                    ...(select === undefined ? {} : { select }),
+                    ...(read === undefined ? {} : { consistency: consistencyJsonMessage(read) }),
+                    ...(after === undefined ? {} : { after }),
+                }, call);
+                for (const doc of (page?.documents ?? [])) {
+                    yield doc;
+                }
+                if (page?.next === undefined || page.next.id?.case === undefined) {
+                    return;
+                }
+                after = page.next;
+            }
+        },
+    };
+}
+/** A `Consistency` init object for a call that takes one directly. */
+function consistencyJsonMessage(level) {
+    const json = consistencyJson(level);
+    if ('atLeast' in json) {
+        return { atLeast: json.atLeast };
+    }
+    return { freshness: json.freshness === 'FRESHNESS_EVENTUAL' ? 2 : 1 };
+}
+async function* mapOps(docs) {
+    for await (const doc of docs) {
+        yield WriteOps.upsert(doc);
+    }
+}
+/** The search conveniences over `search.query`. */
+export function searchCalls(search) {
+    const run = (builder, options) => search.query(builder.build(), options);
+    return {
+        /** A text search: one field is a `match`, several a `multi_match`, none a
+         * `query_string`. */
+        text(collection, text, options = {}) {
+            const { namespace, filter, limit, fields, ...call } = options;
+            let builder = Search.on(collection, { namespace }).text(text, { fields });
+            if (filter !== undefined)
+                builder = builder.filter(filter);
+            if (limit !== undefined)
+                builder = builder.limit(limit);
+            return run(builder, call);
+        },
+        /** Text plus vector, fused (RRF by default). */
+        hybrid(collection, text, vector, options) {
+            const { namespace, filter, limit, fields, field, fusion, k, ...call } = options;
+            let builder = Search.on(collection, { namespace })
+                .text(text, { fields, k })
+                .vector(field, vector, { k })
+                .fuse(fusion ?? rrf());
+            if (filter !== undefined)
+                builder = builder.filter(filter);
+            if (limit !== undefined)
+                builder = builder.limit(limit);
+            return run(builder, call);
+        },
+        /**
+         * Every hit, page after page, following `search_after` from the last hit's
+         * `sortValues` until a page comes back short. The sort must end in a
+         * primary-key tiebreaker (`Sort.pk()`), or two hits with equal sort values
+         * could straddle a page and be skipped or repeated; without one this
+         * refuses with `invalid_argument` before any call.
+         */
+        async *queryAll(builder, options = {}) {
+            if (!builder.hasTiebreak) {
+                throw new InvalidArgumentError('search.queryAll needs a sort that ends in the primary key, such as .sort(Sort.score(), Sort.pk())', { code: Code.InvalidArgument, reason: 'search_after_needs_tiebreak', metadata: { field: 'sort' } });
+            }
+            const limit = builder.toJson().limit ?? 10;
+            let page = builder;
+            for (;;) {
+                const answer = await run(page, options);
+                const hits = (answer?.hits ?? []);
+                for (const hit of hits) {
+                    yield hit;
+                }
+                const last = hits[hits.length - 1];
+                if (hits.length < limit || last === undefined || last.sortValues === undefined) {
+                    return;
+                }
+                page = builder.after(last.sortValues);
+            }
+        },
+    };
+}
+/**
+ * A `sql.query` answer's rows as one object per row, keyed by column name
+ * (SDKP §2.5). A value is its JSON: a 64-bit integer past 2^53 is the decimal
+ * string the server sent, so it stays exact. A column name that repeats keeps
+ * its last value, as a JavaScript object must.
+ */
+export function sqlRecords(answer) {
+    const names = answer.columns.map((column) => column.name);
+    return answer.rows.map((row) => {
+        const values = toJson(ListValueSchema, row);
+        const record = {};
+        names.forEach((name, at) => {
+            record[name] = values[at] ?? null;
+        });
+        return record;
+    });
+}
+/** The SQL conveniences over `sql.query`. */
+export function sqlCalls(sql) {
+    return {
+        /**
+         * One read-only statement with its `$1…$n` values, answered as records
+         * (`sqlRecords`). The values are JSON scalars; the server casts each to the
+         * type its placeholder was inferred as.
+         */
+        async records(statement, params = [], options = {}) {
+            const { namespace, maxRows, ...call } = options;
+            const answer = (await sql.query({
+                sql: statement,
+                params: params.map((value) => fromJson(ValueSchema, value)),
+                ...(namespace !== undefined ? { namespace } : {}),
+                ...(maxRows !== undefined ? { maxRows } : {}),
+            }, call));
+            return sqlRecords(answer);
+        },
+    };
+}
+/** The stream conveniences over `streams.fetch`. */
+export function streamCalls(streams) {
+    return {
+        /** Every record from `fromOffset` on, as an async iterable (R14). */
+        subscribe(request, options = {}) {
+            return subscribe((fetchRequest, loopOptions) => streams.fetch(fetchRequest, { ...options, signal: loopOptions?.signal }), request, { signal: options.signal });
+        },
+    };
+}
+/**
+ * Adds the hand-written calls to the generated module objects, in place.
+ *
+ * Every paged call gets `<call>All`; `documents`, `search` and `streams` get
+ * their conveniences when the facade generated them. A name the facade
+ * already uses is never overwritten.
+ */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export function attachAppCalls(modules, bindings) {
+    const add = (module, calls) => {
+        // Module names come from the generated bindings, but an own-property
+        // check keeps a name such as `__proto__` from reaching Object.prototype.
+        if (!Object.hasOwn(modules, module) || UNSAFE_KEYS.has(module)) {
+            return;
+        }
+        const target = modules[module];
+        if (target === undefined) {
+            return;
+        }
+        for (const [name, fn] of Object.entries(calls)) {
+            if (!UNSAFE_KEYS.has(name) && !(name in target)) {
+                target[name] = fn;
+            }
+        }
+    };
+    for (const module of bindings) {
+        const target = modules[module.name];
+        if (target === undefined) {
+            continue;
+        }
+        for (const binding of module.calls) {
+            if (binding.pagination === null || binding.streaming !== 'unary') {
+                continue;
+            }
+            const call = target[binding.name];
+            if (typeof call !== 'function') {
+                continue;
+            }
+            add(module.name, {
+                [`${binding.name}All`]: (request = {}, options) => paginate(binding, call, request, options),
+            });
+        }
+    }
+    const documents = modules.documents;
+    if (typeof documents?.write === 'function') {
+        add('documents', documentCalls(documents));
+    }
+    const search = modules.search;
+    if (typeof search?.query === 'function') {
+        add('search', searchCalls(search));
+    }
+    const sql = modules.sql;
+    if (typeof sql?.query === 'function') {
+        add('sql', sqlCalls(sql));
+    }
+    const streams = modules.streams;
+    if (typeof streams?.fetch === 'function') {
+        add('streams', streamCalls(streams));
+    }
+}

package/dist/builders/filter.d.ts

@@ -0,0 +1,96 @@
+import { type JsonObject, type JsonValue } from '@bufbuild/protobuf';
+import { type Query } from '../vendor/proto/gen/loams/collection/v1/query_pb.js';
+/** One filter, as the proto3 JSON of a `loams.collection.v1.Query`. */
+export type FilterJson = JsonObject;
+/** A document id, as a filter or a document call takes it. A `number` must be
+ * a safe integer; pass a `bigint` above 2^53. */
+export type DocId = number | bigint | string | {
+    uuid: string;
+} | {
+    uint: string | number | bigint;
+};
+/** `{"auto": {}}` or an exact number of edits, 0 to 2. */
+export type Fuzziness = 'auto' | 0 | 1 | 2;
+/** A document id as the `Query.ids` `Value` spells it: `{"uint": "1"}`,
+ * `{"uuid": "…"}` or a bare string. */
+export declare function idValue(id: DocId): JsonValue;
+/** The bounds of a range: any of `gt`, `gte`, `lt`, `lte`. */
+export interface Bounds {
+    gt?: JsonValue;
+    gte?: JsonValue;
+    lt?: JsonValue;
+    lte?: JsonValue;
+}
+/** The options of a `match`. */
+export interface MatchOptions {
+    /** `'or'` (the default) or `'and'`. */
+    operator?: 'or' | 'and';
+    minimumShouldMatch?: string | number;
+    fuzziness?: Fuzziness;
+    analyzer?: string;
+}
+/** The options of a `query_string`. */
+export interface QueryStringOptions {
+    fields?: string[];
+    operator?: 'or' | 'and';
+}
+/** The options of a `multi_match`. */
+export interface MultiMatchOptions {
+    /** `best_fields` (the default), `most_fields`, `cross_fields`, `phrase`,
+     * `phrase_prefix`. */
+    kind?: 'best_fields' | 'most_fields' | 'cross_fields' | 'phrase' | 'phrase_prefix';
+    operator?: 'or' | 'and';
+    tieBreaker?: number;
+}
+/** The filter verbs. */
+export declare const Filter: {
+    /** Every document. */
+    readonly all: () => FilterJson;
+    /** No document. */
+    readonly none: () => FilterJson;
+    /** The field equals `value` (a term query). */
+    readonly eq: (field: string, value: JsonValue) => FilterJson;
+    /** The field equals any of `values` (a terms query). */
+    readonly in: (field: string, values: JsonValue[]) => FilterJson;
+    /** The field is within the bounds; an omitted bound is open. */
+    readonly range: (field: string, bounds: Bounds) => FilterJson;
+    /** The field is present, whatever its value. */
+    readonly exists: (field: string) => FilterJson;
+    /** The field is `null` or absent. */
+    readonly isNull: (field: string) => FilterJson;
+    /** The field is an empty string, list or object. */
+    readonly isEmpty: (field: string) => FilterJson;
+    /** The field starts with `value`. */
+    readonly prefix: (field: string, value: string) => FilterJson;
+    /** The field matches a `*`/`?` pattern. */
+    readonly wildcard: (field: string, pattern: string) => FilterJson;
+    /** The field is within `fuzziness` edits of `value`. */
+    readonly fuzzy: (field: string, value: string, edits?: Fuzziness) => FilterJson;
+    /** A full-text match on one field. */
+    readonly match: (field: string, text: string, options?: MatchOptions) => FilterJson;
+    /** The words of `text`, in order, at most `slop` positions apart. */
+    readonly phrase: (field: string, text: string, slop?: number) => FilterJson;
+    /** A full-text match over several fields; `'title^2'` boosts one. */
+    readonly multiMatch: (fields: string[], text: string, options?: MultiMatchOptions) => FilterJson;
+    /** The query-string syntax, over `fields` or the collection's defaults. */
+    readonly queryString: (query: string, options?: QueryStringOptions) => FilterJson;
+    /** The documents with these ids, and no others. */
+    readonly ids: (...ids: DocId[]) => FilterJson;
+    /** Every query matches (a bool `must`). */
+    readonly and: (...queries: FilterJson[]) => FilterJson;
+    /** At least one of the queries matches (a bool `should`). */
+    readonly or: (...queries: FilterJson[]) => FilterJson;
+    /** At least `minimumShouldMatch` of the queries match: `or` with an explicit
+     * `minimum_should_match`. */
+    readonly anyOf: (queries: FilterJson[], minimumShouldMatch: number | string) => FilterJson;
+    /** None of the queries match (a bool `must_not`). */
+    readonly not: (...queries: FilterJson[]) => FilterJson;
+    /** Every query matches, without scoring (a bool `filter`). */
+    readonly filter: (...queries: FilterJson[]) => FilterJson;
+    /** Multiplies the query's score by `boost`. */
+    readonly boost: (query: FilterJson, boost: number) => FilterJson;
+    /** Every match of `query` scores `score`. */
+    readonly constantScore: (query: FilterJson, score: number) => FilterJson;
+};
+/** Decodes a filter into the generated `Query` message. */
+export declare function toQuery(filter: FilterJson): Query;