@jarenjs/db 0.49.2 → 0.66.1

package/dist/types/series.d.ts

@@ -1,227 +0,0 @@
-/**
- * @file The temporal recognizer: which documents ask a §8.16 question,
- * which of those a declared `(series, at)` index can answer, and what
- * the honest reason is when it cannot.
- *
- * No SQL and no storage kind live here. The physical feature is the
- * composite JSONPath index a model already declares
- * (`{ "name": "by_series_at", "path": ["$.series", "$.at"] }`); this
- * module only decides which of the three CLOSED shapes a planned
- * selection is in:
- *
- *  1. **range** — an equality on every leading column of an instant
- *     index plus a half-open range on the instant column, ordered by
- *     the instant. The index seeks; nothing is left over.
- *  2. **as-of** — the same prefix with ONE instant bound, ordered by
- *     the instant and cut to a finite window. One index seek per probe.
- *  3. **bucket** — a fixed-width ladder over the instant column with
- *     the exact `sum|mean|min|max|count` aggregates, which is a
- *     `GROUP BY` over integer arithmetic.
- *
- * Everything else — a calendar ladder, a fill policy, a rolling window,
- * an as-of JOIN, `first`/`last` — is a named core refinement: the
- * database narrows through the index and `@jarenjs/core/series` (via
- * the residual, which is the ENGINE running the caller's own document)
- * decides. The narrowing is the contribution; the answer is always the
- * engine's, which is what makes a refinement idempotent.
- *
- * Every refusal here has a CODE, and the code is the first word of the
- * sentence the plan carries, so `explain().series.reasons[].code` and
- * `explain().residual.reasons[].reason` cannot drift apart.
- */
-/** The three §8.16 operators a whole document can BE. */
-export declare const SERIES_ROOT_OPS: readonly string[];
-/** Every §8.16 operator: naming one makes a document temporal. */
-export declare const SERIES_OPS: readonly string[];
-/**
- * The D5 aggregates a `GROUP BY` reproduces exactly, and the plan's
- * name for each. `count` is `rows` because it counts SOURCE ROWS —
- * duplicates and measured gaps included — which is `COUNT(*)` and not
- * `COUNT(value)`; the six value aggregates skip a `null` reading,
- * which is what SQL's aggregates already do with SQL `NULL`.
- *
- * `first` and `last` are deliberately absent: they name a row by its
- * position in the series, and a group's order is not the series' order.
- */
-export declare const NATIVE_AGGREGATES: Readonly<{
-    mean: "avg";
-    sum: "sum";
-    min: "min";
-    max: "max";
-    count: "rows";
-}>;
-/**
- * The closed reason table. A reason is a CODE and a sentence; the plan
- * carries `"<code>: <sentence>"` so one string serves strict mode's
- * refusal, `explain().residual.reasons` and the machine-readable
- * `explain().series.reasons[].code` at once.
- */
-export declare const SERIES_REASONS: Readonly<{
-    'missing-series-prefix': string;
-    'calendar-width': string;
-    'named-zone': string;
-    'fill-policy': string;
-    'rolling-refinement': string;
-    'asof-refinement': "an as-of join walks both sides once, so the index bounds the fetch and the kernel joins";
-    'nonliteral-spec': string;
-    'unsupported-aggregate': string;
-    'row-selector': string;
-    'instant-not-integer': string;
-    'value-not-numeric': string;
-    'nonnative-grouping': "the grouping key or the projection is not the closed bucket shape";
-    'invalid-spec': string;
-}>;
-/**
- * One reason, in both spellings at once.
- * @param {keyof SERIES_REASONS | string} code
- * @param {string} construct - the operator or clause that forced it
- * @returns {{ code: string, construct: string, reason: string }}
- */
-export declare function seriesReason(code: keyof SERIES_REASONS | string, construct: string): {
-    code: string;
-    construct: string;
-    reason: string;
-};
-/**
- * Every declared index whose LAST covered column is `column`, with the
- * columns before it as the prefix that must be pinned.
- *
- * `minColumns` is what keeps an ordinary query ordinary. A collection
- * that declares `(age)` and is asked for `age > 21` is not asking a
- * temporal question, and nothing in a column can say otherwise — so
- * the shape D9 actually names, a COMPOSITE index whose last column is
- * the instant, is what makes a plain selection temporal. A document
- * that named a §8.16 operator has already said so itself, and reads
- * the singular index too.
- * @param {any} shape - { indexes?: { name, columns }[] }
- * @param {string} column
- * @param {number} [minColumns]
- * @returns {{ name: string, prefix: string[], column: string }[]}
- */
-export declare function instantIndexesOver(shape: any, column: string, minColumns?: number): {
-    name: string;
-    prefix: string[];
-    column: string;
-}[];
-/**
- * The index a fetch actually SEEKS through, or `null` when none does.
- *
- * A B-tree is seekable exactly as far as its leading columns are
- * decided: a run of equalities, and then at most one range. So the
- * index that wins is the one with the longest leading run of PINNED
- * columns whose next column is the instant the query ranges over —
- * which is `(series, at)` under an equality on the series, and is
- * nothing at all under a bare instant bound, because a range on a
- * trailing column reads every row of the index.
- *
- * With no instant column of its own (an as-of join reading an instant
- * the model does not index) a pinned prefix alone still seeks, and is
- * reported as what it is.
- * @param {any} shape
- * @param {string | null} column - the instant column, or `null`
- * @param {{ pinned: Set<string>, bounds: Map<string, any> }} facts
- * @param {number} [minColumns] - see {@link instantIndexesOver}
- * @returns {{ name: string, prefix: string[], column: string | null } | null}
- */
-export declare function seekingIndexFor(shape: any, column: string | null, facts: {
-    pinned: Set<string>;
-    bounds: Map<string, any>;
-}, minColumns?: number): {
-    name: string;
-    prefix: string[];
-    column: string | null;
-} | null;
-/**
- * Walk a pushed filter and report, per column, what it decided: which
- * columns an equality pinned and what instant bounds a range put on
- * one. Only a top-level conjunction counts — a disjunction or a
- * negation decides nothing about a seek.
- * @param {import('./algebra.js').PlanPredicate | null} filter
- * @returns {{ pinned: Set<string>,
- *   bounds: Map<string, { from: any, fromOp: string | null,
- *     to: any, toOp: string | null }> }}
- */
-export declare function filterFacts(filter: import('./algebra.js').PlanPredicate | null): {
-    pinned: Set<string>;
-    bounds: Map<string, {
-        from: any;
-        fromOp: string | null;
-        to: any;
-        toOp: string | null;
-    }>;
-};
-/**
- * The fixed ladder a `$time-bucket`/`$resample` spec asks for, or the
- * reason it is not one. `origin` is folded to an epoch here — a
- * `{ offset }` context moves the ladder's default anchor off UTC's
- * midnight, which is arithmetic, while a named zone is not.
- *
- * The width is read through the temporal kernel's OWN compiler, so
- * `'PT1H'`, `3600000` and `'PT60M'` are the same ladder, the default
- * anchor is the kernel's rather than a second guess at it, and a width
- * mixing the two families was already refused when the query compiled.
- * @param {{ every: any, origin?: any, zone?: any, offset?: any }} spec
- * @param {(spec: any, options: any) => any} compileBuckets - the kernel's
- * @returns {{ every: number, origin: number } | { code: string }}
- */
-export declare function fixedLadder(spec: {
-    every: any;
-    origin?: any;
-    zone?: any;
-    offset?: any;
-}, compileBuckets: (spec: any, options: any) => any): {
-    every: number;
-    origin: number;
-} | {
-    code: string;
-};
-/**
- * Whether a `PlanRef` can carry a native bucket ladder: the instant
- * must be a declared whole epoch, because the boundary arithmetic in
- * SQL is integer arithmetic and a truncating division over a real
- * would put an instant before 1970 in the bucket after its own.
- * @param {import('./algebra.js').PlanRef | null} ref
- * @returns {string | null} the reason code, or `null` when it can
- */
-export declare function instantRefusal(ref: import('./algebra.js').PlanRef | null): string | null;
-/**
- * Whether a `PlanRef` can carry a native VALUE aggregate.
- * @param {import('./algebra.js').PlanRef | null} ref
- * @returns {string | null}
- */
-export declare function valueRefusal(ref: import('./algebra.js').PlanRef | null): string | null;
-/**
- * The one member name a `'$.on'`-style row selector reads, or `null`
- * for anything a declared column cannot stand in for. The language's
- * own reader (`compileSelector`) folds a single-segment path to a bare
- * name; this reads the same two spellings out of the FROZEN literal a
- * planner sees, and refuses everything else rather than guessing.
- * @param {any} text
- * @returns {string | null}
- */
-export declare function singularSelector(text: any): string | null;
-/**
- * The explain record for one temporal document. Counts are the LAST
- * ACTUAL execution's — never an estimate — and are `null` until the
- * document has run once.
- * @param {{ mode: 'native' | 'hybrid' | 'engine', operation: string,
- *   index?: string | null, prefix?: string[], range?: any,
- *   ladder?: any, aggregates?: string[], refinement?: string | null,
- *   reasons?: { code: string, construct: string, reason: string }[] }} facts
- * @returns {any}
- */
-export declare function seriesRecord(facts: {
-    mode: 'native' | 'hybrid' | 'engine';
-    operation: string;
-    index?: string | null;
-    prefix?: string[];
-    range?: any;
-    ladder?: any;
-    aggregates?: string[];
-    refinement?: string | null;
-    reasons?: {
-        code: string;
-        construct: string;
-        reason: string;
-    }[];
-}): any;

