@jarenjs/db 0.73.0 → 0.83.2

package/src/mutation.js

@@ -0,0 +1,165 @@
+//@ts-check
+/** Bounded column mutation documents, lowered through the entity's writer plan. */
+import { analyzeQuery } from '@jarenjs/json/query';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { chain, attempt } from './driver.js';
+import { DbCompileError, DbRuntimeError, wrapDriverError } from './errors.js';
+import { entityShape, planEntityPredicate } from './plan.js';
+import { createEntityPredicateEmitters } from './emit.js';
+import { physicalSelection } from './physical.js';
+import { utf8Length } from './cursor.js';
+
+/** Compile once per document, execute within the existing guarded transaction.
+ * @param {any} connection @param {any} entity @param {any} mapping @param {any} core */
+export function createEntityMutation(connection, entity, mapping, core) {
+  const dialect = connection.dialect;
+  const q = dialect.quoteIdentifier;
+  const plans = new Map();
+  const fail = (reason) => { throw new DbCompileError('JD0038', reason, entity.docPath); };
+  const column = (name) => {
+    const c = mapping.columns.find((entry) => entry.name === name);
+    if (!c) return fail(`unknown stored member '${name}'`);
+    return c;
+  };
+  const writableColumn = (name) => {
+    const c = column(name);
+    if (c.generated || core.plan.keys.includes(name) || name === entity.version)
+      fail(`'${name}' is an identity, revision or generated member`);
+    return c;
+  };
+  const comparison = (c, prefix = '') => {
+    const value = prefix + q(c.physical);
+    return c.storage === 'string' ? dialect.codepoint(value) : value;
+  };
+  const compile = (document) => {
+    if (entity.physical == null || dialect.name !== 'sqlite') fail('native mutations require a declared SQLite column layout');
+    core.plan.writable();
+    if (!document || typeof document !== 'object' || Array.isArray(document)) fail('a mutation is an object');
+    const allowed = { update: ['key', 'expectedRevision', 'set'], upsert: ['values', 'conflict', 'update'],
+      'insert-select': ['source', 'where', 'select', 'conflict', 'onConflict'] }[document.op];
+    if (!allowed) fail('op must be update, upsert or insert-select');
+    for (const key of Object.keys(document))
+      if (!['op', 'returning', 'maxRows', 'maxBytes', ...allowed].includes(key)) fail(`unknown mutation member '${key}'`);
+    const maxRows = document.maxRows ?? 100;
+    const maxBytes = document.maxBytes ?? 1_048_576;
+    if (![maxRows, maxBytes].every((n) => Number.isSafeInteger(n) && n > 0 && n < Number.MAX_SAFE_INTEGER)) fail('mutation row and byte bounds must be positive safe integers');
+    const returning = document.returning ?? mapping.columns.map((c) => c.name);
+    if (!Array.isArray(returning) || !returning.length || new Set(returning).size !== returning.length) fail('returning is a nonempty distinct member list');
+    returning.forEach(column);
+    // A before/after invariant needs the preimage. These plans promise one
+    // data statement; database invariants retain their trigger enforcement.
+    if (entity.invariants.some((rule) => rule.enforcement === 'store')) fail('store invariants require the entity writer with before/after images');
+    const params = [];
+    const param = (value) => { params.push(value); return dialect.parameterRef(params.length, 'v'); };
+    const table = q(mapping.table);
+    let sql;
+    let prefix = '';
+    if (document.op === 'update') {
+      if (!document.set || typeof document.set !== 'object' || Array.isArray(document.set) || !Object.keys(document.set).length) fail('update needs a nonempty set object');
+      const assignments = Object.entries(document.set).map(([name, value]) => {
+        const c = writableColumn(name);
+        const encoded = core.plan.encodeColumn(name, value);
+        return { name: q(c.physical), compare: comparison(c), value: param(encoded), encoded };
+      });
+      const parts = core.normalizeKey(document.key);
+      const where = core.plan.keys.map((key, i) => `${q(column(key).physical)} = ${param(core.plan.encodeColumn(key, parts[i]))}`);
+      if (entity.version !== null) {
+        if (!Number.isSafeInteger(document.expectedRevision) || document.expectedRevision < 0) fail('a versioned update needs expectedRevision');
+        where.push(`${q(column(entity.version).physical)} = ${param(document.expectedRevision)}`);
+      }
+      else if (document.expectedRevision !== undefined) fail('expectedRevision needs a declared version member');
+      where.push(`(${assignments.map((a) => `${a.compare} IS NOT ${param(a.encoded)}`).join(' OR ')})`);
+      const sets = assignments.map((a) => `${a.name} = ${a.value}`);
+      if (entity.version !== null) sets.push(`${q(column(entity.version).physical)} = ${q(column(entity.version).physical)} + 1`);
+      sql = `UPDATE ${table} SET ${sets.join(', ')} WHERE ${where.join(' AND ')}`;
+    }
+    else {
+      if (JSON.stringify(document.conflict) !== JSON.stringify(core.plan.keys)) fail('conflict must name the complete ordered primary key');
+      let names;
+      let source;
+      if (document.op === 'upsert') {
+        if (!document.values || typeof document.values !== 'object' || Array.isArray(document.values)) fail('upsert needs values');
+        const complete = core.complete(document.values, { updating: false });
+        const split = core.plan.split(complete);
+        names = split.values.map((v) => v.name);
+        if (core.plan.keys.some((key) => !names.includes(key))) fail('upsert requires every primary-key value');
+        source = `VALUES (${split.values.map((v) => param(v.value)).join(', ')})`;
+      }
+      else {
+        if (document.source !== entity.name || document.onConflict !== 'nothing') fail('insert-select supports same-entity sources with onConflict nothing');
+        if (!document.select || typeof document.select !== 'object' || Array.isArray(document.select)) fail('insert-select needs a projection');
+        names = Object.keys(document.select);
+        if (!names.length || core.plan.keys.some((key) => !names.includes(key))) fail('insert-select projects every primary-key member');
+        const values = names.map((name) => {
+          const target = column(name);
+          if (target.generated || name === entity.version) fail('insert-select leaves generated values and revisions database-owned');
+          const value = document.select[name];
+          if (typeof value === 'string' && value.startsWith('$it.')) {
+            const from = column(value.slice(4));
+            if (from.codec !== target.codec || from.null !== target.null) fail('insert-select requires identical source and target codecs');
+            return `${q('s')}.${q(from.physical)}`;
+          }
+          if (value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && Object.hasOwn(value, '$literal'))
+            return param(core.plan.encodeColumn(name, value.$literal));
+          return fail('insert-select values are singular member paths or $literal values');
+        });
+        const analyzed = analyzeQuery({ $for: { it: '$[*]' }, $where: document.where ?? true, $return: '$it' });
+        const predicate = planEntityPredicate(analyzed.root.where, analyzed.root.forBindings[0].slot, entityShape(entity, mapping));
+        if ('refusal' in predicate) fail(predicate.refusal.reason);
+        const emitter = createEntityPredicateEmitters(dialect, (slot) => {
+          if (!Object.hasOwn(slot, 'literal')) return fail('mutation predicates use literal values');
+          return param(slot.literal);
+        });
+        const where = emitter.emitPred(q('s'), `${q('s')}.${q('doc')}`, predicate.pred);
+        source = `SELECT ${values.join(', ')} FROM ${table} AS ${q('s')} WHERE ${where}`
+          + ` ORDER BY ${core.plan.keys.map((key) => `${q('s')}.${q(column(key).physical)}`).join(', ')}`
+          + ` LIMIT ${maxRows + 1}`;
+        const aliases = names.map((name, i) => q(`v${i}`));
+        prefix = `WITH ${q('_jaren_source')} (${aliases.join(', ')}) AS MATERIALIZED (${source}) `;
+        source = `SELECT ${aliases.join(', ')} FROM ${q('_jaren_source')} WHERE `
+          + dialect.mutationRowGuard(`(SELECT COUNT(*) FROM ${q('_jaren_source')})`, maxRows);
+      }
+      sql = `INSERT INTO ${table} (${names.map((name) => q(column(name).physical)).join(', ')}) ${source}`
+        + ` ON CONFLICT (${core.plan.keys.map((key) => q(column(key).physical)).join(', ')})`;
+      if (document.op === 'insert-select') sql += ' DO NOTHING';
+      else {
+        if (!Array.isArray(document.update) || !document.update.length || new Set(document.update).size !== document.update.length) fail('upsert update names distinct stored members');
+        const changes = document.update.map((name) => {
+          const c = writableColumn(name);
+          if (!names.includes(name)) fail('an upsert update member must be supplied in values');
+          return { name: q(c.physical), compare: comparison(c, `${table}.`) };
+        });
+        const sets = changes.map(({ name }) => `${name} = excluded.${name}`);
+        if (entity.version !== null) sets.push(`${q(column(entity.version).physical)} = ${table}.${q(column(entity.version).physical)} + 1`);
+        sql += ` DO UPDATE SET ${sets.join(', ')} WHERE ${changes.map(({ name, compare }) => `${compare} IS NOT excluded.${name}`).join(' OR ')}`;
+      }
+    }
+    sql = prefix + sql + ` RETURNING ${physicalSelection(mapping, dialect)}`;
+    return { sql, params, returning, maxRows, maxBytes, statement: null };
+  };
+  return (document) => {
+    const key = canonicalizeJson(document);
+    let plan = plans.get(key);
+    if (!plan) {
+      plan = compile(document);
+      if (plans.size >= 64) plans.delete(plans.keys().next().value);
+      plans.set(key, plan);
+    }
+    return connection.transaction(() => {
+      plan.statement ??= connection.prepare(plan.sql);
+      return chain(plan.statement, (statement) => chain(attempt(() => statement.all(plan.params),
+        (error) => String(error?.message).includes('jaren-mutation-row-bound')
+          ? new DbRuntimeError('JD2007', 'insert-select exceeded its source row bound', { cause: error })
+          : wrapDriverError(error, { collection: entity.name, docPath: entity.docPath })), (rows) => {
+        const stored = rows.map(core.plan.merge);
+        if (rows.length > plan.maxRows || utf8Length(JSON.stringify(stored)) > plan.maxBytes)
+          throw new DbRuntimeError('JD2007', 'native mutation exceeded its returned row or byte bound');
+        stored.forEach(core.validateOnly);
+        const returned = stored.map((row) => Object.fromEntries(plan.returning
+          .filter((name) => Object.hasOwn(row, name)).map((name) => [name, row[name]])));
+        return { mode: 'native', affected: rows.length, rows: returned,
+          admitted: { statements: 1, rows: rows.length, bytes: utf8Length(JSON.stringify(stored)) } };
+      }));
+    });
+  };
+}

