okmodel 0.0.0 → 0.1.1

package/README.md

@@ -1 +1,246 @@
-okmodel — work in progress
+# OKModel
+
+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.1.1. Apache-2.0.
+
+## Contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+  - [Configure](#configure)
+  - [Schema](#schema)
+  - [Push](#push)
+  - [Reviewed migrations](#reviewed-migrations)
+  - [One client](#one-client)
+  - [Insert](#insert)
+  - [Find](#find)
+  - [Errors](#errors)
+  - [Close](#close)
+- [Commands](#commands)
+- [Roadmap](#roadmap)
+- [Size](#size)
+- [Docs](#docs)
+
+## Install
+
+Install okmodel and the postgres.js driver.
+
+```sh
+bun add okmodel postgres
+```
+
+PGlite is the in-process driver.
+
+```sh
+bun add okmodel @electric-sql/pglite
+```
+
+okmodel has no runtime dependencies. The driver is a peer.
+
+## Quickstart
+
+`DATABASE_URL` is a direct Postgres URL, not a pooler. The client, insert, find, and error blocks are one script, `run.ts`. `script.ts` is the `await using` form. The last block calls `db.close()`.
+
+### Configure
+
+Point the CLI at the schema and at that URL.
+
+`okmodel.config.ts`:
+
+```ts
+import { defineConfig } from "okmodel/migrate";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) {
+  throw new Error("DATABASE_URL is not set");
+}
+
+export default defineConfig({
+  schema: "./schema.ts",
+  database: url,
+});
+```
+
+### Schema
+
+`t.identity()` is the primary key. An insert omits the id, and the row that comes back carries it. Identity ids come back as strings by default. `t.identity({ as: "number" })` returns numbers. Push and reviewed migrations are two ways to do the same job: pick one per database.
+
+Tested on PostgreSQL 15 to 18.
+
+`schema.ts`:
+
+```ts
+import { one, schema, table, t } from "okmodel/pg";
+
+const authors = table("authors", {
+  id: t.identity(),
+  name: t.text().unique(),
+});
+
+const notes = table(
+  "notes",
+  {
+    id: t.identity(),
+    title: t.text(),
+    authorId: t.bigint().references("authors", { columns: ["id"] }),
+  },
+  { relations: { author: one("authors") } },
+);
+
+const tables = [authors, notes];
+
+export default schema({ tables });
+```
+
+### Push
+
+Create the tables with push, which is allowed because this target is not protected.
+
+```sh
+bunx okm push
+```
+
+A protected target refuses push. Production settings are in the [production checklist](https://github.com/omqkhafi/okmodel/blob/main/docs/production.md).
+
+### Reviewed migrations
+
+Generate writes a SQL file and `.okm`, and apply runs that file later so you can read the migration first.
+
+```sh
+bunx okm generate init
+bunx okm migrate apply
+```
+
+### One client
+
+This module is cached, so the process has one client.
+
+`db.ts`:
+
+```ts
+import { connect } from "okmodel/pg/postgresjs";
+
+import schema from "./schema.ts";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) throw new Error("DATABASE_URL is not set");
+
+export const db = connect(url, { schema });
+```
+
+### Insert
+
+Insert an author, then a note that points at the author's id.
+
+```ts
+import { db } from "./db.ts";
+
+const author = await db.authors.insert({ name: "Ada" });
+const note = await db.notes.insert({
+  title: "hello",
+  authorId: author.id,
+});
+if (author.name !== "Ada" || note.title !== "hello" || author.id.length === 0) {
+  throw new Error("insert did not return the row");
+}
+```
+
+### Find
+
+Load that note and its author by the id the insert returned.
+
+```ts
+const found = await db.notes.find({
+  where: { id: note.id },
+  limit: 5,
+  include: { author: true },
+});
+const row = found[0];
+if (row?.title !== "hello" || row.author?.name !== "Ada") {
+  throw new Error("find did not return the note and its author");
+}
+```
+
+### Errors
+
+`safe` returns the `OkmError` instead of throwing when the author name is already used.
+
+```ts
+import { OkmError, safe } from "okmodel";
+
+const duplicate = await safe(db.authors.insert({ name: "Ada" }));
+if (duplicate.ok || !(duplicate.error instanceof OkmError) || duplicate.error.kind !== "unique") {
+  throw new Error("expected an OkmError of kind unique");
+}
+```
+
+### Close
+
+A script exits when its queries finish. It does not need `close()` for that. `await using` closes the pool at the end of the block. `db.close()` is that call on a line you choose. A server keeps the client and its connections. A pool opened with `ssl` still waits out the driver's 30 second idle timer.
+
+`script.ts`:
+
+```ts
+import { connect } from "okmodel/pg/postgresjs";
+
+import schema from "./schema.ts";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) throw new Error("DATABASE_URL is not set");
+
+await using db = connect(url, { schema });
+const author = await db.authors.insert({ name: "Lin" });
+if (author.name !== "Lin" || author.id.length === 0) {
+  throw new Error("insert did not return the row");
+}
+```
+
+```ts
+await db.close();
+```
+
+## Commands
+
+| Command                   | What it does                                                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `okm build`               | Validates the schema and writes `.okm/` (catalog, hash, emitted row types). `okm generate` writes those files too.           |
+| `okm check`               | Reports a stale `renamedFrom` and a table file the schema does not import.                                                   |
+| `okm generate [name]`     | Writes a SQL migration and `.okm/`. The name defaults to `migration`. Prints `no changes` when the schema matches.           |
+| `okm dev`                 | Uses a target named `dev`, or creates a PGlite database in `.okm/dev-db`. It does not apply migrations or write the catalog. |
+| `okm push`                | Applies the schema directly. Refused when the target is protected.                                                           |
+| `okm migrate plan <name>` | Prints the plan and its class. The name is required.                                                                         |
+| `okm migrate apply`       | Replays migration files on the database.                                                                                     |
+| `okm migrate status`      | Prints version, catalog hash, and state for each target.                                                                     |
+| `okm --version`           | Prints the package version.                                                                                                  |
+
+`okmodel` and `okm` are the same command.
+
+## Roadmap
+
+- [x] 0.1 — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
+- [ ] 0.2 — Hidden and sensitive fields, validation, traits, tenancy, archive and restore, richer relations, presets, transactions, and operators for JSON, arrays, ranges, and search.
+- [ ] 0.3 — Extensions, domains, functions, triggers, views, roles, and grants.
+- [ ] 0.4 — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
+- [ ] 0.5 — A primary with replicas, read routing, and a reference app.
+
+`okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
+
+Each limit, with the version that lifts it, is in [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
+
+## Size
+
+Measured on this release.
+
+|                                   | Minified |   Gzip | Cold import |
+| --------------------------------- | -------: | -----: | ----------: |
+| Runtime entry                     |    5,525 |  2,042 |    1.758 ms |
+| App startup (10 tables, one find) |   77,537 | 25,625 |    9.922 ms |
+
+The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
+
+## Docs
+
+- [Quickstart](https://github.com/omqkhafi/okmodel/blob/main/docs/quickstart.md)
+- [Production checklist](https://github.com/omqkhafi/okmodel/blob/main/docs/production.md)
+- [Known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md)

package/dist/adapters/capabilities.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Driver capability registry.
+ *
+ * The flags are data (spec §4). A helper reads them. Spec section 21 has no
+ * OKM11xx for a driver that lacks a flag: OKM1110 is the engine-version gate,
+ * and OKM1801 is a dialect mismatch. This module does not invent a code and
+ * does not throw for a missing flag.
+ */
+import type { DriverCapabilities } from "../contracts/driver.js";
+/** Capability names a caller can read. */
+export declare const CAPABILITY_NAMES: readonly ["transactions", "stream", "listen", "cancel", "prepared", "describe"];
+/** One name in {@link DriverCapabilities}. */
+export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
+/**
+ * postgres.js execution flags.
+ *
+ * Interactive transactions, streaming, listen, cancel, and describe.
+ * Statements use the unnamed extended protocol so a plain execute is one
+ * round trip. Named prepares are a later opt-in.
+ */
+export declare const POSTGRESJS_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: true;
+    readonly listen: true;
+    readonly cancel: true;
+    readonly prepared: "unnamed";
+    readonly describe: true;
+};
+/**
+ * PGlite execution flags.
+ *
+ * A pool of one with interactive transactions, listen, and describe.
+ * `cancel` is false: an in-flight statement cannot be aborted, and
+ * `statement_timeout` is not enforced.
+ */
+export declare const PGLITE_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: false;
+    readonly listen: true;
+    readonly cancel: false;
+    readonly prepared: "unnamed";
+    readonly describe: true;
+};
+/**
+ * Reads one capability flag.
+ *
+ * @param flags - Declared capabilities
+ * @param name - Flag name
+ * @returns The flag value
+ */
+export declare function readCapability<Name extends CapabilityName>(flags: DriverCapabilities, name: Name): DriverCapabilities[Name];
+/**
+ * Reports whether a boolean capability is set.
+ *
+ * `transactions` and `prepared` are not boolean. Use {@link readCapability}
+ * for those.
+ *
+ * @param flags - Declared capabilities
+ * @param name - `stream`, `listen`, `cancel`, or `describe`
+ * @returns The flag
+ */
+export declare function hasCapability(flags: DriverCapabilities, name: "stream" | "listen" | "cancel" | "describe"): boolean;

package/dist/adapters/error.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Errors an adapter throws.
+ *
+ * Database failures stay {@link DriverError}. The Postgres dialect maps that
+ * to {@link OkmError}. Acquire exhaustion is OKM1846 on {@link OkmError}:
+ * that code is the pool's own deadline (spec §15.2), not a SQLSTATE.
+ */
+import { OkmError } from "../contracts/error.js";
+import type { DriverErrorFields, DriverFailureKind } from "../contracts/driver.js";
+/**
+ * A driver failure normalised to the contract fields.
+ *
+ * `batchIndex` is `null` except on a failed batch statement, where it is that
+ * statement's index. A commit failure (a deferred constraint) stays `null`.
+ */
+export declare class DriverError extends Error {
+    /** SQLSTATE, when the server sent one. */
+    readonly sqlstate: string | undefined;
+    /** Constraint name, when the server sent one. */
+    readonly constraint: string | undefined;
+    /** Table name, when the server sent one. */
+    readonly table: string | undefined;
+    /** Column name, when the server sent one. */
+    readonly column: string | undefined;
+    /** Server detail line. */
+    readonly detail: string | undefined;
+    /** Driver or server error underneath. */
+    readonly cause: unknown;
+    /** Statement index inside a batch, or `null` when this is not that case. */
+    readonly batchIndex: number | null;
+    /** `timeout` or `cancelled`. Absent on a database error. */
+    readonly kind: DriverFailureKind | undefined;
+    /**
+     * @param message - Error text
+     * @param fields - Normalised fields
+     */
+    constructor(message: string, fields?: DriverErrorFields);
+    /**
+     * Same error with a batch index.
+     *
+     * @param batchIndex - Statement index, or `null` at commit
+     * @returns A new error when the index differs
+     */
+    at(batchIndex: number | null): DriverError;
+}
+/**
+ * An abort from the caller's `signal` (D124).
+ *
+ * @param cause - Underlying error, when one exists
+ * @returns Kind `cancelled`
+ */
+export declare function cancelled(cause?: unknown): DriverError;
+/**
+ * A statement, transaction, or batch deadline (D124).
+ *
+ * @param cause - Underlying error, when one exists
+ * @returns Kind `timeout`
+ */
+export declare function timedOut(cause?: unknown): DriverError;
+/**
+ * A commit was sent and its result never arrived (OKM1401 once mapped).
+ *
+ * @param cause - Underlying error, when one exists
+ * @returns Kind `outcome_unknown`, batch index `null`
+ */
+export declare function outcomeUnknown(cause?: unknown): DriverError;
+/**
+ * The pool did not hand out a connection within `timeouts.acquire`.
+ *
+ * @returns OKM1846, kind `timeout`
+ */
+export declare function acquireTimeout(): OkmError;
+/**
+ * Reads a string field from an unknown error object.
+ *
+ * @param error - Caught value
+ * @param key - Field name
+ * @returns The string, or `undefined`
+ */
+export declare function errorField(error: unknown, key: string): string | undefined;
+/**
+ * Maps a driver exception into {@link DriverError}.
+ *
+ * {@link OkmError} and {@link DriverError} pass through. A batch index on an
+ * existing {@link DriverError} is applied with {@link DriverError.at}.
+ *
+ * @param error - Caught value
+ * @param batchIndex - Statement index, or `null` at commit
+ * @returns A normalised error
+ */
+export declare function mapDriverError(error: unknown, batchIndex?: number | null): unknown;

package/dist/adapters/failure.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Driver-error constructors, loaded on the first failure.
+ *
+ * A successful `execute` does not import {@link import("./error.js")}.
+ */
+type ErrorModule = typeof import("./error.js");
+/**
+ * Loads driver-error constructors once.
+ *
+ * @returns The error module
+ */
+export declare function driverErrors(): Promise<ErrorModule>;
+/**
+ * Rejects with a closed-pool {@link import("./error.js").DriverError}.
+ *
+ * @param message - Error text
+ * @returns A rejected promise
+ */
+export declare function rejectClosed(message?: string): Promise<never>;
+/**
+ * Rejects with kind `cancelled`.
+ *
+ * @returns A rejected promise
+ */
+export declare function rejectCancelled(): Promise<never>;
+/**
+ * Rejects with kind `timeout`.
+ *
+ * @returns A rejected promise
+ */
+export declare function rejectTimedOut(): Promise<never>;
+/**
+ * Maps a caught driver exception.
+ *
+ * @param error - Caught value
+ * @returns A normalised error
+ */
+export declare function mapFailure(error: unknown): Promise<unknown>;
+export {};

package/dist/adapters/pg/batch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Atomic batch for an interactive connection.
+ *
+ * Statements run one at a time. A failure rolls the unit back. Inside an open
+ * transaction the unit is a savepoint and the outer transaction stays open
+ * (D124). A timeout stays kind `timeout`. An abort stays kind `cancelled`.
+ */
+import type { ExecuteResult, Statement, WireValue } from "../../contracts/driver.js";
+import type { Watch } from "./call.js";
+/** A connection that can run the batch protocol. */
+export type BatchSession = {
+    /** This driver can abort an in-flight statement. */
+    readonly canCancel: boolean;
+    /**
+     * Runs one statement.
+     *
+     * @param text - SQL
+     * @param params - Wire parameters
+     * @param watch - Shared deadline for the batch, when there is one
+     * @returns The statement result
+     */
+    query(text: string, params: readonly WireValue[] | undefined, watch: Watch | undefined): Promise<ExecuteResult>;
+    /** Reports whether a transaction is open on this connection. */
+    inTransaction(): boolean;
+    /** Forgets a transaction after a rollback that did not complete. */
+    abandon(): void;
+};
+/**
+ * Runs statements as one atomic unit.
+ *
+ * @param session - Connection to use
+ * @param statements - Statements in order
+ * @param watch - Deadline for the whole batch
+ * @returns One result per statement
+ */
+export declare function runAtomicBatch(session: BatchSession, statements: readonly Statement[], watch: Watch | undefined): Promise<readonly ExecuteResult[]>;

package/dist/adapters/pg/call.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One deadline for a call.
+ *
+ * Created only when the caller passed `signal` or `timeout`. A plain execute
+ * does not allocate one.
+ */
+import type { DriverFailureKind, ExecuteOptions } from "../../contracts/driver.js";
+/** A signal plus the reason it aborted. */
+export type Watch = {
+    /** Aborts on the caller's signal or on the deadline. */
+    readonly signal: AbortSignal;
+    /** Stops the timer and drops the caller's listener. */
+    finish(): void;
+    /**
+     * Why {@link signal} aborted.
+     *
+     * `undefined` until it aborts.
+     */
+    reason(): DriverFailureKind | undefined;
+};
+/**
+ * Reports whether `options` carries a signal or a timeout.
+ *
+ * @param options - Per-call options
+ * @returns True when a {@link Watch} is required
+ */
+export declare function needsWatch(options: ExecuteOptions | undefined): boolean;
+/**
+ * Next transaction depth after one statement.
+ *
+ * Only a whole command matches, so `ROLLBACK TO SAVEPOINT` stays inside the
+ * transaction. Kept here so a read does not load the batch runner.
+ *
+ * @param depth - Depth before the statement
+ * @param text - Statement text
+ * @returns Depth after a successful statement
+ */
+export declare function nextTransactionDepth(depth: number, text: string): number;
+/**
+ * Opens a watch for one call.
+ *
+ * The caller has already rejected a pre-aborted signal and a non-positive
+ * timeout.
+ *
+ * @param options - Options that include a signal or a timeout
+ * @returns The watch. The caller must {@link Watch.finish} it
+ */
+export declare function openWatch(options: ExecuteOptions): Watch;
+/**
+ * Runs `fn` with a watch when the caller set a signal or a timeout.
+ *
+ * A plain call passes `undefined` and returns `fn`'s promise unchanged.
+ *
+ * @param closed - The pool has been closed
+ * @param options - Per-call options
+ * @param fn - Work that receives the watch
+ * @returns Whatever `fn` returns
+ */
+export declare function runCall<T>(closed: boolean, options: ExecuteOptions | undefined, fn: (watch: Watch | undefined) => Promise<T>): Promise<T>;

package/dist/adapters/pg/pglite.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PGlite adapter (`okmodel/pg/pglite`).
+ *
+ * One database is a pool of one. `cancel` is false: a statement already
+ * running cannot be aborted. `@electric-sql/pglite` is a peer of this entry.
+ */
+import type { DriverPool, DriverPoolConfig } from "../../contracts/driver.js";
+export { hasCapability, PGLITE_CAPABILITIES as capabilities, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** Options for {@link open}. The pool size is always one. */
+export type PgliteConfig = DriverPoolConfig & {
+    /** Data directory. `memory://` when omitted. */
+    readonly dataDir?: string;
+};
+/**
+ * Opens a PGlite pool of one.
+ *
+ * @param config - Data directory and acquire timeout. `max` is ignored
+ * @returns The pool
+ */
+export declare function open(config?: PgliteConfig): Promise<DriverPool>;

package/dist/adapters/pg/postgres-extra.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pool operations a read does not use: checkout, describe, and stream.
+ *
+ * Loaded on the first reserve, batch, describe, or stream.
+ */
+import type { Sql } from "postgres";
+import type { DescribeResult, DriverConnection, WireValue } from "../../contracts/driver.js";
+import { type Canceller, type Counters, type NoticeBuffer } from "./postgresjs.js";
+/** State `open` shares with a checkout. */
+export type HeldPool = {
+    readonly sql: Sql;
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly isClosed: () => boolean;
+    readonly notices: NoticeBuffer;
+    readonly named: boolean;
+    readonly poolInflight: Set<Canceller>;
+};
+/**
+ * Checks out one connection and clears it on release.
+ *
+ * @param pool - The open pool
+ * @returns A connection the caller must release
+ */
+export declare function checkout(pool: HeldPool): Promise<DriverConnection>;
+/**
+ * Describes a statement.
+ *
+ * @param sql - Pool client
+ * @param text - SQL
+ * @param params - Wire parameters
+ * @returns Column names and the parameter count
+ */
+export declare function describe(sql: Sql, text: string, params?: readonly WireValue[]): Promise<DescribeResult>;
+/**
+ * Yields cursor chunks.
+ *
+ * @param sql - Pool client
+ * @param text - SQL
+ * @param params - Wire parameters
+ * @returns Chunks of wire rows
+ */
+export declare function stream(sql: Sql, text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;