@jarenjs/db 0.49.2 → 0.66.1

package/types/node-pool.d.ts

@@ -0,0 +1,28 @@
+import type { Driver } from './index.js';
+import type { NodeWorkerOptions, WorkerConnection } from './node-worker.js';
+
+export interface NodeWorkerPoolOptions {
+  readers?: number;
+  queueCapacity?: number;
+  graceMs?: number;
+  worker?: NodeWorkerOptions;
+}
+
+/** One writer and bounded read-only WAL workers. Memory uses the writer alone. */
+export declare function nodeWorkerPoolDriver(options?: NodeWorkerPoolOptions): NodeWorkerPoolDriver;
+
+export interface PoolMetrics {
+  readonly active: number;
+  readonly idle: number;
+  readonly queued: number;
+  readonly waitMs: Readonly<{ p50: number; p95: number }>;
+  readonly workers: readonly Readonly<{
+    readOnly: boolean; healthy: boolean; active: boolean; generation: number; executions: number;
+  }>[];
+}
+export interface NodeWorkerPoolConnection extends WorkerConnection {
+  metrics(): PoolMetrics;
+}
+export interface NodeWorkerPoolDriver extends Driver {
+  open(path?: string, options?: import('./node.js').NodeOpenOptions): Promise<NodeWorkerPoolConnection>;
+}

package/types/node-worker.d.ts

