okmodel 0.9.0 → 0.9.1

package/README.md

@@ -50,7 +50,15 @@ bun add okmodel @electric-sql/pglite
 bun add okmodel
 ```
 
-postgres.js is the default on Node and Bun. node-postgres is for a project that already has `pg`. PGlite runs Postgres in the process. The last line is Bun.sql, built into Bun, and it runs only there.
+postgres.js is the default on Node and Bun. node-postgres is for a project that already has `pg`. PGlite runs Postgres in the process. The last line is Bun.sql, built into Bun 1.4+, and it runs only there.
+
+Date and time columns need a `Temporal` global. Bun and Node 26 have it. On Node 22 and 24 assign a polyfill before those columns run (OKM1210 when it is missing). Example with `temporal-polyfill` (not part of the quickstart script):
+
+```typescript
+import { Temporal } from "temporal-polyfill";
+
+globalThis.Temporal = Temporal;
+```
 
 ## Quick start
 

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

@@ -4,14 +4,15 @@
  * Loaded on the first reserve, batch, stream, or dead connection. A read that
  * succeeds does not use it.
  */
-import type { ReservedSQL, SQL } from "./bun-sql.js";
+import type { SQL } from "./bun-sql.js";
 import type { DriverConnection, WireValue } from "../../contracts/driver.js";
 import { type HeldPool } from "./bunsql.js";
 /**
  * Checks out one connection and clears it on release.
  *
- * A connection that is gone is neither reset nor parked: Bun.sql has already
- * dropped it, and parking it would hand a dead session to the next caller.
+ * A connection that is gone is neither reset nor returned to the pool: Bun.sql
+ * has already dropped it. A reset or release failure after the caller's work
+ * finished destroys the handle and does not fail the call.
  *
  * @param held - The pool and its counters
  * @returns A connection the caller must release
@@ -45,13 +46,12 @@ export declare function drainClosed(sql: SQL): Promise<void>;
  * Subscribes on one pooled connection.
  *
  * @param sql - The pool
- * @param parked - Reserved handles to put back first
  * @param closed - The pool is closed
  * @param channel - Notify channel
  * @param onNotify - Payload callback
  * @returns Stops the subscription
  */
-export declare function listen(sql: SQL, parked: ReservedSQL[], closed: boolean, channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
+export declare function listen(sql: SQL, closed: boolean, channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
 export declare function checkout(held: HeldPool): Promise<DriverConnection & {
     evict(): void;
 }>;

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

@@ -36,7 +36,6 @@ export type BunSqlConfig = DriverPoolConfig & {
 /** What a checkout needs from the pool that opened it. */
 export type HeldPool = {
     readonly sql: SQL;
-    readonly parked: ReservedSQL[];
     readonly acquireMs: number | undefined;
     readonly counters: Counters;
     readonly notices: ReturnType<typeof noticeBuffer>;
@@ -70,4 +69,9 @@ export type Counters = {
 export declare function open(config: BunSqlConfig): DriverPool;
 export declare function send(sql: SQL, text: string, params: readonly WireValue[] | undefined): WireQuery;
 export declare function reserve(sql: SQL, acquireMs: number | undefined, counters: Counters): Promise<ReservedSQL>;
-export declare function park(parked: ReservedSQL[], reserved: ReservedSQL): Promise<void>;
+/**
+ * Returns a reserved handle to Bun's pool.
+ *
+ * @param reserved - The handle to release
+ */
+export declare function releaseReserved(reserved: ReservedSQL): Promise<void>;

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

@@ -55,7 +55,22 @@ export type Counters = {
  * @param source - Pool or client
  * @param handle - What to do with the error
  */
-export declare function armDriverError(source: object, handle?: () => void): void;
+export declare function armDriverError(source: object, handle?: (error?: unknown) => void): void;
+/**
+ * Records an idle or checked-out client error on the notice path (B-44).
+ *
+ * Does not throw. The pool has already dropped a dead idle client.
+ *
+ * @param notices - Pool notice buffer
+ * @param error - The `error` event value
+ */
+export declare function logClientError(notices: {
+    push(notice: {
+        severity: string;
+        message: string;
+        code?: string;
+    }): void;
+}, error: unknown): void;
 /**
  * Opens a node-postgres pool for one endpoint.
  *

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

@@ -29,23 +29,7 @@ export type HeldPool = {
  * @returns A connection the caller must release
  */
 export declare function checkout(pool: HeldPool, timeoutMs?: number): 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[])[]>;
 /**
  * Settles `run` when `ms` elapses, the reserved connection closes, or every
@@ -80,7 +64,9 @@ export declare function runBatch(pool: HeldPool, statements: readonly Statement[
  * @param sql - Reserved connection
  * @param lost - Set when that socket closes
  */
-export declare function watchReserved(sql: Sql, lost: Lost): void;
+declare function arm(sql: Sql, lost: Lost): void;
+/** @inheritdoc */
+export declare const watchReserved: typeof arm;
 type Gate = {
     enter(): void;
     leave(): void;

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

@@ -53,7 +53,8 @@ export declare function open(config: PostgresJsConfig): DriverPool;
 export declare class PgSession implements BatchSession {
     readonly canCancel = true;
     private transactionDepth;
-    private readonly sql;
+    /** Current client. A storm rebuild assigns a new pool client here. */
+    sql: Sql;
     private readonly counters;
     private readonly scope;
     private readonly local;

package/dist/contracts/driver.d.ts

@@ -162,8 +162,9 @@ export type DriverPoolConfig = {
     readonly max?: number;
     /**
      * Ceilings in milliseconds. An adapter reads `acquire`: it waits for a
-     * connection up to that long, then fails with OKM1846. Omitted means wait
-     * without a deadline. The other keys belong to the runtime.
+     * connection up to that long, then fails with OKM1846. Omitted means the
+     * adapter default (10 s on postgres.js and node-postgres). The other keys
+     * belong to the runtime.
      */
     readonly timeouts?: DriverTimeouts;
 };

package/dist/contracts/error.d.ts

@@ -31,7 +31,7 @@ export type ColumnCode = (typeof COLUMN_CODES)[number];
  * These are spec §21 codes. They are a type only, so the runtime entry does
  * not gain a second registry.
  */
-export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1125" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
+export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1125" | "OKM1126" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
 /** Kinds from spec §14, in category order. */
 export declare const ERROR_KINDS: readonly ["invalid", "not_null", "check", "foreign_key", "unique", "exclusion", "conflict", "not_found", "not_unique", "forbidden", "serialization", "deadlock", "lock_timeout", "timeout", "cancelled", "unavailable", "schema_drift", "driver", "read_only", "outcome_unknown"];
 /** One spec §14 kind. */

package/dist/dialects/pg/errors.d.ts

@@ -25,6 +25,8 @@ export type MapPostgresErrorSchema = {
 type SqlField = {
     readonly field: string;
     readonly sql: string;
+    /** When true, mapped errors for this table keep values out of `cause` (B-33). */
+    readonly sensitive?: boolean;
 };
 /** Options for {@link mapPostgresError}. */
 export type MapPostgresErrorOptions = {

package/dist/dialects/pg/ext/fuzzystrmatch.js

@@ -7,7 +7,7 @@ import {
 import {
   fnEqualsArg,
   fnDistance
-} from "../../../shared/xqacq37x.js";
+} from "../../../shared/zecrwdk9.js";
 
 // src/dialects/pg/ext/fuzzystrmatch.ts
 function fuzzystrmatch(options = {}) {

package/dist/dialects/pg/ext/hstore.js

@@ -3,7 +3,7 @@ import {
 } from "../../../shared/6f0z3hzh.js";
 import {
   opArg
-} from "../../../shared/xqacq37x.js";
+} from "../../../shared/zecrwdk9.js";
 import {
   usingIndex
 } from "../../../shared/h9811jjm.js";

package/dist/dialects/pg/ext/ltree.js

@@ -3,7 +3,7 @@ import {
 } from "../../../shared/6f0z3hzh.js";
 import {
   opArg
-} from "../../../shared/xqacq37x.js";
+} from "../../../shared/zecrwdk9.js";
 import {
   usingIndex
 } from "../../../shared/h9811jjm.js";

package/dist/dialects/pg/ext/pgcrypto.js

@@ -7,7 +7,7 @@ import {
 import {
   bareCall,
   digestEquals
-} from "../../../shared/xqacq37x.js";
+} from "../../../shared/zecrwdk9.js";
 
 // src/dialects/pg/ext/pgcrypto.ts
 function pgcrypto(options = {}) {

package/dist/dialects/pg/ext/unaccent.js

@@ -3,7 +3,7 @@ import {
 } from "../../../shared/6f0z3hzh.js";
 import {
   fnEqualsArg
-} from "../../../shared/xqacq37x.js";
+} from "../../../shared/zecrwdk9.js";
 
 // src/dialects/pg/ext/unaccent.ts
 function unaccent(options = {}) {

package/dist/dialects/pg/filters.d.ts

@@ -11,9 +11,9 @@ import type { FilterSpec, ParsedFilters } from "./table.js";
  * @param table - Table the filters belong to
  * @param relations - Relation calls stored on the table, when it has any
  * @param spec - Allow, sort, and relation fields
- * @param hiddenFields - `table.field` keys recorded while tables were defined
+ * @param isHidden - Whether `table.field` is hidden (own columns or related names)
  * @returns A parser for one request object
  */
-export declare function openFilters(table: string, relations: unknown, spec: FilterSpec, hiddenFields: ReadonlySet<string>): {
+export declare function openFilters(table: string, relations: unknown, spec: FilterSpec, isHidden: (table: string, field: string) => boolean): {
     parse(query: unknown): Promise<ParsedFilters>;
 };

package/dist/dialects/pg/fn/index.js

@@ -9,7 +9,7 @@ import {
   isFragmentParts,
   sqlExpression,
   identName
-} from "../../../shared/bsek72fg.js";
+} from "../../../shared/s5qe47a6.js";
 import {
   staticNamespace2
 } from "../../../shared/358zsv4r.js";

package/dist/dialects/pg/index.js

@@ -47,7 +47,7 @@ import {
 } from "../../shared/ecn8mfdq.js";
 import {
   schema2
-} from "../../shared/9dr2qnx7.js";
+} from "../../shared/qqm3ze6q.js";
 import {
   one2,
   many2,
@@ -68,7 +68,7 @@ import {
   table2,
   index2,
   sql2
-} from "../../shared/gcefca6p.js";
+} from "../../shared/f9t9g54z.js";
 import {
   ColumnBuilder2,
   required,
@@ -78,7 +78,7 @@ import {
   isFragmentParts,
   fragment2,
   ident2
-} from "../../shared/bsek72fg.js";
+} from "../../shared/s5qe47a6.js";
 import {
   domainType
 } from "../../shared/ywspezzx.js";

package/dist/dialects/pg/introspect.d.ts

@@ -74,3 +74,15 @@ export declare function atomicBody(definition: string): string;
  * @returns The reprinted expression, without the `CHECK` keyword
  */
 export declare function reprintCheck(runner: CatalogQuery, expression: string): Promise<string>;
+/**
+ * Creates a temporary domain and reads the check Postgres stores.
+ *
+ * Domain checks use `VALUE`, which is not valid on a table check. Two
+ * authoring spellings of the same domain predicate compare equal after this.
+ *
+ * @param runner - Database connection
+ * @param base - Domain base type, as Postgres `format_type` spells it
+ * @param expression - Check expression without the `CHECK` keyword
+ * @returns The reprinted expression, without the `CHECK` keyword
+ */
+export declare function reprintDomainCheck(runner: CatalogQuery, base: string, expression: string): Promise<string>;

package/dist/dialects/pg/view/index.js

@@ -8,10 +8,10 @@ import {
 } from "../../../shared/fk9vef30.js";
 import {
   viewClient
-} from "../../../shared/760ppr76.js";
+} from "../../../shared/4a3mmhhe.js";
 import {
   snakeCase
-} from "../../../shared/gcefca6p.js";
+} from "../../../shared/f9t9g54z.js";
 import {
   formatType
 } from "../../../shared/606g0nbf.js";

package/dist/runtime/param-limit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Postgres protocol parameter budget (B-40).
+ *
+ * Loaded only when a statement goes over the limit. Small statements pay one
+ * integer compare in the path that already holds the parameter list.
+ */
+/** Postgres binds at most this many parameters on one statement. */
+export declare const PG_PARAM_LIMIT = 65535;
+/**
+ * Refuses a statement that exceeds the protocol parameter limit.
+ *
+ * @param count - Parameter count of the finished statement
+ */
+export declare function refuseParamLimit(count: number): never;
+/**
+ * Throws OKM1126 when `count` is above {@link PG_PARAM_LIMIT}.
+ *
+ * @param count - Parameter count of the finished statement
+ */
+export declare function assertParamCount(count: number): void;

package/dist/runtime/pg/bun.js

@@ -4,7 +4,7 @@ import {
 import {
   markClientPool,
   open5
-} from "../../shared/62b603gr.js";
+} from "../../shared/n6je5b28.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
@@ -12,12 +12,12 @@ import {
 } from "../../shared/mfvx6kjx.js";
 import {
   createClient
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/71n0jmhc.js").then((mod) => mod.default(target, options, (config) => {
+    return import("../../shared/ysdw2fg3.js").then((mod) => mod.default(target, options, (config) => {
       const pool = open5(config);
       markClientPool(pool);
       return pool;

package/dist/runtime/pg/neon.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/cm3w0ywp.js";
 import {
   open6
-} from "../../shared/mazpbcdj.js";
+} from "../../shared/4te76xc5.js";
 import {
   NEON_WEBSOCKET_CAPABILITIES,
   NEON_HTTP_CAPABILITIES,
@@ -12,12 +12,12 @@ import {
 } from "../../shared/mfvx6kjx.js";
 import {
   createClient
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 
 // src/runtime/pg/neon.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/71n0jmhc.js").then((mod) => mod.default(target, options, (config) => open6({
+    return import("../../shared/ysdw2fg3.js").then((mod) => mod.default(target, options, (config) => open6({
       url: config.url,
       ...options.mode !== undefined ? { mode: options.mode } : {},
       ...config.max !== undefined ? { max: config.max } : {},

package/dist/runtime/pg/pg.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/cm3w0ywp.js";
 import {
   open4
-} from "../../shared/1mxm04fy.js";
+} from "../../shared/tyqapcgk.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
@@ -11,12 +11,12 @@ import {
 } from "../../shared/mfvx6kjx.js";
 import {
   createClient
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/71n0jmhc.js").then((mod) => mod.default(target, options, open4));
+    return import("../../shared/ysdw2fg3.js").then((mod) => mod.default(target, options, open4));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({

package/dist/runtime/pg/pglite.js

@@ -12,12 +12,12 @@ import {
 } from "../../shared/mfvx6kjx.js";
 import {
   createClient
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/71n0jmhc.js").then((mod) => mod.default(target, options, open3));
+    return import("../../shared/ysdw2fg3.js").then((mod) => mod.default(target, options, open3));
   }
   const pool = isPool(target) ? seal2(target) : await open3({
     ...target !== undefined ? { dataDir: target } : {},

package/dist/runtime/pg/postgresjs.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/cm3w0ywp.js";
 import {
   open2
-} from "../../shared/dd5pmnky.js";
+} from "../../shared/jvxcp1qk.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
@@ -11,22 +11,22 @@ import {
 } from "../../shared/mfvx6kjx.js";
 import {
   createClient
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/71n0jmhc.js").then((mod) => mod.default(target, options, open2));
+    return import("../../shared/ysdw2fg3.js").then((mod) => mod.default(target, options, open2));
   }
   const owned = !isPool(target);
-  const pool = isPool(target) ? target : open2({
+  const pool = owned ? open2({
     url: target,
-    ...options.max !== undefined ? { max: options.max } : {},
-    ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {},
-    ...options.prepared !== undefined ? { prepared: options.prepared } : {},
-    ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
-    ...options.ssl !== undefined ? { ssl: options.ssl } : {}
-  });
+    max: options.max,
+    timeouts: options.timeouts,
+    prepared: options.prepared,
+    searchPath: options.searchPath,
+    ssl: options.ssl
+  }) : target;
   return createClient(options.schema, pool, {
     ownsPool: owned,
     http: options.errors?.http,

package/dist/runtime/tenancy/index.js

@@ -10,7 +10,7 @@ import {
 import {
   index2,
   snakeCase
-} from "../../shared/gcefca6p.js";
+} from "../../shared/f9t9g54z.js";
 import {
   ColumnBuilder2,
   retarget

package/dist/runtime/traits/index.js

@@ -24,7 +24,7 @@ import {
 } from "../../shared/ecn8mfdq.js";
 import {
   snakeCase
-} from "../../shared/gcefca6p.js";
+} from "../../shared/f9t9g54z.js";
 import {
   ColumnBuilder2,
   retarget
@@ -41,7 +41,7 @@ import {
   queryHandle,
   attachHttp,
   settleCall
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 import {
   installArchiveInspect,
   indexes,

package/dist/runtime/validate/index.js

@@ -3,10 +3,10 @@ import {
 } from "../../shared/w9ejzaqf.js";
 import {
   addSchemaHook
-} from "../../shared/9dr2qnx7.js";
+} from "../../shared/qqm3ze6q.js";
 import {
   queryHandle
-} from "../../shared/npdftanb.js";
+} from "../../shared/xbvz446k.js";
 import {
   OkmError2
 } from "../../shared/52szzakm.js";

package/dist/runtime/write.d.ts

@@ -39,7 +39,7 @@ export type PreparedWrite = {
     readonly statements: readonly Statement[];
     readonly options: ExecuteOptions | undefined;
     /** Set when `finish` can refuse a statement that already ran. `batch` refuses such a write (D183). */
-    readonly checked?: "restore" | "expect" | "parent";
+    readonly checked?: "restore" | "expect" | "parent" | "tree";
     finish(results: readonly ExecuteResult[]): unknown;
     /**
      * More statements once the planned ones have run.

package/dist/shared/{5kyb3tqx.js → 1h5h1rf5.js}

@@ -1,6 +1,6 @@
 import {
   build3
-} from "./cexb7z6b.js";
+} from "./gr9sn4za.js";
 export {
   build3 as build
 };

package/dist/shared/{4vbf83xx.js → 2vcnpf0n.js}

@@ -1,6 +1,6 @@
 import {
   emitSqlValue
-} from "./3bb7wsqt.js";
+} from "./ycnft340.js";
 import {
   assertOperatorFits,
   sqlType,

package/dist/shared/{8n688yjg.js → 3ap5hxvj.js}

@@ -15,7 +15,8 @@ import {
   expectOf2,
   allowSet2,
   noteGuarded2
-} from "./9dtgn1z2.js";
+} from "./63qjmhnp.js";
+import"./ddh72ym5.js";
 import"./mss6ctgv.js";
 export {
   Sql2 as Sql,

package/dist/shared/{wvtjg5m3.js → 3d7a80fq.js}

@@ -8,7 +8,7 @@ import {
   openClient,
   withHttp,
   settleCall
-} from "./npdftanb.js";
+} from "./xbvz446k.js";
 import {
   rejectKeys,
   isRecord,