package/dist/types/store.d.ts

@@ -1,60 +0,0 @@
-/**
- * @file The store: `openStore(model, options)` normalizes the model
- * document, opens a database through the injected driver, applies (or
- * verifies) the physical shape, and gives transactional,
- * schema-validated reads and writes.
- *
- * The public surface is ASYNCHRONOUS — every method returns a promise
- * — because the browser's OPFS story forces it regardless of any other
- * backend. Where the driver is synchronous the same operations exist
- * without the promise under `store.sync`, present only there — never a
- * throwing stub — so portable code pays one declared microsecond and
- * code that wants it back opts in knowingly. Internally everything
- * composes through the sync-capable {@link chain}, so the async
- * surface allocates exactly one promise per call, not one per step.
- *
- * Writes validate through an injected `compileSchema` hook with the
- * `compileTypeTest` signature; absent, writes are unvalidated and
- * `store.capabilities.validated === false` — a declared downgrade,
- * never a silent one. `@jarenjs/validate` is never imported here.
- */
-/** The model format version this store implements. */
-export declare const MODEL_VERSION = "0.1";
-/**
- * Normalize and check a model document. Every failure is `JD0005` with
- * a `docPath` into the model.
- * @param {any} model
- * @returns {Map<string, any>} collection name -> normalized collection
- */
-export declare function normalizeModel(model: any): Map<string, any>;
-/**
- * Open (or create) a store described by a model document.
- * @param {any} model - A `jaren-model` document (the 0.1 subset)
- * @param {{ driver: any, path?: string, compileSchema?: Function,
- *   busyTimeout?: number, queueTimeout?: number, journalMode?: string,
- *   statementCacheBound?: number, profile?: any, operators?: any,
- *   functions?: any, extensions?: any, zoneProvider?: any,
- *   readOnly?: boolean }} options
- *   `zoneProvider` is D7's injected clock: a named zone in a temporal
- *   spec (`{ "every": "P1M", "zone": "Europe/Amsterdam" }`) is host code
- *   the database cannot have, so a store that never received one refuses
- *   such a document (`JQ0003`) rather than answering it in UTC. It
- *   reaches every residual compilation, which is where the calendar
- *   ladder actually walks.
- * @returns {Promise<any>}
- */
-export declare function openStore(model: any, options: {
-    driver: any;
-    path?: string;
-    compileSchema?: Function;
-    busyTimeout?: number;
-    queueTimeout?: number;
-    journalMode?: string;
-    statementCacheBound?: number;
-    profile?: any;
-    operators?: any;
-    functions?: any;
-    extensions?: any;
-    zoneProvider?: any;
-    readOnly?: boolean;
-}): Promise<any>;