package/src/physical.js

@@ -0,0 +1,147 @@
+//@ts-check
+/** Explicit column layouts and lossless JSON-facing column codecs. */
+import { getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339 } from '@jarenjs/core/dates/rfc3339';
+import { DbCompileError, DbRuntimeError } from './errors.js';
+import { chain } from './driver.js';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+
+const compiledCodecs = new WeakMap();
+const CODECS = new Set(['text', 'integer', 'number', 'boolean', 'json', 'date', 'datetime', 'epoch-ms', 'bigint', 'decimal', 'blob-hex']);
+const STORAGE = { text: 'string', integer: 'integer', number: 'number', boolean: 'boolean',
+  json: 'string', date: 'string', datetime: 'string', 'epoch-ms': 'integer', bigint: 'integer', decimal: 'string', 'blob-hex': 'string' };
+const identifier = (v) => typeof v === 'string' && v.length > 0 && !v.includes('\0');
+
+/** Normalize a declared layout; implicit conversions are never adoption policy.
+ * @param {any} physical @param {Map<string, any>} properties @param {string[]} keys
+ * @param {string} path @returns {any} */
+export function normalizePhysical(physical, properties, keys, path) {
+  if (physical === undefined) return null;
+  const fail = (reason) => { throw new DbCompileError('JD0005', reason, `${path}/physical`); };
+  if (!physical || typeof physical !== 'object' || Array.isArray(physical)) fail('physical must be an object');
+  for (const key of Object.keys(physical))
+    if (!['table', 'kind', 'keys', 'columns'].includes(key)) fail(`unknown physical member '${key}'`);
+  if (!identifier(physical.table)) fail('physical.table must be a nonempty SQL identifier');
+  if (physical.kind !== undefined && !['table', 'view'].includes(physical.kind)) fail('physical.kind is table or view');
+  if (!physical.columns || typeof physical.columns !== 'object' || Array.isArray(physical.columns)) fail('physical.columns is required');
+  const ordered = physical.keys ?? keys;
+  if (!Array.isArray(ordered) || ordered.length !== keys.length || new Set(ordered).size !== keys.length
+    || ordered.some((key) => !keys.includes(key))) fail('physical.keys must order every declared key exactly once');
+  const used = new Set();
+  const columns = [];
+  for (const [name, property] of properties) {
+    if (property.relation) continue;
+    const c = physical.columns[name];
+    if (!c || typeof c !== 'object' || Array.isArray(c) || !CODECS.has(c.codec)) fail(`'${name}' needs an explicit supported column codec`);
+    for (const key of Object.keys(c))
+      if (!['name', 'codec', 'null', 'default', 'generated'].includes(key)) fail(`unknown column member '${key}'`);
+    if (!identifier(c.name) || used.has(c.name.toLowerCase())) fail(`'${name}' needs a distinct physical column name`);
+    if (!['null', 'absent', 'reject'].includes(c.null)) fail(`'${name}' must declare SQL NULL as null, absent or reject`);
+    if (c.default !== undefined && c.default !== 'database') fail('column default ownership is database');
+    if (c.generated !== undefined && typeof c.generated !== 'boolean') fail('generated must be boolean');
+    if (property.key && (!['text', 'integer', 'bigint'].includes(c.codec) || c.null !== 'reject')) fail('keys require non-null text, integer or bigint codecs');
+    if (property.column !== undefined) fail('physical codecs replace hybrid column overrides');
+    if (c.default === 'database' && property.default !== undefined && property.default !== 'auto') fail('a default has exactly one owner');
+    used.add(c.name.toLowerCase());
+    columns.push({ name, physical: c.name, codec: c.codec, null: c.null, databaseDefault: c.default === 'database',
+      generated: c.generated === true, storage: STORAGE[c.codec], source: 'column', key: property.key });
+  }
+  for (const name of Object.keys(physical.columns))
+    if (!properties.has(name) || properties.get(name).relation) fail(`column '${name}' is not a stored property`);
+  return { table: physical.table, kind: physical.kind ?? 'table', keys: [...ordered], columns };
+}
+
+/** Compile one codec once, with a JSON-safe public value and a bound SQL value.
+ * @param {any} column @returns {{ encode: Function, decode: Function, normalize: Function }} */
+export function columnCodec(column) {
+  if (compiledCodecs.has(column)) return compiledCodecs.get(column);
+  const fail = () => { throw new DbRuntimeError('JD2003', `column '${column.name}' refuses a lossy or invalid ${column.codec} value`); };
+  const date = (v, only) => typeof v === 'string' && Number.isFinite(only
+    ? getEpochOfDateOnlyRFC3339(v) : getEpochOfDateTimeRFC3339(v));
+  const convert = (v, reading) => {
+    if (v === undefined || v === null) {
+      if (!reading && v === null && column.codec === 'json') return 'null';
+      if (column.null === 'reject') return fail();
+      return reading ? (column.null === 'absent' ? undefined : null) : null;
+    }
+    switch (column.codec) {
+      case 'text': if (typeof v === 'string') return v; break;
+      case 'integer': if (typeof v === 'number' && Number.isSafeInteger(v)) return v; break;
+      case 'number': if (typeof v === 'number' && Number.isFinite(v) && (!Number.isInteger(v) || Number.isSafeInteger(v))) return v; break;
+      case 'boolean':
+        if (reading && (v === 0 || v === 1 || typeof v === 'boolean')) return v === 1 || v === true;
+        if (!reading && typeof v === 'boolean') return v ? 1 : 0;
+        break;
+      case 'bigint': if (typeof v === 'string' && /^(?:0|-?[1-9][0-9]*)$/.test(v)
+        && BigInt(v) >= -9223372036854775808n && BigInt(v) <= 9223372036854775807n) return v; break;
+      case 'decimal': if (typeof v === 'string' && /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(v)) return v; break;
+      case 'date': if (date(v, true)) return v; break;
+      case 'datetime': if (date(v, false)) return v; break;
+      case 'epoch-ms':
+        if (reading && typeof v === 'number' && Number.isSafeInteger(v) && Number.isFinite(new Date(v).getTime())) return new Date(v).toISOString();
+        if (!reading && date(v, false) && new Date(v).toISOString() === v) return getEpochOfDateTimeRFC3339(v);
+        break;
+      case 'blob-hex':
+        if (typeof v === 'string' && /^(?:[0-9a-fA-F]{2})*$/.test(v))
+          return reading ? v.toLowerCase() : Uint8Array.from(v.match(/../g) ?? [], (b) => parseInt(b, 16));
+        break;
+      case 'json':
+        try {
+          if (reading) return JSON.parse(v);
+          canonicalizeJson(v);
+          const text = JSON.stringify(v);
+          if (text !== undefined && JSON.stringify(JSON.parse(text)) === text) return text;
+        }
+        catch { return fail(); }
+        break;
+    }
+    return fail();
+  };
+  const codec = { encode: (v) => convert(v, false), decode: (v) => convert(v, true), normalize: (v) => {
+    const encoded = convert(v, false);
+    return column.codec === 'blob-hex' && encoded !== null ? v.toLowerCase() : convert(encoded, true);
+  } };
+  compiledCodecs.set(column, codec);
+  return codec;
+}
+
+/** SQL selection keeps unsafe integers and byte handles out of application state.
+ * @param {any} column @param {any} dialect @param {string} [prefix] @returns {string} */
+export function physicalRead(column, dialect, prefix = '') {
+  const sql = `${prefix}${dialect.quoteIdentifier(column.physical ?? column.name)}`;
+  return dialect.physicalRead(column.codec, sql);
+}
+
+/** Verify an existing mapped object without executing DDL. Unmapped columns and
+ * all application-owned programs remain physical facts, never inferred drops.
+ * @param {any} connection @param {any} mapping @param {any} schema @returns {any} */
+export function verifyPhysical(connection, mapping, schema) {
+  const fail = (why) => { throw new DbCompileError('JD0002', `physical '${mapping.table}': ${why}`); };
+  if (connection.dialect.name !== 'sqlite') fail('column adoption is qualified only for SQLite');
+  const object = schema.objects.find((o) => o.name === mapping.table && o.type === mapping.kind);
+  if (!object) fail(`declared ${mapping.kind} does not exist`);
+  for (const trigger of mapping.triggers ?? []) {
+    const actual = schema.objects.find((o) => o.type === 'trigger' && o.name === trigger.name);
+    if (!actual || actual.sql?.trim().replace(/;$/, '') !== trigger.sql.trim().replace(/;$/, '')) fail(`invariant trigger '${trigger.name}' is missing or changed; apply an explicit migration`);
+  }
+  const read = mapping.kind === 'view'
+    ? chain(connection.prepare(connection.dialect.introspect.columns(mapping.table)), (s) =>
+      chain(s.all([]), (columns) => ({ columns: columns.map((c) => ({ ...c, generated: !!c.hidden })), primaryKey: [] })))
+    : schema.tables.find((t) => t.name === mapping.table);
+  return chain(read, (table) => {
+    if (mapping.kind !== 'view' && JSON.stringify(table.primaryKey) !== JSON.stringify(mapping.keys.map((k) => mapping.columns.find((c) => c.name === k).physical))) fail('ordered primary key disagrees');
+    for (const column of mapping.columns) {
+      const actual = table.columns.find((c) => c.name === column.physical);
+      if (!actual) fail(`column '${column.physical}' does not exist`);
+      const type = actual.type.toUpperCase();
+      if (!connection.dialect.physicalTypeMatches(column.codec, type)) fail(`'${column.physical}' type ${type} cannot guarantee codec ${column.codec}`);
+      if (mapping.kind !== 'view' && actual.generated !== column.generated) fail(`'${column.physical}' generated ownership disagrees`);
+    }
+    return null;
+  });
+}
+
+/** Select mapped columns with their physical aliases for the shared row merger.
+ * @param {any} mapping @param {any} dialect @param {string} [prefix] @returns {string} */
+export function physicalSelection(mapping, dialect, prefix = '') {
+  return mapping.columns.map((c) => `${physicalRead(c, dialect, prefix)} AS ${dialect.quoteIdentifier(c.physical ?? c.name)}`).join(', ');
+}