okmodel 0.0.0 → 0.1.0

package/README.md

@@ -1 +1,44 @@
-okmodel — work in progress
+# OKModel
+
+Catalog-first TypeScript ORM for PostgreSQL. Version 0.1.
+
+## Install
+
+```sh
+bun add okmodel
+```
+
+postgres.js and PGlite are optional peers. Install the one you connect with.
+
+```sh
+bun add postgres
+# or
+bun add @electric-sql/pglite
+```
+
+The repository docs have the [quickstart](docs/quickstart.md), the [production checklist](docs/production.md), and the [known limits](docs/known-limits.md). Those files are not in the npm tarball.
+
+```ts
+import { schema, table, t } from "okmodel/pg";
+import { defineConfig } from "okmodel/migrate";
+
+export const notes = table("notes", {
+  id: t.uuid(),
+  title: t.text(),
+});
+
+export const app = schema({ tables: [notes] });
+
+export default defineConfig({ schema: "./schema.ts" });
+```
+
+```sh
+bunx okm build
+bunx okm generate init
+```
+
+`table` and `index` for a schema come from `okmodel/pg`. Stable, experimental, and internal exports are listed in `tests/fixtures/api-surface.json` in the repository. `okmodel/internal` has no stability promise.
+
+A production target sets `protected: true`. A production `connect` sets `requireMeta: true`. `prepared: "named"` is not for a transaction-mode pooler.
+
+Apache-2.0.

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[])[]>;

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

@@ -0,0 +1,95 @@
+/**
+ * postgres.js adapter (`okmodel/pg/postgresjs`).
+ *
+ * One pool per `open` call. Plain `execute` uses the driver's pool directly,
+ * so it does not take an extra checkout. `reserve` checks out one connection
+ * and clears session state on release. `postgres` is a peer of this entry.
+ */
+import { type Sql } from "postgres";
+import type { DriverPool, DriverPoolConfig, ExecuteResult, Notice, WireValue } from "../../contracts/driver.js";
+import type { BatchSession } from "./batch.js";
+import { type Watch } from "./call.js";
+export { POSTGRESJS_CAPABILITIES as capabilities, hasCapability, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** Options for {@link open}. */
+export type PostgresJsConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * Named prepared statements, or the unnamed protocol.
+     *
+     * Unnamed is the default. It stays valid behind a pooler in transaction mode.
+     * `prepared: "named"` is not for transaction-mode poolers.
+     */
+    readonly prepared?: "named" | "unnamed";
+    /** Session search path for every connection in the pool. */
+    readonly searchPath?: string;
+    /** TLS mode passed to postgres.js. */
+    readonly ssl?: boolean | "require" | "allow" | "prefer" | "verify-full" | object;
+};
+/** Something an in-flight query can abort. */
+export type Canceller = {
+    cancel(): void;
+};
+/** Pool occupancy. Shared by execute and by a reserved connection. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/** Notice slice shared by the pool. */
+export type NoticeBuffer = {
+    start(): number;
+    since(start: number): readonly Notice[];
+};
+/**
+ * Opens a postgres.js pool for one endpoint.
+ *
+ * @param config - URL, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: PostgresJsConfig): DriverPool;
+export declare class PgSession implements BatchSession {
+    readonly canCancel = true;
+    private transactionDepth;
+    private readonly sql;
+    private readonly counters;
+    private readonly scope;
+    private readonly local;
+    private readonly isClosed;
+    private readonly shared;
+    private readonly notices;
+    private readonly named;
+    /**
+     * @param sql - Root client or a reserved connection
+     * @param counters - Pool counters
+     * @param scope - Pool executes are not checkouts
+     * @param local - In-flight queries this connection cancels
+     * @param isClosed - Pool closed flag
+     * @param shared - Pool-wide in-flight set for a reserved connection
+     * @param notices - Notice buffer shared by the pool
+     */
+    constructor(sql: Sql, counters: Counters, scope: "pool" | "reserved", local: Set<Canceller>, isClosed: () => boolean, shared: Set<Canceller> | undefined, notices: NoticeBuffer, named: boolean);
+    /** @inheritdoc */
+    query(text: string, params: readonly WireValue[] | undefined, watch: Watch | undefined): Promise<ExecuteResult>;
+    /** @inheritdoc */
+    inTransaction(): boolean;
+    /** @inheritdoc */
+    abandon(): void;
+    /**
+     * Open transaction depth.
+     *
+     * @returns The depth. Zero means no transaction
+     */
+    depth(): number;
+    /** Aborts in-flight statements on this connection. */
+    cancel(): void;
+    private note;
+    private enter;
+    private leave;
+    private track;
+    private untrack;
+    private watched;
+    private finishWatched;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Turns a driver result into wire rows.
+ *
+ * The empty notice list is shared. A call that received none does not allocate one.
+ */
+import type { ExecuteResult, Notice, WireValue } from "../../contracts/driver.js";
+/** Shared notice list for a statement that received none. */
+export declare const EMPTY_NOTICES: readonly Notice[];
+/**
+ * Reads one cell as wire text.
+ *
+ * @param value - A driver cell
+ * @returns Wire text, or `null` for SQL NULL
+ */
+export declare function cell(value: unknown): WireValue;
+/**
+ * Reads rows as arrays of wire text.
+ *
+ * @param value - A driver result, or its row list
+ * @returns Wire rows
+ */
+export declare function rowsFrom(value: unknown): WireValue[][];
+/**
+ * Builds an {@link ExecuteResult}.
+ *
+ * @param value - A driver result
+ * @param notices - Notices observed during the call
+ * @returns Rows, count, and notices
+ */
+export declare function resultFrom(value: unknown, notices: readonly Notice[]): ExecuteResult;

