okmodel 0.7.0 → 0.8.0

package/dist/adapters/capabilities.d.ts

@@ -78,6 +78,38 @@ export declare const BUNSQL_CAPABILITIES: {
     readonly prepared: "unnamed";
     readonly describe: false;
 };
+/**
+ * Neon WebSocket pool execution flags.
+ *
+ * Interactive transactions pass on a direct connection. `stream`, `listen`,
+ * `cancel`, and `describe` stay false: a server cursor, `LISTEN`, and a
+ * side-channel cancel are session features the pooler does not keep, and the
+ * client has no describe API. Statements use the unnamed protocol.
+ * `prepared: "named"` is not for a transaction-mode pooler.
+ */
+export declare const NEON_WEBSOCKET_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: false;
+    readonly listen: false;
+    readonly cancel: false;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
+/**
+ * Neon HTTP execution flags.
+ *
+ * One request is one statement. `sql.transaction` is the atomic batch.
+ * There is no interactive `tx()`, no `LISTEN`, no server cursor, and no
+ * cancel of a statement the server has already started.
+ */
+export declare const NEON_HTTP_CAPABILITIES: {
+    readonly transactions: "batch";
+    readonly stream: false;
+    readonly listen: false;
+    readonly cancel: false;
+    readonly prepared: "none";
+    readonly describe: false;
+};
 /**
  * Reads one capability flag.
  *

package/dist/adapters/failure.d.ts

@@ -22,7 +22,7 @@ export declare function rejectClosed(): Promise<never>;
 /**
  * Rejects with OKM1120 when a driver cannot cancel a positive timeout.
  *
- * The message stays `timeout`. Kind stays `invalid`. Bun.sql and PGlite call
+ * The message stays `timeout`. Kind stays `invalid`. Bun.sql, PGlite, and Neon call
  * this. Other drivers do not, so their connect graphs omit it.
  *
  * @returns A rejected promise

package/dist/adapters/pg/bun-sql.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The slice of Bun.sql this adapter uses.
+ *
+ * `bun` is the runtime, not an npm package, and it ships no types. The
+ * published declarations name these types instead of importing `bun`, so a
+ * consumer can typecheck `okmodel/pg/bun` without `bun-types`.
+ */
+/** A pending query. `raw()` asks for rows as arrays. */
+export interface SQLQuery extends Promise<unknown> {
+    /** Rows as arrays instead of objects. */
+    raw(): SQLQuery;
+}
+/** One pooled Bun.sql client. */
+export interface SQL {
+    /**
+     * Runs a statement.
+     *
+     * @param text - SQL text
+     * @param values - Positional parameters
+     */
+    unsafe(text: string, values?: readonly unknown[]): SQLQuery;
+    /**
+     * Checks out one connection.
+     *
+     * @param options - `signal` aborts the wait
+     */
+    reserve(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ReservedSQL>;
+    /** Closes the pool. */
+    close(): Promise<void>;
+    /**
+     * Subscribes to one `LISTEN` channel.
+     *
+     * @param channel - Channel name
+     * @param onnotify - Payload callback
+     */
+    listen(channel: string, onnotify: (payload: string) => void): Promise<SQLListen>;
+}
+/** A `LISTEN` registration. */
+export interface SQLListen {
+    /** Drops this registration. */
+    unlisten(): Promise<void>;
+}
+/**
+ * One connection reserved from {@link SQL.reserve}.
+ *
+ * `release` returns it to the pool.
+ */
+export interface ReservedSQL extends SQL {
+    /** Returns the connection to the pool. */
+    release(): void;
+}

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

@@ -4,7 +4,7 @@
  * Loaded on the first reserve, batch, stream, or dead connection. A read that
  * succeeds does not use it.
  */
-import type { ReservedSQL, SQL } from "bun";
+import type { ReservedSQL, SQL } from "./bun-sql.js";
 import type { DriverConnection, WireValue } from "../../contracts/driver.js";
 import { type HeldPool } from "./bunsql.js";
 /**

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

@@ -9,7 +9,7 @@
  * finished script exits without `close()`. `Query.cancel()` does not abort
  * the backend, so `cancel` is false. Server notices are not surfaced.
  */
-import { SQL, type ReservedSQL } from "bun";
+import type { ReservedSQL, SQL } from "./bun-sql.js";
 import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
 import { DriverError } from "../error.js";
 import { noticeBuffer, type WireQuery } from "./session.js";

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

@@ -0,0 +1,18 @@
+/**
+ * Reserved connections for the Neon WebSocket pool.
+ *
+ * Loaded on the first reserve or batch. A read does not use it.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type HeldPool } from "./neon.js";
+/**
+ * Checks out one client and clears it on release.
+ *
+ * A client whose connection is gone is destroyed on release, and nothing more
+ * is sent to it. A checked-out client has no pool error listener, so one is
+ * set here: without it a dropped socket is an uncaught `error` event.
+ *
+ * @param held - The pool and its counters
+ * @returns A connection the caller must release
+ */
+export declare function checkout(held: HeldPool): Promise<DriverConnection>;

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

@@ -0,0 +1,104 @@
+/**
+ * Neon adapter (`okmodel/pg/neon`).
+ *
+ * `@neondatabase/serverless` is an optional peer. This module is the only
+ * place that imports it. `mode: "websocket"` (the default) is a pooled
+ * WebSocket client with interactive transactions. `mode: "http"` is one HTTP
+ * request per statement, and `batch` is the driver's non-interactive
+ * transaction. A positive `timeout` is refused: neither mode aborts a
+ * statement the server has already started.
+ *
+ * The first WebSocket `open` sets `webSocketConstructor` only when it is
+ * still unset, so a caller can install one first. A transaction-mode pooler
+ * does not promise session state. One small compute can reuse a backend, so
+ * a custom `SET`, `LISTEN`, or a prepared statement may still be visible.
+ */
+import { Pool, type PoolClient } from "@neondatabase/serverless";
+import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { NEON_WEBSOCKET_CAPABILITIES as capabilities, NEON_HTTP_CAPABILITIES as httpCapabilities, hasCapability, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** How {@link open} talks to Neon. */
+export type NeonMode = "websocket" | "http";
+/** Options for {@link open}. */
+export type NeonConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * `websocket` is a pooled WebSocket client. `http` is one-shot HTTP.
+     *
+     * Omitted means `websocket`.
+     */
+    readonly mode?: NeonMode;
+    /**
+     * 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. HTTP ignores it.
+     */
+    readonly prepared?: "named" | "unnamed";
+    /** Session search path for every WebSocket connection in the pool. */
+    readonly searchPath?: string;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/** What a WebSocket checkout needs from the pool that opened it. */
+export type HeldPool = {
+    readonly pool: Pool;
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly notices: ReturnType<typeof noticeBuffer>;
+    readonly named: boolean;
+    readonly isClosed: () => boolean;
+};
+/** A client that can run one array-mode statement. */
+type Queryable = {
+    query(config: {
+        text: string;
+        values?: readonly WireValue[];
+        rowMode: "array";
+        types: typeof WIRE;
+        name?: string;
+    }): Promise<unknown>;
+};
+declare const WIRE: {
+    getTypeParser(): (value: string) => string;
+};
+/**
+ * Opens a Neon pool for one endpoint.
+ *
+ * WebSocket mode connects once before returning, so a later short acquire
+ * timeout measures the queue and not a cold start. HTTP mode does not open a
+ * socket.
+ *
+ * @param config - URL, mode, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: NeonConfig): Promise<DriverPool>;
+/**
+ * Checks out one WebSocket client.
+ *
+ * The wait uses `timeouts.acquire`. A timeout is OKM1846 and does not keep the
+ * client.
+ *
+ * @param pool - Neon pool
+ * @param acquireMs - Wait ceiling, when one was set
+ * @param counters - Pool occupancy
+ * @returns The client
+ */
+export declare function connectClient(pool: Pool, acquireMs: number | undefined, counters: Counters): Promise<PoolClient>;
+/**
+ * Sends one statement and returns the driver's promise.
+ *
+ * @param runner - Pool or checked-out client
+ * @param text - SQL
+ * @param params - Wire parameters
+ * @param named - Use a named prepared statement
+ * @returns The pending result
+ */
+export declare function send(runner: Queryable, text: string, params: readonly WireValue[] | undefined, named: boolean): WireQuery;

package/dist/adapters/pg/no-inflight-timeout.d.ts

@@ -1,7 +1,7 @@
 /**
  * Refusal for a driver that cannot cancel an in-flight statement (D224).
  *
- * Bun.sql and PGlite refuse a positive `timeout`. The OKM1120 text loads with
+ * Bun.sql, PGlite, and Neon refuse a positive `timeout`. The OKM1120 text loads with
  * the lazy error module, so a connect entry does not carry it. Kind is
  * `invalid`, which separates it from kind `timeout`. `timeout: 0` still fails
  * immediately as kind `timeout`. `signal` is unchanged. postgres.js and

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" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
+export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1125" | "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/fn/index.d.ts

@@ -5,12 +5,46 @@
  * records. `schema()` only asks each declared object for those records.
  */
 import type { CatalogObject, FunctionLanguage, FunctionSecurity, FunctionVolatility, TriggerEvent, TriggerLevel, TriggerTiming } from "../../../contracts/catalog/types.js";
+import { type FragmentIdent } from "../ops/fragment.js";
+import { type Eq } from "../operators.js";
+import type { Window } from "../ops/window.js";
 import type { AnyTable, SqlText } from "../table.js";
 /** One argument of {@link fn}. */
 export type FunctionArgumentInput = {
     readonly name: string;
     readonly type: string;
 };
+/** Postgres types that bind as a number. Anything else binds as text. */
+type NumericReturn = "smallint" | "integer" | "bigint" | "int2" | "int4" | "int8" | "real" | "double precision" | "float4" | "float8" | "numeric";
+/** A select name for {@link FnCall.as}. Numeric returns are numbers. Text stays text. */
+type CallAs<R extends string, A extends string> = R extends NumericReturn | `numeric${string}` ? Window<A, number> : Window<A, string>;
+/**
+ * A typed call.
+ *
+ * It is a `sql` fragment, so `where` accepts it as {@link Eq}. `.as(name)` is
+ * the `select` form. `orderBy` does not: adding the call to that union is one
+ * composite type over the ceiling.
+ *
+ * @typeParam R - Declared return type
+ */
+export type FnCall<R extends string = string> = Eq<never> & {
+    /**
+     * Names the select result.
+     *
+     * @typeParam A - Result key
+     * @param name - Result key. Not a column name
+     * @returns A select entry
+     */
+    as<const A extends string>(name: A): CallAs<R, A>;
+};
+/** One argument value. `ident` names a field. Null is SQL null. */
+type CallValue<T extends string> = T extends "boolean" | "bool" ? boolean | FragmentIdent | null : T extends NumericReturn | `numeric${string}` ? number | FragmentIdent | null : string | FragmentIdent | null;
+/** Argument list of a call, in declaration order. */
+type CallArgs<A extends readonly FunctionArgumentInput[]> = {
+    [I in keyof A]: A[I] extends FunctionArgumentInput ? CallValue<A[I]["type"]> : never;
+};
+/** `fn.slugify(col)`. The value is {@link FnCall}. */
+type FnCaller<A extends readonly FunctionArgumentInput[], R extends string> = (...args: CallArgs<A>) => FnCall<R>;
 /**
  * A table, or one column of a table.
  *
@@ -96,7 +130,10 @@ export type TriggerDeclaration = {
  * @param options - Signature, language, body, and dependencies
  * @returns The definition object `schema({ functions })` stores
  */
-export declare function fn(name: string, options: FunctionOptions): Routine;
+export declare function fn<const A extends readonly FunctionArgumentInput[] = readonly [], const R extends string = string>(name: string, options: FunctionOptions & {
+    readonly arguments?: A;
+    readonly returns: R;
+}): Routine & FnCaller<A, R>;
 /**
  * Declares a trigger.
  *
@@ -105,3 +142,4 @@ export declare function fn(name: string, options: FunctionOptions): Routine;
  * @returns The definition object `schema({ triggers })` stores
  */
 export declare function trigger(name: string, options: TriggerOptions): TriggerDeclaration;
+export {};

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

@@ -1,10 +1,23 @@
 import {
   functionObject,
   triggerObject
-} from "../../../shared/y34a8714.js";
+} from "../../../shared/12z7aznj.js";
+import {
+  isFragmentParts,
+  sqlExpression,
+  identName
+} from "../../../shared/bsek72fg.js";
+import {
+  quoteIdent
+} from "../../../shared/sjk86yrx.js";
 import {
   staticNamespace2
 } from "../../../shared/358zsv4r.js";
+import {
+  isOperator,
+  operatorName,
+  operatorValue
+} from "../../../shared/cn0n68ft.js";
 import {
   assertIdentifier2
 } from "../../../shared/nfzc5z0w.js";
@@ -36,32 +49,111 @@ function fn(name, options) {
   }
   const argTypes = (options.arguments ?? []).map((argument) => argument.type);
   const schema = options.schema ?? "public";
-  return {
-    name,
-    schema,
-    argTypes,
-    contribute(peers, built) {
-      assertPeers(peers, "functions");
-      const namespace = staticNamespace2(schema);
-      const provenance = { origin: "file", name };
-      return [
-        functionObject({
-          namespace,
-          name,
-          ...options.arguments !== undefined ? { arguments: options.arguments } : {},
-          returns: options.returns,
-          language,
-          ...options.volatility !== undefined ? { volatility: options.volatility } : {},
-          ...options.security !== undefined ? { security: options.security } : {},
-          ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
-          body,
-          ...atomic ? { atomic: true } : {},
-          provenance,
-          dependencies: dependencyEdges(options.dependsOn, built)
-        })
-      ];
-    }
+  const declared = options.arguments ?? [];
+  const contribute = (peers, built) => {
+    assertPeers(peers, "functions");
+    const namespace = staticNamespace2(schema);
+    const provenance = { origin: "file", name };
+    return [
+      functionObject({
+        namespace,
+        name,
+        ...options.arguments !== undefined ? { arguments: options.arguments } : {},
+        returns: options.returns,
+        language,
+        ...options.volatility !== undefined ? { volatility: options.volatility } : {},
+        ...options.security !== undefined ? { security: options.security } : {},
+        ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
+        body,
+        ...atomic ? { atomic: true } : {},
+        provenance,
+        dependencies: dependencyEdges(options.dependsOn, built)
+      })
+    ];
   };
+  const call = (...args) => invoke(schema, name, declared, options.returns, args);
+  define(call, "name", name);
+  define(call, "schema", schema);
+  define(call, "argTypes", argTypes);
+  define(call, "contribute", contribute);
+  return call;
+}
+function define(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true
+  });
+}
+var NUMERIC_RETURNS = new Set([
+  "smallint",
+  "integer",
+  "bigint",
+  "int2",
+  "int4",
+  "int8",
+  "real",
+  "double precision",
+  "float4",
+  "float8",
+  "numeric"
+]);
+function invoke(schemaName, name, declared, returns, args) {
+  if (args.length !== declared.length) {
+    throw new OkmError2("OKM1120", `Function ${name} expects ${String(declared.length)} arguments.`, { fix: { summary: "Pass one value for each declared argument, in order." } });
+  }
+  const parts = [{ k: "t", s: `${quoteIdent(schemaName)}.${quoteIdent(name)}(` }];
+  for (let index = 0;index < args.length; index += 1) {
+    if (index > 0)
+      parts.push({ k: "t", s: ", " });
+    appendArg(parts, args[index], name);
+  }
+  parts.push({ k: "t", s: ")" });
+  const textual = !(NUMERIC_RETURNS.has(returns) || returns.startsWith("numeric("));
+  return sqlExpression(parts, textual);
+}
+function appendArg(parts, value, name) {
+  if (value === null) {
+    parts.push({ k: "n" });
+    return;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    parts.push({ k: "p", v: String(value) });
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new OkmError2("OKM1120", `Function ${name} needs a finite number.`, {
+        fix: { summary: "Pass a finite number, or leave it out." }
+      });
+    }
+    parts.push({ k: "p", v: String(value) });
+    return;
+  }
+  const field = identName(value);
+  if (field !== undefined) {
+    parts.push({ k: "i", n: field });
+    return;
+  }
+  if (isOperator(value) && operatorName(value) === "sql") {
+    const stored = operatorValue(value);
+    if (isFragmentParts(stored)) {
+      parts.push({ k: "f", parts: stored });
+      return;
+    }
+  }
+  if (isHandle(value)) {
+    assertIdentifier2(value.name, `function ${name}`);
+    parts.push({ k: "i", n: value.name });
+    return;
+  }
+  throw new OkmError2("OKM1121", `Function ${name} received a value it cannot bind.`, {
+    fix: { summary: "Pass a string, number, boolean, null, or ident(field)." }
+  });
+}
+function isHandle(value) {
+  return typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && value.name.length > 0 && !isOperator(value);
 }
 function trigger(name, options) {
   return {

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

@@ -57,4 +57,6 @@ export { or } from "./ops/or.js";
 export { overlaps } from "./ops/overlaps.js";
 export { path } from "./ops/path.js";
 export { startsWith } from "./ops/startsWith.js";
+export { fragment, ident, type Fragment } from "./ops/fragment.js";
+export { explain, raw, type ExplainResult } from "./ops/lane.js";
 export { many, manyThrough, morph, morphMany, morphTo, one, type ManyRelation, type ManyThroughRelation, type MorphManyRelation, type MorphRelation, type OneRelation, type RelationCall, } from "./relations.js";