okmodel 0.0.0 → 0.1.1

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

@@ -0,0 +1,7 @@
+/**
+ * Public entry for `okmodel/migrate`.
+ *
+ * `defineConfig` and its types. The CLI imports planning and apply helpers
+ * from their modules, so those names are not exported.
+ */
+export { defineConfig, type MigrateConfig, type TargetInput } from "./config.js";

package/dist/tooling/migrate/index.js

@@ -0,0 +1,7 @@
+// src/tooling/migrate/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};

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

@@ -0,0 +1,76 @@
+/**
+ * Diffs two catalogs into an ordered, classified plan.
+ *
+ * Renames are applied to a copy of the previous catalog before the diff, so
+ * a declared rename is not a drop and an add. An unexplained drop-and-add is
+ * OKM1530. The planner never prompts.
+ *
+ * Picklist and enum removals are expand `UPDATE`s plus a contract swap
+ * (D131). Those data steps are plain statements here. Batching them is P52.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { DeclaredRename } from "../../dialects/pg/declarations.js";
+import { type Replacement } from "./values.js";
+/** Expand, contract, or a step that is neither. */
+export type MigrationClass = "expand" | "contract" | "unclassified";
+/**
+ * One statement in a plan.
+ *
+ * `backfill` is data; P16B runs it as written. `transactional: false` marks a
+ * step that cannot share a transaction with a later use (`ALTER TYPE … ADD
+ * VALUE`, spec 19.2).
+ */
+export type PlanStep = {
+    readonly sql: string;
+    readonly class: MigrationClass;
+    readonly action: "ddl" | "backfill";
+    readonly lock: string;
+    readonly transactional: boolean;
+};
+/** A named plan and the class of its strictest step. */
+export type MigrationPlan = {
+    readonly name: string;
+    readonly class: MigrationClass;
+    readonly steps: readonly PlanStep[];
+};
+/** What the planner needs besides the two catalogs. */
+export type PlanRequest = {
+    readonly before: Catalog;
+    readonly after: Catalog;
+    readonly renames?: readonly DeclaredRename[];
+    readonly replacements?: readonly Replacement[];
+    readonly schema?: string;
+    /** Concrete schema written into the SQL. Identities stay logical. */
+    readonly name?: string;
+};
+/**
+ * Builds a plan from catalog `before` to catalog `after`.
+ *
+ * @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;
+/**
+ * Prints a plan. The text is SQL plus class comments, never TypeScript.
+ *
+ * @param plan - Plan from {@link planMigration}
+ * @returns The text `okm generate` writes and `okm migrate plan` prints
+ */
+export declare function formatPlan(plan: MigrationPlan): string;
+/**
+ * Reads a plan written by {@link formatPlan}.
+ *
+ * @param text - SQL file text
+ * @returns The plan. The header class is kept when the file has no steps
+ */
+export declare function parsePlan(text: string): MigrationPlan;
+/**
+ * Renames whose previous name is absent from the last snapshot.
+ *
+ * No snapshot means nothing is stale: there is no history to disagree with.
+ *
+ * @param previous - Last migration catalog, or `undefined` when there is none
+ * @param renames - Declarations on the current schema
+ * @returns Messages, empty when every rename still matches
+ */
+export declare function staleRenames(previous: Catalog | undefined, renames: readonly DeclaredRename[]): readonly string[];

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

