okmodel 0.1.1 → 0.3.0

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

@@ -0,0 +1,36 @@
+/**
+ * Engine-version checks `okm migrate apply` runs before the first statement.
+ *
+ * The only engine-dependent feature in 0.2 is a `uuidv7()` database default,
+ * which Postgres has from 18. Nothing here is reachable from `connect()`.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import type { StoredMigration } from "./files.js";
+/** Where a migration sets a `uuidv7()` default. */
+export type UuidV7Default = {
+    readonly migrationId: string;
+    readonly stepIndex: number;
+    /** `table.column`, or `undefined` when the statement does not name both. */
+    readonly column: string | undefined;
+};
+/**
+ * Finds the first pending step that sets a `uuidv7()` database default.
+ *
+ * Only `default uuidv7()` counts, so a string in a data step is not a hit.
+ *
+ * @param migrations - Migrations in apply order
+ * @returns The first hit, or `undefined`
+ */
+export declare function findUuidV7Default(migrations: readonly StoredMigration[]): UuidV7Default | undefined;
+/**
+ * Refuses a run that would set a `uuidv7()` default on a server that has none.
+ *
+ * The server is asked only when a step needs it, so a schema without the
+ * default costs no round trip. A server below 18 that already has a
+ * `uuidv7()` function, such as one the application defined, is accepted.
+ *
+ * @param connection - The reserved apply connection
+ * @param migrations - Migrations in apply order
+ * @throws OkmError OKM1812, before any statement of the plan runs
+ */
+export declare function assertUuidV7Available(connection: DriverConnection, migrations: readonly StoredMigration[]): 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,7 +1,7 @@
 {
   "name": "okmodel",
-  "version": "0.1.1",
-  "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first. Other SQL databases are the direction. Version 0.1 supports PostgreSQL only. The schema is the single source. Migrations and queries come from it.",
+  "version": "0.3.0",
+  "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first.",
   "keywords": [
     "migrations",
     "orm",
@@ -57,10 +57,58 @@
     "./pg/pglite": {
       "types": "./dist/runtime/pg/pglite.d.ts",
       "import": "./dist/runtime/pg/pglite.js"
+    },
+    "./pg/pg": {
+      "types": "./dist/runtime/pg/pg.d.ts",
+      "import": "./dist/runtime/pg/pg.js"
+    },
+    "./pg/bun": {
+      "types": "./dist/runtime/pg/bun.d.ts",
+      "import": "./dist/runtime/pg/bun.js"
+    },
+    "./ids": {
+      "types": "./dist/runtime/ids/index.d.ts",
+      "import": "./dist/runtime/ids/index.js"
+    },
+    "./safety": {
+      "types": "./dist/runtime/safety/index.d.ts",
+      "import": "./dist/runtime/safety/index.js"
+    },
+    "./traits": {
+      "types": "./dist/runtime/traits/index.d.ts",
+      "import": "./dist/runtime/traits/index.js"
+    },
+    "./tenancy": {
+      "types": "./dist/runtime/tenancy/index.d.ts",
+      "import": "./dist/runtime/tenancy/index.js"
+    },
+    "./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/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 && 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",
@@ -70,6 +118,8 @@
     "format:check": "oxfmt --check",
     "layers-check": "bun ./scripts/layers-check.ts",
     "core-purity": "bun ./scripts/core-purity.ts",
+    "okid-drift": "bun ./scripts/okid-drift.ts",
+    "test:runtimes": "bun ./scripts/runtimes.ts",
     "docs:check": "bun ./scripts/docs-check.ts",
     "readme:check": "bun ./scripts/readme-check.ts",
     "compiler-api": "bun ./scripts/compiler-api.ts",
@@ -81,7 +131,7 @@
     "test:postgres": "bun ./scripts/postgres-suite.ts",
     "test:tarball": "bun ./scripts/tarball-smoke.ts",
     "verify": "bun ./scripts/verify.ts",
-    "check": "bun run format:check && bun run lint && bun run typecheck && bun run editor-check && bun run type-cost && bun run layers-check && bun run core-purity && bun run docs:check && bun run readme:check && bun run compiler-api && bun run bundle-purity && bun run build && bun test && bun run publint && bun run attw && bun run size",
+    "check": "bun run format:check && bun run lint && bun run typecheck && bun run editor-check && bun run type-cost && bun run layers-check && bun run core-purity && bun run okid-drift && bun run docs:check && bun run readme:check && bun run compiler-api && bun run bundle-purity && bun run build && bun test && bun run test:runtimes && bun run publint && bun run attw && bun run size",
     "bump": "bun ./scripts/bump-version.ts",
     "release-check": "bun ./scripts/release-check.ts",
     "db:up": "bun ./packages/harness/src/docker-cli.ts up",
@@ -108,14 +158,21 @@
   },
   "peerDependencies": {
     "@electric-sql/pglite": "^0.5.8",
+    "pg": "^8.16.0",
     "postgres": "^3.4.9"
   },
   "peerDependenciesMeta": {
     "@electric-sql/pglite": {
       "optional": true
     },
+    "pg": {
+      "optional": true
+    },
     "postgres": {
       "optional": true
     }
+  },
+  "engines": {
+    "node": ">=22"
   }
 }