@jarenjs/db 0.34.0

package/src/typed.js

@@ -0,0 +1,19 @@
+//@ts-check
+/**
+ * @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 function typedStore(store) {
+  return store;
+}

package/src/types.js

@@ -0,0 +1,36 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { schemaTypeAt } from './ddl.js';
+
+const KNOWN = new Set(['string', 'integer', 'number', 'boolean']);
+
+/**
+ * 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 function typeOfPath(schema, segments) {
+  const declared = schemaTypeAt(schema, segments);
+  return declared !== undefined && KNOWN.has(declared)
+    ? /** @type {any} */ (declared)
+    : 'unknown';
+}
+
+/**
+ * Whether a planner type is numeric (SQL comparison family).
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isNumericType(type) {
+  return type === 'integer' || type === 'number';
+}

package/src/udf.js

@@ -0,0 +1,132 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { semanticKey } from '@jarenjs/core/object';
+import { hashContent } from '@jarenjs/core/string';
+import { compileJsonQuery, analyzeQuery } from '@jarenjs/json/query';
+
+/**
+ * The SQL identifier for one fragment identity: a short fingerprint of
+ * the identity, not the identity itself (SQLite names are not the place
+ * for a whole serialized document). Distinct identities may collide
+ * here; {@link registerFragment} disambiguates.
+ * @param {string} identity
+ * @returns {string}
+ */
+const functionNameFor = (identity) => `jaren_p_${hashContent(identity)}`;
+
+/**
+ * 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).
+ * @returns {{ key: string, name: string,
+ *   compile: () => (docText: string) => number } | null}
+ */
+export function deterministicFragment(fragment, operators = null) {
+  const analyzeOpts = operators === null
+    ? undefined
+    : { functions: operators.functions, extensions: operators.extensions };
+  let dependencies;
+  try {
+    dependencies = analyzeQuery({ $let: { it: '$' }, $return: fragment }, analyzeOpts).dependencies;
+  }
+  catch {
+    return null;
+  }
+  // determinism: a UDF registered `deterministic:true` must not close
+  // over changing state — no externals, no collations, ever
+  if (dependencies.externals.length > 0
+    || dependencies.collations.length > 0) return null;
+  // pushability: core operators are always fine; a REGISTERED operator or
+  // host function is admitted only where the pack marked it
+  // `pushable:'scalar'`. With no registry, any host function still
+  // disqualifies (the original hatch was engine-internal fragments only).
+  const pushable = operators === null ? null : operators.pushableScalar ?? new Set();
+  const registered = operators === null ? null : operators.extensions;
+  for (const name of dependencies.functions) {
+    if (pushable === null || !pushable.has(name)) return null;
+  }
+  for (const name of dependencies.operators) {
+    if (registered !== null && Object.prototype.hasOwnProperty.call(registered, name)
+      && !pushable.has(name)) return null;
+  }
+  /** @type {string} */
+  let key;
+  try {
+    key = semanticKey(fragment);
+  }
+  catch {
+    // a fragment that cannot be keyed injectively must not be shared
+    // under some other fragment's registration; the residual is always
+    // correct, so it does not qualify for the hatch
+    return null;
+  }
+  return {
+    key,
+    name: functionNameFor(key),
+    compile: () => {
+      const compiled = compileJsonQuery({ $let: { it: '$' }, $return: fragment }, analyzeOpts);
+      return (docText) => (compiled.ebv(JSON.parse(docText)) ? 1 : 0);
+    },
+  };
+}
+
+/**
+ * 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 function registerFragment(connection, registered, fragment) {
+  const owned = registered.get(fragment.key);
+  if (owned !== undefined) return owned;
+  const stem = functionNameFor(fragment.key);
+  const taken = new Set(registered.values());
+  let name = stem;
+  for (let n = 2; taken.has(name); n++) name = `${stem}_${n}`;
+  connection.registerFunction(name, { deterministic: true }, fragment.compile());
+  registered.set(fragment.key, name);
+  return name;
+}

package/src/window.js

@@ -0,0 +1,125 @@
+//@ts-check
+/**
+ * @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 function compareCodepoint(a, b) {
+  if (a === b) return 0;
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length;) {
+    const ca = /** @type {number} */ (a.codePointAt(i));
+    const cb = /** @type {number} */ (b.codePointAt(i));
+    if (ca !== cb) return ca < cb ? -1 : 1;
+    i += ca > 0xffff ? 2 : 1;
+  }
+  return a.length < b.length ? -1 : 1;
+}
+
+/**
+ * Compare two sort VALUES of one order term. Absent (`undefined`)
+ * ranks per `emptyGreatest` as the greatest or least value; direction
+ * is applied by the caller. Mixed types rank number-before-string —
+ * deterministic on hostile data, exact on schema-conformant data (the
+ * same precondition the pushdown ordering documents).
+ * @param {any} a
+ * @param {any} b
+ * @param {boolean} emptyGreatest
+ * @returns {number}
+ */
+function compareValues(a, b, emptyGreatest) {
+  const aEmpty = a === undefined;
+  const bEmpty = b === undefined;
+  if (aEmpty || bEmpty) {
+    if (aEmpty && bEmpty) return 0;
+    return (aEmpty ? 1 : -1) * (emptyGreatest ? 1 : -1);
+  }
+  const aNumber = typeof a === 'number';
+  const bNumber = typeof b === 'number';
+  if (aNumber && bNumber) return a < b ? -1 : a > b ? 1 : 0;
+  if (aNumber !== bNumber) return aNumber ? -1 : 1;
+  return compareCodepoint(String(a), String(b));
+}
+
+/**
+ * @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 function createSortedWindow(terms, limit) {
+  /** @type {WindowEntry[]} */
+  const entries = [];
+  /** @type {Map<string, WindowEntry>} */
+  const byToken = new Map();
+
+  /**
+   * @param {WindowEntry} a
+   * @param {WindowEntry} b
+   */
+  const compare = (a, b) => {
+    for (let i = 0; i < terms.length; i++) {
+      const term = terms[i];
+      const cmp = compareValues(a.sortValues[i], b.sortValues[i], term.emptyGreatest);
+      if (cmp !== 0) return term.desc ? -cmp : cmp;
+    }
+    return compareCodepoint(a.token, b.token);
+  };
+
+  /** Binary search for the insertion index of `entry`. */
+  const positionOf = (entry) => {
+    let low = 0;
+    let high = entries.length;
+    while (low < high) {
+      const mid = (low + high) >>> 1;
+      if (compare(entries[mid], entry) < 0) low = mid + 1;
+      else high = mid;
+    }
+    return low;
+  };
+
+  return {
+    compare,
+    size: () => entries.length,
+    /** The visible slice: the first `limit` entries (all, unbounded). */
+    visible: () => (limit === null ? [...entries] : entries.slice(0, limit)),
+    /**
+     * Insert a row; the token MUST not be present.
+     * @param {string} token
+     * @param {any[]} sortValues
+     * @param {any} item
+     */
+    insert(token, sortValues, item) {
+      const entry = { token, sortValues, item };
+      entries.splice(positionOf(entry), 0, entry);
+      byToken.set(token, entry);
+    },
+    /** Remove a row by token; absent tokens are a no-op. */
+    remove(token) {
+      const entry = byToken.get(token);
+      if (entry === undefined) return false;
+      entries.splice(entries.indexOf(entry), 1);
+      byToken.delete(token);
+      return true;
+    },
+  };
+}