@@ -0,0 +1,78 @@
+/**
+ * Target names, the aliasing guard, pooler refusal, and the protection policy.
+ *
+ * One function, {@link assertTargetPolicy}, is what every entry point calls.
+ * Protection is a property of the target. It is not read from `NODE_ENV`.
+ */
+import type { MigrateConfig } from "./config.js";
+/** An operation the policy table allows or blocks. */
+export type PolicyOperation = "plan" | "status" | "check" | "drift" | "verify" | "pull" | "catalog-export" | "inspect" | "expand" | "reference" | "provision" | "contract" | "unclassified" | "push" | "backfill" | "seed" | "history-repair" | "drop" | "rollback";
+/** Flags shared by commands that touch a target. */
+export type InvokeFlags = {
+    readonly target?: string;
+    readonly allowProtected: boolean;
+    readonly allowPooler: boolean;
+    readonly lockTimeoutMs?: number;
+    readonly statementTimeoutMs?: number;
+};
+/** A resolved migration target. The plan stores the name, not the URL. */
+export type TargetRecord = {
+    readonly name: string;
+    readonly url: string;
+    readonly protected: boolean;
+    readonly host: string;
+    readonly port: string;
+    readonly database: string;
+};
+/**
+ * Refuses an operation the target's protection does not allow.
+ *
+ * `--allow-protected` is per invocation. It does not lift `drop` or `rollback`.
+ * `provision` is allowed here; the caller still refuses a target that is not empty.
+ *
+ * @param target - Name and protection flag
+ * @param operation - What the entry point is about to do
+ * @param allowProtected - The invocation passed `--allow-protected`
+ */
+export declare function assertTargetPolicy(target: {
+    readonly name: string;
+    readonly protected: boolean;
+}, operation: PolicyOperation, allowProtected?: boolean): void;
+/**
+ * Fails when targets on one host, port, and database disagree about protection.
+ *
+ * Two unprotected targets may share a database. The comparison ignores schema.
+ *
+ * @param targets - Resolved targets
+ */
+export declare function assertTargetAlias(targets: readonly TargetRecord[]): void;
+/**
+ * Refuses a known pooler URL.
+ *
+ * Apply needs one session for the advisory lock. A transaction-mode pooler
+ * does not keep that session. `--allow-pooler` is the override.
+ *
+ * @param url - Target URL
+ * @param allowPooler - The invocation opted in
+ */
+export declare function assertDirectConnection(url: string, allowPooler: boolean): void;
+/**
+ * Lists configured targets.
+ *
+ * `database` is the target named `default`. `targets` replaces it. Setting
+ * both is refused.
+ *
+ * @param config - Project config
+ * @returns Targets in name order
+ */
+export declare function listTargets(config: MigrateConfig): readonly TargetRecord[];
+/**
+ * Picks the target a command that must not guess will use.
+ *
+ * One configured target is that target. Several require `name` (OKM1853).
+ *
+ * @param config - Project config
+ * @param name - `--target`, when the command passed one
+ * @returns The target
+ */
+export declare function selectTarget(config: MigrateConfig, name: string | undefined): TargetRecord;

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

@@ -0,0 +1,69 @@
+/**
+ * `okm build`, `okm generate`, `okm check`, and `okm migrate plan`.
+ *
+ * Build writes the catalog it already validated. Check and dev read
+ * `.catalog`, which runs that validation. Generate writes SQL only.
+ */
+import { type DeclaredRename } from "../../dialects/pg/declarations.js";
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type MigrateConfig } from "./config.js";
+import { type MigrationPlan } from "./plan.js";
+/**
+ * Validates the schema and writes `.okm/`.
+ *
+ * @param cwd - Project directory
+ * @returns The output directory
+ */
+export declare function buildProject(cwd: string): Promise<string>;
+/**
+ * Plans the current schema against the latest snapshot and writes SQL.
+ *
+ * An empty plan writes nothing. The file is SQL, not TypeScript.
+ *
+ * @param cwd - Project directory
+ * @param name - Migration name
+ * @param flags - `--replace` values
+ * @returns The SQL path, or `undefined` when nothing changed
+ */
+export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<string | undefined>;
+/**
+ * Plans and returns the text. Nothing is written.
+ *
+ * @param cwd - Project directory
+ * @param name - Plan name
+ * @param flags - `--replace` values
+ * @returns The plan
+ */
+export declare function planProject(cwd: string, name: string, flags: readonly string[]): Promise<MigrationPlan>;
+/**
+ * Validates the schema, then reports stale renames and unlisted table files.
+ *
+ * @param cwd - Project directory
+ */
+export declare function checkProject(cwd: string): Promise<void>;
+/**
+ * Table files whose names do not appear in the schema module.
+ *
+ * @param schemaSource - Source text of the schema module
+ * @param fileNames - File names in the tables directory
+ * @returns Files `okm check` reports as OKM1024
+ */
+export declare function unlistedTableFiles(schemaSource: string, fileNames: readonly string[]): readonly string[];
+/**
+ * The catalogs `okm push` diffs, after stale renames are refused.
+ *
+ * @param cwd - Project directory
+ * @returns The previous snapshot, the current catalog, and declared renames
+ */
+export declare function projectHead(cwd: string): Promise<{
+    readonly previous: Catalog;
+    readonly catalog: Catalog;
+    readonly renames: readonly DeclaredRename[];
+}>;
+/**
+ * Loads `okmodel.config.ts`.
+ *
+ * @param cwd - Project directory
+ * @returns The config object
+ */
+export declare function loadConfig(cwd: string): Promise<MigrateConfig>;

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

