okmodel 0.1.1 → 0.2.1

package/dist/runtime/traits/index.js

@@ -0,0 +1,509 @@
+import {
+  checkPresetNames,
+  duplicatePreset
+} from "../../shared/nsva2a6b.js";
+import {
+  checkTrait
+} from "../../shared/g1b5zzj9.js";
+import {
+  timestamptz2
+} from "../../shared/xkz8g6by.js";
+import {
+  uuid2
+} from "../../shared/ps43134h.js";
+import {
+  snakeCase
+} from "../../shared/x9v1qgeb.js";
+import {
+  ColumnBuilder2,
+  retarget
+} from "../../shared/dd4f8mnx.js";
+import {
+  definition,
+  unavailable
+} from "../../shared/xatfg0gn.js";
+import {
+  compareText
+} from "../../shared/t4tbsy9h.js";
+import {
+  queryHandle,
+  attachHttp,
+  settleCall
+} from "../../shared/mxmcdsh5.js";
+import {
+  installArchiveInspect
+} from "../../shared/xrfnq5k8.js";
+import {
+  OkmError2,
+  catalogError2,
+  throwNamed2
+} from "../../shared/52szzakm.js";
+
+// src/dialects/pg/archive-bind.ts
+function rewriteArchivable(self, tables, casing, schemaTraits, cascade) {
+  const byName = new Map(tables.map((item) => [item.name, item]));
+  const accepted = tables.map((item) => item.name);
+  const edges = foreignKeys(tables, casing, byName);
+  const archiveSql = casing === "snake" ? "archived_at" : "archivedAt";
+  const idSql = casing === "snake" ? "archive_id" : "archiveId";
+  const predicate = `"${archiveSql.replaceAll('"', '""')}" is null`;
+  return tables.map((item) => {
+    if (!applies(self, item, schemaTraits))
+      return item;
+    return rewriteOne(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql, predicate);
+  });
+}
+function rewriteOne(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql, predicate) {
+  const links = childLinks(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql);
+  const parents = parentLinks(item, byName, edges, casing, schemaTraits, archiveSql, idSql);
+  const primary = primaryFields(item);
+  if ((links.length > 0 || parents.length > 0) && primary.length === 0) {
+    catalogError2("OKM1020", `Table ${item.name} is archivable and needs a primary key.`);
+  }
+  const options = item.options;
+  const partials = [];
+  const named = options?.unique;
+  if (named !== undefined) {
+    for (const fields of Object.values(named)) {
+      partials.push(partialIndex(fields.map((field) => fieldSql(field, item.columns[field], casing)), predicate));
+    }
+  }
+  let columns;
+  for (const [field, builder] of Object.entries(item.columns)) {
+    if (!(builder instanceof ColumnBuilder2) || builder.state.unique === undefined)
+      continue;
+    columns ??= { ...item.columns };
+    columns[field] = retarget(builder, { dropUnique: true });
+    partials.push(partialIndex([fieldSql(field, builder, casing)], predicate));
+  }
+  const prior = options?.indexes;
+  const indexes = partials.length === 0 ? undefined : (handles) => {
+    const calls = prior === undefined ? [] : prior(handles);
+    return [...partials, ...Array.isArray(calls) ? calls : []];
+  };
+  const archiveModel = {
+    at: archiveSql,
+    id: idSql,
+    atField: "archivedAt",
+    idField: "archiveId",
+    cascade: links,
+    parents
+  };
+  return {
+    ...item,
+    ...columns !== undefined ? { columns } : {},
+    ...named !== undefined || indexes !== undefined ? { options: nextOptions(item.options, indexes) } : {},
+    archiveModel
+  };
+}
+function childLinks(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql) {
+  const seen = new Set;
+  const links = [];
+  for (const name of cascade) {
+    if (seen.has(name))
+      catalogError2("OKM1020", `Cascade ${item.name} names ${name} more than once.`);
+    seen.add(name);
+    if (name === item.name)
+      catalogError2("OKM1020", `Cascade ${item.name} names itself.`);
+    const child = byName.get(name);
+    if (child === undefined) {
+      throwNamed2("OKM1020", name, accepted, `Cascade ${item.name} names ${name}, which is not a table. Accepted names: ${list(accepted)}.`);
+    }
+    if (!isArchivable(child, schemaTraits)) {
+      catalogError2("OKM1020", `Cascade ${item.name} names ${name}, which is not archivable.`);
+    }
+    const matches = edges.filter((edge) => edge.from === name && edge.to === item.name);
+    if (matches.length !== 1) {
+      const hint = matches.map((edge) => edge.field).sort();
+      const which = hint.length === 0 ? "none" : hint.join(", ");
+      catalogError2("OKM1021", `Cascade ${item.name} names ${name}, which has ${matches.length === 0 ? "no" : "more than one"} foreign key to ${item.name}. Accepted columns: ${which}.`);
+    }
+    const edge = matches[0];
+    if (edge === undefined) {
+      catalogError2("OKM1021", `Cascade ${item.name} names ${name}, which has no foreign key to ${item.name}. Accepted columns: none.`);
+    }
+    links.push({
+      table: name,
+      sql: tableSql(child, casing),
+      at: archiveSql,
+      id: idSql,
+      local: edge.local,
+      remote: edge.remote
+    });
+  }
+  return links;
+}
+function parentLinks(item, byName, edges, casing, schemaTraits, archiveSql, idSql) {
+  const parents = [];
+  for (const edge of edges) {
+    if (edge.from !== item.name)
+      continue;
+    const parent = byName.get(edge.to);
+    if (parent === undefined || !isArchivable(parent, schemaTraits))
+      continue;
+    parents.push({
+      table: parent.name,
+      sql: tableSql(parent, casing),
+      at: archiveSql,
+      id: idSql,
+      local: edge.local,
+      remote: edge.remote
+    });
+  }
+  parents.sort((left, right) => compareText(left.table, right.table));
+  return parents;
+}
+function foreignKeys(tables, casing, byName) {
+  const edges = [];
+  for (const item of tables) {
+    for (const [field, builder] of Object.entries(item.columns)) {
+      if (!(builder instanceof ColumnBuilder2))
+        continue;
+      const reference = builder.state.references;
+      if (reference === undefined)
+        continue;
+      const target = byName.get(reference.table);
+      if (target === undefined)
+        continue;
+      edges.push({
+        from: item.name,
+        field,
+        to: reference.table,
+        local: localNames(item, field, builder, reference, casing),
+        remote: remoteNames(target, reference, casing)
+      });
+    }
+  }
+  return edges;
+}
+function localNames(item, field, builder, reference, casing) {
+  const names = [fieldSql(field, builder, casing)];
+  for (const extra of reference.along ?? [])
+    names.push(fieldSql(extra, item.columns[extra], casing));
+  return names;
+}
+function remoteNames(target, reference, casing) {
+  if (reference.columns !== undefined) {
+    return reference.columns.map((name) => fieldSql(name, target.columns[name], casing));
+  }
+  return primaryFields(target).map((name) => fieldSql(name, target.columns[name], casing));
+}
+function applies(self, item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  if (own.includes(self))
+    return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  return schemaTraits?.includes(self) ?? false;
+}
+function isArchivable(item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  for (const trait of own)
+    if (marked(trait))
+      return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  if (schemaTraits === undefined)
+    return false;
+  for (const trait of schemaTraits)
+    if (marked(trait))
+      return true;
+  return false;
+}
+function marked(value) {
+  return value["~archive"] === true;
+}
+function nextOptions(options, indexes) {
+  const record = { ...options };
+  delete record.unique;
+  if (indexes !== undefined)
+    record.indexes = indexes;
+  return record;
+}
+function partialIndex(columns, predicate) {
+  return {
+    columns,
+    isUnique: true,
+    predicate,
+    unique() {
+      return partialIndex(columns, predicate);
+    }
+  };
+}
+function primaryFields(item) {
+  const listed = item.options?.primaryKey;
+  if (listed !== undefined && listed.length > 0)
+    return [...listed];
+  const fields = [];
+  for (const [field, builder] of Object.entries(item.columns)) {
+    if (builder instanceof ColumnBuilder2 && builder.state.primaryKey === true)
+      fields.push(field);
+  }
+  return fields;
+}
+function fieldSql(field, builder, casing) {
+  if (builder instanceof ColumnBuilder2 && builder.state.sqlName !== undefined)
+    return builder.state.sqlName;
+  return casing === "snake" ? snakeCase(field) : field;
+}
+function tableSql(item, casing) {
+  const named = item.options?.sqlName;
+  return named ?? (casing === "snake" ? snakeCase(item.name) : item.name);
+}
+function list(names) {
+  return names.join(", ");
+}
+
+// src/runtime/archive-rules.ts
+function installArchiveContributions() {
+  installArchiveInspect(archiveContributions);
+}
+function archiveContributions(model, view) {
+  const archive = model?.archive;
+  if (archive === undefined)
+    return;
+  const rules = [
+    view === "with" ? { rule: "archive", contribution: "with archived", provenance: "caller" } : view === "only" ? { rule: "archive", contribution: "only archived", provenance: "caller" } : { rule: "archive", contribution: "active set", provenance: "planner" }
+  ];
+  for (const child of archive.cascade) {
+    rules.push({
+      rule: "archive",
+      contribution: `cascade ${child.table}`,
+      provenance: "catalog"
+    });
+  }
+  return rules;
+}
+
+// src/runtime/archive-handle.ts
+function attachArchive(target, ctx) {
+  const table = ctx.table;
+  const reopen = ctx.reopen;
+  const session = ctx.session;
+  if (table === undefined || reopen === undefined || session === undefined)
+    return;
+  const host = session;
+  const mods = { uses: ctx.uses };
+  target.archive = (input, options = {}) => lifecycle(host, "archive", table, input, options, mods);
+  target.restore = (input, options = {}) => lifecycle(host, "restore", table, input, options, mods);
+  target.withArchived = () => {
+    refuse(host, table);
+    return reopen("with");
+  };
+  target.onlyArchived = () => {
+    refuse(host, table);
+    return reopen("only");
+  };
+}
+function lifecycle(host, op, table, input, options, mods) {
+  refuse(host, table);
+  return queryHandle(() => run(host, op, table, input, options, mods), {
+    "~plan": async () => {
+      await host.connected;
+      const [mod, planned] = await Promise.all([loadArchive(), settle(host, table, mods)]);
+      try {
+        return mod.prepareArchive(host.schema, op, table, input, options, planned, host.scope);
+      } catch (error) {
+        return settleCall(host, error);
+      }
+    },
+    sql() {
+      return Promise.all([loadArchive(), settle(host, table, mods)]).then(([mod, planned]) => mod.explainArchive(host.schema, op, table, input, options, planned, host.scope));
+    },
+    expect(count) {
+      return lifecycle(host, op, table, input, options, { ...mods, expect: count });
+    },
+    all(reason) {
+      return lifecycle(host, op, table, input, options, { ...mods, all: reason });
+    }
+  });
+}
+function refuse(host, table) {
+  if (host.schema.model[table]?.archive !== undefined)
+    return;
+  throw attachHttp(host.http, new OkmError2("OKM1052", `Table ${table} is not archivable.`, {
+    fix: { summary: "Call archive and restore only on an archivable table." }
+  }));
+}
+var archiveMod;
+function loadArchive() {
+  archiveMod ??= import("../../shared/m9tv7xn7.js");
+  return archiveMod;
+}
+async function settle(host, table, mods) {
+  if (mods.uses === undefined)
+    return mods;
+  const { resolve } = await import("../../shared/r6nwkxnt.js");
+  return { ...mods, presets: resolve(host.schema, table, mods.uses).wheres };
+}
+async function run(host, op, table, input, options, mods) {
+  await host.connected;
+  const mod = await loadArchive();
+  try {
+    return await mod.executeArchive(host, op, table, input, options, await settle(host, table, mods), host.scope);
+  } catch (error) {
+    return settleCall(host, error);
+  }
+}
+
+// src/runtime/traits/index.ts
+function trait(name, input) {
+  if (input.presets !== undefined)
+    checkPresetNames(Object.keys(input.presets), `trait ${name}`);
+  if (input.methods !== undefined) {
+    unavailable("Trait option methods is not available yet. It arrives in 0.2.");
+  }
+  if (input.requires !== undefined) {
+    unavailable("Trait option requires is not available yet. It arrives in 0.2.");
+  }
+  const checked = checkTrait({
+    name,
+    fields: input.fields,
+    ...input.touch !== undefined ? { touch: input.touch } : {},
+    ...input.sealed !== undefined ? { sealed: input.sealed } : {}
+  }, `trait(${name})`);
+  markFields(checked.fields, name);
+  const sealed = sealTouch(checked.sealed, checked.touch);
+  return {
+    name,
+    fields: checked.fields,
+    ...checked.touch !== undefined ? { touch: checked.touch } : {},
+    ...sealed !== undefined ? { sealed } : {},
+    ...input.presets !== undefined ? { presets: input.presets } : {},
+    apply(model, ctx) {
+      addFields(name, checked.fields, model, ctx);
+      if (input.presets !== undefined)
+        addPresets(name, input.presets, model, ctx);
+    }
+  };
+}
+function addPresets(name, presets, model, ctx) {
+  const merged = model.presets = { ...model.presets };
+  const from = model.presetFrom ??= {};
+  for (const key of Object.keys(presets)) {
+    if (Object.hasOwn(merged, key)) {
+      const first = from[key];
+      duplicatePreset(key, ctx.table, first === undefined ? `table ${ctx.table}` : `trait ${first}`, `trait ${name}`);
+    }
+    merged[key] = presets[key];
+    from[key] = name;
+  }
+}
+function timestamps(options) {
+  if (options !== undefined) {
+    for (const key of Object.keys(options)) {
+      if (key !== "enforce") {
+        definition(`timestamps() option ${key} is not supported. Accepted options: enforce.`);
+      }
+    }
+    if (options.enforce === "trigger") {
+      unavailable(`timestamps({ enforce: "trigger" }) is not available yet. It arrives in 0.3.`);
+    }
+    if (options.enforce !== undefined) {
+      definition(`timestamps() enforce ${String(options.enforce)} must be trigger.`);
+    }
+  }
+  return trait("timestamps", {
+    fields: {
+      createdAt: stamped(),
+      updatedAt: stamped()
+    },
+    touch: ["updatedAt"],
+    sealed: ["createdAt", "updatedAt"]
+  });
+}
+function stamped() {
+  return timestamptz2().defaultSql("now()").guarded();
+}
+function archivable(options) {
+  installArchiveContributions();
+  const cascade = readCascade(options);
+  const base = trait("archivable", {
+    fields: {
+      archivedAt: timestamptz2().nullable().guarded(),
+      archiveId: uuid2().nullable().guarded()
+    },
+    sealed: ["archivedAt", "archiveId"]
+  });
+  const self = {
+    ...base,
+    "~archive": true,
+    apply(model, ctx) {
+      base.apply(model, ctx);
+      model.archive = { at: "archivedAt", id: "archiveId", cascade };
+    },
+    rewrite(tables, casing, schemaTraits) {
+      return rewriteArchivable(self, tables, casing, schemaTraits, cascade);
+    },
+    hook: attachArchive
+  };
+  return self;
+}
+function readCascade(options) {
+  if (options === undefined)
+    return [];
+  for (const key of Object.keys(options)) {
+    if (key !== "strategy" && key !== "cascade") {
+      definition(`archivable() option ${key} is not supported. Accepted options: strategy, cascade.`);
+    }
+  }
+  if (options.strategy === "table") {
+    unavailable('archivable({ strategy: "table" }) is not available yet. It arrives once archived snapshots can follow migrations.');
+  }
+  if (options.strategy !== undefined && options.strategy !== "column") {
+    definition(`archivable() strategy ${String(options.strategy)} must be column.`);
+  }
+  const cascade = options.cascade;
+  if (cascade === undefined)
+    return [];
+  if (!Array.isArray(cascade))
+    definition("archivable() cascade must be a list of table names.");
+  const names = [];
+  for (const name of cascade) {
+    if (typeof name !== "string" || name.length === 0) {
+      definition("archivable() cascade must name tables.");
+    }
+    names.push(name);
+  }
+  return names;
+}
+function markFields(fields, name) {
+  for (const field of Object.keys(fields)) {
+    const builder = fields[field];
+    if (typeof builder === "object" && builder !== null)
+      Object.assign(builder, { trait: name });
+  }
+}
+function sealTouch(sealed, touch) {
+  if (touch === undefined)
+    return sealed;
+  if (sealed === undefined)
+    return touch;
+  const names = [...sealed];
+  for (const field of touch)
+    if (!names.includes(field))
+      names.push(field);
+  return names;
+}
+function addFields(name, fields, model, ctx) {
+  for (const field of Object.keys(fields)) {
+    const builder = fields[field];
+    if (builder === undefined)
+      continue;
+    if (Object.hasOwn(model.columns, field)) {
+      const previous = model.columns[field].trait;
+      const which = typeof previous === "string" ? `trait ${previous} already adds it` : `${ctx.table} already declares it`;
+      throw new OkmError2("OKM1012", `Trait ${name} adds ${ctx.table}.${field}, and ${which}.`, {
+        fix: { summary: "Rename the table field or drop one of the traits." }
+      });
+    }
+    model.columns[field] = builder;
+  }
+}
+export {
+  archivable,
+  timestamps,
+  trait
+};

