@jarenjs/db 0.49.2 → 0.66.1

package/src/udf.js

@@ -16,10 +16,16 @@
  * 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.
+ * WHERE-clause use only, and that is the difference between this hatch
+ * and a DECLARED index expression (MODEL-FORMAT §7A). An index over a
+ * registered function makes the database unwritable from a connection
+ * that has not registered the identical function; a fragment registered
+ * here is a QUERY's, discovered from the caller's document at run time,
+ * and indexing one would make a passing query a permanent schema
+ * dependency nobody declared. A model's `indexes[].expression` carries
+ * exactly that dependency in the model, where every store that opens it
+ * is handed the same declaration and one that cannot honour it refuses
+ * at open.
  *
  * Ring 3 extends the hatch to registry `pushable:'scalar'`
  * operators: a predicate fragment that uses a registered scalar operator
@@ -34,7 +40,7 @@
 
 import { semanticKey } from '@jarenjs/core/object';
 import { hashContent } from '@jarenjs/core/string';
-import { compileJsonQuery, analyzeQuery } from '@jarenjs/json/query';
+import { compileJsonQuery, analyzeQuery, JsonQueryRuntimeError } from '@jarenjs/json/query';
 
 /**
  * The SQL identifier for one fragment identity: a short fingerprint of
@@ -61,7 +67,14 @@ const functionNameFor = (identity) => `jaren_p_${hashContent(identity)}`;
  *   external, the determinism check below rejects the fragment, and the
  *   hatch silently never engages.
  * @returns {{ key: string, name: string,
- *   compile: () => (docText: string) => number } | null}
+ *   compile: () => (docText: string, mount?: string) => number } | null}
+ *   - the compiled function takes the row's document text and the
+ *   conjunct's JSON Pointer in the CALLER's document (`/$where`, or
+ *   `/$where/$and/<i>`), which the emitter passes as a literal: an
+ *   engine error raised inside names the wrapper's path (`/$return/…`)
+ *   and is rebased onto that mount, so the native mode and the residual
+ *   report the same location while one registration still serves every
+ *   document that carries the fragment
  */
 export function deterministicFragment(fragment, operators = null, binding = 'it') {
   const analyzeOpts = operators === null
@@ -103,6 +116,7 @@ export function deterministicFragment(fragment, operators = null, binding = 'it'
     // correct, so it does not qualify for the hatch
     return null;
   }
+  const WRAPPER = '/$return';
   return {
     key,
     name: functionNameFor(key),
@@ -111,7 +125,25 @@ export function deterministicFragment(fragment, operators = null, binding = 'it'
       // different name than the analysis would judge one document and
       // run another
       const compiled = compileJsonQuery(wrap(fragment), analyzeOpts);
-      return (docText) => (compiled.ebv(JSON.parse(docText)) ? 1 : 0);
+      // two declared parameters on purpose: node:sqlite registers the
+      // function with the arity `fn.length` reports, and the emitter
+      // always passes the mount beside the document
+      return (docText, mount) => {
+        try {
+          return compiled.ebv(JSON.parse(docText)) ? 1 : 0;
+        }
+        catch (error) {
+          // the engine's own refusal, relocated from the wrapper onto
+          // the caller's document; anything else propagates as it is
+          if (error instanceof JsonQueryRuntimeError && typeof error.docPath === 'string'
+            && error.docPath.startsWith(WRAPPER)) {
+            throw new JsonQueryRuntimeError(error.code, error.reason,
+              (typeof mount === 'string' ? mount : '/$where') + error.docPath.slice(WRAPPER.length),
+              Object.hasOwn(error, 'cause') ? { cause: error.cause } : undefined);
+          }
+          throw error;
+        }
+      };
     },
   };
 }
@@ -139,3 +171,52 @@ export function registerFragment(connection, registered, fragment) {
   registered.set(fragment.key, name);
   return name;
 }
+
+/**
+ * The SQL identifier for one registered aggregate. Unlike a predicate
+ * fragment, the identity IS the operator name — one registry, one
+ * function per name — so the fingerprint has nothing to disambiguate.
+ * @param {string} name
+ * @returns {string}
+ */
+const aggregateNameFor = (name) => `jaren_a_${hashContent(name)}`;
+
+/**
+ * Register a pushable aggregate once per store and answer the SQL name
+ * to call. The SQL fold accumulates the column's values and hands them
+ * to the SAME pure function the residual would call, so the two sides
+ * differ in who drives the loop and in nothing else.
+ *
+ * A `NULL` column value is SKIPPED, because the engine's sequence has no
+ * item where the member is absent — which is why only a path the schema
+ * types as a number that cannot hold `null` reaches here: a stored
+ * `null` and an absent member are one value in SQL, and dropping a
+ * present `null` would answer where the engine does not.
+ *
+ * `undefined` — what these summaries answer for an input they cannot
+ * summarise — becomes SQL `NULL`, which the aggregate decoder reads back
+ * as the empty answer, exactly as the engine's empty sequence does.
+ * @param {any} connection
+ * @param {Map<string, string>} registered - operator name → SQL name
+ * @param {string} name - the registry operator name (`$mean`)
+ * @param {{ fn: Function }} spec
+ * @returns {string} the SQL function name to call
+ */
+export function registerAggregateOperator(connection, registered, name, spec) {
+  const owned = registered.get(name);
+  if (owned !== undefined) return owned;
+  const sqlName = aggregateNameFor(name);
+  connection.registerAggregate(sqlName, {
+    start: () => [],
+    step: (values, value) => {
+      if (value !== null && value !== undefined) values.push(value);
+      return values;
+    },
+    result: (values) => {
+      const out = spec.fn(values);
+      return out === undefined || out === null ? null : out;
+    },
+  });
+  registered.set(name, sqlName);
+  return sqlName;
+}