@substrio/sdk 0.0.0-stage → 0.1.0

package/substrio.d.ts

@@ -0,0 +1,1087 @@
+// Types of the SDK's entry point. The operation surface (client.ops, every
+// input, result and the error envelope) is generated: substrio_operations.d.mts.
+import type { SubstrioOperations, SubstrioErrorBody, SubstrioErrorCode } from './substrio_operations.mjs';
+
+export * from './substrio_operations.mjs';
+
+export interface SubstrioErrorInfo {
+    readonly hex: number;
+    readonly name: string;
+    readonly message: string;
+    readonly status: number;
+}
+
+export declare const SUBSTRIO_ERRORS: Readonly<Record<string, SubstrioErrorInfo>>;
+
+/** A failed call: the HTTP status, the error code and the server's envelope. */
+export declare class SubstrioError extends Error {
+    constructor(status: number, code: SubstrioErrorCode | '', message: string, body: unknown);
+    readonly status: number;
+    readonly code: SubstrioErrorCode | '';
+    readonly body: SubstrioErrorBody | unknown;
+    readonly isRetryable: boolean;
+    readonly isAuth: boolean;
+    readonly isQuota: boolean;
+    readonly isNotFound: boolean;
+    static fromResponse(status: number, parsed: unknown): SubstrioError;
+}
+
+export interface SubstrioConfig {
+    url: string;
+    key?: string;
+    token?: string;
+    tenant?: string;
+}
+
+export default class Substrio {
+    constructor(config: SubstrioConfig);
+    /** Every registry operation at the words of its name: ops.kv.get(input). */
+    readonly ops: SubstrioOperations;
+    // The HTTP surface (collections, queries, realtime, KV wire) is not typed yet.
+    [member: string]: any;
+}
+
+// @substrio-chain-begin (the single owner of embedded types; src/substrio/CMakeLists.txt copies this block into jsc/substrio_runtime.d.ts)
+/** Synchronous embedded collection contracts, separate from the HTTP client. */
+export type SubstrioDocumentId = string | number | bigint;
+/** A value a filter member compares to: a string, number, boolean, Date or null (null names the documents without a value). */
+export type SubstrioFilterValue = null | boolean | number | string | Date;
+/** A binary operand: an ArrayBuffer or any ArrayBufferView (a Uint8Array, another typed array, a DataView), compared by the bytes it views. */
+export type SubstrioBinaryValue = ArrayBuffer | ArrayBufferView;
+/** {$binary: base64}: binary written as its base64 text, the bytes a document stores for it. */
+export interface SubstrioBinaryWrapper { $binary: string }
+/**
+ * What an equality compares to: a SubstrioFilterValue, or binary. A binary equals a stored binary of the same bytes
+ * only (never a string of those bytes), and an array holding one by any element. Only $eq, $ne, $in, $nin and
+ * a field's own value take it; an ordering or a text operator throws.
+ */
+export type SubstrioFilterEquality = SubstrioFilterValue | SubstrioBinaryValue | SubstrioBinaryWrapper;
+/** The operators of an element condition ($elemMatch): the ones a chain's elemMatch takes. */
+export interface SubstrioElementOperators {
+  $eq?: SubstrioFilterEquality;
+  $ne?: SubstrioFilterEquality;
+  $gt?: number | string | Date;
+  $gte?: number | string | Date;
+  $lt?: number | string | Date;
+  $lte?: number | string | Date;
+  $in?: SubstrioFilterEquality[];
+  $nin?: SubstrioFilterEquality[];
+  $exists?: boolean;
+  $startsWith?: string;
+  $endsWith?: string;
+  $contains?: string;
+  $icontains?: string;
+}
+/**
+ * The operators of one field of a filter. $not takes a non-empty object of the
+ * operators before it (every document they do not select, one without the field
+ * included); $regex is a pattern string and $options "" or "i"; $all, $size and
+ * $elemMatch read an array held by a top-level field. null is the operand of $eq,
+ * $ne, $in and $nin only; _id takes $eq, $ne, $in and $nin over ids.
+ */
+export interface SubstrioFieldOperators {
+  $eq?: SubstrioFilterEquality;
+  $ne?: SubstrioFilterEquality;
+  $gt?: number | string | Date;
+  $gte?: number | string | Date;
+  $lt?: number | string | Date;
+  $lte?: number | string | Date;
+  $in?: SubstrioFilterEquality[];
+  $nin?: SubstrioFilterEquality[];
+  $exists?: boolean;
+  $startsWith?: string;
+  $not?: SubstrioFieldOperators;
+  $regex?: string;
+  $options?: '' | 'i';
+  /** The array field holds every one of the values (containsAll). */
+  $all?: (string | number | boolean)[];
+  /** The array field has exactly this many elements (size). */
+  $size?: number;
+  /** An element satisfies every member: a value is an equality, an object takes SubstrioElementOperators (elemMatch). */
+  $elemMatch?: Record<string, SubstrioFilterValue | SubstrioElementOperators>;
+}
+/**
+ * A filter object. A member is a field (or a dotted path) holding a value (an equality) or an object of
+ * operators; $and, $or and $nor take non-empty arrays of filters. Every filter is a chain's plan: a filter
+ * the chain has no plan for throws a TypeError that says why (undefined, a BigInt, an integer from 2^53,
+ * a RegExp object, an unknown operator, $text, $fuzzy, $search, $knn, $sparseKnn, $near, $geoWithin, $box,
+ * $sphere and $whereJS). null or undefined means every document; any other non-object throws.
+ */
+export interface SubstrioFilterObject {
+  $and?: SubstrioFilterObject[];
+  $or?: SubstrioFilterObject[];
+  $nor?: SubstrioFilterObject[];
+  [field: string]: SubstrioFilterEquality | SubstrioFieldOperators | SubstrioFilterObject[] | undefined;
+}
+export type SubstrioFilter = SubstrioFilterObject | null | undefined;
+/** Every condition must hold on the stored row; otherwise the write returns null. {_version: v} is compare-and-set. */
+export interface SubstrioWriteOptions { if?: Record<string, unknown>; }
+/**
+ * Plain fields are set, or use operators; mixing the two forms throws.
+ * $inc/$mul/$min/$max require finite numbers or BigInts inside int64, and a
+ * nonnumeric stored field throws without changing the row. Integer overflow
+ * throws RangeError. $push accepts a value or {$each, $position, $slice};
+ * $pull accepts a value, scalar condition, or fields of an object element.
+ * $setWhere takes {arrayField: {where: {field: value}, set: {field: value}}}.
+ * A dotted key in $set, $unset, $inc, $mul, $min and $max ("address.city") writes the member of a document,
+ * creating the documents of a missing step; a step that is a scalar, null or an array throws and writes nothing.
+ * The array operators, $rename and $setWhere do not take a dotted key.
+ * $setWhere rebuilds each matching element (a document) with only the fields of `set` written (a dotted name in
+ * `set` writes a path); every other member of every element keeps its stored type and bytes.
+ * Values store as JSON writes them: -0 stores 0, NaN and the infinities null, a Date its ISO text, a hole of a
+ * sparse array null, undefined is no member of an object; the same at the top level, nested and in an array.
+ * An ArrayBuffer and every ArrayBufferView (a Uint8Array, any other typed array, a DataView) store as binary, the
+ * bytes they view in native byte order, and a stored binary value reads back as a Uint8Array (in a row, a pluck,
+ * a join, a group key or a distinct value); the same at the top level, nested and in an array. {$binary: base64}
+ * stores the same binary.
+ */
+export type SubstrioUpdate = Record<string, unknown> & {
+  $set?: Record<string, unknown>;
+  $unset?: Record<string, unknown>;
+  $inc?: Record<string, number | bigint>;
+  $mul?: Record<string, number | bigint>;
+  $min?: Record<string, number | bigint>;
+  $max?: Record<string, number | bigint>;
+  $push?: Record<string, unknown>;
+  $addToSet?: Record<string, unknown>;
+  $pull?: Record<string, unknown>;
+  $pullAll?: Record<string, unknown[]>;
+  $pop?: Record<string, 1 | -1>;
+  $rename?: Record<string, string>;
+  $currentDate?: Record<string, true>;
+  $setWhere?: Record<string, { where: Record<string, unknown>; set: Record<string, unknown> }>;
+};
+export interface SubstrioFindOptions {
+  /** Keys in order, with numeric directions; a bare name in the array is ascending. */
+  sort?: Record<string, 1 | -1> | Array<string | [string, (1 | -1)?]>;
+  limit?: number;
+  skip?: number;
+  /** Projection answers plain objects of these fields, rather than records. */
+  select?: string[];
+  /** Naming either token (even null/undefined) requests a page; limit is required and skip must be zero. */
+  after?: string | null;
+  before?: string | null;
+}
+/** Find pages never carry total. Rows retain the unprojected/projected result form. */
+export interface SubstrioFindPage<Rows> {
+  rows: Rows;
+  next: string | null;
+  prev: string | null;
+}
+export type SubstrioUnpagedFindOptions = Omit<SubstrioFindOptions, 'after' | 'before'> & { after?: never; before?: never };
+/** Two nonempty tokens, multiple sort keys, or a filter requiring fallback are refused at runtime. */
+export type SubstrioFindCursorOptions = Omit<SubstrioFindOptions, 'limit' | 'skip'> & { limit: number; skip?: 0 } &
+  ({ after: string | null | undefined } | { before: string | null | undefined });
+/** $setOnInsert applies only when the upsert inserts; ignored on a match. */
+export type SubstrioUpsertDocument<T> = Partial<T> & { $setOnInsert?: Record<string, unknown> };
+export type SubstrioIdentifiedDocument<T> = SubstrioUpsertDocument<T> & { _id: SubstrioDocumentId };
+export interface SubstrioRecordMethods extends SubstrioRecordLinks {
+  /**
+   * Writes changes and returns true. A detached row inserts and gains _id and
+   * _version. A stored row saves against its version; a concurrent change
+   * throws ConflictError and overwrites nothing. Reload, assign and save again.
+   */
+  save(): boolean;
+  has(field: string): boolean;
+  set(field: string, value: unknown): this;
+  /** Assigns own fields in memory; save() writes them. */
+  merge(fields: Record<string, unknown>): this;
+  /** Exact integer addition (BigInt beyond 2^53); TypeError for nonnumbers, RangeError beyond int64. */
+  inc(field: string, delta?: number | bigint): this;
+  keys(): string[];
+  /** The stored type of a field ("string", "number", "boolean", "date", "null", "object", "array"); undefined when absent. */
+  typeOf(field: string): string | undefined;
+  push(field: string, value: unknown): this;
+  pull(field: string, value: unknown): this;
+  /** Whether this row has unsaved changes. */
+  dirty(): boolean;
+  unset(field: string): this;
+  /** Deletes the stored document. */
+  delete(): boolean;
+  /** Re-reads the stored row and drops unsaved changes. */
+  reload(): this;
+  /** Alias of reload. */
+  revert(): this;
+  toggle(field: string): this;
+  /** JSON.stringify gives the stored document. */
+  toJSON(): Record<string, unknown>;
+}
+export type SubstrioRecord<T = Record<string, unknown>> = Omit<T, '_id'> & SubstrioRecordMethods & { _id: string };
+/**
+ * Constructing copies fields without storing them. No generated id is present
+ * yet; an input's own _id is copied as supplied. save() returns boolean and
+ * does not statically narrow this object's id after the call.
+ */
+export type SubstrioConstructedRecord<T = Record<string, unknown>, Fields extends object = {}> =
+  Omit<Partial<T>, '_id'> & Fields & SubstrioRecordMethods & { _id?: unknown };
+/** An unprojected result. Array map/filter produce ordinary arrays. */
+export interface SubstrioQueryResult<T = Record<string, unknown>> extends Omit<Array<SubstrioRecord<T>>, 'reduce'> {
+  sort(compare?: (a: SubstrioRecord<T>, b: SubstrioRecord<T>) => number): this;
+  toArray(): SubstrioRecord<T>[];
+  toJSON(): Record<string, unknown>[];
+  project(fields: string[]): Record<string, unknown>[];
+  first(): SubstrioRecord<T> | undefined;
+  last(): SubstrioRecord<T> | undefined;
+  ids(): string[];
+  pluck(field: string): unknown[];
+  /** Without an initial value, acc starts undefined and every row is visited; an empty result returns undefined. */
+  reduce<U>(fn: (acc: U | undefined, record: SubstrioRecord<T>, index: number, result: this) => U): U | undefined;
+  reduce<U>(fn: (acc: U, record: SubstrioRecord<T>, index: number, result: this) => U, initial: U): U;
+  /** Saves rows with unsaved changes; reports the first conflict while other current rows may still save. */
+  saveAll(): number;
+  /** Deletes each row's stored document; returns the number removed. */
+  deleteAll(): number;
+  setAll(field: string, value: unknown): number;
+  incAll(field: string, delta?: number | bigint): number;
+}
+/**
+ * Documents are live records read in place. Dates store as ISO strings,
+ * undefined fields are dropped and BigInts inside int64 round trip.
+ */
+export interface SubstrioCollection<T = Record<string, unknown>> extends Omit<SubstrioChainStart<T>, 'all'>, SubstrioCollectionDeclarations {
+  /** Detached row: copies own fields; nothing is stored until save(). */
+  new <Fields extends Partial<T> & Record<string, unknown>>(fields: Fields): SubstrioConstructedRecord<T, Fields>;
+  new (fields?: Partial<T>): SubstrioConstructedRecord<T>;
+  /** Same as new. */
+  <Fields extends Partial<T> & Record<string, unknown>>(fields: Fields): SubstrioConstructedRecord<T, Fields>;
+  (fields?: Partial<T>): SubstrioConstructedRecord<T>;
+  all(...args: SubstrioChainArgument[]): SubstrioQueryResult<T>;
+  /** Zero limit exits before projection and paging, answering an empty record result. */
+  find(filter: SubstrioFilter, options: SubstrioFindOptions & { limit: 0 }): SubstrioQueryResult<T>;
+  /** A page, or the empty record result when limit is zero. No total is returned. */
+  find(filter: SubstrioFilter, options: SubstrioFindCursorOptions & { select: string[] }): SubstrioFindPage<Partial<T>[]> | SubstrioQueryResult<T>;
+  find(filter: SubstrioFilter, options: SubstrioFindCursorOptions & { select?: undefined }): SubstrioFindPage<SubstrioQueryResult<T>> | SubstrioQueryResult<T>;
+  find(filter: SubstrioFilter, options: SubstrioFindCursorOptions): SubstrioFindPage<SubstrioQueryResult<T> | Partial<T>[]> | SubstrioQueryResult<T>;
+  /** Without limit or cursor, selection answers plain projected objects. */
+  find(filter: SubstrioFilter, options: SubstrioUnpagedFindOptions & { select: string[]; limit?: undefined }): Partial<T>[];
+  find(filter: SubstrioFilter, options: SubstrioUnpagedFindOptions & { select: string[] }): Partial<T>[] | SubstrioQueryResult<T>;
+  find(filter?: SubstrioFilter, options?: SubstrioUnpagedFindOptions & { select?: undefined }): SubstrioQueryResult<T>;
+  /** Optional token/selection properties can select either the paged or unpaged result form. */
+  find(filter: SubstrioFilter, options: SubstrioFindOptions): SubstrioFindPage<SubstrioQueryResult<T> | Partial<T>[]> | SubstrioQueryResult<T> | Partial<T>[];
+  findOne(filter?: SubstrioFilter): SubstrioRecord<T> | null;
+  /**
+   * Inserts and returns only the id envelope. The collection assigns `_id`: a document that
+   * names one is refused (a TypeError), use put to choose an id. `_createdAt`, `_updatedAt`
+   * and `_version` are the system's and ignored.
+   */
+  insert(document: Partial<T>): { _id: string };
+  /** Alias of insert. */
+  add(document: Partial<T>): { _id: string };
+  /** Inserts and returns the stored row; refuses a document that names `_id`, as insert does. */
+  create(document: Partial<T>): SubstrioRecord<T>;
+  /** A record, or null if no document has the id. */
+  get(id: SubstrioDocumentId): SubstrioRecord<T> | null;
+  /** Alias of get. */
+  findById(id: SubstrioDocumentId): SubstrioRecord<T> | null;
+  /**
+   * The document as a live row: a field reads as on a plain row, and every assignment to a field is written at
+   * once (no save()). Null if no document has the id. Any id: a synced collection's wide time-ordered ids too.
+   * A held row is a snapshot whose writes are checked: after another writer changed the document, an assignment
+   * throws an Error with `code` 0x4012 (ROW_STALE), writes nothing, and the row then holds the document as it is
+   * (read the field again and retry). No update is lost.
+   */
+  live(id: SubstrioDocumentId | number | bigint): (T & { _id: string }) | null;
+  /**
+   * live(id) for an integer id from 1 to 2^32 - 2 (an array index): `db.users[id]` reads, `id in db.users`
+   * asks, `db.users[id] = doc` replaces a stored document (a missing id throws a TypeError, nothing written)
+   * and `delete db.users[id]` deletes. A larger id (a synced collection's) reads undefined here: use live(id).
+   */
+  [id: number]: (T & { _id: string }) | undefined;
+  /** for (const doc of db.users): every document as a live row, in id order, read 64 at a time. */
+  [Symbol.iterator](): Iterator<T & { _id: string }>;
+  /**
+   * The base of a class on the collection's documents: `class User extends db.users.Model { ... }`. `new User(doc)`
+   * inserts once and answers the live row (an assignment after super(doc) is a write). The class's statics:
+   * live(id), use(Class), every chain start (User.where(...).all() answers User instances) and iteration.
+   */
+  readonly Model: new (doc?: Partial<T>) => T & { _id: string };
+  /** Binds `klass` (a class that extends Model): every live row of the collection is then an instance of it. */
+  use<C extends new (...args: any[]) => any>(klass: C): C;
+  /** Sets plain fields by id. */
+  set(id: SubstrioDocumentId, fields: Partial<T>): SubstrioRecord<T> | null;
+  /** Row after the write; null if absent or if the guard fails. */
+  update(id: SubstrioDocumentId, ops: SubstrioUpdate, options?: SubstrioWriteOptions): SubstrioRecord<T> | null;
+  /**
+   * One batch, ids in order; default error rolls back every insertion on a
+   * unique conflict. onConflict:'ignore' skips refused documents and returns
+   * only inserted ids. A non-object element throws TypeError naming its index.
+   * returning:true answers the inserted rows (records, in order) instead of ids.
+   */
+  insertMany(documents: Partial<T>[], options: { onConflict?: 'error' | 'ignore'; returning: true }): SubstrioRecord<T>[];
+  insertMany(documents: Partial<T>[], options?: { onConflict?: 'error' | 'ignore'; returning?: false }): string[];
+  /** Stores each document under its own `_id` (ids in input order; the same id twice gives one row, the last values win). */
+  upsertMany(key: '_id', documents: SubstrioIdentifiedDocument<T>[]): string[];
+  /** Matches on every key field; ids in input order, repeated keys share a row and later values win. */
+  upsertMany<K extends string>(key: K extends '_id' ? never : K, documents: SubstrioUpsertDocument<T>[]): string[];
+  upsertMany(key: string[], documents: SubstrioUpsertDocument<T>[]): string[];
+  /** Number written; a filter object uses updateWhere. Missing ids are not counted. */
+  updateMany(ids: SubstrioDocumentId[] | SubstrioFilter, ops: SubstrioUpdate, options?: SubstrioWriteOptions): number;
+  /** Number removed; a filter object uses deleteWhere. Missing ids are not counted. */
+  deleteMany(ids: SubstrioDocumentId[] | SubstrioFilter): number;
+  /** Updates the first match; returns the row after the write or null. */
+  findOneAndUpdate(filter: SubstrioFilter, ops: SubstrioUpdate, options?: SubstrioWriteOptions): SubstrioRecord<T> | null;
+  /** Removed document as a plain object, or null; it is no longer a record to save. */
+  findOneAndDelete(filter: SubstrioFilter): (T & { _id: string }) | null;
+  /** Replaces fields, retaining system fields; null if absent. */
+  replace(id: SubstrioDocumentId, document: Partial<T>): SubstrioRecord<T> | null;
+  /** True when the document existed. */
+  delete(id: SubstrioDocumentId): boolean;
+  count(filter?: SubstrioFilter): number;
+  /** True when a document matches; without a filter, whether the collection holds any document. */
+  exists(filter?: SubstrioFilter): boolean;
+  /** Updates the first match with plain document fields, else inserts. */
+  upsert(filter: SubstrioFilter, document: SubstrioUpsertDocument<T>): SubstrioRecord<T>;
+  /** Updates the stored document with this `_id`, else inserts it under that id. */
+  upsert(key: '_id', document: SubstrioIdentifiedDocument<T>): SubstrioRecord<T>;
+  /** The first match as it is (never written), else `document` inserted; `created` says which. */
+  findOrCreate(filter: SubstrioFilter, document: Partial<T>): { row: SubstrioRecord<T>; created: boolean };
+  /** The first match takes `update`'s plain fields, else the filter's equality fields with them are inserted; `created` says which. */
+  updateOrCreate(filter: SubstrioFilter, update: Partial<T>): { row: SubstrioRecord<T>; created: boolean };
+  /** Stores the document under the `_id` it holds: a stored document takes its fields, else it is inserted under that id. */
+  put(document: SubstrioIdentifiedDocument<T>): SubstrioRecord<T>;
+  /** put for each document: ids are returned as strings in input order. */
+  putMany(documents: SubstrioIdentifiedDocument<T>[]): string[];
+  /** Number removed. */
+  deleteWhere(filter?: SubstrioFilter, options?: { limit?: number }): number;
+  /** Number written, using the same operators as update. */
+  updateWhere(filter: SubstrioFilter, ops: SubstrioUpdate, options?: SubstrioWriteOptions): number;
+  /** Declares a text field searched by match. */
+  text(field: string): this;
+  /** Declares a prefix top-k field used by startsWith(...).top(...). */
+  top(field: string, weight: string): this;
+  /**
+   * Declares a string field (a top-level name or a dotted path such as 'profile.bio') keyword: contains/icontains of a word read the field's suffix
+   * terms (each distinct word keyed by its suffixes, each cut to termBytes, default 64), with no
+   * record read for a one-word icontains. Idempotent for the same termBytes; the field's keys are
+   * built before this returns. index.drop (kind collection, keyword true) takes it away.
+   */
+  keyword(field: string, termBytes?: number): this;
+}
+
+// The object chain: db.<collection>.eq(...).gt(...).sort(...).all(...args).
+// SubstrioChain lists exactly the methods of the engine's chain table
+// (kChainMethods, src/substrio/jsc/jsc_db_direct.cpp) and SubstrioChainStart the ones
+// a collection answers to as a chain's first call (not exists: a collection's
+// exists takes a filter and refuses a field name; the terminals first, last,
+// ids, pluck and count also run on the bare collection, see SubstrioChainStart);
+// jsc_chain_conformance_test fails when the names differ.
+export interface SubstrioChainArg {}
+export type SubstrioChainArgument = null | boolean | number | string | Date | SubstrioBinaryValue;
+export type SubstrioChainValue = SubstrioChainArgument | SubstrioChainArg;
+export type SubstrioChainBuilder = (q: SubstrioChain) => unknown;
+/** A value of a field as the documents hold it (a nested value is the value itself). */
+export type SubstrioFieldValue = null | boolean | number | string | unknown[] | Record<string, unknown>;
+/**
+ * The bytes json() or jsonFirst() answers: already a JSON document, not a value to read. `toString()`
+ * is the one way to get the text; `length` is its byte length. Returned from a function (or passed to
+ * `new Response(body, init)`) it is sent as the response body with no further encoding; used a second
+ * time that way, the call fails instead of sending an empty body.
+ */
+export interface SubstrioJsonBody {
+  readonly length: number;
+  toString(): string;
+}
+/**
+ * Options of values(), distinct(field) and facets(). `top`: the most values
+ * per field (facets: 10 by default; values and distinct: every value; 0 is
+ * every value, and past 65536 values the call throws: page with `after`).
+ * `order`: 'value' (numbers, then strings in byte order; the default of values
+ * and distinct) or 'count' (most first, ties by value; the default of facets).
+ * `missing`: true adds one last { value: null, count } entry for the documents
+ * with no value. `after` (value order only): the answer starts past this value.
+ */
+/** sort's options: where the documents with no value (null or missing) go. 'last' is the default. */
+export interface SubstrioSortOptions {
+  nulls: 'first' | 'last';
+}
+export interface SubstrioValuesOptions {
+  top?: number;
+  order?: 'value' | 'count';
+  missing?: boolean;
+  after?: null | boolean | number | string;
+}
+/** A field's values and the number of matching documents holding each; `more`: `top` cut them. */
+export interface SubstrioValueCounts {
+  values: { value: SubstrioFieldValue; count: number }[];
+  more: boolean;
+}
+/** What a refused write of a unique field throws (collection.unique). */
+export interface SubstrioUniqueError extends Error {
+  name: 'UniqueError';
+  code: 'unique';
+  collection: string;
+  field: string;
+  /** The held value, as text. */
+  value: string;
+}
+
+/** One member of a unique space (db.uniqueSpace): a field, or dotted path, of a collection. */
+export interface SubstrioUniqueSpaceMember {
+  collection: string;
+  field: string;
+}
+
+/** A field rule of a collection schema (collection.schema). */
+export interface SubstrioSchemaRule {
+  field: string;
+  /** Leave it out, or 'any', for any type. */
+  type?: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'datetime' | 'any';
+  required?: boolean;
+  nullable?: boolean;
+  min?: number;
+  max?: number;
+  pattern?: string;
+  enum?: string[];
+}
+/**
+ * A rule across fields. A field is present when it holds a value other than null. Every field named has a
+ * rule of type string, number, boolean or datetime in the same schema.
+ */
+export type SubstrioSchemaConstraint =
+  | { kind: 'exactly_one' | 'at_least_one' | 'at_most_one'; fields: string[] }
+  | { kind: 'required_when'; field: string; equals: string; required?: string[]; forbidden?: string[] };
+/** A collection's schema (collection.schema). */
+export interface SubstrioSchemaDefinition {
+  strict?: boolean;
+  rules?: SubstrioSchemaRule[];
+  constraints?: SubstrioSchemaConstraint[];
+}
+/** What a write that breaks a collection's schema throws. */
+export interface SubstrioSchemaError extends Error {
+  name: 'SchemaError';
+  code: 'schema';
+  collection: string;
+  violations: { field: string; message: string; constraint?: SubstrioSchemaConstraint['kind']; fields?: string[] }[];
+}
+/** What declaring a constraint over documents that already break it throws (collection.schema). */
+export interface SubstrioSchemaViolatorsError extends Error {
+  name: 'SchemaViolatorsError';
+  code: 'schema_violators';
+  collection: string;
+  /** How many stored documents break a constraint. */
+  count: number;
+  /** The id of the first of them. */
+  first: string;
+}
+
+/** Declarations a collection takes. */
+export interface SubstrioCollectionDeclarations {
+  /**
+   * Reads the collection's schema, or null when it has none.
+   */
+  schema(): (SubstrioSchemaDefinition & { collection: string; strict: boolean }) | null;
+  /**
+   * Sets the collection's schema, replacing the old one (the same declaration as schema.update; returns the
+   * collection). `rules` and `constraints` (at least one rule or constraint); a rule's type is a TypeError
+   * unless it is one of the listed words. Declaring a constraint over documents that already break it throws
+   * a SubstrioSchemaViolatorsError and declares nothing, unless `existing` is 'allow'.
+   */
+  schema(definition: SubstrioSchemaDefinition & { existing?: 'refuse' | 'allow' }): this;
+  /**
+   * Declares the field (a top-level name or a dotted path such as 'stripe.account_id') unique (idempotent; returns the collection):
+   * no two live documents hold the same value. An insert, upsert, put, update,
+   * updateWhere, row save, claim or setAll that would make two hold one value
+   * throws a SubstrioUniqueError and writes nothing for that document. A missing
+   * field, null and an empty string never conflict; rewriting a document's own
+   * value does not either. $inc, $mul, $min, $max and $push on the field are a
+   * TypeError; $unset is allowed. Declaring over documents that already share
+   * a value throws a SubstrioUniqueError and declares nothing. A field name or a
+   * dotted path; an array of them declares a compound (the tuple of their values
+   * is unique, and the error also carries `fields` and `values`). `nulls`
+   * ('skip', the default, or 'count') says how a null or missing member counts:
+   * skipped (a document with no value for a member is not checked) or as one
+   * value (two documents with the same other members and a null member conflict;
+   * top-level fields only). A member holding several values (an array) is a
+   * TypeError, as is declaring the same fields with the other `nulls`.
+   * `within` ('collection', the default, 'document' or 'both') says where the
+   * value must be unique: across the collection, inside each document (an array
+   * at the path may not hold it twice; documents may share it) or both. A
+   * document or both declaration is one field with `nulls` skip; a compound or
+   * counted one is a TypeError, as is declaring the same fields with another
+   * `within`.
+   */
+  unique(field: string | string[], options?: { nulls?: 'skip' | 'count'; within?: 'collection' | 'document' | 'both' }): this;
+  /**
+   * Declares that a document is gone `after` milliseconds after the date its field (a name or dotted path)
+   * holds (`after` 0: the date is the time it expires; returns the collection). A document without a value in
+   * the field never expires. From the moment a document expires every read hides it (find, count, joins,
+   * sorted reads, get, findById, exists); the collection's sweeper then deletes it at its time, with its
+   * keys, counters and unique values, and publishes its delete. A unique value an expired document holds is
+   * free for a new write. The field is declared indexed. Declaring over documents that hold a value that is
+   * not a date throws a TypeError naming the first, unless `existing` is 'allow'. Declaring again replaces
+   * the period.
+   */
+  expire(field: string, options?: { after?: number; existing?: 'refuse' | 'allow' }): this;
+  /** Takes the expiry declaration away (the field's keys stay; a pending sweep is cancelled); returns the collection. */
+  dropExpiry(): this;
+  /** Keys each element object of the array field by the values of `members` (in that order): an elemMatch of equalities on the first members and one range on the next reads one key range. */
+  elements(field: string, members: string[]): this;
+  /** Takes an element declaration away (its keys, id and record); true when it was declared, false when it was not. */
+  dropElements(field: string, members: string[]): boolean;
+  /** The collection's element declarations, as index.list lists them. */
+  elementIndexes(): Array<{ kind: 'collection'; collection: string; field: string; elements: string[]; state: 'none' | 'building' | 'ready'; reason: string | null }>;
+  /** Declares a compound index: an equality on every `lead` field and a range or order on the `order` field read one key range (plain top-level field names, none twice). */
+  compound(lead: string[], order: string): this;
+  /** Takes a compound declaration away (its keys, id and record); true when it was declared, false when it was not. */
+  dropCompound(lead: string[], order: string): boolean;
+  /** The collection's compound declarations, as index.list lists them. */
+  compoundIndexes(): Array<{ kind: 'collection'; collection: string; compound: string[]; state: 'none' | 'building' | 'ready'; reason: string | null }>;
+  /** Declares a live count and sum per group (an absent or empty `group` is the whole collection as one group), kept current by every write; idempotent for the same name and shape, a TypeError naming the refusal for a different one; returns the declaration's state. */
+  aggregate(name: string, declaration: { group?: Array<string | { field: string; step?: number }>; metrics: Record<string, 'count' | { sum: string }>; where?: string }): 'none' | 'building' | 'ready';
+  /** Takes an aggregate declaration away (its group records with it); true when it was declared, false when it was not. */
+  dropAggregate(name: string): boolean;
+  /** The collection's aggregate declarations, as index.list lists them. */
+  aggregates(): Array<{ kind: 'aggregate'; collection: string; name: string; group: Array<string | { field: string; step: number }>; metrics: Record<string, 'count' | { sum: string }>; where?: string; state: 'none' | 'building' | 'ready'; reason: string | null }>;
+  /** Declares a one-to-many relation: `key` is the field of `target` holding the id of a document of this collection. */
+  hasMany(name: string, target: unknown, key: string): this;
+  /** Declares a one-to-one relation: `key` is the field of `target` holding the id of a document of this collection. */
+  hasOne(name: string, target: unknown, key: string): this;
+  /** Declares a relation to one document: `key` is the field of this collection holding the id of a document of `target`. */
+  belongsTo(name: string, target: unknown, key: string): this;
+  /**
+   * Declares a many-to-many relation named `as`, held by one document per link in the `through`
+   * collection: `key` is the field of those documents holding this collection's id and `otherKey` the one
+   * holding the target's id (each defaults to the collection's name in the singular with Id: 'users' is
+   * 'userId'). with(as) loads the related records, withCount(as) their number as `<as>Count`,
+   * whereHas(as, q => ...) and whereNone(as) filter by them; record.link(as, other) and
+   * record.unlink(as, other) write the links.
+   */
+  belongsToMany(target: unknown, options: SubstrioManyToManyOptions): this;
+  /**
+   * Declares a named scope: `Users.scope('active', c => c.eq('status', 'active'))`, then
+   * `Users.active()` starts a chain with the scope applied and `chain.active()` adds it to
+   * any chain of the collection (also inside and, or and not). The function is called
+   * with the chain at that moment and may add any conditions, a sort or a limit; scopes
+   * compose in any order. Declaring a name again replaces the scope. A name that is a
+   * built-in method of a collection or chain is a TypeError, and so is calling a scope
+   * on a collection that has not declared it. Returns the collection.
+   */
+  scope(name: string, define: (chain: SubstrioChain) => unknown): this;
+}
+
+export interface SubstrioManyToManyOptions {
+  through: unknown;
+  as: string;
+  key?: string;
+  otherKey?: string;
+}
+
+/** The link methods of a record that has a many-to-many relation declared on its collection. */
+export interface SubstrioRecordLinks {
+  /** Links this record to `other` (a record or its _id) through the relation `name`: one write on the through collection, none when the link exists. Answers this record. */
+  link(name: string, other: { _id: string } | string): this;
+  /** Removes the link to `other` through the relation `name`: one write on the through collection, none when there is no link. Answers this record. */
+  unlink(name: string, other: { _id: string } | string): this;
+}
+
+/** One condition of a chain as explain() reports it: groups and elemMatch list their conditions. */
+export interface SubstrioExplainCondition {
+  op: string;
+  field?: string;
+  /** The second field of a field comparison (gtField and the others). */
+  other?: string;
+  conditions?: SubstrioExplainCondition[];
+}
+/**
+ * How a chain is answered (chain.explain()), from the route's own record of what it
+ * decided. route: `direct` (the document route read value keys), `columns` (the
+ * executor over the column mirror) or `relational` (the SQL engine, or a chain that
+ * runs no rows). driver: what named the candidate rows: `id` (the ids of an _id
+ * condition), `postings` (an eq or in condition's posting lists), `keyedSets` (row sets
+ * of keyed conditions combined), `sortWalk` (the sort field's keys in order) or
+ * `counter` (a count read from the counters of one equality's keys: no row read); null
+ * when no key drove. `keys: 'trigram'` says a substring leaf read its candidates from
+ * the trigram keys. residual: the top-level conditions tested on each candidate's
+ * stored record (all of them when no key proves any). aggregate: where a grouped or
+ * folded answer came from, `keys` (the field's value keys, no record read) or `rows`
+ * (each matched record read once); present on the direct route of an aggregate only.
+ * declined: why the direct route did not answer, when it did not (see SubstrioExplainDecline).
+ */
+export interface SubstrioExplain {
+  route: 'direct' | 'columns' | 'relational';
+  aggregate?: 'keys' | 'rows';
+  driver: { field: string | null; kind: 'id' | 'postings' | 'keyedSets' | 'sortWalk' | 'counter'; keys?: 'trigram' } | null;
+  conditions: SubstrioExplainCondition[];
+  residual: SubstrioExplainCondition[];
+  sort: { field: string; direction: 'asc' | 'desc' }[];
+  skip: number;
+  limit: number | null;
+  declined?: SubstrioExplainDecline;
+}
+/** Why the direct route declined a chain (SubstrioExplain.declined); the columns route or the engine answered it. */
+export type SubstrioExplainDecline =
+  | 'Shape' | 'Bind' | 'NoKeyedLeaf' | 'SortField' | 'SortKinds' | 'SortFilterUnkeyed' | 'SortUnbounded'
+  | 'Join' | 'Aggregate' | 'MixedIds' | 'Relation';
+
+/**
+ * A field name of a leaf or a sort key. Besides a top-level field it may be a nested path, the member of a
+ * document held in a field ('address.city', 'stats.views'). A top-level field named exactly that text wins;
+ * a missing or null member, or a step that is not a document, reads as a missing value; an array anywhere
+ * on the path is never traversed (a document holding one never matches, and once an array is keyed under
+ * the path the chain throws 'a nested path does not traverse arrays'). A path is for eq, neq, gt, gte, lt,
+ * lte, in, nin, between, exists, startsWith, ieq, iin, istartsWith, like, ilike, contains, icontains and
+ * endsWith, and for sort keys; select, groupBy, aggregates, joins and the array leaves take top-level
+ * names only.
+ */
+export type SubstrioFieldPath = string;
+
+/** A stored document as a chain reads it: the type's own fields and its string `_id`. */
+export type SubstrioDocument<T> = Omit<T, '_id'> & { _id: string };
+/**
+ * What a chain's rows are. 'records' (the default) is the collection's own documents as records (save, set
+ * and inc work on them); a select, join, group, bucket or compound answers plain rows of the shape given.
+ */
+export type SubstrioRowShape = 'records' | object;
+/** A plain row: the fields of a group (its keys and aggregate aliases), a compound's columns, a path's members. */
+export type SubstrioPlainRow = Record<string, unknown>;
+/** A row of a join: the document's fields and the joined document under its `as` name (null for a left join with no match). */
+export type SubstrioJoinedRow<T> = Partial<SubstrioDocument<T>> & Record<string, unknown>;
+/** The result of a record chain's all(): an Array of records with the result methods (SubstrioQueryResult). */
+export type SubstrioRows<T = Record<string, unknown>> = SubstrioQueryResult<T> & SubstrioRecord<T>[];
+/** One row of a chain of the given shape. */
+export type SubstrioChainRow<T, Shape> = Shape extends 'records' ? SubstrioRecord<T> : Shape;
+/** The rows of a chain of the given shape, as all() answers them. */
+export type SubstrioChainRows<T, Shape> = Shape extends 'records' ? SubstrioRows<T> : Shape[];
+/** A column of columns(): see SubstrioChain.columns. */
+export type SubstrioColumn<V> = [NonNullable<V>] extends [number | boolean]
+  ? Float64Array | Array<NonNullable<V> | (number extends NonNullable<V> ? bigint : never) | null>
+  : Array<NonNullable<V> | null>;
+/** One column per field of the shape. */
+export type SubstrioColumns<S> = { [K in keyof S]-?: SubstrioColumn<S[K]> };
+/** What columns() answers: a record chain, every field and `_id`; a select, the selected fields. */
+export type SubstrioChainColumns<T, Shape> = Shape extends 'records'
+  ? { _id: string[] } & SubstrioColumns<Omit<T, '_id'>>
+  : SubstrioColumns<Shape>;
+
+export interface SubstrioChain<T = Record<string, unknown>, Shape extends SubstrioRowShape = 'records', Grouped extends boolean = false> {
+  /** A binary (an ArrayBuffer or a view such as a Uint8Array) is compared by its bytes: eq, neq, ne, in and nin take it. */
+  eq(field: SubstrioFieldPath, value: SubstrioChainValue | SubstrioBinaryValue): this;
+  neq(field: SubstrioFieldPath, value: SubstrioChainValue | SubstrioBinaryValue): this;
+  /** Alias of neq. */
+  ne(field: SubstrioFieldPath, value: SubstrioChainValue | SubstrioBinaryValue): this;
+  gt(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  gte(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  /** Alias of gte. */
+  ge(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  lt(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  lte(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  /** Alias of lte. */
+  le(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  in(field: SubstrioFieldPath, values: (SubstrioChainValue | SubstrioBinaryValue)[]): this;
+  nin(field: SubstrioFieldPath, values: (SubstrioChainValue | SubstrioBinaryValue)[]): this;
+  /** The condition that the field is present (present = true) or absent (false). */
+  exists(field: SubstrioFieldPath, present?: boolean): this;
+  /** With no argument, a terminal: whether any document matches. */
+  exists(): boolean;
+  startsWith(field: SubstrioFieldPath, value: SubstrioChainValue): this;
+  /** The array field holds every one of the values as an element (the same kind: 1 is not '1'). An empty list matches every array. */
+  containsAll(field: string, values: SubstrioChainValue[]): this;
+  /** The array field holds at least one of the values as an element. An empty list matches nothing. */
+  containsAny(field: string, values: SubstrioChainValue[]): this;
+  /** The array field has exactly n elements. */
+  size(field: string, n: number): this;
+  /** The array field has more than n elements. */
+  sizeGt(field: string, n: number): this;
+  /** The array field has fewer than n elements. */
+  sizeLt(field: string, n: number): this;
+  /**
+   * The array of objects has an element satisfying every property of the filter: a value is an
+   * equality, an object of operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $startsWith,
+   * $endsWith, $contains, $icontains) one condition each.
+   */
+  elemMatch(field: string, filter: Record<string, unknown>): this;
+  /**
+   * The string field ends with the text (case sensitive). endsWith, contains, icontains and like / ilike read their
+   * candidates from the field's trigram keys (built by the first such query, kept by every write), each candidate
+   * then tested on its record. A text under 3 bytes (a like pattern's longest literal) has no key: beside another
+   * keyed condition it is a per-candidate test, alone it throws (never a walk over every document).
+   */
+  endsWith(field: SubstrioFieldPath, text: string): this;
+  /** The string field holds the text (case sensitive); keyed by trigrams, see endsWith. */
+  contains(field: SubstrioFieldPath, text: string): this;
+  /** The string field holds the text, ASCII letters compared without case; keyed by trigrams, see endsWith. */
+  icontains(field: SubstrioFieldPath, text: string): this;
+  /**
+   * The string field equals the text, ASCII letters compared without case (`É` and `é` differ). A field
+   * that is not a string never matches. Answered from a folded key of the field, built when first asked.
+   */
+  ieq(field: SubstrioFieldPath, text: string): this;
+  /** The string field equals one of the texts, ASCII letters compared without case (see ieq). */
+  iin(field: SubstrioFieldPath, texts: string[]): this;
+  /** The string field starts with the text, ASCII letters compared without case (see ieq). */
+  istartsWith(field: SubstrioFieldPath, text: string): this;
+  /** The string field matches the pattern somewhere (a string or RegExp, ECMAScript grammar; only the i flag). */
+  regex(field: string, pattern: string | RegExp): this;
+  /** Field a equals field b of the same document (both hold a value; a number equals a number, a string a string). */
+  eqField(field: string, other: string): this;
+  neField(field: string, other: string): this;
+  gtField(field: string, other: string): this;
+  gteField(field: string, other: string): this;
+  ltField(field: string, other: string): this;
+  lteField(field: string, other: string): this;
+  /** The number (milliseconds) field falls on the day of the date, UTC or the zone given as minutes east of UTC. */
+  onDay(field: string, date: Date | number, zone?: number): this;
+  /** The field falls in the month (1 to 12) of the year, UTC or in the zone. */
+  inMonth(field: string, year: number, month: number, zone?: number): this;
+  /** The field falls in the last n calendar days (today and the n - 1 before it) up to now, when the chain is built. */
+  lastDays(field: string, n: number, zone?: number): this;
+  /** n distinct documents of the answer picked at random, in the answer's order (all of them when fewer match). */
+  sample(n: number, ...args: SubstrioChainArgument[]): SubstrioChainRows<T, Shape>;
+  /** One document of the answer at random, or null when none match. */
+  random(...args: SubstrioChainArgument[]): SubstrioChainRow<T, Shape> | null;
+  /**
+   * fn(document, index) for each document of the answer in its order, stopping when fn returns
+   * false; fn may write to the collection. Returns how many documents fn was given.
+   */
+  each(fn: (document: SubstrioChainRow<T, Shape>, index: number) => unknown, ...args: SubstrioChainArgument[]): number;
+  /** fn(documents, page) for each page of n documents of the answer, stopping when fn returns false. Returns the documents given. */
+  chunk(n: number, fn: (documents: SubstrioChainRow<T, Shape>[], page: number) => unknown, ...args: SubstrioChainArgument[]): number;
+  /** How the chain is answered (runs it once). */
+  explain(...args: SubstrioChainArgument[]): SubstrioExplain;
+  /**
+   * The documents whose text field holds every word of text (mode 'all', the
+   * default) or at least one ('any'; with no sort they come ranked by distinct
+   * words matched, ties in row order). Words are runs of letters, digits and
+   * '_', ASCII case folded. The field is declared with collection.text(field);
+   * any other field is an error.
+   */
+  match(field: string, text: SubstrioChainValue, options?: { mode?: 'all' | 'any' } | 'all' | 'any'): this;
+  /**
+   * The count documents of greatest numeric weight, ties in row order: sets
+   * the chain's sort and limit, and leaves out documents whose weight is not a
+   * number. After startsWith(field, prefix) on a field declared with
+   * collection.top(field, weight) a prefix of 1 to 3 bytes reads count keys.
+   */
+  top(count: number, weight: string): this;
+  /**
+   * The k nearest documents to the vector, ranked nearest first beside the other conditions. The field has a
+   * vector index; the vector is a non-empty array of numbers and k a count from 1.
+   */
+  knn(field: SubstrioFieldPath, vector: number[], k: number): this;
+  /**
+   * The k (default 10) documents nearest to the point (latitude, longitude), ranked nearest first. The field has a
+   * geo index.
+   */
+  near(field: SubstrioFieldPath, latitude: number, longitude: number, k?: number): this;
+  /**
+   * The documents whose point lies inside the box: `low` and `high` are its two corners, non-empty arrays of
+   * numbers of one length (one number per dimension). The field has a geo or vector index.
+   */
+  withinBox(field: SubstrioFieldPath, low: number[], high: number[]): this;
+  /**
+   * The documents whose point lies within `radius` (above 0) of `center`, a non-empty array of numbers. The field
+   * has a geo or vector index.
+   */
+  withinSphere(field: SubstrioFieldPath, center: number[], radius: number): this;
+  /**
+   * The k documents of greatest dot product with a sparse vector (`indices` and `values` of one length, not empty),
+   * ranked best first. The field has a sparse index.
+   */
+  sparseKnn(field: SubstrioFieldPath, vector: { indices: number[]; values: number[] }, k: number): this;
+  /**
+   * The documents whose text field holds the text's words as a phrase, or with `fuzzy` (true, or a nonzero number)
+   * the documents a fuzzy match of the text reaches. The field has a trigram index. Words are runs of ASCII letters
+   * and digits, without case; any other character (punctuation, space, non-ASCII) separates words, and stop words and
+   * 1-letter words are skipped on both sides. The phrase's words must stand adjacent and in order: the first ends a
+   * word, the last begins one, middle words are whole, a single word lies inside a word, and a word under 3 letters
+   * matches only an equal word. A text of only stop words matches nothing.
+   */
+  textNear(field: SubstrioFieldPath, text: string, fuzzy?: boolean | number): this;
+  /**
+   * The collection's $search in its vector mode: the text is embedded by the collection's RAG configuration and the
+   * k (default 50) documents nearest to the embedding in the RAG vector field are kept, ranked nearest first. The
+   * hybrid mode, decay, boost_feedback and strict_model are options of the HTTP $search, not of a chain (a chain
+   * that names them throws).
+   */
+  search(text: string, options?: { k?: number; mode?: 'vector' }): this;
+  and(...conditions: SubstrioChainBuilder[]): this;
+  or(...conditions: SubstrioChainBuilder[]): this;
+  not(...conditions: SubstrioChainBuilder[]): this;
+  /** The conditions of a filter object (the operators find takes), ANDed with the chain's: where({ n: { $lt: 5 } }). */
+  where(filter: SubstrioFilter): this;
+  /**
+   * direction: 1, 'asc' or false ascending (the default); -1, 'desc' or true
+   * descending. Repeated calls (or an array of [field, direction]) add keys in
+   * order; several keys make the chain relational (SQL semantics apply). A
+   * field may be 'as.field' of a join. The documents with no value (null or
+   * missing) come last in either direction; { nulls: 'first' } puts them first
+   * (in id order), on a plain single-key sort of the collection's own field
+   * only: it is refused with several keys, a cursor page, last() or an aggregate.
+   */
+  sort(field: SubstrioFieldPath, direction?: 1 | -1 | 'asc' | 'desc' | boolean, options?: SubstrioSortOptions): this;
+  /**
+   * Several sort keys (chained `sort` calls, or the array form) of the collection's own fields: the first
+   * key's order, each run of equal values ordered by the next key, a document with no value (null or
+   * missing) after those with one on every key in either direction, ties in id order. They run on the
+   * keyed executor, not SQL; a cursor page (`page`, `pages`) refuses them.
+   */
+  sort(keys: Array<string | [string, (1 | -1 | 'asc' | 'desc' | boolean)?]>): this;
+  /** Alias of sort. */
+  sort_by(field: string, direction?: 1 | -1 | 'asc' | 'desc' | boolean, options?: SubstrioSortOptions): this;
+  sort_by(keys: Array<string | [string, (1 | -1 | 'asc' | 'desc' | boolean)?]>): this;
+  /**
+   * Groups the matching documents by a field's value: sum, avg, min, max and
+   * count then answer per group (see SubstrioGroupedChain).
+   */
+  group_by(field: string): SubstrioGroupedChain<T>;
+  limit(count: number): this;
+  skip(count: number): this;
+  /**
+   * The queue terminal: takes up to `n` (an integer from 1) documents the
+   * chain selects, in its sort order, and applies `ops` (what update(id, ops)
+   * takes: $set, $inc, $mul, $min, $max, $unset) to each one, guarded by the
+   * chain's own conditions so two claimers never both claim a document.
+   * Resolves to the claimed rows as all() answers them, after the update, in
+   * claim order; [] when none. Refused: a join, select, groupBy, skip, limit,
+   * and a condition a guard cannot re-test (or, not, in, between, like, ...).
+   */
+  claim(n: number, ops: Record<string, unknown>, ...args: SubstrioChainValue[]): SubstrioChainRows<T, Shape>;
+  /**
+   * Applies `ops` (what updateWhere takes: update operators, or plain fields to
+   * set) to every document the chain answers; its sort, skip and limit choose
+   * the documents as they do for ids(). Returns the number written. Refused:
+   * a join, with, groupBy, distinct or compound chain. A trailing { returning: true }
+   * answers the rows written (records, in order) instead of the count.
+   */
+  update(ops: Record<string, unknown>, ...args: SubstrioChainArgument[]): number;
+  update(ops: Record<string, unknown>, ...args: [...SubstrioChainArgument[], { returning: true }]): SubstrioRecord<T>[];
+  /** Deletes every document the chain answers (the same documents as ids()); returns the number removed. */
+  delete(...args: SubstrioChainArgument[]): number;
+  /** update({ $inc: { [field]: n } }) with n = 1 by default (a finite number, or a BigInt inside int64); returns the number written. */
+  increment(field: string, n?: number | bigint, ...args: SubstrioChainArgument[]): number;
+  /** With a trailing { returning: true }: the rows written (records, in order). */
+  increment(field: string, n: number | bigint, ...args: [...SubstrioChainArgument[], { returning: true }]): SubstrioRecord<T>[];
+  /** update({ $inc: { [field]: -n } }) with n = 1 by default; returns the number written. */
+  decrement(field: string, n?: number | bigint, ...args: SubstrioChainArgument[]): number;
+  /** With a trailing { returning: true }: the rows written (records, in order). */
+  decrement(field: string, n: number | bigint, ...args: [...SubstrioChainArgument[], { returning: true }]): SubstrioRecord<T>[];
+  /** first(), but a chain that matches nothing throws an Error named NotFoundError. */
+  firstOrFail(...args: SubstrioChainArgument[]): SubstrioChainRow<T, Shape>;
+  /** The field of the first row the chain answers; undefined when it matches nothing or the row has no such field. */
+  value<K extends keyof T & string>(field: K, ...args: SubstrioChainArgument[]): T[K] | undefined;
+  value(field: SubstrioFieldPath, ...args: SubstrioChainArgument[]): unknown;
+  /** The negation of exists(): true when no document matches. */
+  missing(): boolean;
+  /**
+   * One page of the chain in its sort order (or id order when unsorted).
+   * `next` and `prev` are opaque cursors bound to this query: pass `next` as
+   * `after` for the following page (null on the last page), `prev` as `before`
+   * for the page ahead. A page at any depth costs what the first page costs on
+   * a keyed number sort. `skip` cannot be combined with a page.
+   */
+  page(options: { size: number; after?: string | null; before?: string | null; total?: boolean }, ...args: SubstrioChainValue[]):
+    { rows: SubstrioChainRows<T, Shape>; next: string | null; prev: string | null; total?: number };
+  /** Every page of the chain in turn, as an iterator of row arrays. */
+  pages(options: { size: number }, ...args: SubstrioChainValue[]): IterableIterator<SubstrioChainRows<T, Shape>>;
+  /**
+   * The fields each row carries. A name with a dot that no join alias spells is a nested path: select('name', 'address.city')
+   * answers `{name, address: {city}}`, the member read in place from each document; a member the document lacks (a
+   * missing step, a scalar or an array on the path) is absent from the row, a stored null is null. Only a plain chain
+   * answers a path (not with join, groupBy, distinct or columns()).
+   */
+  select<K extends keyof SubstrioDocument<T> & string>(...fields: K[] | [K[]]): SubstrioChain<T, Pick<SubstrioDocument<T>, K>>;
+  select(...fields: string[] | [string[]]): SubstrioChain<T, SubstrioPlainRow>;
+  join(collection: string, localField: string, foreignField: string, as: string): SubstrioChain<T, SubstrioJoinedRow<T>>;
+  // Relational chains: a chain that uses any of the methods below runs through
+  // the SQL engine and SQL semantics apply to it (a null never compares equal,
+  // a root document
+  // appears once per joined match). A chain that uses none keeps the document
+  // rules of the methods above.
+  /** SQL semantics apply: every match of the foreign collection; a document with none is dropped. */
+  innerJoin(collection: string, localField: string, foreignField: string, as: string): SubstrioChain<T, SubstrioJoinedRow<T>>;
+  /** SQL semantics apply: every match of the foreign collection; a document with none stays, its `as` null. */
+  leftJoin(collection: string, localField: string, foreignField: string, as: string): SubstrioChain<T, SubstrioJoinedRow<T>>;
+  /** Each row carries the related records declared on the collection (hasMany: an array; hasOne and belongsTo: a record or null). Without projection these remain collection records. */
+  with(...relations: (string | string[] | ((q: SubstrioChain<T>) => SubstrioChain<T>))[]): this;
+  /** The documents that have a related record of the relation (matching the function's chain when given); the related side is read when called. */
+  whereHas(relation: string, constraint?: (q: SubstrioChain) => SubstrioChain): this;
+  /**
+   * The documents whose number of related records of a hasMany or hasOne relation compares to `n` ('>=', '>', '=',
+   * '<', '<='; `n` a whole number from 0): one count lookup per candidate document, no related key set is built.
+   * An owner with no related record has 0. Not with sort, nor inside and, or, not; a plain run (all, first, count, ids, pluck) answers it.
+   */
+  whereHas(relation: string, op: '>=' | '>' | '=' | '<' | '<=', n: number): this;
+  /** The documents that have no related record of the relation (matching the function's chain when given). */
+  whereNone(relation: string, constraint?: (q: SubstrioChain) => SubstrioChain): this;
+  /** Each row carries the number of related records of a hasMany relation as `<name>Count`, with no record read. */
+  withCount(...relations: (string | string[])[]): this;
+  /** The distinct values of a field among the matching documents (values() without the counts). */
+  distinct(field: string, options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): SubstrioFieldValue[];
+  /**
+   * Each row of select() once; answers plain rows. select(fields).distinct() of the collection's own fields
+   * is the groups of those fields (no group or aggregate), read from the rows the filter yields by the
+   * aggregate stage (not a relational chain: explain().route is 'direct'); whole rows and joined fields keep
+   * SQL semantics. An integer from 2^53 up in a distinct or grouped key is returned exact, as a BigInt.
+   */
+  distinct(): SubstrioChain<T, Shape extends 'records' ? SubstrioJoinedRow<T> : Shape, Grouped>;
+  /** SQL semantics apply: groups by fields ('as.field' names a join's); with count/sum/avg/min/max selectors all() answers one plain row per group. */
+  groupBy(...fields: string[] | [string[]]): SubstrioChain<T, SubstrioPlainRow, true>;
+  /**
+   * A group key that cuts a field's numbers (or dates, in ms) into buckets of `step`: a number, or text such as
+   * '1h', '1d', '1w', '30m', '15s', '250ms'. The group's value is the bucket's first value (floor(v / step) * step);
+   * rows with no number are one null group. `fill: true` also answers the empty buckets between the first and
+   * the last. Like groupBy it takes count, sum, avg, min and max after it.
+   */
+  bucket(field: string, step: number | string, options?: { fill?: boolean }): SubstrioChain<T, SubstrioPlainRow, true>;
+  /** bucket(field, step, options) with a count: rows are { [field]: bucket start, count }. */
+  histogram(field: string, step: number | string, options?: { fill?: boolean }): SubstrioChain<T, SubstrioPlainRow, true>;
+  /**
+   * The first `n` documents of each group of `groupField` in `sortField`'s order (direction 1, -1, 'asc' or
+   * 'desc'; ascending by default), the groups in value order. Each group is an ordered key walk stopped at `n`
+   * rows, never a sort of all the rows. Documents with no group value are in no group. The chain holds
+   * conditions only (no sort, skip, limit or select).
+   */
+  topPerGroup(groupField: string, n: number, sortField: string, direction?: 1 | -1 | 'asc' | 'desc', ...args: SubstrioChainArgument[]): SubstrioChainRows<T, Shape>;
+  /** How many different values the field holds among the matching documents (null and missing do not count). */
+  countDistinct(field: string, ...args: SubstrioChainArgument[]): number;
+  /** SQL semantics apply: a condition over a group key or an aggregate alias; op is '=', '!=', '>', '>=', '<' or '<='. */
+  having(field: string, op: '=' | '==' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne' | 'neq' | 'gt' | 'gte' | 'ge' | 'lt' | 'lte' | 'le', value: SubstrioChainValue): this;
+  /**
+   * `%` any run of characters, `_` any one character, a backslash makes the next character literal. Case-sensitive;
+   * a document whose field is not a string never matches. Run by the executor: `abc%` is startsWith, `%abc` endsWith,
+   * `%abc%` contains and `abc` eq (keyed); any other pattern tests each candidate, behind a startsWith of its literal
+   * prefix. A pattern is a string (or an argument). Wherever the chain runs through SQL (a subquery, a compound, a join the document route declines) it is refused, as contains and regex are.
+   */
+  like(field: SubstrioFieldPath, pattern: SubstrioChainValue): this;
+  /** like folding ASCII letters only (as icontains does): `É` and `é` differ. */
+  ilike(field: SubstrioFieldPath, pattern: SubstrioChainValue): this;
+  /**
+   * low <= field <= high, both bounds included, run by the executor as gte(low) and lte(high) of one field; a
+   * document with a null or missing field never matches, and a null bound is refused. (SQL semantics apply
+   * to a joined field's between and to having.)
+   */
+  between(field: SubstrioFieldPath, low: SubstrioChainValue, high: SubstrioChainValue): this;
+  /** SQL semantics apply: IN over another chain's field (a null in it makes notInQuery match nothing). The chain is read as it is now. */
+  inQuery(field: SubstrioFieldPath, chain: SubstrioChain<any, any>, chainField: string): this;
+  /** SQL semantics apply: NOT IN over another chain's field. */
+  notInQuery(field: string, chain: SubstrioChain<any, any>, chainField: string): this;
+  /** SQL semantics apply: every document when the chain has one, none otherwise. */
+  existsQuery(chain: SubstrioChain<any, any>): this;
+  /** SQL semantics apply: the rows of both chains' select() fields, duplicates removed; answers plain rows. The other chain cannot itself be a compound yet (flatten it: a.union(b).union(c)) and cannot carry its own sort, skip or limit yet: this chain's apply to the whole compound. */
+  union(chain: SubstrioChain<any, any>): SubstrioChain<T, SubstrioPlainRow>;
+  /** SQL semantics apply: the rows of both chains' select() fields, duplicates kept. The other chain cannot itself be a compound yet or carry its own sort, skip or limit yet. */
+  unionAll(chain: SubstrioChain<any, any>): SubstrioChain<T, SubstrioPlainRow>;
+  /** SQL semantics apply: the rows both chains have. The other chain cannot itself be a compound yet or carry its own sort, skip or limit yet. */
+  intersect(chain: SubstrioChain<any, any>): SubstrioChain<T, SubstrioPlainRow>;
+  /** SQL semantics apply: the rows this chain has and the other does not. The other chain cannot itself be a compound yet or carry its own sort, skip or limit yet. */
+  except(chain: SubstrioChain<any, any>): SubstrioChain<T, SubstrioPlainRow>;
+  all(...args: SubstrioChainArgument[]): SubstrioChainRows<T, Shape>;
+  first(...args: SubstrioChainArgument[]): SubstrioChainRow<T, Shape> | null;
+  /**
+   * The JSON array of exactly the rows all() answers, in the same order, as one SubstrioJsonBody: no
+   * JavaScript object is built per row. Not yet for a chain with select, a join, with, whereHas,
+   * whereNone, groupBy or a compound (union, intersect, except, distinct) or window (bucket,
+   * histogram): throws naming the first one it finds.
+   */
+  json(...args: SubstrioChainArgument[]): SubstrioJsonBody;
+  /** The one object first() answers, or the four bytes `null`, as a SubstrioJsonBody. Same restrictions as json(). */
+  jsonFirst(...args: SubstrioChainArgument[]): SubstrioJsonBody;
+  /**
+   * The last row in the chain's order, or null. A sorted chain reads its reversed walk (no walk of
+   * all rows); a chain with no condition, sort or window reads the end of the collection.
+   */
+  last(...args: SubstrioChainArgument[]): SubstrioChainRow<T, Shape> | null;
+  /**
+   * The number of matching documents (before skip and limit). Once groupBy, bucket or histogram was
+   * called, count(alias = 'count') adds the group's row count as column `alias` and answers the chain
+   * (SQL semantics apply; end it with all(), first() or having()).
+   */
+  count(...args: SubstrioChainArgument[]): Grouped extends true ? this : number;
+  ids(...args: SubstrioChainArgument[]): string[];
+  /**
+   * One field's value of every match, in the chain's order (no row is built). A nested path ('address.city') is read in
+   * place from each document: undefined for a document that lacks it (a missing step, a scalar or an array on the
+   * path), null for a stored null.
+   */
+  pluck<K extends keyof T & string>(field: K, ...args: SubstrioChainArgument[]): (T[K] | undefined)[];
+  pluck(field: SubstrioFieldPath, ...args: SubstrioChainArgument[]): unknown[];
+  /**
+   * One array per selected field (every field of the collection, and `_id`, when nothing is selected), in the
+   * chain's order. A column whose every cell is present and a number or boolean is a Float64Array (a boolean
+   * reads 0 or 1); any other is an Array of the cells' own values (strings, Dates, BigInts past 2^53), null
+   * where a document lacks the field. Throws a TypeError when a selected field is a nested path (a.b).
+   */
+  columns(...args: SubstrioChainArgument[]): SubstrioChainColumns<T, Shape>;
+  /**
+   * The sum of a field's numbers over the matching documents (sort, skip and
+   * limit do not apply); 0 when none holds a number. Integers add exactly
+   * (int64) and the result is the nearest double, so it is exact up to 2^53;
+   * past int64 the sum continues as a double and never wraps. Once groupBy, bucket or histogram was
+   * called, sum(field, alias = 'sum_<field>') adds the group's sum as column `alias` and answers the
+   * chain; avg, min and max do the same (aliases `avg_<field>`, `min_<field>`, `max_<field>`).
+   */
+  sum(field: string, ...args: SubstrioChainArgument[]): Grouped extends true ? this : number;
+  /** The mean of a field's numbers, null when no matching document holds one. */
+  avg(field: string, ...args: SubstrioChainArgument[]): Grouped extends true ? this : number | null;
+  /** The smallest of a field's numbers, null when there is none. */
+  min(field: string, ...args: SubstrioChainArgument[]): Grouped extends true ? this : number | null;
+  /** The largest of a field's numbers, null when there is none. */
+  max(field: string, ...args: SubstrioChainArgument[]): Grouped extends true ? this : number | null;
+  /**
+   * Each value of a field among the matching documents with the number of
+   * documents holding it, read from the field's value keys where it has them
+   * (sort, skip and limit do not apply). See SubstrioValuesOptions.
+   */
+  values(field: string, options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): SubstrioValueCounts;
+  /** values() of several fields over the chain's one filter, in one call: one property per field. */
+  facets(fields: string | string[], options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): Record<string, SubstrioValueCounts>;
+}
+export type SubstrioChainStart<T = Record<string, unknown>> = Pick<SubstrioChain<T>,
+  'eq' | 'neq' | 'ne' | 'gt' | 'gte' | 'ge' | 'lt' | 'lte' | 'le' | 'in' | 'nin' | 'startsWith' | 'containsAll' | 'containsAny' | 'size' | 'sizeGt' | 'sizeLt' | 'elemMatch' | 'endsWith' | 'contains' | 'icontains' | 'ieq' | 'iin' | 'istartsWith' | 'regex' | 'eqField' | 'neField' | 'gtField' | 'gteField' | 'ltField' | 'lteField' | 'onDay' | 'inMonth' | 'lastDays' | 'match' | 'knn' | 'near' | 'withinBox' | 'withinSphere' | 'sparseKnn' | 'textNear' | 'search' | 'and' | 'or' | 'not' | 'where' | 'sort' | 'sort_by' | 'group_by' | 'limit' | 'skip' | 'select' | 'join' | 'innerJoin' | 'leftJoin' | 'distinct' | 'groupBy' | 'bucket' | 'histogram' | 'like' | 'ilike' | 'between' | 'inQuery' | 'notInQuery' | 'existsQuery' | 'with' | 'withCount' | 'whereHas' | 'whereNone' | 'page' | 'pages'
+> & {
+  /** Every document of the collection: the chain with no condition, run. */
+  all(...args: SubstrioChainArgument[]): SubstrioRows<T>;
+  /** The terminals over the ids of every document (see SubstrioChain). */
+  sample(n: number, ...args: SubstrioChainArgument[]): SubstrioRows<T>;
+  random(...args: SubstrioChainArgument[]): SubstrioRecord<T> | null;
+  each(fn: (document: SubstrioRecord<T>, index: number) => unknown, ...args: SubstrioChainArgument[]): number;
+  chunk(n: number, fn: (documents: SubstrioRecord<T>[], page: number) => unknown, ...args: SubstrioChainArgument[]): number;
+  explain(...args: SubstrioChainArgument[]): SubstrioExplain;
+  /** The first and the last document (the ends of the collection), or null when it is empty. */
+  first(): SubstrioRecord<T> | null;
+  last(): SubstrioRecord<T> | null;
+  /** The first document, or a NotFoundError when the collection is empty; one field of it; whether the collection is empty. */
+  firstOrFail(): SubstrioRecord<T>;
+  value<K extends keyof T & string>(field: K): T[K] | undefined;
+  value(field: SubstrioFieldPath): unknown;
+  missing(): boolean;
+  /** The ids and one field of every document (count() is the collection's own, from its counter). */
+  ids(): string[];
+  pluck<K extends keyof T & string>(field: K): (T[K] | undefined)[];
+  pluck(field: SubstrioFieldPath): unknown[];
+  /** The aggregates over every document of the collection (see SubstrioChain). */
+  sum(field: string, ...args: SubstrioChainArgument[]): number;
+  avg(field: string, ...args: SubstrioChainArgument[]): number | null;
+  min(field: string, ...args: SubstrioChainArgument[]): number | null;
+  max(field: string, ...args: SubstrioChainArgument[]): number | null;
+  countDistinct(field: string, ...args: SubstrioChainArgument[]): number;
+  /** The first `n` documents of each group in `sortField`'s order (see SubstrioChain). */
+  topPerGroup(groupField: string, n: number, sortField: string, direction?: 1 | -1 | 'asc' | 'desc', ...args: SubstrioChainArgument[]): SubstrioRows<T>;
+  /** The values, distinct values and facets over every document of the collection (see SubstrioChain). */
+  values(field: string, options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): SubstrioValueCounts;
+  distinct(field: string, options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): SubstrioFieldValue[];
+  facets(fields: string | string[], options?: SubstrioValuesOptions, ...args: SubstrioChainArgument[]): Record<string, SubstrioValueCounts>;
+};
+/**
+ * A chain after group_by(field). Its terminals return a plain object with one
+ * property per group: the key is the group value as JS spells it (a string as
+ * is, String(number), "true", "false", "null" for null or a missing field,
+ * an object's or an array's JSON), and values spelled the same (1 and "1")
+ * share a property. Integer-like keys enumerate first, as in any object; the
+ * others in first-seen order. No match gives an empty object. A group with no
+ * number in the field has sum 0 and null for avg, min and max. A Date written
+ * from script is stored as its ISO string and groups under that string. The
+ * group value "__proto__" is refused.
+ */
+export type SubstrioGroupedChain<T = Record<string, unknown>> = {
+  [K in 'eq' | 'neq' | 'ne' | 'gt' | 'gte' | 'ge' | 'lt' | 'lte' | 'le' | 'in' | 'nin' | 'exists' | 'startsWith' | 'and' | 'or' | 'not' | 'group_by']:
+    (...args: Parameters<SubstrioChain<T>[K]>) => SubstrioGroupedChain<T>;
+} & {
+  sum(field: string, ...args: SubstrioChainArgument[]): Record<string, number>;
+  avg(field: string, ...args: SubstrioChainArgument[]): Record<string, number | null>;
+  min(field: string, ...args: SubstrioChainArgument[]): Record<string, number | null>;
+  max(field: string, ...args: SubstrioChainArgument[]): Record<string, number | null>;
+  /** The matching documents of each group. */
+  count(...args: SubstrioChainArgument[]): Record<string, number>;
+};
+// @substrio-chain-end