@jarenjs/db 0.46.5 → 0.56.0

package/src/store.js

@@ -23,19 +23,20 @@
 import { applyJSONPatch } from '@jarenjs/json/patch';
 import { parseJSONPointer } from '@jarenjs/json/pointer';
 
-import { DbCompileError, DbRuntimeError } from './errors.js';
-import { chain, toPromise, isThenable } from './driver.js';
+import { DbCompileError, DbRuntimeError, isDuplicateKeyError } from './errors.js';
+import { chain, toPromise, isThenable, attempt } from './driver.js';
 import { planCollection, planEntity, planJoinTable, verifyShape } from './ddl.js';
 import { translatePatch } from './patch-sql.js';
 import { createQueryEngine, createQueryState, createEntityQueryEngine, createLoadEngine } from './query.js';
 import { normalizeProfile } from './profile.js';
 import { normalizeEntities, explainMapping } from './model.js';
 import { entityCore } from './entity.js';
-import { createTracker } from './tracker.js';
+import { createTracker, membershipKeys } from './tracker.js';
 import { createCaptureEngine, DEFAULT_RETENTION } from './capture.js';
 import { createLiveRegistry, classifyLiveQuery, LIVE_DEFAULTS } from './live.js';
+import { normalizeEventTime } from './live-time.js';
 import { createJobEngine } from './jobs.js';
