@jarenjs/db 0.49.2 → 0.56.0

package/types/typed.d.ts

@@ -15,6 +15,8 @@
 import type {
   EntityKeyArg, LoadExplanation, SaveReport, Store, StoreCapabilities,
   StoreStats, Collection, ExecuteOptions, SequenceResult, ValueOrPromise,
+  Dialect, ChangeRecord, LiveOptions, LiveQuery, JobsApi, SyncStore,
+  EntityScope, RelationEntry, RelationTable,
 } from '@jarenjs/db';
 
 /** The self-referential constraint an interface can satisfy: generated
@@ -36,9 +38,14 @@ 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 & { include?: TypedInclude<E, M> };
+
 export interface TypedLoadSpecBase {
   /** A query expression over `$it` — its format is the runtime's. */
   where?: unknown;
@@ -68,15 +75,31 @@ 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>>>>;
@@ -85,18 +108,51 @@ export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
   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>>;
+  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;
+  changesSince?(after: number): Promise<ChangeRecord[]>;
+  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,10 @@ 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;

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;

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;
-};