package/dist/types/tracker.d.ts

@@ -1,43 +0,0 @@
-/**
- * @file The unit of work (§11): copy-on-write change tracking and
- * minimal writes. Materialised entities are plain, DEEP-FROZEN JSON —
- * no proxies anywhere — and the tracker retains exactly ONE reference
- * per tracked entity: the frozen document itself is the snapshot.
- * Mutation is replacement (`put(next)`); `saveChanges()` diffs
- * snapshot against current with the suite's own diff engine and plans
- * the MINIMAL set of parameterised statements: scalar/epoch/foreign-
- * key column writes, `jsonb_set`/`jsonb_remove` chains for document
- * paths, join-table synchronisation for many-to-many members, and a
- * counted whole-row fallback for anything untranslatable.
- *
- * Ordering never violates a foreign key mid-transaction: inserts run
- * parent-first, deletes child-first, updates in between, join rows
- * after both endpoints exist. A foreign-key cycle among the entities
- * being inserted or deleted is `JD0040`, reported, never a deadlock.
- * The whole save is one transaction; the tracker is mutated ONLY
- * after commit, so a failed save leaves it exactly as it was and a
- * retry is possible.
- */
-/** Rows per batched INSERT: bounded by the portable parameter budget. */
-export declare const BATCH_PARAM_BUDGET = 900;
-export declare const BATCH_ROW_BOUND = 100;
-/**
- * Deep-freeze a JSON value in place and return it. Idempotent; shared
- * substructure (a graph load's children) freezes once.
- * @template T
- * @param {T} value
- * @returns {T}
- */
-export declare function deepFreeze<T>(value: T): T;
-/**
- * The store-level unit of work.
- * @param {{ connection: any, entities: Map<string, any>, mapping: any,
- *   coreFor: (name: string) => any }} context
- * @returns {any}
- */
-export declare function createTracker(context: {
-    connection: any;
-    entities: Map<string, any>;
-    mapping: any;
-    coreFor: (name: string) => any;
-}): any;

