@jarenjs/db 0.49.2 → 0.66.1

package/src/entity.js

@@ -18,9 +18,10 @@ import { compileJsonQuery } from '@jarenjs/json/query';
 import {
   getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339,
 } from '@jarenjs/core/dates/rfc3339';
+import { resolveRuntime } from '@jarenjs/core/runtime';
 
-import { DbRuntimeError } from './errors.js';
-import { chain } from './driver.js';
+import { DbRuntimeError, wrapDriverError } from './errors.js';
+import { chain, attempt } from './driver.js';
 
 /**
  * The write/read machinery for one entity, prepared once.
@@ -28,9 +29,13 @@ import { chain } from './driver.js';
  * @param {any} entity - the normalized entity (model.js)
  * @param {any} entityMapping - `explainMapping(...).entities[name]`
  * @param {((doc: any) => any) | null} validate
+ * @param {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime] - the
+ *   host's runtime record: the clock a `default: 'now'` stamps and the
+ *   identifier a `default: 'uuid'` allocates; the platform's own when absent
  * @returns {any}
  */
-export function entityCore(connection, entity, entityMapping, validate) {
+export function entityCore(connection, entity, entityMapping, validate, runtime = undefined) {
+  const host = resolveRuntime(runtime);
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
   const table = entityMapping.table;
@@ -132,6 +137,28 @@ export function entityCore(connection, entity, entityMapping, validate) {
     return doc;
   };
 
+  /** The document as a read will answer it. For a column-mapped scalar,
+   * JSON `null` and absence both store as SQL NULL and read back ABSENT
+   * (§9.3) — so a value a write RETURNS drops it too, and the promise
+   * this file opens with holds: the value the application sees IS the
+   * value stored. A property that needs present-`null` declares
+   * `column: "json"` and stays in the document, where it survives; an
+   * epoch column keeps its string in the document for the same reason. */
+  const asStored = (doc) => {
+    let out = doc;
+    const drop = (name) => {
+      if (!(name in out) || (out[name] !== null && out[name] !== undefined)) return;
+      if (out === doc) out = { ...doc };
+      delete out[name];
+    };
+    for (const column of scalarColumns) {
+      if (column.epoch) continue; // the string is in the document, null and all
+      drop(column.name);
+    }
+    for (const fk of fkColumns) drop(fk);
+    return out;
+  };
+
   // defaults, compiled once
   const defaulters = [];
   const updateStamps = [];
@@ -139,13 +166,17 @@ export function entityCore(connection, entity, entityMapping, validate) {
     const declared = property.default;
     if (declared === undefined || property.relation !== undefined) continue;
     if (declared === 'now' || declared === 'updated') {
-      defaulters.push({ name: property.name, fill: () => new Date().toISOString() });
-      if (declared === 'updated')
-        updateStamps.push({ name: property.name, fill: () => new Date().toISOString() });
+      // a `date` property takes the calendar date; a date-time stamp on
+      // it was invalid under its own format and refused by an epoch column
+      const stamp = property.format === 'date'
+        ? () => new Date(host.now()).toISOString().slice(0, 10)
+        : () => new Date(host.now()).toISOString();
+      defaulters.push({ name: property.name, fill: stamp });
+      if (declared === 'updated') updateStamps.push({ name: property.name, fill: stamp });
       continue;
     }
     if (declared === 'uuid') {
-      defaulters.push({ name: property.name, fill: () => crypto.randomUUID() });
+      defaulters.push({ name: property.name, fill: () => host.uuid() });
       continue;
     }
     if (declared === 'auto') continue; // the database allocates
@@ -162,12 +193,42 @@ export function entityCore(connection, entity, entityMapping, validate) {
     for (const { name, fill } of defaulters) {
       if (out[name] === undefined) out[name] = fill(out);
     }
+    // the version token starts at 0 on insert: a row written with SQL
+    // NULL never matched the tracker's `WHERE ver = 0` and could not be
+    // saved through the unit of work at all
+    if (!updating && entity.version !== null && entity.version !== undefined
+      && out[entity.version] === undefined) {
+      out[entity.version] = 0;
+    }
     if (updating) {
       for (const { name, fill } of updateStamps) out[name] = fill(out);
     }
     return out;
   };
 
+  /**
+   * Refuse relation members a write cannot store: every relation member
+   * is a projection (§10.1), except a many-to-many MEMBERSHIP array,
+   * which `create()`/`add()` attach through the join table.
+   * @param {any} doc
+   * @param {string} verb
+   * @param {boolean} memberships - whether membership arrays are taken
+   */
+  const refuseProjections = (doc, verb, memberships) => {
+    for (const name of relationNames) {
+      const value = doc?.[name];
+      if (value === undefined || (Array.isArray(value) && value.length === 0)) continue;
+      const relation = entity.properties.get(name).relation;
+      if (memberships && relation.kind === 'manyToMany' && Array.isArray(value)) continue;
+      throw new DbRuntimeError('JD2003',
+        `'${name}' is a relation member — ${verb}() stores no projections; `
+        + (relation.kind === 'manyToMany'
+          ? 'membership changes through the unit of work (put + saveChanges)'
+          : 'write the related entities themselves'),
+        { docPath, collection: entity.name });
+    }
+  };
+
   const checkValid = (doc) => {
     if (validate === null) return;
     const outcome = validate(doc);
@@ -187,7 +248,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
   const prepared = (name, sql) => {
     let statement = statements.get(name);
     if (statement === undefined) {
-      statement = connection.prepare(sql);
+      statement = connection.prepare(sql, { readOnly: name === 'get' });
       statements.set(name, statement);
     }
     return statement;
@@ -232,14 +293,11 @@ export function entityCore(connection, entity, entityMapping, validate) {
       { docPath, collection: entity.name });
   };
 
-  const wrapWrite = (error, key) => {
-    if (/** @type {any} */ (error)?.code === 'JD2003') return error;
-    return new DbRuntimeError('JD2005',
-      `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
-      key === undefined
-        ? { docPath, collection: entity.name, cause: error }
-        : { docPath, collection: entity.name, key, cause: error });
-  };
+  const wrapWrite = (error, key) => wrapDriverError(error, {
+    docPath, collection: entity.name, ...(key === undefined ? undefined : { key }),
+    ...(keys.length === 1 ? { unique: { table, column: keys[0] } } : undefined),
+    duplicateReason: `a '${entity.name}' already exists under key ${JSON.stringify(key)}`,
+  });
 
   const columnByName = new Map(scalarColumns.map((column) => [column.name, column]));
   /** Encode ONE column assignment the way {@link split} would. */
@@ -269,7 +327,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
     complete: (doc, { updating }) => {
       const completed = applyDefaults(doc, { updating });
       checkValid(completed);
-      return completed;
+      return asStored(completed);
     },
     validateOnly: (doc) => checkValid(doc),
     stampUpdated: (doc) => {
@@ -280,15 +338,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
     },
     normalizeKey: (key) => normalizeKeyArg(key),
     create(doc) {
-      for (const name of relationNames) {
-        const value = doc?.[name];
-        if (value !== undefined && (!Array.isArray(value) || value.length > 0)) {
-          throw new DbRuntimeError('JD2003',
-            `'${name}' is a relation member — create() stores no `
-            + 'projections; use the unit of work for membership',
-            { docPath, collection: entity.name });
-        }
-      }
+      refuseProjections(doc, 'create', true);
       const completed = applyDefaults(doc, { updating: false });
       checkValid(completed);
       const { values, rest } = split(completed);
@@ -296,33 +346,39 @@ export function entityCore(connection, entity, entityMapping, validate) {
       const sql = insertSqlFor(names);
       return chain(prepared(`insert:${names.join(',')}`, sql), (statement) => {
         const params = [...values.map((value) => value.value), JSON.stringify(rest)];
-        let out;
-        try {
-          out = autoKey !== null && !names.includes(autoKey)
-            ? statement.get(params)
-            : (statement.run(params), null);
-        }
-        catch (error) {
-          throw wrapWrite(error, completed[keys[0]]);
-        }
-        if (out !== null) return { ...completed, [autoKey]: out.key };
-        return completed;
+        const returning = autoKey !== null && !names.includes(autoKey);
+        return chain(
+          attempt(() => (returning ? statement.get(params) : statement.run(params)),
+            (error) => wrapWrite(error, completed[keys[0]])),
+          (out) => asStored(returning ? { ...completed, [autoKey]: out.key } : completed));
       });
     },
     get(key) {
       const parts = normalizeKeyArg(key);
       const sql = `SELECT ${selectColumns} FROM ${q(table)} WHERE ${keyWhere(0)}`;
-      return chain(prepared('get', sql), (statement) =>
-        chain(statement.get(parts), (row) => (row === undefined ? undefined : merge(row))));
+      // classified like every read of the query engines, never raw
+      return attempt(() => chain(prepared('get', sql), (statement) =>
+        chain(statement.get(parts), (row) => (row === undefined ? undefined : merge(row)))),
+      (error) => wrapDriverError(error, { docPath, collection: entity.name, key }));
     },
     update(key, changes) {
       const parts = normalizeKeyArg(key);
+      refuseProjections(changes, 'update', false);
       return chain(this.get(key), (current) => {
         if (current === undefined) {
           throw new DbRuntimeError('JD2006',
             `no '${entity.name}' to update under that key`,
             { docPath, collection: entity.name });
         }
+        for (const keyName of keys) {
+          // the key identifies the row the UPDATE addresses; rewriting it
+          // through `changes` moved rows out from under the tracker
+          if (changes?.[keyName] !== undefined && changes[keyName] !== current[keyName]) {
+            throw new DbRuntimeError('JD2003',
+              `'${keyName}' is the primary key — update() cannot rewrite it; delete and create`,
+              { docPath, collection: entity.name, key: parts[0] });
+          }
+        }
         const next = applyDefaults({ ...current, ...changes }, { updating: true });
         // an explicit update is last-write-wins by contract (§11.2),
         // but it still moves a declared version token so optimistic
@@ -337,31 +393,18 @@ export function entityCore(connection, entity, entityMapping, validate) {
         ].join(', ');
         const sql = `UPDATE ${q(table)} SET ${assignments} `
           + `WHERE ${keyWhere(values.length + 1)}`;
-        return chain(prepared(`update:${values.length}`, sql), (statement) => {
-          try {
-            statement.run([...values.map((value) => value.value),
-              JSON.stringify(rest), ...parts]);
-          }
-          catch (error) {
-            throw wrapWrite(error, parts[0]);
-          }
-          return next;
-        });
+        return chain(prepared(`update:${values.length}`, sql), (statement) =>
+          chain(attempt(() => statement.run([...values.map((value) => value.value),
+            JSON.stringify(rest), ...parts]), (error) => wrapWrite(error, parts[0])),
+          () => asStored(next)));
       });
     },
     delete(key) {
       const parts = normalizeKeyArg(key);
       const sql = `DELETE FROM ${q(table)} WHERE ${keyWhere(0)}`;
-      return chain(prepared('delete', sql), (statement) => {
-        let out;
-        try {
-          out = statement.run(parts);
-        }
-        catch (error) {
-          throw wrapWrite(error, parts[0]);
-        }
-        return chain(out, (result) => Number(result?.changes ?? 0) > 0);
-      });
+      return chain(prepared('delete', sql), (statement) =>
+        chain(attempt(() => statement.run(parts), (error) => wrapWrite(error, parts[0])),
+          (result) => Number(result?.changes ?? 0) > 0));
     },
   };
 }