@jarenjs/db 0.46.5 → 0.56.0

package/dist/types/store.d.ts

@@ -1,53 +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,
- *   readOnly?: boolean }} options
- * @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;
-    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;
-};