okmodel 0.1.0 → 0.2.1

package/dist/runtime/tenancy/index.js

@@ -0,0 +1,365 @@
+import {
+  uuid2
+} from "../../shared/ps43134h.js";
+import {
+  ColumnBuilder2,
+  retarget
+} from "../../shared/dd4f8mnx.js";
+import {
+  definition,
+  unavailable
+} from "../../shared/xatfg0gn.js";
+import {
+  quote
+} from "../../shared/xrfnq5k8.js";
+import {
+  assertIdentifier2
+} from "../../shared/nfzc5z0w.js";
+import {
+  OkmError2
+} from "../../shared/52szzakm.js";
+
+// src/runtime/tenancy/index.ts
+function global(reason) {
+  if (typeof reason !== "string" || reason.trim().length === 0) {
+    definition("global() needs a reason.");
+  }
+  return { kind: "global", reason: reason.trim() };
+}
+function columnTenancy(input) {
+  if (input === undefined || typeof input !== "object") {
+    definition("columnTenancy() needs { key, type }.");
+  }
+  if (input.type !== "uuid") {
+    definition(`columnTenancy() type ${String(input.type)} must be uuid.`);
+  }
+  if (typeof input.key !== "string" || input.key.length === 0) {
+    definition("columnTenancy() key must be a field name.");
+  }
+  assertIdentifier2(input.key, "tenancy key");
+  const key = input.key;
+  const column = uuid2().guarded();
+  const encode = column.state.encode;
+  const tenants = new Set;
+  const globals = new Map;
+  const exemptions = new Map;
+  const api = {
+    key,
+    type: "uuid",
+    strategy: "column",
+    rewrite(tables) {
+      tenants.clear();
+      globals.clear();
+      exemptions.clear();
+      return rewriteTables(key, column, tables, tenants, globals, exemptions);
+    },
+    column: () => column,
+    predicate(spec) {
+      return writePredicate(key, tenants, spec);
+    },
+    guard(table, field, kind) {
+      if (!tenants.has(table) || field !== key)
+        return;
+      refuseKey(kind, table, field);
+    },
+    stamp(table, rows, scope) {
+      if (!tenants.has(table))
+        return;
+      stampRows(key, table, rows, scope);
+    },
+    client(spec) {
+      const names = spec.scoped ? spec.names : spec.names.filter((name) => !tenants.has(name));
+      if (spec.scoped)
+        return { names };
+      return { names, ...bindClient(key, encode, spec.open) };
+    },
+    rules(table, source, scope) {
+      return tenancyRules(table, source, scope, tenants, globals, exemptions);
+    },
+    hook(target, ctx) {
+      if (ctx.tables === undefined || ctx.names === undefined || ctx.open === undefined || ctx.scoped === undefined) {
+        return;
+      }
+      const view = api.client({ names: ctx.names, scoped: ctx.scoped, open: ctx.open });
+      if (!ctx.scoped) {
+        for (const name of ctx.names) {
+          if (view.names.includes(name))
+            continue;
+          delete ctx.tables[name];
+          delete target[name];
+        }
+      }
+      if (view.for !== undefined)
+        target.for = view.for;
+      if (view.unscoped !== undefined)
+        target.unscoped = view.unscoped;
+    },
+    missing(table) {
+      throw new OkmError2("OKM1701", `Table ${table} is tenant-scoped. Call for({ ${key} }) or unscoped("reason").`);
+    }
+  };
+  return api;
+}
+function rewriteTables(key, column, tables, tenants, globals, exemptions) {
+  const kind = new Map;
+  for (const item of tables) {
+    const options = item.options;
+    const mark = options?.tenancy;
+    if (mark === undefined) {
+      kind.set(item.name, "tenant");
+      continue;
+    }
+    if (isGlobal(mark)) {
+      kind.set(item.name, "global");
+      globals.set(item.name, mark.reason);
+      continue;
+    }
+    if (isRecord(mark) && "via" in mark) {
+      unavailable(`Table ${item.name} tenancy via is not available yet. It arrives later.`);
+    }
+    definition(`Table ${item.name} tenancy must be global("reason").`);
+  }
+  return tables.map((item) => {
+    if (kind.get(item.name) !== "tenant") {
+      if (kind.get(item.name) === "global")
+        refuseGlobalReference(item, kind);
+      return item;
+    }
+    return rewriteTenant(key, column, item, tables, kind, tenants, exemptions);
+  });
+}
+function refuseGlobalReference(item, kind) {
+  for (const [field, builder] of Object.entries(item.columns)) {
+    if (!(builder instanceof ColumnBuilder2))
+      continue;
+    const reference = builder.state.references;
+    if (reference !== undefined && kind.get(reference.table) === "tenant") {
+      throw new OkmError2("OKM1705", `Table ${item.name}.${field} is global and references tenant table ${reference.table}. Drop the reference, or make ${item.name} a tenant table.`);
+    }
+  }
+}
+function rewriteTenant(key, column, item, tables, kind, tenants, exemptions) {
+  if (Object.hasOwn(item.columns, key)) {
+    throw new OkmError2("OKM1012", `Table ${item.name} already declares ${key}, which tenancy adds. Rename the field or drop it from the table.`);
+  }
+  const options = item.options;
+  const columns = {};
+  const unique = {};
+  const named = options?.unique;
+  if (named !== undefined) {
+    for (const [name, fields] of Object.entries(named)) {
+      unique[name] = fields.includes(key) ? fields : [key, ...fields];
+    }
+  }
+  const notes = [];
+  for (const [field, builder] of Object.entries(item.columns)) {
+    if (!(builder instanceof ColumnBuilder2)) {
+      columns[field] = builder;
+      continue;
+    }
+    const patch = {};
+    if (builder.state.primaryKey === true)
+      patch.dropPrimary = true;
+    const flag = builder.state.unique;
+    if (flag !== undefined) {
+      if (flag.global === true) {
+        const reason = flag.reason?.trim() ?? "";
+        if (reason.length === 0) {
+          definition(`Unique ${item.name}.${field} sets global and needs a reason.`);
+        }
+        notes.push({ name: field, reason });
+      } else {
+        patch.dropUnique = true;
+        unique[field] = [key, field];
+      }
+    }
+    const reference = builder.state.references;
+    if (reference !== undefined) {
+      const widened = widenReference(key, item.name, field, reference, tables, kind);
+      if (widened !== undefined)
+        patch.references = widened;
+    }
+    const changed = patch.dropUnique === true || patch.dropPrimary === true || patch.references !== undefined;
+    columns[field] = changed ? retarget(builder, patch) : builder;
+  }
+  const primary = primaryFields(item);
+  const primaryKey = primary.length > 0 && !primary.includes(key) ? [...primary, key] : undefined;
+  if (primaryKey !== undefined)
+    unique[`${primary.join("_")}_${key}`] = primaryKey;
+  columns[key] = column;
+  tenants.add(item.name);
+  if (notes.length > 0)
+    exemptions.set(item.name, notes);
+  const indexes = wrapIndexes(key, item.name, options?.indexes);
+  return {
+    ...item,
+    columns,
+    options: {
+      ...options,
+      ...primaryKey !== undefined ? { primaryKey } : {},
+      ...Object.keys(unique).length > 0 ? { unique } : {},
+      ...indexes !== undefined ? { indexes } : {}
+    }
+  };
+}
+function widenReference(key, table, field, reference, tables, kind) {
+  const targetKind = kind.get(reference.table);
+  if (targetKind !== "tenant")
+    return;
+  const action = [reference.onDelete, reference.onUpdate].find((item) => item === "set null" || item === "set default");
+  if (action !== undefined) {
+    definition(`Foreign key ${table}.${field} includes ${key}, so ${action} cannot clear it. Accepted actions: cascade, restrict, no action.`);
+  }
+  const target = tables.find((item) => item.name === reference.table);
+  const remote = reference.columns ?? (target === undefined ? undefined : primaryFields(target));
+  if (remote === undefined || remote.length === 0)
+    return;
+  if (remote.includes(key)) {
+    if (reference.along?.includes(key))
+      return;
+    return { ...reference, along: [...reference.along ?? [], key] };
+  }
+  return {
+    ...reference,
+    columns: [...remote, key],
+    along: [...reference.along ?? [], key]
+  };
+}
+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 wrapIndexes(key, table, build) {
+  if (build === undefined)
+    return;
+  return (columns) => {
+    const calls = build(columns);
+    const tenantSql = columns[key]?.name;
+    if (!Array.isArray(calls) || tenantSql === undefined)
+      return calls;
+    for (const call of calls) {
+      if (call.columns[0] === tenantSql)
+        continue;
+      throw new OkmError2("OKM1706", `Index on ${table} starts with ${call.columns[0] ?? "no column"}. Put ${tenantSql} first.`);
+    }
+    return calls;
+  };
+}
+function writePredicate(key, tenants, input) {
+  if (!tenants.has(input.table))
+    return false;
+  const scope = input.scope;
+  if (scope === undefined) {
+    throw new OkmError2("OKM1701", `Table ${input.table} is tenant-scoped. Call for({ ${key} }) or unscoped("reason").`);
+  }
+  if ("unscoped" in scope) {
+    input.sink.mark("unscoped|");
+    return false;
+  }
+  const sql = input.fieldSql(key);
+  if (sql === undefined) {
+    throw new OkmError2("OKM1701", `Table ${input.table} is missing its tenant key ${key}.`);
+  }
+  input.sink.text(input.appended ? " and " : " where ");
+  input.sink.text(input.alias);
+  input.sink.text(".");
+  input.sink.text(quote(sql));
+  input.sink.text(" = ");
+  input.sink.param(input.encode === undefined ? scope.value : input.encode(scope.value));
+  input.sink.mark("tenant|");
+  return true;
+}
+function refuseKey(kind, table, field) {
+  if (kind === "insert") {
+    throw new OkmError2("OKM1190", `Field ${table}.${field} is the tenant key. The scope sets it. Input cannot.`);
+  }
+  if (kind === "update") {
+    throw new OkmError2("OKM1704", `Field ${table}.${field} is the tenant key. An update cannot change it.`);
+  }
+  throw new OkmError2("OKM1704", `Field ${table}.${field} is the tenant key. A filter cannot set it.`);
+}
+function stampRows(key, table, rows, scope) {
+  if (scope === undefined || "unscoped" in scope) {
+    throw new OkmError2("OKM1701", `insert on ${table} has no tenant. Call for({ ${key} }) so the scope can set it.`);
+  }
+  for (const row of rows)
+    row[key] = scope.value;
+}
+function bindClient(key, encode, openScope) {
+  return {
+    for: (input) => {
+      if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new OkmError2("OKM1701", `for() needs { ${key} }.`);
+      }
+      const record = input;
+      const value = record[key];
+      if (typeof value !== "string" || value.length === 0) {
+        throw new OkmError2("OKM1701", `for() needs { ${key} } as a uuid.`);
+      }
+      for (const name of Object.keys(record)) {
+        if (name !== key) {
+          throw new OkmError2("OKM1701", `for() accepts ${key}. ${name} is not the tenant key.`);
+        }
+      }
+      encode(value);
+      return openScope({ value });
+    },
+    unscoped: (reason) => {
+      if (typeof reason !== "string" || reason.trim().length === 0) {
+        throw new OkmError2("OKM1701", "unscoped() needs a reason.");
+      }
+      return openScope({ unscoped: reason.trim() });
+    }
+  };
+}
+function tenancyRules(table, source, scope, tenants, globals, exemptions) {
+  const rules = [];
+  const reason = globals.get(table);
+  if (reason !== undefined) {
+    rules.push({
+      rule: "tenancy",
+      contribution: `global ${reason}`,
+      provenance: "catalog",
+      ...source !== undefined ? { source } : {}
+    });
+  }
+  const notes = exemptions.get(table);
+  if (notes !== undefined) {
+    for (const item of notes) {
+      rules.push({
+        rule: "tenancy",
+        contribution: `unique ${item.name} global ${item.reason}`,
+        provenance: "catalog",
+        ...source !== undefined ? { source } : {}
+      });
+    }
+  }
+  if (tenants.has(table) && scope !== undefined && "value" in scope) {
+    rules.push({ rule: "tenancy", contribution: "scoped", provenance: "planner" });
+  }
+  if (scope !== undefined && "unscoped" in scope) {
+    rules.push({
+      rule: "tenancy",
+      contribution: `unscoped ${scope.unscoped}`,
+      provenance: "caller"
+    });
+  }
+  return rules;
+}
+function isGlobal(value) {
+  return isRecord(value) && value.kind === "global" && typeof value.reason === "string";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  columnTenancy,
+  global
+};

