okmodel 0.1.1 → 0.3.0

package/dist/shared/{dkn3y60a.js → xw1d69vd.js}

@@ -1,13 +1,12 @@
 import {
   POSTGRESJS_CAPABILITIES,
-  driverErrors,
   rejectClosed,
   mapFailure,
   nextTransactionDepth,
   runCall,
   EMPTY_NOTICES,
   resultFrom
-} from "./xy79j5hq.js";
+} from "./rrstp3kb.js";
 
 // src/adapters/pg/postgresjs.ts
 import net from "node:net";
@@ -37,61 +36,29 @@ class PoolSockets {
       this.park();
     });
   }
-  async hold(checkout) {
-    this.busy += 1;
-    this.wake();
-    try {
-      const connection = await checkout();
-      let released = false;
-      const release = connection.release.bind(connection);
-      connection.release = () => {
-        if (released)
-          return Promise.resolve();
-        released = true;
-        return release().finally(() => {
-          this.busy -= 1;
-          this.park();
-        });
-      };
-      return connection;
-    } catch (error) {
-      this.busy -= 1;
-      this.park();
-      throw error;
-    }
-  }
-  async* stream(open) {
-    this.busy += 1;
-    this.wake();
-    try {
-      yield* open();
-    } finally {
-      this.busy -= 1;
-      this.park();
-    }
+  busyGate() {
+    return {
+      enter: () => {
+        this.busy += 1;
+        this.wake();
+      },
+      leave: () => {
+        this.busy -= 1;
+        this.park();
+      }
+    };
   }
-  async listen(start) {
-    this.listeners += 1;
-    this.wake();
-    try {
-      const stop = await start();
-      let stopped = false;
-      return async () => {
-        if (stopped)
-          return;
-        stopped = true;
-        try {
-          await stop();
-        } finally {
-          this.listeners -= 1;
-          this.park();
-        }
-      };
-    } catch (error) {
-      this.listeners -= 1;
-      this.park();
-      throw error;
-    }
+  listenerGate() {
+    return {
+      enter: () => {
+        this.listeners += 1;
+        this.wake();
+      },
+      leave: () => {
+        this.listeners -= 1;
+        this.park();
+      }
+    };
   }
   wake() {
     for (const socket of this.held)
@@ -150,7 +117,7 @@ function open2(config) {
     },
     async batch(statements, options) {
       return sockets.occupy(async () => {
-        const { checkout } = await import("./xqbhg6cn.js");
+        const { checkout } = await import("./999ade2q.js");
         const connection = await checkout(held);
         try {
           return await connection.batch(statements, options);
@@ -160,21 +127,36 @@ function open2(config) {
       });
     },
     reserve() {
-      return sockets.hold(async () => {
-        const mod = await import("./xqbhg6cn.js");
-        return mod.checkout(held);
+      const gate = sockets.busyGate();
+      gate.enter();
+      return import("./999ade2q.js").then((mod) => mod.holdCheckout(gate, () => mod.checkout(held)), (error) => {
+        gate.leave();
+        throw error;
       });
     },
-    describe: (text, params) => sockets.occupy(() => import("./xqbhg6cn.js").then((mod) => mod.describe(sql, text, params))),
+    describe: (text, params) => sockets.occupy(() => import("./999ade2q.js").then((mod) => mod.describe(sql, text, params))),
     stream(text, params) {
-      return sockets.stream(() => loadStream(sql, text, params));
+      const gate = sockets.busyGate();
+      return async function* () {
+        gate.enter();
+        try {
+          yield* loadStream(sql, text, params);
+        } finally {
+          gate.leave();
+        }
+      }();
     },
     listen(channel, onNotify) {
-      return sockets.listen(async () => {
+      const gate = sockets.listenerGate();
+      gate.enter();
+      return import("./999ade2q.js").then((mod) => mod.holdListener(gate, async () => {
         const listening = await sql.listen(channel, onNotify);
         return async () => {
           await listening.unlisten();
         };
+      }), (error) => {
+        gate.leave();
+        throw error;
       });
     },
     cancel() {
@@ -228,7 +210,36 @@ class PgSession {
         });
       });
     }
-    return this.watched(pending, watch, start, text);
+    this.local.add(pending);
+    this.shared?.add(pending);
+    const onAbort = () => {
+      pending.cancel();
+    };
+    if (watch.signal.aborted)
+      onAbort();
+    else
+      watch.signal.addEventListener("abort", onAbort, { once: true });
+    return import("./999ade2q.js").then((mod) => mod.watchQuery(pending, watch, onAbort, {
+      start,
+      text,
+      notices: this.notices,
+      leave: () => {
+        this.leave();
+      },
+      note: (sqlText) => {
+        this.note(sqlText);
+      },
+      untrack: (item) => {
+        this.local.delete(item);
+        this.shared?.delete(item);
+      }
+    }), (error) => {
+      this.leave();
+      this.local.delete(pending);
+      this.shared?.delete(pending);
+      watch.signal.removeEventListener("abort", onAbort);
+      throw error;
+    });
   }
   inTransaction() {
     return this.transactionDepth > 0;
@@ -258,43 +269,9 @@ class PgSession {
     else
       this.counters.reservedBusy = Math.max(0, this.counters.reservedBusy - 1);
   }
-  track(pending) {
-    this.local.add(pending);
-    this.shared?.add(pending);
-  }
-  untrack(pending) {
-    this.local.delete(pending);
-    this.shared?.delete(pending);
-  }
-  watched(pending, watch, start, text) {
-    this.track(pending);
-    const onAbort = () => {
-      pending.cancel();
-    };
-    if (watch.signal.aborted)
-      onAbort();
-    else
-      watch.signal.addEventListener("abort", onAbort, { once: true });
-    return pending.then((result) => {
-      this.finishWatched(pending, watch, onAbort);
-      const why = watch.reason();
-      if (why === "timeout" || why === "cancelled")
-        return classify(why, watch);
-      this.note(text);
-      return resultFrom(result, this.notices.since(start));
-    }, (error) => {
-      this.finishWatched(pending, watch, onAbort);
-      return classify(error, watch);
-    });
-  }
-  finishWatched(pending, watch, onAbort) {
-    this.leave();
-    this.untrack(pending);
-    watch.signal.removeEventListener("abort", onAbort);
-  }
 }
 async function* loadStream(sql, text, params) {
-  const { stream } = await import("./xqbhg6cn.js");
+  const { stream } = await import("./999ade2q.js");
   yield* stream(sql, text, params);
 }
 function send(sql, text, params, named) {
@@ -307,19 +284,6 @@ function asParams(params) {
     return [];
   return params;
 }
-async function classify(error, watch) {
-  const errors = await driverErrors();
-  if (error instanceof errors.DriverError)
-    return Promise.reject(error);
-  const why = typeof error === "string" ? error : watch.reason();
-  if (why === "timeout")
-    return Promise.reject(errors.timedOut(typeof error === "string" ? undefined : error));
-  const code = errors.errorField(error, "code");
-  if (why === "cancelled" || code === "57014") {
-    return Promise.reject(errors.cancelled(typeof error === "string" ? undefined : error));
-  }
-  return Promise.reject(errors.mapDriverError(error));
-}
 function statsOf(counters, size) {
   return {
     size,

package/dist/shared/y005b761.js

@@ -0,0 +1,112 @@
+import {
+  staticNamespace2,
+  assertNamespace2,
+  normaliseEdges,
+  assertProvenance
+} from "./t4tbsy9h.js";
+import {
+  assertIdentifier2,
+  fitIdentifier2,
+  deterministicName2
+} from "./nfzc5z0w.js";
+import {
+  catalogError2
+} from "./52szzakm.js";
+
+// src/contracts/catalog/view.ts
+function normaliseViewQuery(query) {
+  return query.trim().replace(/;\s*$/, "");
+}
+function viewObject(input) {
+  const namespace = input.namespace ?? staticNamespace2("public");
+  const columns = readColumns(input.name, input.columns);
+  const query = readQuery(input.name, input.query);
+  assertNamespace2(namespace);
+  assertProvenance(input.provenance);
+  const definition = { columns, query };
+  return {
+    kind: "view",
+    identity: { kind: "view", namespace, name: input.name },
+    owner: input.owner ?? "managed",
+    definition,
+    dependencies: normaliseEdges(input.dependencies ?? []),
+    provenance: input.provenance
+  };
+}
+function materializedViewObject(input) {
+  const namespace = input.namespace ?? staticNamespace2("public");
+  const columns = readColumns(input.name, input.columns);
+  const query = readQuery(input.name, input.query);
+  assertNamespace2(namespace);
+  assertProvenance(input.provenance);
+  const definition = {
+    columns,
+    query,
+    ...input.refresh === "concurrently" ? { refresh: "concurrently" } : {}
+  };
+  return {
+    kind: "materializedView",
+    identity: { kind: "materializedView", namespace, name: input.name },
+    owner: input.owner ?? "managed",
+    definition,
+    dependencies: normaliseEdges(input.dependencies ?? []),
+    provenance: input.provenance
+  };
+}
+function materializedViewIndex(input) {
+  assertNamespace2(input.parent.namespace);
+  assertIdentifier2(input.parent.name, "index parent");
+  assertProvenance(input.provenance);
+  const columns = [...input.columns];
+  for (const name of columns)
+    assertIdentifier2(name, "index column");
+  if (columns.length === 0 && input.expression === undefined) {
+    catalogError2("OKM1020", `Index on ${input.parent.name} needs a column or an expression.`);
+  }
+  const nameKey = input.nameKey ?? (columns.length > 0 ? columns.join("_") : "expr");
+  const name = input.name === undefined ? deterministicName2({ parent: input.parent.name, purpose: "index", nameKey }) : fitIdentifier2(input.name);
+  const parentView = {
+    kind: "materializedView",
+    namespace: input.parent.namespace,
+    name: input.parent.name
+  };
+  return {
+    kind: "index",
+    identity: { kind: "index", parent: input.parent, name },
+    owner: input.owner ?? "managed",
+    definition: {
+      columns,
+      unique: input.unique === true,
+      nameKey,
+      ...input.expression !== undefined ? { expression: input.expression } : {},
+      ...input.predicate !== undefined ? { predicate: input.predicate } : {}
+    },
+    dependencies: normaliseEdges(input.dependencies ?? [parentView]),
+    provenance: input.provenance
+  };
+}
+function readColumns(view, columns) {
+  assertIdentifier2(view, "view");
+  if (columns.length === 0)
+    catalogError2("OKM1020", `View ${view} needs a column.`);
+  const seen = new Set;
+  return columns.map((column) => {
+    assertIdentifier2(column.name, `view ${view} column`);
+    if (seen.has(column.name)) {
+      catalogError2("OKM1020", `View ${view} lists column ${column.name} twice.`);
+    }
+    seen.add(column.name);
+    if (column.dataType.length === 0 || /[;'"\\]/.test(column.dataType)) {
+      catalogError2("OKM1020", `View ${view} column ${column.name} type is not a type name.`);
+    }
+    return { name: column.name, dataType: column.dataType };
+  });
+}
+function readQuery(view, query) {
+  const text = normaliseViewQuery(query);
+  if (text.length === 0)
+    catalogError2("OKM1020", `View ${view} needs a query.`);
+  return text;
+}
+
+export { normaliseViewQuery, viewObject, materializedViewObject, materializedViewIndex };

package/dist/shared/ydaz1sv3.js

@@ -0,0 +1,55 @@
+import {
+  decodeRows,
+  readHandle,
+  readCall,
+  attachHttp
+} from "./k34e0xf2.js";
+import {
+  fail
+} from "./xrfnq5k8.js";
+import {
+  OkmError2,
+  throwNamed2
+} from "./52szzakm.js";
+
+// src/runtime/lock.ts
+var LOCKS = ["update", "share"];
+var WAITS = ["nowait", "skip"];
+function shown(value) {
+  return typeof value === "string" ? value : JSON.stringify(value) ?? "undefined";
+}
+function build(session, table, options, mods, view) {
+  try {
+    return plan(session, table, options, mods, view);
+  } catch (error) {
+    throw error instanceof OkmError2 ? attachHttp(session.http, error) : error;
+  }
+}
+function plan(session, table, options, mods, view) {
+  const { lock, wait, ...rest } = options;
+  if (session.tx === undefined) {
+    throw new OkmError2("OKM1830", "A row lock needs a transaction. find was called outside tx().", {
+      fix: { summary: "Move the find into tx(): the lock lasts until the transaction ends." }
+    });
+  }
+  if (lock === undefined)
+    fail("OKM1121", "wait needs lock: pass lock: update or lock: share.");
+  if (typeof lock !== "string" || !LOCKS.includes(lock)) {
+    throwNamed2("OKM1120", shown(lock), LOCKS, `lock must be one of: ${LOCKS.join(", ")}.`);
+  }
+  if (wait !== undefined && (typeof wait !== "string" || !WAITS.includes(wait))) {
+    throwNamed2("OKM1120", shown(wait), WAITS, `wait must be one of: ${WAITS.join(", ")}.`);
+  }
+  const clause = ` for ${lock} of t${wait === undefined ? "" : wait === "skip" ? " skip locked" : " nowait"}`;
+  const call = {
+    ...readCall("find", table, rest, mods.all, session.scope, session.schema.model[table], session.schema, view),
+    tail(sink) {
+      sink.text(clause);
+      sink.mark(`lock:${clause}`);
+    }
+  };
+  return readHandle(session, table, call, mods, (compiled, rows) => decodeRows(compiled, rows, table));
+}
+export {
+  build
+};

package/dist/shared/{p0cbr3g2.js → zwmqxb0g.js}

@@ -1,6 +1,6 @@
 import {
   OkmError2
-} from "./ycwz42az.js";
+} from "./52szzakm.js";
 
 // src/runtime/drift-detail.ts
 function driftVerdict(codeHash, recordedHash, migrations) {

package/dist/tooling/cli.js

@@ -1,14 +1,17 @@
-import"../shared/y9m15dfv.js";
+import"../shared/t616ynfn.js";
+import"../shared/n442h54c.js";
 import {
-  formatPlan,
   buildProject,
   generateProject,
   planProject,
   checkProject
-} from "../shared/05w44d8g.js";
+} from "../shared/5nmdenb6.js";
+import {
+  formatPlan
+} from "../shared/2ssqrv66.js";
 import {
   OkmError2
-} from "../shared/ycwz42az.js";
+} from "../shared/52szzakm.js";
 
 // src/tooling/cli.ts
 import { readFileSync } from "node:fs";
@@ -16,6 +19,11 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/tooling/migrate/commands.ts
+function formatFailure(error) {
+  return `${error.code}: ${error.message}
+${error.fix.summary}
+`;
+}
 async function run(argv, io) {
   const cwd = io?.cwd ?? process.cwd();
   const stdout = io?.stdout ?? ((text) => process.stdout.write(text));
@@ -27,7 +35,7 @@ async function run(argv, io) {
     return;
   }
   if (command === "check") {
-    await checkProject(cwd);
+    await checkProject(cwd, invoke(splitFlags(rest)));
     stdout(`ok
 `);
     return;
@@ -41,12 +49,12 @@ async function run(argv, io) {
     return;
   }
   if (command === "dev") {
-    const { devProject } = await import("../shared/kprcwaha.js");
+    const { devProject } = await import("../shared/1tfdfvhh.js");
     stdout(await devProject(cwd));
     return;
   }
   if (command === "push") {
-    const { pushProject } = await import("../shared/m3ypagh5.js");
+    const { pushProject } = await import("../shared/dbjej1tw.js");
     stdout(await pushProject(cwd, invoke(splitFlags(rest))));
     return;
   }
@@ -61,16 +69,38 @@ async function run(argv, io) {
       return;
     }
     if (sub === "apply") {
-      const { applyProject } = await import("../shared/m3ypagh5.js");
+      const { applyProject } = await import("../shared/dbjej1tw.js");
       stdout(await applyProject(cwd, invoke(parsed)));
       return;
     }
     if (sub === "status") {
-      const { statusProject } = await import("../shared/523ft3e8.js");
+      const { statusProject } = await import("../shared/scwxrpx2.js");
       stdout(await statusProject(cwd, invoke(parsed)));
       return;
     }
   }
+  if (command === "doctor") {
+    const parsed = splitFlags(rest);
+    const { doctorProject } = await import("../shared/ne02ng5c.js");
+    stdout(await doctorProject(cwd, parsed.name, invoke(parsed)));
+    return;
+  }
+  if (command === "ext") {
+    const sub = rest[0];
+    if (sub === "test" || sub === "scaffold") {
+      throw new OkmError2("invalid", `okm ext ${sub} is not available yet.`, {
+        fix: { summary: "okm ext list and okm ext check are the commands in this version." }
+      });
+    }
+    if (sub === "list" || sub === "check") {
+      const { extProject } = await import("../shared/meck53jv.js");
+      stdout(await extProject(cwd, sub, invoke(splitFlags(rest.slice(1)))));
+      return;
+    }
+    throw new OkmError2("invalid", `Unknown command ext ${sub ?? ""}.`, {
+      fix: { summary: "Use okm ext list or okm ext check." }
+    });
+  }
   throw new OkmError2("invalid", `Unknown command ${command ?? ""}.`);
 }
 function invoke(parsed) {
@@ -172,9 +202,7 @@ if (process.argv.includes("--version")) {
     await run(process.argv.slice(2));
   } catch (error) {
     if (error instanceof OkmError2) {
-      process.stderr.write(`${error.code}: ${error.message}
-${error.fix.summary}
-`);
+      process.stderr.write(formatFailure(error));
       process.exitCode = 1;
     } else {
       throw error;

package/dist/tooling/migrate/apply.d.ts

@@ -37,11 +37,27 @@ export type ApplyRequest = {
     readonly migrations: readonly StoredMigration[];
     /** Runs after the advisory lock is held and before the first step. */
     readonly onLocked?: () => void;
+    /**
+     * Role that runs the migration.
+     *
+     * When it already exists and is not `current_user`, the runner issues one
+     * `SET ROLE` before any statement. That statement is not a plan step.
+     */
+    readonly migrationRole?: string;
+    /**
+     * Schema the migration role may create in.
+     *
+     * When this run creates that role, the runner grants `USAGE` and `CREATE`
+     * on this schema before `SET ROLE`. The default is `public`.
+     */
+    readonly schema?: string;
 };
 /** Migrations that ran at least one step in this invocation. */
 export type ApplyReport = {
     readonly target: string;
     readonly applied: readonly string[];
+    /** Set when the runner issued `SET ROLE` at session start. */
+    readonly setRole?: string;
 };
 /**
  * Groups pending steps into the transactions apply will run.

package/dist/tooling/migrate/commands.d.ts

@@ -4,16 +4,27 @@
  * The bin wrapper imports {@link run}. Importing this module does not parse
  * `process.argv`.
  */
+import { OkmError } from "../../contracts/error.js";
 /** Where a command reads the project and writes its text. */
 export type CommandIo = {
     readonly cwd?: string;
     readonly stdout?: (text: string) => void;
 };
+/**
+ * Text `okm` writes for a failure.
+ *
+ * The message includes a source location when the schema recorded one.
+ *
+ * @param error - Failure from a command
+ * @returns The stderr text, including the trailing newline
+ */
+export declare function formatFailure(error: OkmError): string;
 /**
  * Runs one `okm` invocation.
  *
  * `--version` stays in the bin. This function handles `build`, `check`,
- * `generate`, `dev`, `push`, and `migrate plan`, `apply`, and `status`.
+ * `generate`, `dev`, `push`, `ext list`, `ext check`, `doctor`, and `migrate plan`,
+ * `apply`, and `status`.
  *
  * @param argv - Arguments after the program name
  * @param io - Working directory and stdout. Defaults to the process

package/dist/tooling/migrate/config.d.ts

@@ -9,6 +9,7 @@ export type TargetInput = string | {
     /** Refuses contract, push, and other non-expand work unless `--allow-protected`. */
     readonly protected?: boolean;
 };
+import type { RolesInput } from "../../dialects/pg/role/index.js";
 /** Paths and targets `okm` reads. */
 export type MigrateConfig = {
     /** Module that exports the built schema. */
@@ -35,6 +36,13 @@ export type MigrateConfig = {
         readonly lock?: number;
         readonly statement?: number;
     };
+    /**
+     * Migration role and application role.
+     *
+     * A name is external unless it is also listed in `managed`. The plan creates
+     * a managed role and never drops one.
+     */
+    readonly roles?: RolesInput;
 };
 /**
  * Returns the config unchanged.

package/dist/tooling/migrate/doctor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `okm doctor`.
+ *
+ * A code prints the registry entry. With no code, the project is loaded and
+ * each table's triggers are listed. When `roles` is set, the command also
+ * connects and checks that those roles exist, that a managed role can be
+ * created, and that the application role can reach each managed object.
+ */
+import type { CatalogObject } from "../../contracts/catalog/types.js";
+import { type InvokeFlags } from "./policy.js";
+/**
+ * Explains one code, or lists the triggers on each table.
+ *
+ * @param cwd - Project directory
+ * @param code - Spec code, when the caller passed one
+ * @returns Text for stdout, including the trailing newline
+ */
+export declare function doctorProject(cwd: string, code: string | undefined, flags?: InvokeFlags): Promise<string>;
+/**
+ * One line per table that has a trigger.
+ *
+ * @param objects - Catalog objects
+ * @returns The listing, or `no triggers` when none are present
+ */
+export declare function formatTriggers(objects: readonly CatalogObject[]): string;

package/dist/tooling/migrate/drift.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Live drift for `okm check`.
+ *
+ * A database that has never been pushed has no `okm_meta` and is left alone.
+ * After push, the introspected catalog is planned back to the schema. Each
+ * view is reprinted on this server first, so a `pg_get_viewdef` spelling is
+ * not drift. Any remaining statement is OKM1520. `okm_meta` and `okm_history`
+ * are omitted by the planner.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { RolesInput } from "../../dialects/pg/role/index.js";
+/**
+ * Refuses when the connected database differs from the schema.
+ *
+ * @param url - Target URL
+ * @param author - Schema catalog, including roles when the config names them
+ * @param roles - `defineConfig({ roles })`, when set
+ */
+export declare function assertAuthorDrift(url: string, author: Catalog, roles?: RolesInput): Promise<void>;