package/types/app.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The app binding for live queries (LIVE-FORMAT §10): generated
+ * documents plus the subscription handler factory — the db package
+ * never imports `@jarenjs/app`.
+ */
+import type { Store } from './index.js';
+
+export interface LiveAppBindingOptions {
+  /** The registered subscription handler name (default 'db/live'). */
+  run?: string;
+  /** The patch-forwarding action name (default 'db/liveChanged'). */
+  action?: string;
+  /** JSON Pointer to the state slot holding `{ rows }`. */
+  statePath: string;
+  /** Collection name; omit for an entity-root document. */
+  collection?: string;
+  query: unknown;
+  externals?: Record<string, unknown>;
+  mode?: 'auto' | 'incremental' | 'rerun';
+  /** An APP-FORMAT `when` query gating the subscription. */
+  when?: unknown;
+}
+
+export interface LiveAppBinding {
+  /** The APP-FORMAT §5.3 subscription entry (plain data). */
+  subscription: unknown;
+  /** `{ [action]: { patch: '$payload' } }` — merge into `actions`. */
+  actions: Record<string, unknown>;
+}
+
+export declare function liveAppBinding(options: LiveAppBindingOptions): LiveAppBinding;
+export declare function prefixLivePatch(
+  patch: ReadonlyArray<{ op: string; path: string }>, statePath: string):
+  Array<{ op: string; path: string }>;
+export declare function createLiveSubscription(store: Store):
+  (props: unknown, dispatch: (action: string, payload: unknown) => void) => () => void;

package/types/bun.d.ts

@@ -0,0 +1,9 @@
+/** Hand-authored declarations for @jarenjs/db/bun (strategy 1). */
+import type { Driver } from '@jarenjs/db';
+
+/** The `bun:sqlite` binding; the builtin loads lazily inside open(). */
+export declare function bunDriver(): Driver;
+/** Adapt an already-constructed bun Database-shaped database. */
+export declare function adaptBunDatabase(db: unknown): unknown;
+/** Construct and adapt from a loaded `bun:sqlite`-shaped module. */
+export declare function fromBunModule(mod: unknown, path: string, options?: unknown): unknown;