package/dist/runtime/trait-read.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Reads sealed and touch columns off the traits stored on a table.
+ *
+ * `schema()` does not copy those lists onto the model. This module is
+ * imported by the write path, which loads on the first write.
+ */
+import type { TableModel } from "../dialects/pg/model.js";
+/**
+ * Fields a trait sets to `now()` on update.
+ *
+ * @param model - Table model
+ * @returns Field names, or `undefined` when no trait touches a column
+ */
+export declare function touchFields(model: TableModel): readonly string[] | undefined;
+/**
+ * Whether a trait owns this field, so input cannot set it.
+ *
+ * @param model - Table model
+ * @param field - Field name
+ * @returns `true` when a trait seals it
+ */
+export declare function fieldSealed(model: TableModel, field: string): boolean;
+/**
+ * The trait that seals a field, when one does.
+ *
+ * @param model - Table model
+ * @param field - Field name
+ * @returns The trait name, or `undefined`
+ */
+export declare function sealingTrait(model: TableModel, field: string): string | undefined;

package/dist/runtime/traits/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Traits (`okmodel/traits`).
+ *
+ * Importing this module is what puts a trait on a schema. An application that
+ * does not import it does not load these columns.
+ */
+import { type PresetMap } from "../../dialects/pg/preset.js";
+import type { AnyTable, RowFrom } from "../../dialects/pg/table.js";
+import { attachArchive } from "../archive-handle.js";
+import { type Trait, type TraitContext, type TraitModel } from "../../dialects/pg/trait.js";
+export type { Trait };
+/**
+ * Options `trait()` accepts.
+ *
+ * `methods` and `requires` are named here and rejected until the prompt that
+ * implements them.
+ *
+ * @typeParam TFields - Columns the trait adds
+ * @typeParam TPresets - Presets the trait adds to each table it applies to
+ */
+export type TraitDefinition<TFields extends Readonly<Record<string, object>>, TPresets extends PresetMap<RowFrom<TFields>> = PresetMap<RowFrom<TFields>>> = {
+    readonly fields: TFields;
+    /** Columns set to `now()` on update. Each one is sealed. */
+    readonly touch?: readonly (keyof TFields & string)[];
+    /** Columns input cannot set, including `{ allow }`. */
+    readonly sealed?: readonly (keyof TFields & string)[];
+    /**
+     * Named query refinements added to every table the trait applies to.
+     *
+     * They see the trait's columns, not the table's. A name a table or another
+     * trait also defines is OKM1040, and so is a reserved name.
+     */
+    readonly presets?: TPresets & PresetMap<RowFrom<TFields>>;
+    readonly methods?: unknown;
+    readonly requires?: unknown;
+};
+/**
+ * Builds a trait.
+ *
+ * The same function the built-in traits use. `schema()` copies `fields` onto
+ * each table and rejects a field the table already has (OKM1012).
+ *
+ * @typeParam TFields - Columns the trait adds
+ * @param name - Provenance name stored on those columns
+ * @param definition - Fields and, when needed, which ones the write path seals
+ * @returns The trait
+ */
+export declare function trait<const TFields extends Readonly<Record<string, object>>, const TPresets extends PresetMap<RowFrom<TFields>> = Record<never, never>>(name: string, input: TraitDefinition<TFields, TPresets>): {
+    readonly name: string;
+    readonly fields: TFields;
+    readonly touch?: readonly (keyof TFields & string)[];
+    readonly sealed?: readonly (keyof TFields & string)[];
+    apply(model: TraitModel, ctx: TraitContext): void;
+} & ([keyof TPresets] extends [never] ? unknown : {
+    readonly presets: TPresets;
+});
+/**
+ * Options for {@link timestamps}.
+ *
+ * `enforce: "trigger"` is the database trigger. It arrives in 0.3.
+ */
+export type TimestampsOptions = {
+    readonly enforce?: "trigger";
+};
+/**
+ * Adds `createdAt` and `updatedAt`.
+ *
+ * Both are `timestamptz not null default now()`, and input cannot set either
+ * of them. Insert leaves them to the default, so one statement stamps both
+ * with the same time. Update sets `updatedAt` to `now()` and leaves `createdAt`.
+ *
+ * @param options - Pass `{ enforce: "trigger" }` only when the trigger ships
+ * @returns The timestamps trait
+ */
+export declare function timestamps(options?: TimestampsOptions): {
+    readonly name: string;
+    readonly fields: {
+        readonly createdAt: import("../../dialects/pg/column.js").ColumnBuilder<Temporal.Instant, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "hasDefault">, "guarded">>;
+        readonly updatedAt: import("../../dialects/pg/column.js").ColumnBuilder<Temporal.Instant, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "hasDefault">, "guarded">>;
+    };
+    readonly touch?: readonly ("createdAt" | "updatedAt")[];
+    readonly sealed?: readonly ("createdAt" | "updatedAt")[];
+    apply(model: TraitModel, ctx: TraitContext): void;
+};
+/**
+ * Options for {@link archivable}.
+ *
+ * `strategy: "column"` keeps archived rows in the same table. `strategy: "table"`
+ * is deferred. `cascade` names the child tables archived and restored with the row.
+ */
+export type ArchivableOptions = {
+    /** `"table"` is reserved and throws OKM1061. */
+    readonly strategy?: "column" | "table";
+    readonly cascade?: readonly string[];
+};
+/**
+ * Adds `archivedAt` and `archiveId`, and enables `archive()` and `restore()`.
+ *
+ * Reads, updates, and deletes target the active set. `withArchived()` and
+ * `onlyArchived()` widen or switch it. Uniques on the table become partial.
+ * `cascade` names children that share the call's `archiveId`.
+ *
+ * @param options - Column strategy and the child tables to cascade
+ * @returns The archivable trait
+ */
+export declare function archivable(options?: ArchivableOptions): {
+    name: string;
+    fields: {
+        readonly archivedAt: import("../../dialects/pg/column.js").ColumnBuilder<Temporal.Instant, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "nullable">, "guarded">>;
+        readonly archiveId: import("../../dialects/pg/column.js").ColumnBuilder<string, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "nullable">, "guarded">>;
+    };
+    touch?: readonly ("archiveId" | "archivedAt")[];
+    sealed?: readonly ("archiveId" | "archivedAt")[];
+    "~archive": true;
+    apply(model: TraitModel, ctx: TraitContext): void;
+    /**
+     * Turns uniques into partial indexes and checks cascade.
+     *
+     * Runs in the schema rewrite, after tenancy widens uniques.
+     *
+     * @param tables - Tables after the tenancy rewrite
+     * @param casing - Schema casing
+     * @param schemaTraits - Traits from `schema()`, when any were passed
+     * @returns The rewritten tables
+     */
+    rewrite(tables: readonly AnyTable[], casing: "snake" | undefined, schemaTraits: readonly object[] | undefined): readonly AnyTable[];
+    hook: typeof attachArchive;
+};