okmodel 0.1.1 → 0.3.0

package/dist/runtime/traits/index.js

@@ -0,0 +1,646 @@
+import {
+  checkPresetNames,
+  duplicatePreset
+} from "../../shared/nsva2a6b.js";
+import {
+  checkTrait
+} from "../../shared/n0dgs0pb.js";
+import {
+  quoteIdent
+} from "../../shared/wekze34d.js";
+import {
+  functionObject,
+  triggerObject
+} from "../../shared/9x25fxhc.js";
+import {
+  timestamptz2
+} from "../../shared/1g0drakv.js";
+import {
+  uuid2
+} from "../../shared/dyj86cmj.js";
+import {
+  snakeCase
+} from "../../shared/6w5j844a.js";
+import {
+  ColumnBuilder2,
+  retarget
+} from "../../shared/c9z5g0fm.js";
+import {
+  definition,
+  unavailable
+} from "../../shared/tmbdywx0.js";
+import {
+  staticNamespace2,
+  compareText
+} from "../../shared/t4tbsy9h.js";
+import {
+  queryHandle,
+  attachHttp,
+  settleCall
+} from "../../shared/k34e0xf2.js";
+import {
+  installArchiveInspect
+} from "../../shared/xrfnq5k8.js";
+import {
+  fitIdentifier2
+} from "../../shared/nfzc5z0w.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/dialects/pg/fn/touch.ts
+function timestampRecords(built) {
+  const columns = updatedColumns(built);
+  if (columns.length === 0)
+    return [];
+  const namespace = staticNamespace2("public");
+  const byColumn = new Map;
+  for (const column of columns) {
+    const list = byColumn.get(column.name) ?? [];
+    list.push(column.parent);
+    byColumn.set(column.name, list);
+  }
+  const records = [];
+  for (const [column, tables] of byColumn) {
+    const name = fitIdentifier2(`okm_touch_${column}`);
+    const present = hasFunction(built, name) || records.some((object) => object.kind === "function" && object.identity.name === name);
+    if (!present) {
+      records.push(functionObject({
+        namespace,
+        name,
+        returns: "trigger",
+        language: "plpgsql",
+        volatility: "volatile",
+        body: `begin new.${quoteIdent(column)} = now(); return new; end`,
+        provenance: { origin: "trait", name: "timestamps" },
+        dependencies: []
+      }));
+    }
+    for (const parent of tables) {
+      const triggerName = fitIdentifier2(`${parent.name}_touch`);
+      if (hasTrigger(built, parent.name, triggerName))
+        continue;
+      if (records.some((object) => object.kind === "trigger" && object.identity.name === triggerName && object.identity.parent.name === parent.name)) {
+        continue;
+      }
+      records.push(triggerObject({
+        parent,
+        name: triggerName,
+        timing: "before",
+        events: ["update"],
+        level: "row",
+        calls: { namespace, name, argTypes: [] },
+        provenance: { origin: "trait", name: "timestamps" }
+      }));
+    }
+  }
+  return records;
+}
+function updatedColumns(built) {
+  if (!Array.isArray(built))
+    return [];
+  const found = [];
+  for (const object of built) {
+    if (typeof object !== "object" || object === null)
+      continue;
+    if (!("kind" in object) || object.kind !== "column")
+      continue;
+    if (!("provenance" in object) || !("identity" in object))
+      continue;
+    const provenance = object.provenance;
+    const identity = object.identity;
+    if (typeof provenance !== "object" || provenance === null)
+      continue;
+    if (typeof identity !== "object" || identity === null)
+      continue;
+    if (!("origin" in provenance) || provenance.origin !== "trait")
+      continue;
+    if (!("name" in provenance) || provenance.name !== "timestamps")
+      continue;
+    if (!("name" in identity) || identity.name !== "updated_at" && identity.name !== "updatedAt")
+      continue;
+    if (!("parent" in identity) || typeof identity.parent !== "object" || identity.parent === null)
+      continue;
+    const parent = identity.parent;
+    if (!("name" in parent) || typeof parent.name !== "string")
+      continue;
+    if (!("namespace" in parent) || typeof parent.namespace !== "object" || parent.namespace === null)
+      continue;
+    const namespace = parent.namespace;
+    if (!("form" in namespace) || namespace.form !== "static")
+      continue;
+    if (!("name" in namespace) || typeof namespace.name !== "string")
+      continue;
+    found.push({
+      parent: { namespace: staticNamespace2(namespace.name), name: parent.name },
+      name: identity.name
+    });
+  }
+  return found;
+}
+function hasFunction(built, name) {
+  return named(built, "function", name);
+}
+function hasTrigger(built, table, name) {
+  if (!Array.isArray(built))
+    return false;
+  return built.some((object) => {
+    if (!isNamed(object, "trigger", name))
+      return false;
+    const identity = object.identity;
+    return typeof identity === "object" && identity !== null && "parent" in identity && typeof identity.parent === "object" && identity.parent !== null && "name" in identity.parent && identity.parent.name === table;
+  });
+}
+function named(built, kind, name) {
+  if (!Array.isArray(built))
+    return false;
+  return built.some((object) => isNamed(object, kind, name));
+}
+function isNamed(object, kind, name) {
+  if (typeof object !== "object" || object === null)
+    return false;
+  if (!("kind" in object) || object.kind !== kind)
+    return false;
+  if (!("identity" in object) || typeof object.identity !== "object" || object.identity === null)
+    return false;
+  return "name" in object.identity && object.identity.name === name;
+}
+
+// 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);
+    },
+    contribute() {
+      return [];
+    }
+  };
+}
+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 !== undefined && options.enforce !== "trigger") {
+      definition(`timestamps() enforce ${String(options.enforce)} must be trigger.`);
+    }
+  }
+  const base = trait("timestamps", {
+    fields: {
+      createdAt: stamped(),
+      updatedAt: stamped()
+    },
+    touch: ["updatedAt"],
+    sealed: ["createdAt", "updatedAt"]
+  });
+  if (options?.enforce !== "trigger")
+    return base;
+  return {
+    ...base,
+    contribute(_peers, built) {
+      return timestampRecords(built);
+    }
+  };
+}
+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>;