okmodel 0.2.1 → 0.4.0

package/dist/dialects/pg/view/index.js

@@ -0,0 +1,289 @@
+import {
+  viewObject,
+  materializedViewObject,
+  materializedViewIndex
+} from "../../../shared/y005b761.js";
+import {
+  encodeUuid,
+  decodeUuid
+} from "../../../shared/dyj86cmj.js";
+import {
+  snakeCase
+} from "../../../shared/jsd07prz.js";
+import {
+  encodeText,
+  decodeText
+} from "../../../shared/4m9fn52z.js";
+import {
+  staticNamespace2
+} from "../../../shared/t4tbsy9h.js";
+import {
+  OkmError2
+} from "../../../shared/52szzakm.js";
+
+// src/dialects/pg/view/client.ts
+function viewClient(name, columns, query, tenancy) {
+  const field = camelCase(name);
+  const marked = readGlobal(name, tenancy);
+  return {
+    field,
+    install(model, scope, tables, casing, scoped) {
+      if (Object.hasOwn(model, field)) {
+        throw new OkmError2("OKM1023", `View ${name} uses the client name ${field}.`, {
+          fix: { summary: "Give the view a name that no table uses." }
+        });
+      }
+      const exposes = exposesKey(columns, scope);
+      if (scope !== undefined && readsTenant(query, tables, casing, scoped)) {
+        if (!exposes && marked === undefined) {
+          throw new OkmError2("OKM1820", `View ${name} reads a tenant table and does not expose ${scope.key}.`, {
+            fix: {
+              summary: "Expose the tenant key so the predicate can be applied, or declare global(reason)."
+            }
+          });
+        }
+        if (exposes) {
+          scope.scopeView(field);
+          scoped.add(name);
+        }
+      }
+      model[field] = {
+        name: field,
+        sql: name,
+        primary: [],
+        uniques: [],
+        columns: columnModels(columns, scope),
+        relations: []
+      };
+    },
+    hook(target, ctx) {
+      publish(field, target, ctx);
+    }
+  };
+}
+function publish(field, target, ctx) {
+  if (ctx.tables === undefined || ctx.table !== undefined)
+    return;
+  const handle = ctx.tables[field];
+  if (typeof handle !== "object" || handle === null)
+    return;
+  const source = handle;
+  const views = target.views;
+  const map = typeof views === "object" && views !== null ? views : {};
+  map[field] = {
+    find: source.find,
+    one: source.one,
+    count: source.count,
+    exists: source.exists
+  };
+  target.views = map;
+  delete ctx.tables[field];
+  delete target[field];
+}
+function columnModels(columns, tenancy) {
+  const seen = new Set;
+  const models = [];
+  for (const column of columns) {
+    const field = fieldName(column.name, tenancy);
+    if (seen.has(field)) {
+      throw new OkmError2("OKM1020", `View column ${column.name} repeats ${field}.`, {
+        fix: { summary: "Declare each output column once." }
+      });
+    }
+    seen.add(field);
+    const uuid = column.type.toLowerCase() === "uuid";
+    const key = tenancy !== undefined && field === tenancy.key;
+    models.push({
+      field,
+      sql: column.name,
+      dataType: column.type,
+      encode: uuid ? (value) => encodeUuid(textValue(value)) : (value) => encodeText(textValue(value)),
+      decode: uuid ? decodeUuid : decodeText,
+      hidden: false,
+      sensitive: false,
+      guarded: key,
+      writable: false,
+      guardUpdate: false
+    });
+  }
+  return models;
+}
+function exposesKey(columns, tenancy) {
+  if (tenancy === undefined)
+    return false;
+  return columns.some((column) => fieldName(column.name, tenancy) === tenancy.key);
+}
+function readsTenant(query, tables, casing, scoped) {
+  for (const name of scoped) {
+    if (mentions(query, name))
+      return true;
+  }
+  for (const table of tables) {
+    const mark = table.options?.tenancy;
+    if (isGlobalMark(mark))
+      continue;
+    const sql = casing === "snake" ? snakeCase(table.name) : table.name;
+    if (mentions(query, sql) || mentions(query, table.name))
+      return true;
+  }
+  return false;
+}
+function readGlobal(name, tenancy) {
+  if (tenancy === undefined)
+    return;
+  if (!isGlobalMark(tenancy)) {
+    throw new OkmError2("OKM1020", `View ${name} tenancy must be global("reason").`, {
+      fix: { summary: 'Pass global("reason") from okmodel/tenancy, or omit tenancy.' }
+    });
+  }
+  return tenancy.reason;
+}
+function isGlobalMark(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const record = value;
+  return record.kind === "global" && typeof record.reason === "string" && record.reason.trim().length > 0;
+}
+function fieldName(column, tenancy) {
+  const field = camelCase(column);
+  if (tenancy !== undefined && (column === tenancy.key || field === tenancy.key))
+    return tenancy.key;
+  return field;
+}
+function camelCase(name) {
+  let out = "";
+  let upper = false;
+  for (const char of name) {
+    if (char === "_") {
+      upper = out.length > 0;
+      continue;
+    }
+    out += upper ? char.toUpperCase() : char;
+    upper = false;
+  }
+  return out;
+}
+function mentions(query, name) {
+  let pattern = '(^|[^A-Za-z0-9_])"?';
+  for (const char of name) {
+    if ("\\^$[]().*+?|{}".includes(char))
+      pattern += "\\";
+    pattern += char;
+  }
+  pattern += '"?(?![A-Za-z0-9_])';
+  return new RegExp(pattern).test(query);
+}
+function textValue(value) {
+  if (typeof value !== "string") {
+    throw new OkmError2("OKM1121", "A view column value must be text.", {
+      fix: { summary: "Pass a string." }
+    });
+  }
+  return value;
+}
+
+// src/dialects/pg/view/index.ts
+function view(name, options) {
+  const schema = options.schema ?? "public";
+  const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
+  const query = bodyText(options.query);
+  const bound = viewClient(name, options.columns, query, options.tenancy);
+  return {
+    name,
+    schema,
+    install: bound.install,
+    hook: bound.hook,
+    contribute(peers, built) {
+      assertPeers(peers);
+      assertNoTable(built, name);
+      const provenance = { origin: "file", name };
+      return [
+        viewObject({
+          namespace: staticNamespace2(schema),
+          name,
+          columns,
+          query,
+          provenance
+        })
+      ];
+    }
+  };
+}
+function materializedView(name, options) {
+  const schema = options.schema ?? "public";
+  const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
+  const query = bodyText(options.query);
+  const bound = viewClient(name, options.columns, query, options.tenancy);
+  const indexes = options.indexes ?? [];
+  if (options.refresh === "concurrently" && !indexes.some((index) => index.unique === true)) {
+    throw new OkmError2("OKM1822", `Materialized view ${name} refreshes concurrently and has no unique index.`, { fix: { summary: "Add a unique index, or refresh without CONCURRENTLY." } });
+  }
+  const columnNames = new Set(columns.map((column) => column.name));
+  for (const index of indexes) {
+    for (const column of index.columns) {
+      if (!columnNames.has(column)) {
+        throw new OkmError2("OKM1020", `Index on ${name} names column ${column}, which the materialized view does not have.`, { fix: { summary: "Name a column of the materialized view." } });
+      }
+    }
+  }
+  return {
+    name,
+    schema,
+    install: bound.install,
+    hook: bound.hook,
+    contribute(peers, built) {
+      assertPeers(peers);
+      assertNoTable(built, name);
+      const namespace = staticNamespace2(schema);
+      const provenance = { origin: "file", name };
+      const parent = { namespace, name };
+      return [
+        materializedViewObject({
+          namespace,
+          name,
+          columns,
+          query,
+          provenance,
+          ...options.refresh === "concurrently" ? { refresh: "concurrently" } : {}
+        }),
+        ...indexes.map((index) => materializedViewIndex({
+          parent,
+          ...index.name !== undefined ? { name: index.name } : {},
+          columns: index.columns,
+          ...index.unique === true ? { unique: true } : {},
+          provenance
+        }))
+      ];
+    }
+  };
+}
+function bodyText(body) {
+  return typeof body === "string" ? body : body.text;
+}
+function assertPeers(peers) {
+  if (!Array.isArray(peers)) {
+    throw new OkmError2("OKM1020", "schema({ views }) must be a list.", {
+      fix: { summary: "Pass an array to schema({ views })." }
+    });
+  }
+}
+function assertNoTable(built, name) {
+  if (!Array.isArray(built))
+    return;
+  for (const object of built) {
+    if (!isRecord(object) || object.kind !== "table" || !isRecord(object.identity))
+      continue;
+    if (object.identity.name === name) {
+      throw new OkmError2("OKM1023", `View ${name} uses the name of a table.`, {
+        fix: { summary: "Give the view a name that no table uses." }
+      });
+    }
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  materializedView,
+  view
+};

package/dist/dialects/pg/view/scratch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Verifies declared views on a scratch schema.
+ *
+ * Domain and enum types from the catalog are created there, then the tables,
+ * then each view. `pg_get_viewdef` replaces the author query and `pg_depend`
+ * supplies column edges (D117).
+ * The scratch schema is dropped before this returns. Plans never use it.
+ */
+import type { Catalog } from "../../../contracts/catalog/types.js";
+import type { CatalogQuery } from "../introspect.js";
+/**
+ * Reads dependencies and reprints for every view in `source`.
+ *
+ * The returned catalog matches what introspection prints for those views
+ * when the same query is applied. A declared column list that disagrees
+ * with the database is OKM1020.
+ *
+ * @param runner - Database connection. Statements share its session
+ * @param source - Catalog whose views are still author SQL
+ * @returns A catalog whose views carry the reprint and `pg_depend` edges
+ */
+export declare function sealViews(runner: CatalogQuery, source: Catalog): Promise<Catalog>;

package/dist/dialects/pg/where.d.ts

@@ -5,11 +5,11 @@
  * `where` without importing the client types. `runtime/types.ts` re-exports
  * the two names callers use.
  */
-import type { Between, Compare, Containment, Eq, HasAnyKey, HasKey, InList, Matches, Not, NotIn, Overlaps, Path, Pattern, RawPattern } from "./operators.js";
+import type { Between, Compare, Containment, Eq, HasAnyKey, HasKey, InList, Matches, Trigram, Not, NotIn, Overlaps, Path, Pattern, RawPattern } from "./operators.js";
 import type { Range } from "./range.js";
 export type IsObject<V> = V extends object ? V extends readonly unknown[] ? false : null extends V ? false : true : false;
 /** Text patterns, including substring `contains`. `matches` is for tsvector, which is also `string`. */
-type TextOps = Pattern<"startsWith"> | Pattern<"contains"> | Pattern<"endsWith"> | RawPattern<"like"> | RawPattern<"ilike"> | Matches;
+type TextOps = Pattern<"startsWith"> | Pattern<"contains"> | Pattern<"endsWith"> | RawPattern<"like"> | RawPattern<"ilike"> | Matches | Trigram<"similar"> | Trigram<"wordSimilar">;
 /** Array, jsonb, or range containment, plus overlap where that operator fits. */
 type StructuredOps<V> = Containment<"contains" | "containedBy", V> | Overlaps<V>;
 /** A JSON fragment. Containment matches part of a document, not the whole column type. */

package/dist/runtime/catalog-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One in-flight catalog load per key.
+ *
+ * Concurrent `connect()` calls in one process share the parse. A failure is
+ * dropped so the next call can try again. Success stays for the process.
+ */
+/**
+ * Runs `load` once for `key`.
+ *
+ * The map is filled before `load` starts, so a second call on the same tick
+ * waits on the first promise instead of parsing again.
+ *
+ * @param key - Directory and hash, or the artifact hash
+ * @param load - Reads and trusts the catalog
+ * @returns The shared load
+ */
+export declare function loadOnce(key: string, load: () => Promise<void>): Promise<void>;

package/dist/runtime/compat-words.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Words shared by `connect()` and `okm migrate status` (D197).
+ *
+ * The startup check and the status command name the same situations.
+ * A failed step adds the resume hint status prints.
+ */
+/** The database and the app record the same catalog. */
+export declare const CURRENT = "current";
+/** Pending migrations are expand only. */
+export declare const BEHIND_EXPAND = "behind by expand";
+/** A pending migration is not expand. */
+export declare const BEHIND_CONTRACT = "behind by contract";
+/** The database has expand migrations the app does not. */
+export declare const AHEAD_EXPAND = "ahead by expand";
+/** The database has a contract migration the app does not. */
+export declare const AHEAD_CONTRACT = "ahead by contract";
+/**
+ * Status text for a migration that stopped mid-way.
+ *
+ * @param step - Zero-based step that has no `okm_history` row
+ * @returns The state, including the resume hint
+ */
+export declare function failedAt(step: number): string;

package/dist/runtime/drift-detail.d.ts

@@ -2,25 +2,41 @@
  * Compatibility check used only when the catalog hashes differ.
  *
  * Ahead by expand is compatible. Ahead by a contract step, or behind, fails
- * closed (OKM1520).
+ * closed (OKM1520). The class is the value stored in `okm_history`.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 /** One applied migration, in history order. */
 export type DriftMigration = {
     readonly id: string;
     readonly catalogHash: string;
-    /** True when every step is expand. */
+    /** True when every stored step class is `expand`. */
     readonly expand: boolean;
 };
+/** How far the database and the app have diverged. */
+export type DriftVerdict = {
+    readonly state: "ok";
+} | {
+    readonly state: "ahead by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by expand";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind";
+    readonly migrationId: string;
+};
 /**
- * Classifies a hash mismatch.
+ * Classifies a hash mismatch from stored history classes.
  *
  * @param codeHash - Hash of the code's catalog
  * @param recordedHash - Hash stored in `okm_meta`
  * @param migrations - Applied migrations, oldest first
  * @returns `ok` when the database is ahead by expand only
  */
-export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): "ok" | "behind" | "contract";
+export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): DriftVerdict;
 /**
  * Reads history and throws OKM1520 when the database is not expand-ahead.
  *

package/dist/runtime/drift.d.ts

@@ -1,8 +1,10 @@
 /**
  * Startup catalog check.
  *
- * The fast path compares two hashes. History, catalog JSON, and
- * {@link loadTrustedCatalog} load only when those hashes differ.
+ * The fast path compares two hashes and returns. History and
+ * `.okm/catalog.json` load only when those hashes differ. A hash read from
+ * `catalog.hash` requires that JSON file; a missing file or a hash that does
+ * not match is OKM1027. Concurrent loads share one parse.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 import type { QuerySchema } from "../dialects/pg/model.js";

package/dist/runtime/pg/bun.js

@@ -3,15 +3,15 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open5
-} from "../../shared/ytg3xf9p.js";
+} from "../../shared/sf8m6tfy.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/9k6vetvf.js";
+} from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/mxmcdsh5.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {

package/dist/runtime/pg/pg.js

@@ -3,15 +3,15 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open4
-} from "../../shared/38crxbgn.js";
+} from "../../shared/6p5k20sm.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/9k6vetvf.js";
+} from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/mxmcdsh5.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {

package/dist/runtime/pg/pglite.js

@@ -3,15 +3,15 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open3
-} from "../../shared/0qkxbm1f.js";
+} from "../../shared/fa9vt245.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/9k6vetvf.js";
+} from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/mxmcdsh5.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {

package/dist/runtime/pg/postgresjs.js

@@ -3,15 +3,15 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open2
-} from "../../shared/ecdzej21.js";
+} from "../../shared/wqem4jed.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/9k6vetvf.js";
+} from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/mxmcdsh5.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {

package/dist/runtime/tenancy/index.js

@@ -1,14 +1,14 @@
 import {
   uuid2
-} from "../../shared/ps43134h.js";
+} from "../../shared/dyj86cmj.js";
 import {
   ColumnBuilder2,
   retarget
-} from "../../shared/dd4f8mnx.js";
+} from "../../shared/c9z5g0fm.js";
 import {
   definition,
   unavailable
-} from "../../shared/xatfg0gn.js";
+} from "../../shared/tmbdywx0.js";
 import {
   quote
 } from "../../shared/xrfnq5k8.js";
@@ -76,6 +76,9 @@ function columnTenancy(input) {
     rules(table, source, scope) {
       return tenancyRules(table, source, scope, tenants, globals, exemptions);
     },
+    scopeView(name) {
+      tenants.add(name);
+    },
     hook(target, ctx) {
       if (ctx.tables === undefined || ctx.names === undefined || ctx.open === undefined || ctx.scoped === undefined) {
         return;

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

@@ -51,13 +51,14 @@ export declare function trait<const TFields extends Readonly<Record<string, obje
     readonly touch?: readonly (keyof TFields & string)[];
     readonly sealed?: readonly (keyof TFields & string)[];
     apply(model: TraitModel, ctx: TraitContext): void;
+    contribute(peers: unknown, built: unknown): readonly unknown[];
 } & ([keyof TPresets] extends [never] ? unknown : {
     readonly presets: TPresets;
 });
 /**
  * Options for {@link timestamps}.
  *
- * `enforce: "trigger"` is the database trigger. It arrives in 0.3.
+ * `enforce: "trigger"` adds a before-update trigger and its function.
  */
 export type TimestampsOptions = {
     readonly enforce?: "trigger";
@@ -68,8 +69,10 @@ export type TimestampsOptions = {
  * 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`.
+ * `{ enforce: "trigger" }` also writes `updatedAt` in the database, including
+ * for writers that bypass the client.
  *
- * @param options - Pass `{ enforce: "trigger" }` only when the trigger ships
+ * @param options - Pass `{ enforce: "trigger" }` for the database trigger
  * @returns The timestamps trait
  */
 export declare function timestamps(options?: TimestampsOptions): {
@@ -81,6 +84,7 @@ export declare function timestamps(options?: TimestampsOptions): {
     readonly touch?: readonly ("createdAt" | "updatedAt")[];
     readonly sealed?: readonly ("createdAt" | "updatedAt")[];
     apply(model: TraitModel, ctx: TraitContext): void;
+    contribute(peers: unknown, built: unknown): readonly unknown[];
 };
 /**
  * Options for {@link archivable}.
@@ -111,6 +115,7 @@ export declare function archivable(options?: ArchivableOptions): {
     };
     touch?: readonly ("archiveId" | "archivedAt")[];
     sealed?: readonly ("archiveId" | "archivedAt")[];
+    contribute(peers: unknown, built: unknown): readonly unknown[];
     "~archive": true;
     apply(model: TraitModel, ctx: TraitContext): void;
     /**