@@ -0,0 +1,74 @@
+/**
+ * `okm migrate status`.
+ *
+ * One row per target: version, catalog hash, state, and a separate protected
+ * column. The state is current, behind by expand, behind by contract, ahead,
+ * or failed at a step.
+ */
+import type { MigrationClass } from "./plan.js";
+import type { StoredMigration } from "./files.js";
+import { type InvokeFlags } from "./policy.js";
+/** One status row. `protected` is its own column, not a state. */
+export type TargetStatus = {
+    readonly target: string;
+    readonly version: string;
+    readonly catalogHash: string;
+    readonly state: string;
+    readonly protected: boolean;
+};
+/** A checkpoint row the state function reads. */
+export type StatusHistory = {
+    readonly migrationId: string;
+    readonly stepIndex: number;
+    readonly class: MigrationClass;
+};
+/**
+ * Decides the status state from files and history.
+ *
+ * A partial migration is `failed at step`. History the files do not contain
+ * is `ahead`. Pending files are behind by expand, or by contract when any
+ * pending step is not expand.
+ *
+ * @param migrations - Files in apply order
+ * @param history - Checkpoint rows
+ * @param recorded - Head row in `okm_meta`, when the target has one
+ * @returns Version, catalog hash, and state
+ */
+export declare function describeStatus(migrations: readonly StoredMigration[], history: readonly StatusHistory[], recorded: {
+    readonly hash: string;
+    readonly version: string;
+} | undefined): {
+    readonly version: string;
+    readonly catalogHash: string;
+    readonly state: string;
+};
+/**
+ * Reads one target and returns its status row.
+ *
+ * @param input - URL, name, protection, and the local migrations
+ * @returns The row
+ */
+export declare function readTargetStatus(input: {
+    readonly url: string;
+    readonly target: string;
+    readonly protected: boolean;
+    readonly searchPath?: string;
+    readonly migrations: readonly StoredMigration[];
+}): Promise<TargetStatus>;
+/**
+ * Prints status for every target, or for `--target` when it is passed.
+ *
+ * Several targets do not require `--target` here: the command lists them.
+ *
+ * @param cwd - Project directory
+ * @param flags - Optional target name
+ * @returns Tab-separated text, with a header
+ */
+export declare function statusProject(cwd: string, flags: InvokeFlags): Promise<string>;
+/**
+ * Prints status rows.
+ *
+ * @param rows - One per target
+ * @returns Header plus one line per target
+ */
+export declare function formatStatus(rows: readonly TargetStatus[]): string;

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

@@ -0,0 +1,29 @@
+/**
+ * `--replace` flags for a removed picklist or enum value (D131).
+ *
+ * The schema never stores the replacement. The flag is the only place it
+ * exists, and a chain (a value replaced by another removed value) is rejected.
+ */
+/** One replacement. `to` is `null` when the flag says `=null`. */
+export type Replacement = {
+    readonly table: string;
+    readonly column: string;
+    readonly from: string;
+    readonly to: string | null;
+};
+/**
+ * Parses `table.column.old=new`.
+ *
+ * The split is the first `=` and the first two dots, so the old value may
+ * contain dots. `=null` is the null replacement.
+ *
+ * @param flag - One `--replace` value
+ * @returns The replacement
+ */
+export declare function parseReplace(flag: string): Replacement;
+/**
+ * Rejects a chain: a replacement whose new value is itself removed.
+ *
+ * @param replacements - Flags for one generate
+ */
+export declare function assertNoChains(replacements: readonly Replacement[]): void;