package/dist/contracts/catalog/build.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Assembles a catalog document.
+ *
+ * Parsing and serialising stay in the document module. `schema()` needs this
+ * check and not the parser.
+ */
+import { type Catalog, type CatalogObject } from "./types.js";
+/**
+ * Checks a set of objects and returns them in identity-key order.
+ *
+ * Duplicate identities are OKM1023. A foreign key whose target is missing is
+ * OKM1021. A dependency cycle is OKM1026. A self-edge or a missing target is
+ * OKM1020.
+ *
+ * @param objects - Built objects, in any order
+ * @returns A catalog document
+ */
+export declare function catalog(objects: readonly CatalogObject[]): Catalog;

package/dist/contracts/catalog/document.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Catalog documents.
+ *
+ * `catalog` checks identity, foreign keys, and cycles, then stores objects in
+ * identity-key order. The serialized form is the canonical JSON of that
+ * document, templates included. The hash is SHA-256 of those bytes.
+ */
+import { catalog } from "./build.js";
+import type { Catalog, CatalogObject, Namespace, ObjectRef } from "./types.js";
+export { catalog };
+/**
+ * Create order for a catalog.
+ *
+ * Ties break by identity key.
+ *
+ * @param source - Catalog document
+ * @returns Dependencies first
+ */
+export declare function creationOrder(source: Catalog): readonly CatalogObject[];
+/**
+ * Renames a column without renaming constraints or indexes.
+ *
+ * Column lists and edges that pointed at the old column move to the new name.
+ * `nameKey` and the stored constraint or index name stay as they were.
+ *
+ * @param source - Catalog document
+ * @param change - Parent table, current column name, and the new name
+ * @returns A new catalog
+ */
+export declare function renameColumn(source: Catalog, change: {
+    readonly parent: ObjectRef;
+    readonly from: string;
+    readonly to: string;
+}): Catalog;
+/**
+ * Renames a table without renaming its constraints or indexes.
+ *
+ * Column, index, and constraint parents move to the new name. Expression text
+ * that names the table is rewritten. Constraint and index names stay.
+ *
+ * @param source - Catalog document
+ * @param change - Namespace, current table name, and the new name
+ * @returns A new catalog
+ */
+export declare function renameTable(source: Catalog, change: {
+    readonly namespace: Namespace;
+    readonly from: string;
+    readonly to: string;
+}): Catalog;
+export declare function serializeCatalog(source: Catalog): string;
+/**
+ * SHA-256 of {@link serializeCatalog}.
+ *
+ * The hash covers the normalised structure. It does not cover a separate
+ * authoring document.
+ *
+ * @param source - Catalog document
+ * @returns Lowercase hex digest
+ */
+export declare function catalogHash(source: Catalog): string;
+/**
+ * Loads a build artifact without validating objects.
+ *
+ * `okm build` already validated the catalog. Production startup checks the
+ * stored hash and the version, then trusts the objects (D133). `okm check`
+ * and dev keep {@link parseCatalog}.
+ *
+ * @param text - Canonical catalog JSON
+ * @param hash - SHA-256 of `text`, stored beside the artifact
+ * @returns The catalog document
+ */
+export declare function loadTrustedCatalog(text: string, hash: string): Catalog;
+/**
+ * Reads canonical catalog JSON.
+ *
+ * @param text - Serialized catalog
+ * @returns A checked catalog
+ */
+export declare function parseCatalog(text: string): Catalog;

package/dist/contracts/catalog/enum.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Enum catalog objects.
+ *
+ * Kind `type`, identity `(namespace, name)`. The definition is the ordered
+ * label list and nothing else: domains are not catalog objects.
+ */
+import type { Namespace, ObjectIdentity, Owner, Provenance, TypeObject } from "./types.js";
+/** Input for {@link enumType}. */
+export type EnumTypeInput = {
+    readonly namespace: Namespace;
+    readonly name: string;
+    /** Labels in stored order. The order is part of the catalog hash. */
+    readonly labels: readonly string[];
+    readonly owner?: Owner;
+    readonly provenance: Provenance;
+    readonly dependencies?: readonly ObjectIdentity[];
+};
+/**
+ * Builds an enum type object.
+ *
+ * Labels are copied in the order given. An empty list, an empty label, or a
+ * repeated label is OKM1020.
+ *
+ * @param input - Namespace, name, and ordered labels
+ * @returns A type envelope
+ */
+export declare function enumType(input: EnumTypeInput): TypeObject;
+/**
+ * Reports whether two label lists are the same text in the same order.
+ *
+ * @param left - First list
+ * @param right - Second list
+ * @returns `true` when every position matches
+ */
+export declare function sameEnumLabels(left: readonly string[], right: readonly string[]): boolean;