package/dist/runtime/transaction.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public `tx()` (spec §15, §15.2).
+ *
+ * One transaction reserves one connection of the primary. Every statement of
+ * the callback, its savepoints, and its batches run on that connection, and it
+ * goes back to the pool at commit, rollback, or cancellation. The callback gets
+ * a client built on a pool that is a facade over that connection, so reads,
+ * writes, includes, presets, tenancy, and archive handling are the ones the
+ * caller's client already has. Loaded the first time `tx()` is called.
+ */
+import { type Session } from "./client.js";
+/**
+ * Runs `fn` in a transaction, or in a savepoint when one is already open.
+ *
+ * @param session - Client session
+ * @param args - `[fn]` or `[options, fn]`
+ * @returns What `fn` returned
+ */
+export declare function tx(session: Session, args: readonly unknown[]): Promise<unknown>;

package/dist/runtime/tx.d.ts

@@ -1,21 +1,36 @@
 /**
- * Internal transaction runner for multi-statement writes.
+ * Writes on one endpoint.
  *
- * One statement uses the pool. Several statements use `batch`, which reserves
- * a connection, begins, and commits. Inside an open transaction, `batch` is a
- * savepoint and does not commit the outer transaction (D124). A connection
- * lost at commit is `outcome_unknown`. Public `tx` is P29.
+ * One statement uses the pool. Several statements use `batch`, which is atomic:
+ * the adapter begins, commits, and rolls back, and inside an open transaction
+ * the unit is a savepoint that never commits the outer transaction (D124). A
+ * connection lost at commit is `outcome_unknown`. The interactive transaction
+ * is `transaction.ts`; the public `batch` is `batch.ts`. Both load on first use.
  */
 import type { DriverConnection, DriverPool, ExecuteOptions, ExecuteResult, Statement } from "../contracts/driver.js";