-import { collectEntityRoots } from './plan.js';
+import { collectEntityRoots, entityRoot } from './plan.js';
 import {
   DERIVE_KINDS, PHYSICAL_KINDS, PRECISION_MIN, PRECISION_MAX, DIMS_MIN, DIMS_MAX,
   derivedValue, memberAt, storedMemberForm, registerDeriveFunctions,
@@ -368,13 +369,6 @@ function requireKey(key, collection, docPath) {
  * @param {string} keyColumn
  * @returns {boolean}
  */
-function isDuplicateKey(error, table, keyColumn) {
-  if (error?.errcode === 1555) return true;
-  return typeof error?.message === 'string'
-    && error.message.includes('UNIQUE constraint failed')
-    && error.message.includes(`${table}.${keyColumn}`);
-}
-
 /**
  * Wrap a database failure for one collection operation.
  * @param {any} error
@@ -385,7 +379,10 @@ function isDuplicateKey(error, table, keyColumn) {
  * @returns {DbRuntimeError}
  */
 function wrapWriteError(error, plan, collection, docPath, key) {
-  if (isDuplicateKey(error, plan.table, plan.keyColumn)) {
+  // an error that already carries a code (a closed store, a refused
+  // document) is the error; only the driver's own failures are wrapped
+  if (typeof error?.code === 'string' && error.code.startsWith('JD')) return error;
+  if (isDuplicateKeyError(error, plan.table, plan.keyColumn)) {
     return new DbRuntimeError('JD2001',
       `a document already exists under key '${String(key)}'`,
       { docPath, collection, key, cause: error });
@@ -593,16 +590,9 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
   };
 
   const runWrite = (statementName, sql, params, key, reads) => {
-    return chain(prepared(statementName, sql), (statement) => {
-      let out;
-      try {
-        out = reads ? statement.get(params) : statement.run(params);
-      }
-      catch (error) {
-        throw wrapWriteError(error, plan, collection.name, collection.docPath, key);
-      }
-      return out;
-    });
+    return chain(prepared(statementName, sql), (statement) =>
+      attempt(() => (reads ? statement.get(params) : statement.run(params)),
+        (error) => wrapWriteError(error, plan, collection.name, collection.docPath, key)));
   };
 
   const core = {
@@ -672,15 +662,10 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
         const { expression, params } = translated.build(
           dialect.quoteIdentifier(plan.docColumn), 1);
         const sql = dialect.dml.updateDoc(shape, expression, params.length + 1);
-        return chain(prepared(`patch:${sql}`, sql), (statement) => {
-          try {
-            statement.run([...params, ...derivedFor(next), key]);
-          }
-          catch (error) {
-            throw wrapWriteError(error, plan, collection.name, collection.docPath, key);
-          }
-          return next;
-        });
+        return chain(prepared(`patch:${sql}`, sql), (statement) =>
+          chain(attempt(() => statement.run([...params, ...derivedFor(next), key]),
+            (error) => wrapWriteError(error, plan, collection.name, collection.docPath, key)),
+          () => next));
       });
     },
     delete(key) {
@@ -755,6 +740,26 @@ function asyncCollection(core, live) {
  * @param {any} options
  * @returns {{ functions: any, extensions: any } | null}
  */
+/**
+ * The schema a WRITE validates against. A store-allocated key (`default:
+ * "auto"`) is absent from the document the injected hook sees — the
+ * database allocates it after validation — so it cannot be required of a
+ * write, and the generated input type already marks it optional; every
+ * other member is the schema's own, defaults filled (§9.6). The read
+ * shape is untouched: the document the store answers carries the key.
+ * @param {any} entity - a normalized entity
+ * @returns {any}
+ */
+function writeSchemaOf(entity) {
+  const schema = entity.schema;
+  const auto = entity.keys.find((key) => entity.properties.get(key).default === 'auto');
+  if (auto === undefined || !Array.isArray(schema?.required) || !schema.required.includes(auto))
+    return schema;
+  const out = { ...schema, required: schema.required.filter((name) => name !== auto) };
+  if (out.required.length === 0) delete out.required;
+  return out;
+}
+
 function resolveOperators(options) {
   const registry = options.operators;
   const hasRegistry = registry !== undefined && registry !== null;
@@ -794,8 +799,14 @@ function resolveOperators(options) {
  * @param {{ driver: any, path?: string, compileSchema?: Function,
  *   busyTimeout?: number, queueTimeout?: number, journalMode?: string,
  *   statementCacheBound?: number, profile?: any, operators?: any,
- *   functions?: any, extensions?: any,
+ *   functions?: any, extensions?: any, zoneProvider?: any,
  *   readOnly?: boolean }} options
+ *   `zoneProvider` is D7's injected clock: a named zone in a temporal
+ *   spec (`{ "every": "P1M", "zone": "Europe/Amsterdam" }`) is host code
+ *   the database cannot have, so a store that never received one refuses
+ *   such a document (`JQ0003`) rather than answering it in UTC. It
+ *   reaches every residual compilation, which is where the calendar
+ *   ladder actually walks.
  * @returns {Promise<any>}
  */
 export function openStore(model, options) {
@@ -1107,8 +1118,9 @@ export function openStore(model, options) {
               });
             }
             for (const joinName of Object.keys(mapping?.joinTables ?? {})) {
-              const pair = joinName.split('_');
-              const columns = pair.map((part) => ({ name: `${part}_key`, role: 'key' }));
+              const join = mapping.joinTables[joinName];
+              const columns = [join.left, join.right]
+                .map((side) => ({ name: side.column, role: 'key' }));
               captureShapes.set(joinName, {
                 kind: 'join', columns,
                 keyIndexes: columns.map((_, i) => i), docIndex: -1,
@@ -1148,12 +1160,21 @@ export function openStore(model, options) {
             defaults: typeof options.jobs === 'object' ? options.jobs : undefined,
           });
           /** Register a collection live query (LIVE-FORMAT §7). */
+          const refuseAsyncLive = () => {
+            if (connection.synchronous !== true) {
+              throw new DbCompileError('JD0051',
+                'live queries are not maintained over an asynchronous connection — a '
+                + 'synchronous driver (node, bun, a synchronous wasm handle) keeps them');
+            }
+          };
           const registerCollectionLive = (core, document, liveOptions) => {
+            refuseAsyncLive();
             const externals = liveOptions?.externals ?? {};
             const keyed = core.model.keySegments !== null;
+            const eventTime = normalizeEventTime(liveOptions, core.model.name);
             const classification = liveOptions?.mode === 'rerun'
               ? { strategy: 'rerun', reason: 'rerun was requested' }
-              : classifyLiveQuery(document, core.queryShape, keyed);
+              : classifyLiveQuery(document, core.queryShape, keyed, eventTime);
             return /** @type {any} */ (liveRegistry).register({
               name: core.model.name,
               tables: new Set([core.model.name]),
@@ -1185,26 +1206,39 @@ export function openStore(model, options) {
           const captureJoinDelete = capture === null || capture.mode !== 'journal'
             ? null
             : (entityName, keyParts) => {
-              const joins = Object.keys(mapping?.joinTables ?? {})
-                .filter((joinName) => joinName.split('_').includes(entityName));
+              const joins = Object.entries(mapping?.joinTables ?? {})
+                .filter(([, join]) => join.left.entity === entityName
+                  || join.right.entity === entityName);
               const nextJoin = (i) => {
                 if (i >= joins.length) return null;
-                const joinName = joins[i];
-                const pair = joinName.split('_');
-                const sql = `SELECT ${pair.map((part) => dialect.quoteIdentifier(`${part}_key`)).join(', ')} `
+                const [joinName, join] = joins[i];
+                const columns = [join.left.column, join.right.column];
+                const own = join.left.entity === entityName ? join.left : join.right;
+                const sql = `SELECT ${columns.map(dialect.quoteIdentifier).join(', ')} `
                   + `FROM ${dialect.quoteIdentifier(joinName)} `
-                  + `WHERE ${dialect.quoteIdentifier(`${entityName}_key`)} = ${dialect.parameterRef(1, 'v')}`;
+                  + `WHERE ${dialect.quoteIdentifier(own.column)} = ${dialect.parameterRef(1, 'v')}`;
                 return chain(connection.prepare(sql), (statement) =>
                   chain(statement.all([keyParts[0]]), (rows) => {
                     for (const row of rows) {
-                      capture.record(joinName,
-                        pair.map((part) => row[`${part}_key`]), undefined, null);
+                      capture.record(joinName, columns.map((column) => row[column]), undefined, null);
                     }
                     return nextJoin(i + 1);
                   }));
               };
               return nextJoin(0);
             };
+          /** The document a keyed `put` replaces, for the journal's
+           * before-image: resolved through the collection's own key when
+           * the caller passed none — a plain upsert recorded as an
+           * `add` of the whole document, and a no-op put as a record. */
+          const readBefore = (core, doc, key) => {
+            const resolved = key !== undefined ? key
+              : core.model.keySegments !== null
+                ? extractKey(doc, core.model.keySegments, core.model.key,
+                  core.model.name, core.model.docPath)
+                : undefined;
+            return resolved === undefined ? undefined : core.get(resolved);
+          };
           /** Journal-mode write wrappers for a collection core. */
           const captureCollection = (collectionName, core) => {
             if (capture === null) return core;
@@ -1216,7 +1250,7 @@ export function openStore(model, options) {
                 return key;
               })),
               put: (doc, key) => guard(() => (journal
-                ? chain(key === undefined ? undefined : core.get(key), (before) =>
+                ? chain(readBefore(core, doc, key), (before) =>
                   chain(core.put(doc, key), (storedKey) => {
                     capture.record(collectionName, [storedKey], before ?? null, doc);
                     return storedKey;
@@ -1295,16 +1329,24 @@ export function openStore(model, options) {
             pushableOperators: operators === null || connection.capabilities.userFunctions !== true
               ? Object.freeze([])
               : Object.freeze([...operators.pushableScalar]),
+            // D7's injected clock: whether a temporal spec naming a
+            // ZONE will compile at all here. Without one the document is
+            // refused (`JQ0003`) rather than answered in UTC, and a
+            // consumer that wants to know before it asks reads this
+            zoneProvider: options.zoneProvider !== undefined && options.zoneProvider !== null,
             capture: captureMode,
             captureLog: captureMode !== 'none'
               && (captureRequested.log === true
                 || (captureRequested.log !== undefined && captureRequested.log !== false)),
-            live: captureMode !== 'none',
+            // maintenance reads rows synchronously; an asynchronous
+            // connection is never maintained (LIVE-FORMAT §12) and says so
+            live: captureMode !== 'none' && connection.synchronous === true,
             jobs: options.jobs === true
               || (options.jobs !== undefined && options.jobs !== false),
           });
 
-          const queryState = createQueryState(options.statementCacheBound, operators);
+          const queryState = createQueryState(options.statementCacheBound, operators,
+            options.zoneProvider);
           const entityEngine = entities.size > 0
             ? createEntityQueryEngine({ connection, entities, mapping, state: queryState })
             : null;
@@ -1336,8 +1378,10 @@ export function openStore(model, options) {
                   { docPath: '/entities', collection: name });
               }
               const validate = options.compileSchema !== undefined
-                ? options.compileSchema(entity.schema)
+                ? options.compileSchema(writeSchemaOf(entity))
                 : null;
+              if (validate !== null && typeof validate !== 'function')
+                throw new TypeError('openStore: compileSchema must return a validation function');
               core = captureEntity(name, entityCore(connection, entity,
                 mapping.entities[name], validate));
               entityCores.set(name, core);
@@ -1367,9 +1411,78 @@ export function openStore(model, options) {
             if (ops !== undefined) return ops;
             const core = entityCoreFor(name);
             const loads = loadEngineFor(name);
+            /**
+             * The many-to-many memberships a document carries, as join
+             * rows: `create()` attaches them after the insert, in the
+             * same transaction — the `<Name>Input` type and `add()` say
+             * a membership array is writable, and `create()` refusing it
+             * made the generated type a lie.
+             * @param {any} doc
+             */
+            const membershipsOf = (doc) => {
+              const out = [];
+              for (const property of entities.get(name).properties.values()) {
+                const relation = property.relation;
+                if (relation?.kind !== 'manyToMany') continue;
+                const join = mapping.joinTables[relation.joinTable];
+                const own = join.left.entity === name ? join.left : join.right;
+                const target = own === join.left ? join.right : join.left;
+                const keys = [...new Set(membershipKeys(doc?.[property.name],
+                  target.referencesKey, property.name,
+                  (reason) => new DbRuntimeError('JD2003', reason,
+                    { docPath: entities.get(name).docPath, collection: name })))];
+                if (keys.length > 0) out.push({ table: relation.joinTable, join, own, target, keys });
+              }
+              return out;
+            };
+            const attach = (made, memberships) => {
+              const ownKey = made[mapping.entities[name].keys[0]];
+              const next = (i) => {
+                if (i >= memberships.length) return null;
+                const { table, join, own, target, keys } = memberships[i];
+                const sql = `INSERT INTO ${dialect.quoteIdentifier(table)} `
+                  + `(${dialect.quoteIdentifier(own.column)}, ${dialect.quoteIdentifier(target.column)}) `
+                  + `VALUES (${dialect.parameterRef(1, 'v')}, ${dialect.parameterRef(2, 'v')})`;
+                return chain(connection.prepare(sql), (statement) => {
+                  const row = (j) => {
+                    if (j >= keys.length) return next(i + 1);
+                    let ran;
+                    try {
+                      ran = statement.run([ownKey, keys[j]]);
+                    }
+                    catch (error) {
+                      throw new DbRuntimeError('JD2005',
+                        `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
+                        { docPath: entities.get(name).docPath, collection: name, key: ownKey, cause: error });
+                    }
+                    return chain(ran, () => {
+                      if (capture !== null && capture.mode === 'journal') {
+                        const value = { [own.column]: ownKey, [target.column]: keys[j] };
+                        const ordered = {};
+                        for (const column of [join.left.column, join.right.column])
+                          ordered[column] = value[column];
+                        capture.record(table, Object.values(ordered), null, ordered);
+                      }
+                      return row(j + 1);
+                    });
+                  };
+                  return row(0);
+                });
+              };
+              return next(0);
+            };
             ops = {
-              create: (doc) => chain(core.create(doc),
-                (made) => tracker.register(name, made)),
+              create: (doc) => {
+                const memberships = membershipsOf(doc);
+                if (memberships.length === 0)
+                  return chain(core.create(doc), (made) => tracker.register(name, made));
+                // one capture scope and one transaction around the row and
+                // its join rows: a membership the database refuses rolls the
+                // row back too, and journal capture records the join rows
+                return chain(guard(() => connection.transaction(() =>
+                  chain(core.create(doc), (made) => chain(attach(made, memberships), () => made)))),
+                (made) => tracker.register(name, made));
+              },
               get: (key) => chain(core.get(key), (doc) =>
                 (doc === undefined ? undefined : tracker.register(name, doc))),
               update: (key, changes) => chain(core.update(key, changes),
@@ -1385,6 +1498,10 @@ export function openStore(model, options) {
               put: (next) => tracker.put(name, next),
               remove: (keyOrDoc) => tracker.remove(name, keyOrDoc),
               discard: (keyOrDoc) => tracker.discard(name, keyOrDoc),
+              // membership (§11.7): local bookkeeping like add/put/remove;
+              // the join rows are written by saveChanges()
+              link: (own, member, target) => tracker.link(name, own, member, target),
+              unlink: (own, member, target) => tracker.unlink(name, own, member, target),
               noTracking: {
                 get: (key) => core.get(key),
                 load: (spec) => loads.load(spec),
@@ -1435,7 +1552,22 @@ export function openStore(model, options) {
                   put: ops.put,
                   remove: ops.remove,
                   discard: ops.discard,
+                  link: ops.link,
+                  unlink: ops.unlink,
                   asNoTracking: () => untracked,
+                  // the provider contract over ONE entity root (MODEL-FORMAT
+                  // §10.1): the document is over the multi-entity root and
+                  // goes to the entity engine whole; `root` is the hint a
+                  // chain binds its items through, `scope` the identity two
+                  // sets of one store share so their documents may be joined
+                  // (it carries every root's `relations`, so a hop may chain),
+                  // `relations` this entity's own relation table (§10.1).
+                  // `execute` stays value-or-promise (D2), as a collection's
+                  execute: (document, queryOptions) => entityEngine.execute(document, queryOptions),
+                  explain: lift((document, queryOptions) => entityEngine.explain(document, queryOptions)),
+                  root: entityRoot(name),
+                  scope: entityEngine,
+                  relations: entityEngine.relations[name],
                 });
                 asyncEntityHandles.set(name, handle);
               }
@@ -1443,11 +1575,15 @@ export function openStore(model, options) {
             },
             saveChanges: entities.size === 0 ? undefined
               : lift(() => guard(() => tracker.saveChanges())),
-            // entity DOCUMENTS query the multi-entity root at the store
+            // entity DOCUMENTS query the multi-entity root at the store;
+            // `roots` names the entity arrays this provider serves, so a
+            // chain asked to iterate the store itself can refuse by name
             execute: entityEngine === null ? undefined
               : (document, queryOptions) => entityEngine.execute(document, queryOptions),
             explain: entityEngine === null ? undefined
               : lift((document, queryOptions) => entityEngine.explain(document, queryOptions)),
+            roots: entityEngine === null ? undefined : Object.freeze([...entities.keys()]),
+            relations: entityEngine === null ? undefined : entityEngine.relations,
             // entity live queries re-run on invalidation — declared,
             // not attempted (LIVE-FORMAT §7)
             live: entityEngine === null ? undefined
@@ -1456,6 +1592,12 @@ export function openStore(model, options) {
                   throw new DbCompileError('JD0050',
                     'live queries require change capture — open the store with { capture: true }');
                 }
+                refuseAsyncLive();
+                if (liveOptions?.eventTime !== undefined) {
+                  throw new DbCompileError('JD0053',
+                    'live eventTime maintains a collection view — an entity document re-runs, '
+                    + 'so a watermark would describe nothing (LIVE-FORMAT §13)');
+                }
                 const roots = collectEntityRoots(document, entities);
                 if (roots.size === 0) {
                   throw new TypeError(
@@ -1564,6 +1706,8 @@ export function openStore(model, options) {
           if (connection.synchronous) {
             /** @type {Map<string, any>} */
             const syncHandles = new Map();
+            /** @type {Map<string, any>} */
+            const syncEntityHandles = new Map();
             store.sync = Object.freeze({
               collection(name) {
                 let handle = syncHandles.get(name);
@@ -1583,31 +1727,61 @@ export function openStore(model, options) {
                 }
                 return handle;
               },
-              transaction: (fn) => topLevelTransaction(fn),
+              transaction: (fn) => {
+                // the synchronous surface answers values: while a
+                // transaction owns the connection it could only QUEUE,
+                // which handed a Promise back under a value's type
+                if (opened.mustQueue) {
+                  throw new DbCompileError('JD0012',
+                    'the synchronous transaction cannot wait for the open transaction to '
+                    + 'settle — nest through the store the callback received, or use the '
+                    + 'asynchronous store.transaction()');
+                }
+                return topLevelTransaction(fn);
+              },
               entity(name) {
-                const ops = trackedOpsFor(name);
-                const untracked = Object.freeze({
-                  get: (key) => ops.noTracking.get(key),
-                  load: (spec) => ops.noTracking.load(spec),
-                });
-                return Object.freeze({
-                  create: (doc) => ops.create(doc),
-                  get: (key) => ops.get(key),
-                  update: (key, changes) => ops.update(key, changes),
-                  delete: (key) => ops.delete(key),
-                  load: (spec) => ops.load(spec),
-                  explainLoad: ops.explainLoad,
-                  add: ops.add,
-                  put: ops.put,
-                  remove: ops.remove,
-                  discard: ops.discard,
-                  asNoTracking: () => untracked,
-                });
+                let handle = syncEntityHandles.get(name);
+                if (handle === undefined) {
+                  const ops = trackedOpsFor(name);
+                  const untracked = Object.freeze({
+                    get: (key) => ops.noTracking.get(key),
+                    load: (spec) => ops.noTracking.load(spec),
+                  });
+                  handle = Object.freeze({
+                    create: (doc) => ops.create(doc),
+                    get: (key) => ops.get(key),
+                    update: (key, changes) => ops.update(key, changes),
+                    delete: (key) => ops.delete(key),
+                    load: (spec) => ops.load(spec),
+                    explainLoad: ops.explainLoad,
+                    add: ops.add,
+                    put: ops.put,
+                    remove: ops.remove,
+                    discard: ops.discard,
+                    link: ops.link,
+                    unlink: ops.unlink,
+                    asNoTracking: () => untracked,
+                    // the same provider members as the asynchronous handle,
+                    // answering values; one handle per name, so two chains
+                    // over one set share one source identity
+                    execute: (document, queryOptions) => entityEngine.execute(document, queryOptions),
+                    explain: (document, queryOptions) => entityEngine.explain(document, queryOptions),
+                    root: entityRoot(name),
+                    scope: entityEngine,
+                    relations: entityEngine.relations[name],
+                  });
+                  syncEntityHandles.set(name, handle);
+                }
+                return handle;
               },
               saveChanges: entities.size === 0 ? undefined
                 : () => guard(() => tracker.saveChanges()),
               execute: entityEngine === null ? undefined
                 : (document, queryOptions) => entityEngine.execute(document, queryOptions),
+              explain: entityEngine === null ? undefined
+                : (document, queryOptions) => entityEngine.explain(document, queryOptions),
+              roots: entityEngine === null ? undefined : Object.freeze([...entities.keys()]),
+              relations: entityEngine === null ? undefined : entityEngine.relations,
             });
           }
           return chain(capture === null ? null : capture.ready,