@@ -0,0 +1,54 @@
+import type { Driver } from './index.js';
+
+export interface NodeWorkerOptions {
+  windowRows?: number;
+  windowBytes?: number;
+  maxPending?: number;
+  maxStatements?: number;
+  maxCursors?: number;
+  allMaxRows?: number;
+  allMaxBytes?: number;
+  closeTimeoutMs?: number;
+  startupTimeoutMs?: number;
+}
+
+/** One worker per connection; SQLite and its iterators live off the caller thread. */
+export declare function nodeWorkerDriver(options?: NodeWorkerOptions): NodeWorkerDriver;
+
+export interface WorkerMetrics {
+  readonly frames: number;
+  readonly rows: number;
+  readonly maxFrameRows: number;
+  readonly maxFrameBytes: number;
+  readonly maxPending: number;
+  readonly pending: number;
+  readonly generation: number;
+  readonly healthy: boolean;
+}
+export interface WorkerStatement {
+  run(params?: readonly unknown[]): Promise<unknown>;
+  get(params?: readonly unknown[]): Promise<Record<string, unknown> | undefined>;
+  all(params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  iterate(params?: readonly unknown[]): Promise<AsyncIterableIterator<Record<string, unknown>>>;
+}
+/** The ordinary Connection operations; transactions pass their owning scope. */
+export interface WorkerConnectionScope {
+  exec(sql: string): Promise<unknown>;
+  prepare(sql: string, metadata?: { readOnly?: boolean; ephemeral?: boolean }): WorkerStatement | Promise<WorkerStatement>;
+  transaction<T>(body: (scope: WorkerConnectionScope) => T | Promise<T>): Promise<T>;
+}
+export interface WorkerConnection extends WorkerConnectionScope {
+  transaction<T>(body: (scope: WorkerConnectionScope) => T | Promise<T>, signal?: AbortSignal, mode?: 'deferred' | 'immediate'): Promise<T>;
+  readonly synchronous: false;
+  readonly capabilities: Readonly<Record<string, unknown>>;
+  close(): Promise<void>;
+}
+export interface NodeWorkerConnection extends WorkerConnection {
+  readonly generation: number;
+  metrics(): WorkerMetrics;
+  /** Fences this handle permanently; returns a newly opened connection. */
+  restart(): Promise<NodeWorkerConnection>;
+}
+export interface NodeWorkerDriver extends Driver {
+  open(path?: string, options?: import('./node.js').NodeOpenOptions): Promise<NodeWorkerConnection>;
+}

package/types/node.d.ts

@@ -2,14 +2,83 @@
 import type { Driver } from '@jarenjs/db';
 
 export interface NodeOpenOptions {
-  path?: string;
+  /** The busy timeout in milliseconds. */
   timeout?: number;
   readOnly?: boolean;
+  /** How long work waits for an open transaction (`JD0012` after). */
+  queueTimeout?: number;
 }
 
 /** The `node:sqlite` binding; the builtin loads lazily inside open(). */
 export declare function nodeDriver(): Driver;
-/** Adapt an already-constructed DatabaseSync-shaped database. */
-export declare function adaptNodeDatabase(db: unknown): unknown;
+/** Adapt an already-constructed DatabaseSync-shaped database. `backup`
+ * is the online-backup primitive triple (`copy`, `rename`, `remove`);
+ * the connection declares the capability exactly when it is given. */
+export declare function adaptNodeDatabase(db: unknown, options?: {
+  queueTimeout?: number;
+  backup?: { copy: Function; rename: Function; remove: Function };
+}): unknown;
 /** Construct and adapt from a loaded `node:sqlite`-shaped module. */
 export declare function fromNodeModule(mod: unknown, path: string, options?: NodeOpenOptions): unknown;
+
+// ————— documents on a filesystem —————
+
+/** A byte source: a path, or anything that yields chunks — a
+ * `node:fs` read stream and `process.stdin` both are. Spelled
+ * structurally so these declarations need no ambient Node types. */
+export type DocumentByteSource = string | AsyncIterable<Uint8Array>;
+
+/** A byte sink: anything with `node:stream`'s callback `write`. */
+export interface DocumentByteSink {
+  write(chunk: string, callback: (error?: Error | null) => void): unknown;
+}
+
+/** The document encodings a file may carry. */
+export declare const DOCUMENT_FORMATS: readonly ['json', 'jsonl'];
+
+/** The encoding a path declares by its extension: `.jsonl`/`.ndjson`
+ * are line-delimited, everything else is one JSON array. */
+export declare function formatOf(file: string): 'json' | 'jsonl';
+
+/** The documents of a top-level JSON array, scanned structurally so the
+ * array is never held whole. Refuses a root that is not an array
+ * (`JD0024`). */
+export declare function readJsonDocuments(
+  source: DocumentByteSource,
+): AsyncGenerator<unknown>;
+
+/** The documents of a JSONL source, one line at a time. */
+export declare function readJsonlDocuments(
+  source: DocumentByteSource,
+): AsyncGenerator<unknown>;
+
+/** The documents of a file or stream in the named encoding. */
+export declare function readDocuments(
+  source: DocumentByteSource, format: 'json' | 'jsonl',
+): AsyncGenerator<unknown>;
+
+/** A sink that publishes whole or not at all. */
+export interface DocumentTarget {
+  /** The sibling file being filled, or null for a sink with no file. */
+  readonly temporary: string | null;
+  write(document: unknown): Promise<void>;
+  /** Flush, rename over the target, and answer what was written. */
+  commit(): Promise<{ bytes: number; documents: number }>;
+  /** Remove the temporary; the target keeps the bytes it had. */
+  abort(): Promise<void>;
+}
+
+/** Replace a file whole: a sibling temporary is renamed over the target
+ * on `commit`, and removed on `abort`, so a failed run leaves the
+ * original byte for byte. */
+export declare function openAtomicTarget(
+  target: string, format: 'json' | 'jsonl',
+): Promise<DocumentTarget>;
+
+/** Write to an open stream; `abort` cannot take back what has left. */
+export declare function openStreamTarget(
+  stream: DocumentByteSink, format: 'json' | 'jsonl',
+): DocumentTarget;
+
+/** Validate everything and write nothing. */
+export declare function openNullTarget(): DocumentTarget;

package/types/postgres.d.ts

@@ -0,0 +1,46 @@
+/** Hand-authored declarations for @jarenjs/db/postgres (strategy 1). */
+import type { Dialect, Driver } from '@jarenjs/db';
+
+/** The byte length PostgreSQL truncates an identifier at; the dialect
+ * refuses a longer one rather than letting two names silently become
+ * one. */
+export declare const IDENTIFIER_BYTES: number;
+/** The minimum server this store accepts, as `server_version_num`
+ * spells it. */
+export declare const POSTGRES_FLOOR: number;
+
+/**
+ * The PostgreSQL 16+ dialect. Pure text: it imports no client, so this
+ * subpath resolves and type-checks with nothing installed.
+ */
+export declare function postgresDialect(options?: {
+  /** The one schema every catalog statement looks in. Unset, the
+   * connection's own search path -- what a disposable per-run schema
+   * needs. */
+  searchPath?: string;
+}): Dialect;
+
+/** One acquired client, adapted to the raw binding contract. */
+export declare function adaptPostgresClient(client: {
+  query: Function;
+  release?: Function;
+}, options?: { onClose?: () => unknown }): unknown;
+
+/** The probe: the server's version floor, and every capability this
+ * engine does and does not have. */
+export declare function postgresProbe(raw: unknown): unknown;
+
+/**
+ * The driver over an injected connection source. A `pg.Pool` satisfies
+ * `{ connect() }` as it stands; a single client becomes one with
+ * `{ connect: () => client }`. One client is acquired at open, held for
+ * the store's life, and released exactly once at close.
+ */
+export declare function postgresDriver(source: {
+  connect: Function;
+}, options?: {
+  /** The schema the store lives in: set on the connection AND given to
+   * the dialect, so the DDL and the catalog reads agree. */
+  schema?: string;
+  queueTimeout?: number;
+}): Driver;

package/types/typed.d.ts

@@ -15,6 +15,9 @@
 import type {
   EntityKeyArg, LoadExplanation, SaveReport, Store, StoreCapabilities,
   StoreStats, Collection, ExecuteOptions, SequenceResult, ValueOrPromise,
+  Dialect, ChangeRecord, LiveOptions, LiveQuery, JobsApi, SyncStore,
+  EntityScope, RelationEntry, RelationTable, EntityCursorOptions, QueryCursor,
+  LoadContinuation, PageOptions, Page, ChangesReader,
 } from '@jarenjs/db';
 
 /** The self-referential constraint an interface can satisfy: generated
@@ -36,9 +39,20 @@ export type TypedInclude<E extends MetaMap<E>, M extends EntityMeta> = {
   readonly [K in keyof M['relations']]?:
     true
     | { count: true }
-    | TypedLoadSpec<E, E[M['relations'][K]['entity'] & keyof E]>;
+    | TypedIncludeSpec<E, E[M['relations'][K]['entity'] & keyof E]>;
 };
 
+/** An include's clauses: the root's without `after` (a keyset cursor
+ * paginates the root alone; an include windows with `skip`/`take`). */
+export type TypedIncludeSpec<E extends MetaMap<E>, M extends EntityMeta> =
+  TypedLoadSpecBase & {
+    /** The per-root bounds (MODEL-FORMAT §10.4); `Infinity` spells the
+     * unbounded case. Crossing one is `JD2073`. */
+    maxRows?: number;
+    maxBytes?: number;
+    include?: TypedInclude<E, M>;
+  };
+
 export interface TypedLoadSpecBase {
   /** A query expression over `$it` — its format is the runtime's. */
   where?: unknown;
@@ -50,7 +64,9 @@ export interface TypedLoadSpecBase {
 
 export type TypedLoadSpec<E extends MetaMap<E>, M extends EntityMeta> =
   TypedLoadSpecBase & {
-    after?: M['key'] extends string | number ? M['key'] : never;
+    /** The keyset cursor: a page's structural continuation, or the
+     * single-column form over the key. */
+    after?: (M['key'] extends string | number ? M['key'] : never) | LoadContinuation;
     include?: TypedInclude<E, M>;
   };
 
@@ -68,35 +84,97 @@ export type Loaded<
         : Loaded<E, E[M['relations'][K]['entity'] & keyof E], I[K]> | null;
 } : NonNullable<unknown>);
 
+/** The relation members `link`/`unlink` take: the many-to-many ones —
+ * exactly the relation members the generated INPUT type also carries,
+ * since a membership array is writable where a projection is not. */
+export type MembershipMember<M extends EntityMeta> =
+  keyof M['relations'] & keyof M['input'] & string;
+
+/** What a membership names on the target side: the target's key, or a
+ * document carrying it. */
+export type MembershipTarget<E extends MetaMap<E>, M extends EntityMeta, K extends keyof M['relations']> =
+  E[M['relations'][K]['entity'] & keyof E]['key'] | M['relations'][K]['doc'];
+
 export interface TypedUntrackedReads<E extends MetaMap<E>, M extends EntityMeta> {
   get(key: EntityKeyArg): Promise<M['doc'] | undefined>;
   load<const S extends TypedLoadSpec<E, M>>(spec?: S): Promise<Array<Loaded<E, M, S>>>;
 }
 
 export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
+  /** The provider phantom: `from(typed.entity('User'))` infers `User`
+   * without a cast. */
+  readonly __item?: M['doc'];
   create(doc: M['input']): Promise<Readonly<M['doc']>>;
   get(key: EntityKeyArg): Promise<Readonly<M['doc']> | undefined>;
-  update(key: EntityKeyArg, changes: Partial<M['doc']>): Promise<Readonly<M['doc']>>;
+  /** A relation member is a projection, never stored state: `update()`
+   * refuses it (`JD2003`), and the type does not offer it. */
+  update(key: EntityKeyArg, changes: Partial<Omit<M['doc'], keyof M['relations']>>): Promise<Readonly<M['doc']>>;
   delete(key: EntityKeyArg): Promise<boolean>;
   load<const S extends TypedLoadSpec<E, M>>(spec?: S):
     Promise<Array<Readonly<Loaded<E, M, S>>>>;
+  /** The graph cursor: one root graph per pull, typed by the includes;
+   * untracked unless `tracking: true`. */
+  loadCursor<const S extends TypedLoadSpec<E, M>>(spec?: S, options?: EntityCursorOptions):
+    QueryCursor<Readonly<Loaded<E, M, S>>>;
+  /** One bounded page over the composite keyset, typed by the includes. */
+  page<const S extends TypedLoadSpec<E, M>>(spec?: S, options?: PageOptions):
+    Promise<Page<Readonly<Loaded<E, M, S>>>>;
   explainLoad(spec?: TypedLoadSpec<E, M>): LoadExplanation;
   add(doc: M['input']): Readonly<M['doc']>;
   put(next: M['doc']): Readonly<M['doc']>;
   remove(key: EntityKeyArg | M['doc']): void;
   discard(key: EntityKeyArg | M['doc']): void;
+  /** Attach / detach one many-to-many membership through the unit of
+   * work (MODEL-FORMAT §11.7): `member` is one of the relation members
+   * `create`/`add` also take as an array — never a projection — and
+   * `target` the target's key or a document carrying it. */
+  link<K extends MembershipMember<M>>(own: M['key'] | M['doc'], member: K, target: MembershipTarget<E, M, K>): void;
+  unlink<K extends MembershipMember<M>>(own: M['key'] | M['doc'], member: K, target: MembershipTarget<E, M, K>): void;
   asNoTracking(): TypedUntrackedReads<E, M>;
+  /** The provider contract over this entity's root (MODEL-FORMAT §10.1);
+   * the answer is the engine's result shape, value-or-promise (D2). */
+  execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  /** The same document as an item cursor: one row per pull, the
+   * statement released on `return()`; untracked unless `tracking: true`. */
+  cursor<R = M['doc']>(document: unknown, options?: EntityCursorOptions): QueryCursor<R>;
+  explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
+  readonly root: string;
+  /** The identity every entity set of one store shares; it carries every
+   * root's relation table. */
+  readonly scope: EntityScope;
+  /** This entity's relation table (MODEL-FORMAT §10.1): exactly the
+   * generated metadata's relation members, as the plain rows a query
+   * producer lowers a hop from. */
+  readonly relations: Readonly<Record<keyof M['relations'] & string, RelationEntry>>;
 }
 