+import type { Hookm, Timeouts } from "./types.js";
+/** What a write needs from the client: a pool, the default statement timeout, and observers. */
+export type RunHost = {
+    readonly pool: DriverPool;
+    readonly timeouts?: Timeouts | undefined;
+    readonly hookm?: readonly Hookm[] | undefined;
+    /** Set inside a transaction. A unit of several statements is a savepoint there, not a transaction. */
+    readonly tx?: object | undefined;
+};
 /**
  * Runs write statements as one atomic unit.
  *
- * @param pool - Endpoint pool
+ * A call with no `timeout` takes `timeouts.statement`. Notices go to
+ * `hookm.onNotice`. A unit of several statements is a transaction to
+ * `hookm.onTransaction`.
+ *
+ * @param host - Pool, default timeout, and observers
  * @param statements - Statements in order
  * @param options - Signal and timeout for the whole unit
+ * @param atomic - Use the driver's atomic `batch` even for one statement, so a failure carries `batchIndex`
  * @returns One result per statement
  */
-export declare function runWrite(pool: DriverPool, statements: readonly Statement[], options: ExecuteOptions | undefined): Promise<readonly ExecuteResult[]>;
+export declare function runWrite(host: RunHost, statements: readonly Statement[], options: ExecuteOptions | undefined, atomic?: true): Promise<readonly ExecuteResult[]>;
 /**
  * Runs statements on a connection the caller already reserved.
  *