package/dist/types/typed.d.ts

@@ -1,15 +0,0 @@
-/**
- * @file The typed-store binding: a zero-cost identity whose ONLY job
- * is carrying the generated `EntityMetaMap` into the type system —
- * `typedStore<EntityMetaMap>(store)` narrows `entity(name)` to the
- * generated document/input shapes and widens `load` results by their
- * include specification. The runtime is the store it was given; every
- * guarantee lives in `types/typed.d.ts` and the generated artifact.
- */
-/**
- * Bind a store to its generated entity metadata. Identity at runtime.
- * @template E
- * @param {any} store - an opened store whose model generated `E`
- * @returns {any}
- */
-export declare function typedStore<E>(store: any): any;

package/dist/types/types.d.ts

@@ -1,26 +0,0 @@
-/**
- * @file Schema-derived path typing: the collection's JSON Schema is the
- * planner's type source (there is no engine-side inference in this
- * phase — the store's own contract carries the types). Where the
- * schema says nothing, the answer is `'unknown'` and the planner emits
- * the defensive form; the guards in the truth table make `'unknown'`
- * safe, so typing here only ever IMPROVES a plan (column choice), it
- * never weakens one.
- */
-/**
- * The planner-facing type of a member path.
- * @param {any} schema - The collection's document schema
- * @param {({ name: string } | { index: number })[]} segments
- * @returns {'string' | 'integer' | 'number' | 'boolean' | 'unknown'}
- */
-export declare function typeOfPath(schema: any, segments: ({
-    name: string;
-} | {
-    index: number;
-})[]): 'string' | 'integer' | 'number' | 'boolean' | 'unknown';
-/**
- * Whether a planner type is numeric (SQL comparison family).
- * @param {string} type
- * @returns {boolean}
- */
-export declare function isNumericType(type: string): boolean;

package/dist/types/udf.d.ts