package/package.json

@@ -1,19 +1,121 @@
 {
   "name": "okmodel",
-  "version": "0.0.0",
-  "description": "A catalog-first TypeScript ORM, work in progress",
-  "type": "module",
+  "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.",
+  "keywords": [
+    "migrations",
+    "orm",
+    "postgres",
+    "postgresql",
+    "typescript"
+  ],
+  "homepage": "https://github.com/omqkhafi/okmodel",
+  "bugs": {
+    "url": "https://github.com/omqkhafi/okmodel/issues"
+  },
   "license": "Apache-2.0",
   "author": "Omq Khafi",
-  "repository": "https://github.com/omqkhafi/okmodel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omqkhafi/okmodel.git"
+  },
+  "bin": {
+    "okm": "./dist/okm.js",
+    "okmodel": "./dist/okmodel.js"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
-  "exports": "./dist/index.js",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/contracts/index.d.ts",
+      "import": "./dist/contracts/index.js"
+    },
+    "./pg": {
+      "types": "./dist/dialects/pg/index.d.ts",
+      "import": "./dist/dialects/pg/index.js"
+    },
+    "./internal": {
+      "types": "./dist/contracts/internal.d.ts",
+      "import": "./dist/contracts/internal.js"
+    },
+    "./migrate": {
+      "types": "./dist/tooling/migrate/index.d.ts",
+      "import": "./dist/tooling/migrate/index.js"
+    },
+    "./pg/postgresjs": {
+      "types": "./dist/runtime/pg/postgresjs.d.ts",
+      "import": "./dist/runtime/pg/postgresjs.js"
+    },
+    "./pg/pglite": {
+      "types": "./dist/runtime/pg/pglite.d.ts",
+      "import": "./dist/runtime/pg/pglite.js"
+    }
+  },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --format esm --target node",
-    "publish:dry": "bun publish --dry-run"
+    "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",
+    "driver-bench": "bun ./scripts/driver-bench.ts",
+    "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "editor-check": "bun ./scripts/editor-check.ts",
+    "type-cost": "bun ./scripts/type-cost.ts",
+    "lint": "oxlint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "layers-check": "bun ./scripts/layers-check.ts",
+    "core-purity": "bun ./scripts/core-purity.ts",
+    "docs:check": "bun ./scripts/docs-check.ts",
+    "readme:check": "bun ./scripts/readme-check.ts",
+    "compiler-api": "bun ./scripts/compiler-api.ts",
+    "publint": "publint run . --strict --pack bun",
+    "attw": "bun ./scripts/attw.ts",
+    "size": "bun ./scripts/size.ts",
+    "bundle-purity": "bun ./scripts/bundle-purity.ts",
+    "test": "bun test",
+    "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",
+    "bump": "bun ./scripts/bump-version.ts",
+    "release-check": "bun ./scripts/release-check.ts",
+    "db:up": "bun ./packages/harness/src/docker-cli.ts up",
+    "db:down": "bun ./packages/harness/src/docker-cli.ts down",
+    "bench": "bun ./packages/bench/src/run.ts",
+    "catalog-bench": "bun ./scripts/catalog-bench.ts",
+    "attest": "ATTEST_shouldFormat=0 ATTEST_updateSnapshots=0 bun ./packages/attest/src/measure.bench.ts",
+    "publish:dry": "bun publish --dry-run",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@electric-sql/pglite-socket": "^0.2.11",
+    "@types/bun": "^1.4.2",
+    "expect-type": "^1.4.0",
+    "fast-check": "^4.10.2",
+    "oxc-parser": "^0.152.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "^1.86.0",
+    "oxlint-tsgolint": "^7.0.2003",
+    "publint": "^0.3.24",
+    "typescript": "7",
+    "typescript-editor": "npm:typescript@6.0.3"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "postgres": "^3.4.9"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
   }
 }