okmodel 0.2.1 → 0.3.0

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/{mrq77sgw.js → ydaz1sv3.js}

@@ -3,7 +3,7 @@ import {
   readHandle,
   readCall,
   attachHttp
-} from "./mxmcdsh5.js";
+} from "./k34e0xf2.js";
 import {
   fail
 } from "./xrfnq5k8.js";

package/dist/tooling/cli.js

@@ -1,12 +1,14 @@
-import"../shared/d2whjz4k.js";
+import"../shared/t616ynfn.js";
 import"../shared/n442h54c.js";
 import {
-  formatPlan,
   buildProject,
   generateProject,
   planProject,
   checkProject
-} from "../shared/5z4q2zda.js";
+} from "../shared/5nmdenb6.js";
+import {
+  formatPlan
+} from "../shared/2ssqrv66.js";
 import {
   OkmError2
 } from "../shared/52szzakm.js";
@@ -33,7 +35,7 @@ async function run(argv, io) {
     return;
   }
   if (command === "check") {
-    await checkProject(cwd);
+    await checkProject(cwd, invoke(splitFlags(rest)));
     stdout(`ok
 `);
     return;
@@ -47,12 +49,12 @@ async function run(argv, io) {
     return;
   }
   if (command === "dev") {
-    const { devProject } = await import("../shared/eaxwrgby.js");
+    const { devProject } = await import("../shared/1tfdfvhh.js");
     stdout(await devProject(cwd));
     return;
   }
   if (command === "push") {
-    const { pushProject } = await import("../shared/eqmtn1bj.js");
+    const { pushProject } = await import("../shared/dbjej1tw.js");
     stdout(await pushProject(cwd, invoke(splitFlags(rest))));
     return;
   }
@@ -67,16 +69,38 @@ async function run(argv, io) {
       return;
     }
     if (sub === "apply") {
-      const { applyProject } = await import("../shared/eqmtn1bj.js");
+      const { applyProject } = await import("../shared/dbjej1tw.js");
       stdout(await applyProject(cwd, invoke(parsed)));
       return;
     }
     if (sub === "status") {
-      const { statusProject } = await import("../shared/d04j53v8.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) {

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

@@ -23,7 +23,8 @@ 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>;

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

@@ -0,0 +1,17 @@
+/**
+ * `okm ext list` and `okm ext check`.
+ *
+ * Both talk to the selected target. List prints every extension the server
+ * can install, and the installed version when one is present. Check compares
+ * the schema's declarations with what is installed.
+ */
+import { type InvokeFlags } from "./policy.js";
+/**
+ * Runs `list` or `check` against the selected target.
+ *
+ * @param cwd - Project directory
+ * @param command - `list` or `check`
+ * @param flags - Target and protection flags
+ * @returns Text for stdout, including the trailing newline
+ */
+export declare function extProject(cwd: string, command: "list" | "check", flags: InvokeFlags): Promise<string>;

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

@@ -0,0 +1,51 @@
+/**
+ * Extension alters and the apply preflight.
+ *
+ * Create and drop SQL come from the dialect. An upgrade is `ALTER EXTENSION
+ * … UPDATE`, marked `path-unverified` until apply checks
+ * `pg_extension_update_paths`. A move is `SET SCHEMA` and only when the
+ * declaration is relocatable.
+ */
+import type { CatalogObject } from "../../contracts/catalog/types.js";
+import type { DriverConnection } from "../../contracts/driver.js";
+/** One extension alter. The planner stores it as a plan step. */
+export type ExtensionStep = {
+    readonly sql: string;
+    readonly class: "expand" | "contract";
+    readonly action: "ddl";
+    readonly lock: string;
+    readonly transactional: boolean;
+    readonly path?: "unverified";
+};
+/** Migrations the preflight reads. Only the statement text is used. */
+type MigrationSql = {
+    readonly steps: readonly {
+        readonly sql: string;
+    }[];
+};
+/**
+ * Upgrade and move steps for extensions whose definition changed.
+ *
+ * Exact downgrades and moves of a non-relocatable extension are OKM1814.
+ * Dropping an extension that an object in the next catalog still uses is
+ * OKM1814. `DROP` is never `CASCADE`.
+ *
+ * @param beforeBy - Previous objects, keyed by identity
+ * @param afterBy - Next objects, keyed by identity
+ * @param dropKeys - Identities the plan drops
+ * @returns Alter steps. Creates and drops stay in the main planner
+ */
+export declare function extensionAlterSteps(beforeBy: ReadonlyMap<string, CatalogObject>, afterBy: ReadonlyMap<string, CatalogObject>, dropKeys: ReadonlySet<string>): ExtensionStep[];
+/**
+ * Refuses a migration that names an extension the server cannot install,
+ * or an upgrade with no path.
+ *
+ * The server is asked only when a step creates or upgrades an extension.
+ * The check runs before any statement.
+ *
+ * @param connection - The reserved apply connection
+ * @param migrations - Migrations in apply order
+ * @throws OkmError OKM1811 when the extension is not available, OKM1814 when the update path is missing
+ */
+export declare function assertExtensionsAvailable(connection: DriverConnection, migrations: readonly MigrationSql[]): Promise<void>;
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * Tables OKModel owns: `okm_meta` and `okm_history`.
+ *
+ * Apply creates them. They are not part of the author schema. Plan, push,
+ * check, and doctor omit them on both sides, so a diff neither drops them
+ * nor creates them.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/**
+ * Removes the migration history tables and the objects that belong to them.
+ *
+ * A catalog that has neither is returned as itself.
+ *
+ * @param source - Catalog about to be diffed or diagnosed
+ * @returns The catalog without OKModel's own tables
+ */
+export declare function omitManagedObjects(source: Catalog): Catalog;

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

@@ -26,6 +26,19 @@ export type PlanStep = {
     readonly action: "ddl" | "backfill";
     readonly lock: string;
     readonly transactional: boolean;
+    /**
+     * Set on an extension upgrade the planner could not check.
+     *
+     * Apply reads `pg_extension_update_paths` before any statement and refuses
+     * a missing path. Offline `okm migrate plan` leaves this unverified.
+     */
+    readonly path?: "unverified";
+    /**
+     * Set on `CREATE OR REPLACE` of a function whose signature did not change.
+     *
+     * The statement is expand. The flag says the body or the settings changed.
+     */
+    readonly behavior?: "change";
 };
 /** A named plan and the class of its strictest step. */
 export type MigrationPlan = {
@@ -49,7 +62,7 @@ export type PlanRequest = {
  * @param request - Catalogs, declared renames, and `--replace` flags
  * @returns Steps in apply order, with one class for the plan
  */
-export declare function planMigration(request: PlanRequest): MigrationPlan;
+export declare function planMigration(input: PlanRequest): MigrationPlan;
 /**
  * Prints a plan. The text is SQL plus class comments, never TypeScript.
  *

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

@@ -5,9 +5,13 @@
  * `.catalog`, which runs that validation. Generate writes SQL only.
  */
 import { type DeclaredRename } from "../../dialects/pg/declarations.js";
+import type { BuiltSchema } from "../../dialects/pg/schema.js";
+import type { AnyTable } from "../../dialects/pg/table.js";
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { type MigrateConfig } from "./config.js";
+import { type InvokeFlags } from "./policy.js";
 import { type MigrationPlan } from "./plan.js";
+type Built = BuiltSchema<readonly AnyTable[]>;
 /**
  * Validates the schema and writes `.okm/`.
  *
@@ -38,9 +42,14 @@ export declare function planProject(cwd: string, name: string, flags: readonly s
 /**
  * Validates the schema, then reports stale renames and unlisted table files.
  *
+ * When exactly one target is configured, or `--target` names one, a database
+ * that already has `okm_meta` is compared with the schema. A difference is
+ * OKM1520. Several targets and no `--target` skip that comparison.
+ *
  * @param cwd - Project directory
+ * @param flags - `--target`, when the caller passed one
  */
-export declare function checkProject(cwd: string): Promise<void>;
+export declare function checkProject(cwd: string, flags?: InvokeFlags): Promise<void>;
 /**
  * Table files whose names do not appear in the schema module.
  *
@@ -60,6 +69,20 @@ export declare function projectHead(cwd: string): Promise<{
     readonly catalog: Catalog;
     readonly renames: readonly DeclaredRename[];
 }>;
+/**
+ * Loads the config, the schema, and the previous catalog snapshot.
+ *
+ * A `renamedFrom` that the previous catalog does not contain is OKM1020.
+ *
+ * @param cwd - Project directory
+ * @returns The loaded project
+ */
+export declare function openProject(cwd: string): Promise<{
+    readonly config: MigrateConfig;
+    readonly built: Built;
+    readonly previous: Catalog;
+    readonly renames: readonly DeclaredRename[];
+}>;
 /**
  * Loads `okmodel.config.ts`.
  *
@@ -67,3 +90,4 @@ export declare function projectHead(cwd: string): Promise<{
  * @returns The config object
  */
 export declare function loadConfig(cwd: string): Promise<MigrateConfig>;
+export {};

package/dist/tooling/migrate/type-name.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One spelling for a SQL type name in a diff (D191).
+ *
+ * The catalog keeps the spelling the schema wrote. Introspection keeps
+ * `format_type`. Both sides of a comparison pass through here, so
+ * `timestamptz` and `timestamp with time zone` are one type. A different
+ * length, precision, or type stays different. An unknown name is returned
+ * as written.
+ */
+/**
+ * Maps a schema spelling or a `format_type` spelling to the long form.
+ *
+ * Modifiers and array ranks stay. `varchar(20)[]` becomes
+ * `character varying(20)[]`.
+ *
+ * @param typeName - Type name from a catalog definition
+ * @returns The Postgres long spelling
+ */
+export declare function canonicalTypeName(typeName: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okmodel",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first.",
   "keywords": [
     "migrations",
@@ -85,10 +85,30 @@
     "./validate": {
       "types": "./dist/runtime/validate/index.d.ts",
       "import": "./dist/runtime/validate/index.js"
+    },
+    "./ext": {
+      "types": "./dist/dialects/pg/ext/index.d.ts",
+      "import": "./dist/dialects/pg/ext/index.js"
+    },
+    "./fn": {
+      "types": "./dist/dialects/pg/fn/index.d.ts",
+      "import": "./dist/dialects/pg/fn/index.js"
+    },
+    "./view": {
+      "types": "./dist/dialects/pg/view/index.d.ts",
+      "import": "./dist/dialects/pg/view/index.js"
+    },
+    "./pg/citext": {
+      "types": "./dist/dialects/pg/ext/citext.d.ts",
+      "import": "./dist/dialects/pg/ext/citext.js"
+    },
+    "./pg/pg_trgm": {
+      "types": "./dist/dialects/pg/ext/pg-trgm.d.ts",
+      "import": "./dist/dialects/pg/ext/pg-trgm.js"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && bun build ./src/contracts/index.ts ./src/contracts/internal.ts ./src/dialects/pg/index.ts ./src/runtime/pg/postgresjs.ts ./src/runtime/pg/pglite.ts ./src/runtime/pg/pg.ts ./src/runtime/pg/bun.ts ./src/runtime/ids/index.ts ./src/runtime/safety/index.ts ./src/runtime/traits/index.ts ./src/runtime/tenancy/index.ts ./src/runtime/validate/index.ts ./src/tooling/migrate/index.ts ./src/tooling/cli.ts --outdir ./dist --root ./src --format esm --target node --splitting --chunk-naming=shared/[hash].js --external postgres --external @electric-sql/pglite --external pg --external bun && bunx tsc -p tsconfig.build.json && bun ./scripts/write-bin-wrappers.ts",
+    "build": "rm -rf dist && bun build ./src/contracts/index.ts ./src/contracts/internal.ts ./src/dialects/pg/index.ts ./src/runtime/pg/postgresjs.ts ./src/runtime/pg/pglite.ts ./src/runtime/pg/pg.ts ./src/runtime/pg/bun.ts ./src/runtime/ids/index.ts ./src/runtime/safety/index.ts ./src/runtime/traits/index.ts ./src/runtime/tenancy/index.ts ./src/runtime/validate/index.ts ./src/dialects/pg/ext/index.ts ./src/dialects/pg/fn/index.ts ./src/dialects/pg/view/index.ts ./src/dialects/pg/ext/citext.ts ./src/dialects/pg/ext/pg-trgm.ts ./src/tooling/migrate/index.ts ./src/tooling/cli.ts --outdir ./dist --root ./src --format esm --target node --splitting --chunk-naming=shared/[hash].js --external postgres --external @electric-sql/pglite --external pg --external bun && bunx tsc -p tsconfig.build.json && bun ./scripts/write-bin-wrappers.ts",
     "driver-bench": "bun ./scripts/driver-bench.ts",
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
     "editor-check": "bun ./scripts/editor-check.ts",