@@ -1,75 +0,0 @@
-/**
- * @file The UDF escape hatch (capability-gated): between native SQL
- * and pulling rows sits registering a compiled predicate conjunct as a
- * DETERMINISTIC function used in the WHERE clause. Only fragments the
- * analysis proves deterministic and side-effect-free qualify — no
- * externals (their values change per call, and a deterministic
- * function must not close over changing state), no host functions, no
- * collations. Registration is keyed by the fragment's COLLISION-FREE
- * structural identity, so identical fragments share one registration
- * per store and different fragments never do. A fingerprint could not
- * decide this: two colliding fragments would claim one SQL function
- * name, the second would silently reuse the first's predicate, and the
- * WHERE clause would filter on the wrong condition. The SQL identifier
- * still derives from a short fingerprint — names must be short — but a
- * fingerprint clash between DIFFERENT identities is disambiguated with
- * a suffix rather than collapsed.
- *
- * WHERE-clause use only: an INDEX over a registered function would
- * make the database unwritable from any connection that has not
- * registered the identical function — that schema-dependency hazard is
- * why the model format declares no UDF-expression indexes.
- *
- * Ring 3 extends the hatch to registry `pushable:'scalar'`
- * operators: a predicate fragment that uses a registered scalar operator
- * (`$sqrt`, `$pow`, …) compiles WITH the store's `{ functions,
- * extensions }` and pushes as the same deterministic UDF — SQLite drives
- * the row iteration and the operator runs inside the callback, instead
- * of every candidate crossing into the residual. The determinism rule is
- * unchanged (no externals, no collations); a registered operator the
- * pack did NOT mark `pushable:'scalar'` (a whole-series `$npv`, an
- * aggregate) stays the residual — Ring 2 keeps it correct.
- */
-/**
- * Decide whether a raw predicate fragment qualifies for the hatch, and
- * build its registration if so.
- * @param {any} fragment - The raw conjunct (a JSON query expression
- *   over `$it`)
- * @param {{ functions?: any, extensions?: any, pushableScalar?: Set<string> } | null}
- *   [operators] - the store's registered operators (Ring 3); only its
- *   `pushable:'scalar'` subset is admitted. `null`/absent keeps the
- *   original engine-internal-only rule (no host function pushes).
- * @param {string} [binding='it'] - the name the caller's document gave
- *   the collection binding. The fragment references it, so the wrapper
- *   below must bind it: under any other name every reference reads as an
- *   external, the determinism check below rejects the fragment, and the
- *   hatch silently never engages.
- * @returns {{ key: string, name: string,
- *   compile: () => (docText: string) => number } | null}
- */
-export declare function deterministicFragment(fragment: any, operators?: {
-    functions?: any;
-    extensions?: any;
-    pushableScalar?: Set<string>;
-} | null, binding?: string): {
-    key: string;
-    name: string;
-    compile: () => (docText: string) => number;
-} | null;
-/**
- * Register a qualified fragment once per store, and answer the SQL name
- * to call. Identity is the fragment's structural key, so the same
- * fragment registers once and two different fragments always get two
- * different functions — even when their short names fingerprint alike,
- * which the suffix resolves.
- * @param {any} connection
- * @param {Map<string, string>} registered - The store's registrations,
- *   fragment identity → the SQL function name it owns
- * @param {{ key: string, name: string, compile: () => Function }} fragment
- * @returns {string} the function name to call in the WHERE clause
- */
-export declare function registerFragment(connection: any, registered: Map<string, string>, fragment: {
-    key: string;
-    name: string;
-    compile: () => Function;
-}): string;

package/dist/types/window.d.ts

@@ -1,52 +0,0 @@
-/**
- * @file The maintained sorted window for `orderBy` (+ optional
- * `limit`) live queries — LIVE-FORMAT §7's window row. The structure
- * keeps EVERY matching row in sorted order (which is what makes a
- * delete inside the visible window answerable without a re-query: the
- * successor is already here), and the visible result is the first
- * `limit` entries. Ties are broken by the collection key token,
- * always ascending — the total order LIVE-FORMAT §9 promises.
- *
- * String comparison is CODEPOINT order (SQLite BINARY over UTF-8 —
- * probed, never assumed), which `<` on JS strings gets wrong for
- * astral-vs-BMP pairs; `compareCodepoint` walks code points.
- */
-/**
- * Compare two strings in Unicode code-point order.
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-export declare function compareCodepoint(a: string, b: string): number;
-export type WindowEntry = {
-    token: string;
-    sortValues: any[];
-    item: any;
-};
-/**
- * @typedef {{ token: string, sortValues: any[], item: any }} WindowEntry
- */
-/**
- * A maintained sorted set of rows under the declared order terms plus
- * the key-token tiebreaker.
- * @param {{ desc: boolean, emptyGreatest: boolean }[]} terms
- * @param {number | null} limit - visible size; `null` = everything
- */
-export declare function createSortedWindow(terms: {
-    desc: boolean;
-    emptyGreatest: boolean;
-}[], limit: number | null): {
-    compare: (a: WindowEntry, b: WindowEntry) => number;
-    size: () => number;
-    /** The visible slice: the first `limit` entries (all, unbounded). */
-    visible: () => WindowEntry[];
-    /**
-     * Insert a row; the token MUST not be present.
-     * @param {string} token
-     * @param {any[]} sortValues
-     * @param {any} item
-     */
-    insert(token: string, sortValues: any[], item: any): void;
-    /** Remove a row by token; absent tokens are a no-op. */
-    remove(token: any): boolean;
-};