@jarenjs/db 0.46.5 → 0.56.0

package/dist/types/algebra.d.ts

@@ -1,199 +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.
- * 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 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;
-    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 {{ 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,
- *   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;

package/dist/types/capture.d.ts

@@ -1,85 +0,0 @@
-/**
- * @file Change capture (D13): committed writes become an observable,
- * ordered stream of RFC 6902 patches — derived from SQLite's own
- * session changesets where the binding has them, from a write-path
- * journal where it does not (`bun:sqlite` has no `createSession`), or
- * off entirely. One diff format then runs end to end: store → patch →
- * live query → patch → O(k) render.
- *
- * The pointer contract (LIVE-FORMAT §2): `/<table>/<key>/<path…>`,
- * every token escaped per RFC 6901. A single key renders as its
- * scalar text (integers in decimal); a composite key renders as the
- * JSON text of its parts array. Join-table rows are tiny documents
- * under the join table's name — membership changes are part of the
- * stream, not a blind spot.
- *
- * Session facts this file is built on (probed, 3.51.2):
- * - a changeset carries ONE NET OP PER ROW (insert+update coalesce;
- *   insert+delete vanish; a no-op update is absent), and within-table
- *   order is NOT statement order — every row op targets a distinct
- *   pointer, so application order across rows cannot matter;
- * - `ROLLBACK TO` a savepoint removes the undone rows from the
- *   session (pinned by test — the classic caveat does NOT hold here);
- * - a rolled-back transaction yields an empty changeset;
- * - virtual generated columns are invisible;
- * - an UPDATE's old record carries the primary key and the CHANGED
- *   columns only — which is exactly enough for property-level ops,
- *   and why the doc column's old/new blobs make a minimal nested
- *   diff possible (`SELECT json(?)` turns JSONB back into text).
- */
-/** The persisted change log (LIVE-FORMAT §5). */
-export declare const CHANGES_TABLE = "_jaren_changes";
-export declare const DEFAULT_RETENTION = 1000;
-/**
- * Decode a binary changeset into row operations.
- * @param {Uint8Array} bytes
- * @returns {{ table: string, pk: boolean[], op: 'insert'|'update'|'delete',
- *   indirect: boolean, oldValues: any[] | null, newValues: any[] | null }[]}
- */
-export declare function parseChangeset(bytes: Uint8Array): {
-    table: string;
-    pk: boolean[];
-    op: 'insert' | 'update' | 'delete';
-    indirect: boolean;
-    oldValues: any[] | null;
-    newValues: any[] | null;
-}[];
-/**
- * The key token (LIVE-FORMAT §2): a single key is its scalar text;
- * a composite key is the JSON text of its parts array.
- * @param {any[]} parts
- * @returns {string}
- */
-export declare function keyToken(parts: any[]): string;
-export type TableShape = {
-    kind: 'collection' | 'entity' | 'join';
-    columns: {
-        name: string;
-        role: 'key' | 'doc' | 'scalar' | 'fk' | 'epoch';
-        storage?: string;
-    }[];
-    keyIndexes: number[];
-    docIndex: number;
-};
-/**
- * Translate parsed row operations into RFC 6902 ops, resolving JSONB
- * blobs through the connection (`SELECT json(?)`).
- * @param {any} connection
- * @param {Map<string, TableShape>} shapes
- * @param {any[]} operations
- * @returns {any} value-or-promise of RFC 6902 ops
- */
-export declare function translateOperations(connection: any, shapes: Map<string, TableShape>, operations: any[]): any;
-/**
- * @param {{ connection: any, shapes: Map<string, TableShape>,
- *   mode: 'session' | 'journal',
- *   log: boolean, retention: number }} options
- * @returns {any}
- */
-export declare function createCaptureEngine(options: {
-    connection: any;
-    shapes: Map<string, TableShape>;
-    mode: 'session' | 'journal';
-    log: boolean;
-    retention: number;
-}): any;

package/dist/types/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/types/dag-job.d.ts

@@ -1,40 +0,0 @@
-/**
- * @file The composition (JOBS-FORMAT §7): a persisted `@jarenjs/flow`
- * DAG run wired to a queue job. THE FLOW ENGINE IS INJECTED, NEVER
- * IMPORTED — the shared invariant forbids `@jarenjs/db` importing
- * `@jarenjs/flow`, so `compileDag` arrives as a capability (the D10
- * shape applied to flow) and a test asserts the manifest and import
- * graph name flow nowhere.
- *
- * Each kind's document compiles ONCE against a delegating checkpoint
- * store; per claimed job, the delegate binds the engine's guarded
- * per-job store (`checkpointsFor`) — `save` refuses once the lease is
- * lost and `complete` records the DAG result, marks the job done and
- * prunes the checkpoint rows in ONE transaction, so a failure leaves
- * neither and a crash resumes instead of restarting.
- */
-/**
- * Build a worker whose handlers run checkpointed DAG documents.
- * @param {any} store - an open store with `{ jobs: true }`
- * @param {{ compileDag: Function,
- *   documents: Record<string, any>,
- *   tasks?: Record<string, Function>,
- *   concurrency?: number, pollInterval?: number, leaseMs?: number,
- *   owner?: string, backoffBase?: number, backoffCap?: number }} options
- * @returns {{ start: () => any, stop: () => Promise<void>, stats: () => any }}
- */
-export declare function createDagJobRunner(store: any, options: {
-    compileDag: Function;
-    documents: Record<string, any>;
-    tasks?: Record<string, Function>;
-    concurrency?: number;
-    pollInterval?: number;
-    leaseMs?: number;
-    owner?: string;
-    backoffBase?: number;
-    backoffCap?: number;
-}): {
-    start: () => any;
-    stop: () => Promise<void>;
-    stats: () => any;
-};

package/dist/types/ddl.d.ts

@@ -1,229 +0,0 @@
-/**
- * @file DDL planning: a normalized collection becomes one physical
- * table — a key column, a JSON document column, a virtual generated
- * column per indexed path, and the declared indexes — with every byte
- * of SQL rendered by the dialect.
- *
- * Index paths are JSONPath expressions analyzed through the engine's
- * PUBLISHED AST (`analyzeQuery`): a path is indexable exactly when the
- * analysis says it is singular and every segment is a plain member or
- * index selection. That reuses the one grammar authority instead of
- * re-parsing, and it fails loudly (`JD0004`) on everything else —
- * wildcards, slices, filters, descendants, functions — rather than
- * silently indexing the wrong thing.
- */
-/** The fixed physical column names of the 0.1 mapping. */
-export declare const KEY_COLUMN = "key";
-export declare const DOC_COLUMN = "doc";
-/**
- * Analyze one index path expression down to typed segments.
- * @param {string} expression - A JSONPath expression (`$.email`)
- * @param {string} docPath - Model-document pointer for diagnostics
- * @returns {{ segments: import('./dialect.js').JsonPathSegment[],
- *   canonical: string }}
- */
-export declare function compileIndexPath(expression: string, docPath: string): {
-    segments: import('./dialect.js').JsonPathSegment[];
-    canonical: string;
-};
-/**
- * The schema subschema at a segment path, walked structurally through
- * `properties` / `items` / `prefixItems`. The collection's schema is
- * the type source — that is why the physical mapping needs no
- * engine-side inference. `undefined` where the walk leaves the schema.
- * @param {any} schema
- * @param {import('./dialect.js').JsonPathSegment[]} segments
- * @returns {any}
- */
-export declare function schemaNodeAt(schema: any, segments: import('./dialect.js').JsonPathSegment[]): any;
-/**
- * The declared schema type at a segment path: the first non-`null`
- * member of a union, which is the type a COLUMN takes its storage
- * from. A caller that must know the whole union (a promotion refusing
- * a member that may also be `null`) reads {@link schemaNodeAt}.
- * @param {any} schema
- * @param {import('./dialect.js').JsonPathSegment[]} segments
- * @returns {string | undefined}
- */
-export declare function schemaTypeAt(schema: any, segments: import('./dialect.js').JsonPathSegment[]): string | undefined;
-/**
- * Plan one collection's physical shape: the DDL statements to create
- * it and the structural facts an existing table must match (the
- * `JD0002` comparison set).
- * A derived index (`derive: 'geohash' | 'bbox'`) maps to the same
- * shape through a registered deterministic function, EXCEPT where the
- * driver cannot index one (`capabilities.deterministicIndexableFunctions`
- * is false): there the columns are ordinary ones the store writes. The
- * two mappings produce different declared text on purpose — a database
- * built under one and opened under the other really does disagree, and
- * `verifyShape` says so rather than papering over it. A
- * `derive: 'vector'` column is the stored shape under BOTH mappings
- * (`derivedMappingFor`), so for it the two agree.
- * @param {string} name - The collection name (also the table name)
- * @param {{ schema: any, keySegments: { name: string }[] | null,
- *   identity: string, indexes: { name: string, paths: string[],
- *   unique: boolean, derive?: string | null, precision?: number,
- *   dims?: number, docPath: string }[] }} collection - normalized
- * @param {any} dialect
- * @param {{ derived?: 'virtual' | 'stored', rtree?: boolean }} [options]
- *   - `derived` is the physical mapping for derived columns:
- *   `'virtual'` (a generated column over a registered function) unless
- *   the driver says it cannot index one. `rtree` is whether the driver
- *   carries the R\*Tree module; when it does not, a column set that
- *   declared `physical: 'rtree'` falls back to the B-tree over its
- *   columns and `explain().prefilters[].via` reports which shape ran
- *   (MODEL-FORMAT §4) — a report, not a silent degradation
- * @returns {{
- *   table: string, keyColumn: string, docColumn: string,
- *   keyType: string,
- *   generated: { name: string, type: string, pathText: string,
- *     canonical: string }[],
- *   derived: { name: string, derive: string, precision?: number,
- *     component?: string, dims?: number, segments: any[] }[],
- *   columnByCanonical: Map<string, string>,
- *   createSql: string[],
- *   virtualTables: { stem: string, name: string, columns: string[],
- *     edges: string[], createSql: string, fillSql: string,
- *     triggers: { name: string, sql: string }[] }[],
- *   expected: { columns: { name: string, type: string,
- *     generated: boolean }[], indexes: { name: string, unique: boolean,
- *     columns: string[] }[] },
- * }}
- */
-export declare function planCollection(name: string, collection: {
-    schema: any;
-    keySegments: {
-        name: string;
-    }[] | null;
-    identity: string;
-    indexes: {
-        name: string;
-        paths: string[];
-        unique: boolean;
-        derive?: string | null;
-        precision?: number;
-        dims?: number;
-        docPath: string;
-    }[];
-}, dialect: any, options?: {
-    derived?: 'virtual' | 'stored';
-    rtree?: boolean;
-}): {
-    table: string;
-    keyColumn: string;
-    docColumn: string;
-    keyType: string;
-    generated: {
-        name: string;
-        type: string;
-        pathText: string;
-        canonical: string;
-    }[];
-    derived: {
-        name: string;
-        derive: string;
-        precision?: number;
-        component?: string;
-        dims?: number;
-        segments: any[];
-    }[];
-    columnByCanonical: Map<string, string>;
-    createSql: string[];
-    virtualTables: {
-        stem: string;
-        name: string;
-        columns: string[];
-        edges: string[];
-        createSql: string;
-        fillSql: string;
-        triggers: {
-            name: string;
-            sql: string;
-        }[];
-    }[];
-    expected: {
-        columns: {
-            name: string;
-            type: string;
-            generated: boolean;
-        }[];
-        indexes: {
-            name: string;
-            unique: boolean;
-            columns: string[];
-        }[];
-    };
-};
-/**
- * Normalize a stored `CREATE` statement for comparison: collapse runs of
- * whitespace, drop whitespace around punctuation, and strip the
- * `IF NOT EXISTS` SQLite does not keep. What survives is every token that
- * carries meaning, so two statements compare equal exactly when they
- * declare the same physical object.
- * @param {string} sql
- * @returns {string}
- */
-export declare function normalizeDeclaredSql(sql: string): string;
-/**
- * A comparable form of one `CREATE` statement.
- *
- * For a TABLE the column definitions compare as a SET, because
- * `ALTER TABLE … ADD COLUMN` can only append — so a migrated table and a
- * freshly built one legitimately differ in column order, and this store
- * never reads a column positionally. Everything else is exact: each
- * column's full definition (type, `PRIMARY KEY`, `NOT NULL`, `DEFAULT`,
- * `CHECK`, `GENERATED … AS`, `REFERENCES … ON DELETE …`), the table
- * constraints, and the trailing table options (`STRICT`,
- * `WITHOUT ROWID`).
- *
- * For an INDEX the text compares whole, because an index IS its order —
- * `(a,b)` and `(b,a)` serve different lookups — as are its partial
- * predicate and each term's collation and direction.
- * @param {string} sql
- * @returns {string}
- */
-export declare function comparableDeclaredSql(sql: string): string;
-/**
- * Verify an existing table against the planned shape; any difference
- * is `JD0002` and nothing is altered. Shared by the store's open path
- * and the migration engine's shadow validation.
- * @param {any} connection
- * @param {any} plan
- * @param {string} collection
- * @param {string} docPath
- * @returns {any} value-or-promise
- */
-export declare function verifyShape(connection: any, plan: any, collection: string, docPath: string): any;
-/**
- * Plan one ENTITY's physical shape from the mapping data
- * `explainMapping` derived: the relational table (typed columns,
- * checks, foreign keys, the JSONB document column), its indexes, and
- * the structural facts an existing table must match. One verify path
- * serves both document kinds.
- * @param {string} name
- * @param {any} entityMapping - `explainMapping(model).entities[name]`
- * @param {any} entities - the full `explainMapping` result (key types
- *   come from the referenced entity's columns)
- * @param {any} dialect
- * @returns {{ table: string, createSql: string[], expected: any,
- *   columnNames: Set<string> }}
- */
-export declare function planEntity(name: string, entityMapping: any, entities: any, dialect: any): {
-    table: string;
-    createSql: string[];
-    expected: any;
-    columnNames: Set<string>;
-};
-/**
- * Plan a many-to-many join table.
- * @param {string} tableName
- * @param {any} join - `explainMapping(model).joinTables[tableName]`
- * @param {any} entities - the full mapping
- * @param {any} dialect
- * @returns {{ table: string, createSql: string[], expected: any }}
- */
-export declare function planJoinTable(tableName: string, join: any, entities: any, dialect: any): {
-    table: string;
-    createSql: string[];
-    expected: any;
-};