@jarenjs/db 0.34.0

package/src/algebra.js

@@ -0,0 +1,105 @@
+//@ts-check
+/**
+ * @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. Constructs beyond it are residuals by
+ * design (see ARCHITECTURE.md's deliberate-residual table).
+ */
+
+/** The plan format version, carried on every plan. */
+export const PLAN_VERSION = 1;
+
+/**
+ * @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 }
+ * )} PlanPredicate
+ *
+ * @typedef {{ ref: PlanRef, desc: boolean, emptyGreatest: boolean }} PlanOrderTerm
+ *
+ * @typedef {{
+ *   planVersion: number,
+ *   alg: 'select',
+ *   collection: string,
+ *   filter: PlanPredicate | null,
+ *   order: PlanOrderTerm[] | null,
+ *   window: { offset: number, limit: number | null } | 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 function selectPlan(collection) {
+  return {
+    planVersion: PLAN_VERSION,
+    alg: 'select',
+    collection,
+    filter: null,
+    order: null,
+    window: null,
+    aggregate: null,
+    project: 'document',
+  };
+}
+
+/**
+ * Conjoin a predicate onto a plan's filter.
+ * @param {PlanPredicate | null} filter
+ * @param {PlanPredicate} predicate
+ * @returns {PlanPredicate}
+ */
+export function conjoin(filter, predicate) {
+  if (filter === null) return predicate;
+  if (filter.p === 'and') return { p: 'and', items: [...filter.items, predicate] };
+  return { p: 'and', items: [filter, predicate] };
+}
+
+/**
+ * Tokens that must never appear anywhere in a plan: if one does, SQL
+ * text leaked out of the dialect layer into the neutral algebra.
+ */
+const SQL_TOKENS = [
+  'SELECT', 'WHERE', 'ORDER BY', 'LIMIT ', 'INSERT', 'FROM ',
+  'jsonb_extract', 'json_type', 'substr(', 'instr(', '"doc"', '@p1', ' AS ',
+];
+
+/**
+ * Throw when a plan value carries anything that smells like SQL.
+ * @param {unknown} plan
+ */
+export function assertNoSqlText(plan) {
+  const text = JSON.stringify(plan);
+  for (const token of SQL_TOKENS) {
+    if (text.includes(token))
+      throw new Error(`plan carries SQL text: found '${token}'`);
+  }
+}

package/src/app.js

@@ -0,0 +1,108 @@
+//@ts-check
+/**
+ * @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 function prefixLivePatch(patch, statePath) {
+  return patch.map((op) => ({
+    ...op,
+    path: statePath + op.path,
+    ...(op.from !== undefined ? { from: statePath + op.from } : {}),
+  }));
+}
+
+/**
+ * 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 function liveAppBinding(options) {
+  if (typeof options?.statePath !== 'string' || !options.statePath.startsWith('/')) {
+    throw new TypeError('liveAppBinding needs a statePath JSON Pointer');
+  }
+  if (options.query === undefined) {
+    throw new TypeError('liveAppBinding needs the query document');
+  }
+  const run = options.run ?? 'db/live';
+  const action = options.action ?? 'db/liveChanged';
+  return {
+    subscription: {
+      run,
+      with: {
+        action,
+        statePath: options.statePath,
+        ...(options.collection !== undefined ? { collection: options.collection } : {}),
+        query: options.query,
+        ...(options.externals !== undefined ? { externals: options.externals } : {}),
+        ...(options.mode !== undefined ? { mode: options.mode } : {}),
+      },
+      ...(options.when !== undefined ? { when: options.when } : {}),
+    },
+    actions: { [action]: { patch: '$payload' } },
+  };
+}
+
+/**
+ * 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 function createLiveSubscription(store) {
+  return (props, dispatch) => {
+    const { action, statePath, collection, query, externals, mode } = props;
+    let closed = false;
+    /** @type {any} */
+    let live = null;
+    const registration = collection !== undefined
+      ? store.collection(collection).live(query, { externals, mode })
+      : store.live(query, { externals, mode });
+    registration.then((handle) => {
+      if (closed) {
+        handle.close();
+        return;
+      }
+      live = handle;
+      dispatch(action, [{ op: 'replace', path: statePath, value: handle.result }]);
+      handle.subscribe((event) => {
+        if (event.error !== undefined) {
+          dispatch(`${action}/error`, {
+            code: event.error.code, message: String(event.error.message ?? event.error),
+          });
+          return;
+        }
+        dispatch(action, prefixLivePatch(event.patch, statePath));
+      });
+    }, (error) => {
+      if (!closed) {
+        dispatch(`${action}/error`, {
+          code: error.code, message: String(error.message ?? error),
+        });
+      }
+    });
+    return () => {
+      closed = true;
+      if (live !== null) live.close();
+    };
+  };
+}