+/** The typed store: every member of `Store` (a typed store is the same
+ * object, identity at runtime), with the entity sets typed. */
 export interface TypedStore<E extends MetaMap<E>> {
   readonly capabilities: StoreCapabilities;
+  readonly dialect: Dialect;
   stats(): StoreStats;
   collection<T = unknown>(name: string): Collection<T>;
   entity<K extends keyof E & string>(name: K): TypedEntitySet<E, E[K]>;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  explain?(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The entity roots this store-level provider serves (present with entities). */
+  readonly roots?: readonly (keyof E & string)[];
+  /** The relation tables of every entity, keyed by entity name. */
+  readonly relations?: Readonly<Record<keyof E & string, RelationTable>>;
   saveChanges?(): Promise<SaveReport>;
   transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
+  observe(fn: (record: ChangeRecord) => void): () => void;
+  /** Unbounded, and unsafe for a reconnecting consumer: `changes.page()`
+   * is the supported path (LIVE-FORMAT §5). */
+  changesSince?(after: number): Promise<ChangeRecord[]>;
+  readonly changes?: ChangesReader;
+  dataVersion(): Promise<number>;
+  live?(document: unknown, options?: LiveOptions): Promise<LiveQuery>;
   close(options?: { graceMs?: number }): Promise<void>;
+  readonly jobs?: JobsApi;
+  readonly sync?: SyncStore;
 }
 
 /**

package/types/wasm.d.ts

@@ -3,3 +3,24 @@ import type { Driver } from '@jarenjs/db';
 
 /** A driver over an injected wasm SQLite handle (possibly async). */
 export declare function wasmDriver(handle: unknown): Driver;
+/** Adapt an `sqlite3.oo1.DB`-shaped database (a loaded sqlite3 module
+ * and one of its database objects) to the raw connection contract. */
+export declare function adaptOo1Database(sqlite3: unknown, db: unknown): unknown;
+/** Build the injected HANDLE for `wasmDriver` from a loaded sqlite3
+ * module: `DbClass` picks the database class (default `sqlite3.oo1.DB`;
+ * the SAH-pool util's `OpfsSAHPoolDb` for OPFS persistence). */
+export declare function sqlite3Handle(sqlite3: unknown, options?: { DbClass?: unknown }): unknown;
+
+export interface SnapshotRecord { readonly revision: number; readonly bytes: Uint8Array }
+export interface SnapshotStorage {
+  read(key: string): Promise<SnapshotRecord | null>;
+  write(key: string, bytes: Uint8Array, revision: number): Promise<number>;
+  remove(key: string): Promise<number>;
+  close(): void;
+}
+/** Atomic version swaps; resolves writes only on IndexedDB transaction completion. */
+export declare function openSnapshotStorage(factory: unknown, name: string): Promise<SnapshotStorage>;
+/** Async SQLite binding with bounded, versioned IndexedDB snapshot durability. */
+export declare function indexedDbSnapshotHandle(sqlite3: unknown, options?: {
+  name?: string; indexedDB?: unknown; maxBytes?: number;
+}): unknown;

package/dist/types/algebra.d.ts

@@ -1,230 +0,0 @@
-/**
- * @file The Plan algebra: the dialect-neutral middle stage between the
- * engine's AST and a dialect's SQL. A plan is a plain JSON value —
- * inspectable, golden-testable without a database — and it carries NO
- * SQL text: every string in a plan is a member name, a type tag, an
- * external name or a reason sentence, never a fragment of any query
- * language. `assertNoSqlText` is the tripwire the tests run over every
- * golden.
- *
- * One plan shape covers this version: a guarded selection over ONE
- * collection with optional ordering, window, aggregate and a
- * whole-document projection — or, instead of an ordering and a window,
- * a k-nearest RANK the engine finishes over the rows the plan fetches,
- * or, instead of a projection, a fixed-width temporal BUCKET the plan
- * groups and aggregates itself. Constructs beyond it are residuals by
- * design (see ARCHITECTURE.md's deliberate-residual table).
- */
-/** The plan format version, carried on every plan. */
-export declare const PLAN_VERSION = 2;
-export type PlanRef = {
-    segments: ({
-        name: string;
-    } | {
-        index: number;
-    })[];
-    type: string;
-    column: string | null;
-};
-export type PlanOperand = {
-    lit: unknown;
-} | {
-    ext: string;
-};
-export type PlanPredicate = ({
-    p: 'and' | 'or';
-    items: PlanPredicate[];
-} | {
-    p: 'not';
-    item: PlanPredicate;
-} | {
-    p: 'cmp';
-    op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge';
-    ref: PlanRef;
-    operand: PlanOperand;
-} | {
-    p: 'typeIs';
-    ref: PlanRef;
-    types: string[];
-    positive: boolean;
-} | {
-    p: 'strop';
-    kind: 'starts' | 'ends' | 'contains';
-    ref: PlanRef;
-    operand: PlanOperand;
-} | {
-    p: 'const';
-    value: boolean;
-} | {
-    p: 'udf';
-    name: string;
-    key: string;
-} | {
-    p: 'bboxOverlap';
-    columns: {
-        w: string;
-        s: string;
-        e: string;
-        n: string;
-    };
-    probe: {
-        box: number[];
-    } | {
-        ext: string;
-    };
-} | {
-    p: 'cellIn';
-    column: string;
-    cells: string[];
-} | {
-    p: 'cellPrefix';
-    column: string;
-    prefix: string;
-});
-export type PlanOrderTerm = {
-    ref: PlanRef;
-    desc: boolean;
-    emptyGreatest: boolean;
-};
-export type PlanBucket = {
-    ref: PlanRef;
-    every: number;
-    origin: number;
-    as: string;
-    order: 'asc' | 'desc' | 'first-seen';
-    aggregates: {
-        fn: 'rows' | 'sum' | 'avg' | 'min' | 'max';
-        ref: PlanRef | null;
-        as: string;
-        empty: 'null' | 'zero' | 'omit';
-    }[];
-};
-export type PlanRank = {
-    column: string;
-    dims: number;
-    probe: {
-        lit: number[];
-    } | {
-        ext: string;
-    };
-    offset: number;
-    limit: number;
-    margin: number;
-};
-export type Plan = {
-    planVersion: number;
-    alg: 'select';
-    collection: string;
-    filter: PlanPredicate | null;
-    order: PlanOrderTerm[] | null;
-    window: {
-        offset: number;
-        limit: number | null;
-    } | null;
-    rank: PlanRank | null;
-    bucket: PlanBucket | null;
-    aggregate: {
-        fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
-        ref: PlanRef | null;
-    } | null;
-    project: 'document';
-};
-/**
- * @typedef {{ segments: ({ name: string } | { index: number })[],
- *   type: string, column: string | null }} PlanRef
- *   A typed reference into the stored document: `type` is the
- *   schema-declared type or `'unknown'`; `column` is the generated
- *   column name when the collection indexes this path.
- *
- * @typedef {{ lit: unknown } | { ext: string }} PlanOperand
- *
- * @typedef {(
- *   { p: 'and' | 'or', items: PlanPredicate[] } |
- *   { p: 'not', item: PlanPredicate } |
- *   { p: 'cmp', op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge',
- *     ref: PlanRef, operand: PlanOperand } |
- *   { p: 'typeIs', ref: PlanRef, types: string[], positive: boolean } |
- *   { p: 'strop', kind: 'starts' | 'ends' | 'contains',
- *     ref: PlanRef, operand: PlanOperand } |
- *   { p: 'const', value: boolean } |
- *   { p: 'udf', name: string, key: string } |
- *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
- *     n: string }, probe: { box: number[] } | { ext: string } } |
- *   { p: 'cellIn', column: string, cells: string[] } |
- *   { p: 'cellPrefix', column: string, prefix: string }
- * )} PlanPredicate
- *   The last three are the SPATIAL forms: predicates over the derived
- *   index columns a model declares, which a spatial conjunct either
- *   translates to exactly or is proven to IMPLY. `bboxOverlap` is true
- *   when the row's stored box meets the probe's (touching edges count,
- *   as the kernel's `bboxIntersects` does); `cellIn` when the row's
- *   cell is one of the listed ones (the nine-cell neighbourhood, or a
- *   single whole cell); `cellPrefix` when it begins with a shorter one.
- *   None carries a `json_type` guard — the derived column IS the value
- *   — but each is TOTAL through its own `IS NOT NULL`, so a row with no
- *   box or no cell answers FALSE rather than SQL's NULL and negation
- *   still composes classically.
- *
- * @typedef {{ ref: PlanRef, desc: boolean, emptyGreatest: boolean }} PlanOrderTerm
- *
- * @typedef {{ ref: PlanRef, every: number, origin: number, as: string,
- *   order: 'asc' | 'desc' | 'first-seen',
- *   aggregates: { fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
- *     ref: PlanRef | null, as: string,
- *     empty: 'null' | 'zero' | 'omit' }[] }} PlanBucket
- *   The fixed-width temporal GROUP BY: the instant column, the ladder's
- *   width and anchor in epoch milliseconds, the name the bucket's start
- *   is answered under, how the groups are ordered, and one aggregate
- *   per answered member. `rows` is `COUNT(*)` — the D5 count of SOURCE
- *   rows, duplicates and measured gaps included — and the four value
- *   aggregates skip a `NULL` reading exactly as the kernel skips a
- *   `null` one. `first-seen` order is the group's earliest row identity,
- *   which is the engine's own "order of first appearance" (§6.5).
- *   A plan carrying a bucket carries no `aggregate` and no `rank`.
- *
- * @typedef {{ column: string, dims: number,
- *   probe: { lit: number[] } | { ext: string },
- *   offset: number, limit: number, margin: number }} PlanRank
- *   The k-nearest stage: the packed vector column the ranking reads,
- *   its declared width, the probe (a plan-time literal vector, or the
- *   external that carries one at call time), the window the ENGINE
- *   will apply, and the inclusive score margin of the candidate cut.
- *   The column cuts — every row whose column score is within `margin`
- *   of the `offset + limit`-th best is a candidate — and the engine
- *   decides: the original document, its whole ordering and window
- *   included, runs over the candidates' documents. A plan carrying a
- *   rank carries no order and no window of its own: nothing in SQL
- *   orders or limits the fetch.
- *
- * @typedef {{
- *   planVersion: number,
- *   alg: 'select',
- *   collection: string,
- *   filter: PlanPredicate | null,
- *   order: PlanOrderTerm[] | null,
- *   window: { offset: number, limit: number | null } | null,
- *   rank: PlanRank | null,
- *   bucket: PlanBucket | null,
- *   aggregate: { fn: 'count' | 'sum' | 'avg' | 'min' | 'max',
- *     ref: PlanRef | null } | null,
- *   project: 'document',
- * }} Plan
- */
-/**
- * A fresh select plan over one collection.
- * @param {string} collection
- * @returns {Plan}
- */
-export declare function selectPlan(collection: string): Plan;
-/**
- * Conjoin a predicate onto a plan's filter.
- * @param {PlanPredicate | null} filter
- * @param {PlanPredicate} predicate
- * @returns {PlanPredicate}
- */
-export declare function conjoin(filter: PlanPredicate | null, predicate: PlanPredicate): PlanPredicate;
-/**
- * Throw when a plan value carries anything that smells like SQL.
- * @param {unknown} plan
- */
-export declare function assertNoSqlText(plan: unknown): void;

package/dist/types/app.d.ts

@@ -1,49 +0,0 @@
-/**
- * @file The app binding for live queries (LIVE-FORMAT §10): GENERATED
- * documents plus a handler factory — the `fsmToApp` precedent. The db
- * package never imports `@jarenjs/app`; the app document declares a
- * subscription (`APP-FORMAT §5.3`) whose registered handler is
- * `createLiveSubscription(store)`, and a two-line action whose whole
- * body is `{ patch: '$payload' }` — the handler prefixes every op
- * with the declared state path, so the app loop applies live patches
- * with the machinery it already has.
- */
-/**
- * Prefix every op path in a live patch with the state slot.
- * @param {any[]} patch
- * @param {string} statePath - JSON Pointer to the slot holding the
- *   live result document
- */
-export declare function prefixLivePatch(patch: any[], statePath: string): any[];
-/**
- * The generated documents (§10): a subscription entry and the
- * patch-forwarding action, both plain data for the app document.
- * @param {{ run?: string, action?: string, statePath: string,
- *   collection?: string, query: any, externals?: any, mode?: string,
- *   when?: any }} options
- * @returns {{ subscription: any, actions: any }}
- */
-export declare function liveAppBinding(options: {
-    run?: string;
-    action?: string;
-    statePath: string;
-    collection?: string;
-    query: any;
-    externals?: any;
-    mode?: string;
-    when?: any;
-}): {
-    subscription: any;
-    actions: any;
-};
-/**
- * The subscription handler factory: registers the live query when the
- * subscription starts, dispatches ONE initializing patch (a `replace`
- * of the whole slot), forwards each emission prefixed, and closes on
- * cleanup. An emission error surfaces as a dispatch of
- * `<action>/error` so the app can render it — silence is not an
- * option the format allows.
- * @param {any} store - an open store with capture
- * @returns {(props: any, dispatch: Function) => Function}
- */
-export declare function createLiveSubscription(store: any): (props: any, dispatch: Function) => Function;