okmodel 0.6.0 → 0.8.0

package/dist/runtime/include.d.ts

@@ -2,14 +2,6 @@
  * LATERAL include planner. Loaded on the first include.
  */
 import { type IncludeHooks, type Plan } from "./plan.js";
-/**
- * Decodes a result that has includes.
- *
- * @param plan - Compiled plan
- * @param rows - Wire rows
- * @param table - Table the call named
- * @returns The call's value
- */
 export declare function decodeIncluded(plan: Plan, rows: readonly (readonly (string | null)[])[], table: string): unknown;
 /** Hooks the read planner calls after this module has loaded. */
 export declare const includeHooks: IncludeHooks;

package/dist/runtime/inflight.d.ts

@@ -2,7 +2,7 @@
  * Refuses a positive timeout on a driver that cannot cancel.
  *
  * `tx({ timeout })` and `batch({ timeout })` load this with the call. The
- * connect graph does not. The message stays the one {@link noTimeout} throws.
+ * connect graph does not. The OKM1120 text loads with the lazy error module.
  */
 import type { DriverPool } from "../contracts/driver.js";
 /**

package/dist/runtime/otel.d.ts

@@ -0,0 +1,105 @@
+/**
+ * OpenTelemetry observers (`okmodel/otel`).
+ *
+ * The package does not import `@opentelemetry/*`. Pass a tracer you already
+ * have. The observers are `hookm`, `onRoute`, and an `inspect()` result.
+ * Statement text is off unless `statement` is true. Parameters and tenant ids
+ * are never attributes (spec §5.5, D267).
+ */
+import type { RouteEvent } from "./topology.js";
+import type { Hookm, Inspection } from "./types.js";
+/** A scalar OpenTelemetry attribute. Arrays are not used. */
+export type OtelAttribute = string | number | boolean;
+/**
+ * Status codes from the OpenTelemetry API.
+ *
+ * `0` is unset, `1` is OK, and `2` is ERROR.
+ */
+export type OtelStatusCode = 0 | 1 | 2;
+/**
+ * The span methods this entry calls.
+ *
+ * A tracer from `@opentelemetry/api` satisfies this shape.
+ */
+export interface OtelSpan {
+    /** Sets one attribute. */
+    setAttribute(key: string, value: OtelAttribute): void;
+    /** Sets the span status. `message` is never sent. */
+    setStatus(status: {
+        readonly code: OtelStatusCode;
+    }): void;
+    /**
+     * Records an exception.
+     *
+     * `name` is the error name. `code` is an OKM code when the error has one.
+     * Message and stack are omitted.
+     */
+    recordException(exception: {
+        readonly name: string;
+        readonly code?: string;
+    }): void;
+    /** Adds a span event. */
+    addEvent(name: string, attributes?: Readonly<Record<string, OtelAttribute>>): void;
+    /** Ends the span. */
+    end(): void;
+}
+/** Options passed to `startSpan`. `kind` is `2` (client). */
+export interface OtelSpanOptions {
+    /** OpenTelemetry span kind. This entry always passes `2`. */
+    readonly kind?: number;
+    /** Attributes set when the span starts. */
+    readonly attributes?: Readonly<Record<string, OtelAttribute>>;
+}
+/**
+ * The tracer methods this entry calls.
+ *
+ * A tracer from `@opentelemetry/api` satisfies this shape.
+ */
+export interface OtelTracer {
+    /**
+     * Starts a span.
+     *
+     * @param name - Span name
+     * @param options - Kind and attributes
+     */
+    startSpan(name: string, options?: OtelSpanOptions): OtelSpan;
+}
+/** What {@link otel} accepts. */
+export interface OtelOptions {
+    /** Tracer the caller owns. This module does not construct one. */
+    readonly tracer: OtelTracer;
+    /**
+     * Record `db.query.text` from `inspect()`.
+     *
+     * Omitted or false, the text is left off. Parameters stay off either way.
+     */
+    readonly statement?: boolean;
+}
+/**
+ * Observers to pass to `connect`, plus `query` for one `inspect()` result.
+ */
+export interface OtelObservers {
+    /** Pass this in `connect({ hookm })`. */
+    readonly hookm: Hookm;
+    /** Pass this in `connect({ onRoute })`. A topology calls it. */
+    readonly onRoute: (event: RouteEvent) => void;
+    /**
+     * Records `db.query.summary` from `inspect()`.
+     *
+     * The fingerprint is that summary. `db.query.text` is included only when
+     * `statement` is true.
+     *
+     * @param inspection - The result of `inspect()`
+     */
+    readonly query: (inspection: Inspection) => void;
+}
+/**
+ * Connects the existing observers to a tracer.
+ *
+ * `onRoute` spans start and end in that call, because the hook fires once.
+ * A transaction span stays open from `start` until `commit` or `rollback`.
+ *
+ * @param options - Tracer, and whether statement text is recorded
+ * @returns `hookm`, `onRoute`, and `query`
+ */
+export declare function otel(options: OtelOptions): OtelObservers;

package/dist/runtime/otel.js

@@ -0,0 +1,97 @@
+// src/runtime/otel.ts
+var SYSTEM = "postgresql";
+var CLIENT = 2;
+var STATUS_OK = 1;
+var STATUS_ERROR = 2;
+function otel(options) {
+  const tracer = options.tracer;
+  const statement = options.statement === true;
+  const open = [];
+  const hookm = {
+    onTransaction(event) {
+      if (event.phase === "start") {
+        const name = event.depth === 0 ? "transaction" : "savepoint";
+        open.push({
+          depth: event.depth,
+          span: begin(tracer, name, {
+            "db.system.name": SYSTEM,
+            "db.operation.name": name
+          })
+        });
+        return;
+      }
+      const index = latest(open, event.depth);
+      const found = index < 0 ? undefined : open[index];
+      if (found === undefined)
+        return;
+      open.splice(index, 1);
+      if (event.phase === "rollback") {
+        found.span.setAttribute("error.type", "rollback");
+        found.span.setStatus({ code: STATUS_ERROR });
+      } else {
+        found.span.setStatus({ code: STATUS_OK });
+      }
+      found.span.end();
+    },
+    onError(error) {
+      const span = begin(tracer, "error", {
+        "db.system.name": SYSTEM,
+        "error.type": errorType(error)
+      });
+      span.recordException(recordedException(error));
+      span.setStatus({ code: STATUS_ERROR });
+      span.end();
+    }
+  };
+  return {
+    hookm,
+    onRoute(event) {
+      const span = begin(tracer, event.op, {
+        "db.system.name": SYSTEM,
+        "db.operation.name": event.op
+      });
+      span.addEvent("route", { endpoint: event.endpoint, reason: event.reason });
+      span.end();
+    },
+    query(inspection) {
+      const op = inspection.intent.op;
+      const table = inspection.intent.table;
+      const attributes = {
+        "db.system.name": SYSTEM,
+        "db.operation.name": op,
+        "db.collection.name": table,
+        "db.query.summary": inspection.plan.fingerprint
+      };
+      if (statement)
+        attributes["db.query.text"] = inspection.sql.text;
+      begin(tracer, `${op} ${table}`, attributes).end();
+    }
+  };
+}
+function begin(tracer, name, attributes) {
+  return tracer.startSpan(name, { kind: CLIENT, attributes });
+}
+function latest(open, depth) {
+  for (let index = open.length - 1;index >= 0; index -= 1) {
+    if (open[index]?.depth === depth)
+      return index;
+  }
+  return -1;
+}
+function errorType(error) {
+  return error instanceof Error && error.name.length > 0 ? error.name : "error";
+}
+function recordedException(error) {
+  const name = errorType(error);
+  const code = okmCode(error);
+  return code === undefined ? { name } : { name, code };
+}
+function okmCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error))
+    return;
+  const code = error.code;
+  return typeof code === "string" && /^OKM\d+$/.test(code) ? code : undefined;
+}
+export {
+  otel
+};

package/dist/runtime/page.d.ts

@@ -20,6 +20,9 @@ import { type ArchiveView } from "./plan.js";
  * @param options - `where`, `select`, `orderBy`, `limit`, `include`, and `after`
  * @param mods - Signal and timeout
  * @param view - Archive visibility
+ * @param pin - Endpoint a stream already chose. Absent for `page()`
  * @returns A handle that resolves to `{ items, next }`
  */
-export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined): Promise<unknown> & Record<string, unknown>;
+export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined, pin?: {
+    name?: string;
+}): Promise<unknown> & Record<string, unknown>;

package/dist/runtime/pg/bun.js

@@ -1,23 +1,27 @@
-import"../../shared/8dqhth8c.js";
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
+  markClientPool,
   open5
-} from "../../shared/32cnm7kn.js";
+} from "../../shared/zbqbmmrp.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/ae4j5f42.js";
 import {
   createClient
-} from "../../shared/j60w0dvr.js";
+} from "../../shared/bah9nbg3.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open5));
+    return import("../../shared/0wrea3jq.js").then((mod) => mod.default(target, options, (config) => {
+      const pool = open5(config);
+      markClientPool(pool);
+      return pool;
+    }));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open5({
@@ -28,6 +32,8 @@ function connect(target, options) {
     ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
     ...options.ssl !== undefined ? { ssl: options.ssl } : {}
   });
+  if (!isPool(target))
+    markClientPool(pool);
   return createClient(options.schema, pool, {
     ownsPool: owned,
     http: options.errors?.http,

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

@@ -0,0 +1,38 @@
+/**
+ * `connect` for Neon (`okmodel/pg/neon`).
+ *
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in.
+ * `mode` is `websocket` (the default) or `http`.
+ */
+import type { DriverPool } from "../../contracts/driver.js";
+import type { QuerySchema } from "../../dialects/pg/model.js";
+import { type NeonConfig } from "../../adapters/pg/neon.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
+import type { ConnectOptions, Connected } from "../types.js";
+export { open, type NeonConfig, type NeonMode } from "../../adapters/pg/neon.js";
+export { capabilities, hasCapability, httpCapabilities, readCapability, } from "../../adapters/pg/neon.js";
+export { DriverError } from "../../adapters/error.js";
+/** A connection string or a pool from {@link open}. */
+export type NeonTarget = string | DriverPool;
+/** Driver options `connect` forwards to {@link open}. */
+export type NeonConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<NeonConfig, "url"> & TopologyOptions;
+/**
+ * Connects one Neon endpoint, or a primary and its replicas.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
+ *
+ * `mode: "websocket"` is the default. Interactive `tx()` needs it. `mode: "http"`
+ * is one-shot HTTP: `batch()` is atomic and `tx()` is refused.
+ *
+ * Named prepared statements are off unless `prepared` is `"named"`.
+ * `prepared: "named"` is not for transaction-mode poolers.
+ *
+ * @typeParam S - Schema
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
+ * @param options - Schema, mode, errors, logger, and driver options
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
+ */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: NeonConnectOptions<S>): Promise<RoutedClient<S>>;
+export declare function connect<const S extends QuerySchema>(target: NeonTarget, options: NeonConnectOptions<S>): Promise<Connected<S>>;

package/dist/runtime/pg/neon.js

@@ -0,0 +1,64 @@
+import {
+  DriverError2
+} from "../../shared/cm3w0ywp.js";
+import {
+  open6
+} from "../../shared/agsfb86s.js";
+import {
+  NEON_WEBSOCKET_CAPABILITIES,
+  NEON_HTTP_CAPABILITIES,
+  readCapability2,
+  hasCapability2
+} from "../../shared/ae4j5f42.js";
+import {
+  createClient
+} from "../../shared/bah9nbg3.js";
+
+// src/runtime/pg/neon.ts
+function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/0wrea3jq.js").then((mod) => mod.default(target, options, (config) => open6({
+      url: config.url,
+      ...options.mode !== undefined ? { mode: options.mode } : {},
+      ...config.max !== undefined ? { max: config.max } : {},
+      ...config.timeouts !== undefined ? { timeouts: config.timeouts } : {},
+      ...config.prepared !== undefined ? { prepared: config.prepared } : {},
+      ...config.searchPath !== undefined ? { searchPath: config.searchPath } : {}
+    })));
+  }
+  const owned = !isPool(target);
+  const opened = isPool(target) ? Promise.resolve(target) : open6({
+    url: target,
+    ...options.mode !== undefined ? { mode: options.mode } : {},
+    ...options.max !== undefined ? { max: options.max } : {},
+    ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {},
+    ...options.prepared !== undefined ? { prepared: options.prepared } : {},
+    ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {}
+  });
+  return opened.then((pool) => createClient(options.schema, pool, {
+    ownsPool: owned,
+    http: options.errors?.http,
+    includeValues: options.errors?.includeValues,
+    logger: options.logger,
+    signal: options.signal,
+    timeout: options.timeout,
+    timeouts: options.timeouts,
+    hookm: options.hookm,
+    catalog: options.catalog,
+    catalogDir: options.catalogDir,
+    requireMeta: options.requireMeta,
+    generators: options.generators
+  }));
+}
+function isPool(target) {
+  return typeof target === "object" && "execute" in target && "capabilities" in target;
+}
+export {
+  DriverError2 as DriverError,
+  NEON_WEBSOCKET_CAPABILITIES as capabilities,
+  connect,
+  hasCapability2 as hasCapability,
+  NEON_HTTP_CAPABILITIES as httpCapabilities,
+  open6 as open,
+  readCapability2 as readCapability
+};

package/dist/runtime/pg/pg.js

@@ -1,22 +1,22 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
   open4
-} from "../../shared/1z04fa85.js";
+} from "../../shared/14x60fbf.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/ae4j5f42.js";
 import {
   createClient
-} from "../../shared/j60w0dvr.js";
+} from "../../shared/bah9nbg3.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open4));
+    return import("../../shared/0wrea3jq.js").then((mod) => mod.default(target, options, open4));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({

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

@@ -2,6 +2,7 @@
  * `connect` for PGlite (`okmodel/pg/pglite`).
  *
  * Opening a database is async. An existing pool is reused and not closed.
+ * Closing that client marks the client closed.
  * A `{ primary, replicas }` object loads the topology module. A replica URL is
  * that endpoint's data directory.
  */

package/dist/runtime/pg/pglite.js

@@ -1,30 +1,30 @@
-import"../../shared/8dqhth8c.js";
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
-  open3
-} from "../../shared/5j36z8dn.js";
+  open3,
+  seal2
+} from "../../shared/4m6hskg8.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/ae4j5f42.js";
 import {
   createClient
-} from "../../shared/j60w0dvr.js";
+} from "../../shared/bah9nbg3.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open3));
+    return import("../../shared/0wrea3jq.js").then((mod) => mod.default(target, options, open3));
   }
-  const pool = isPool(target) ? target : await open3({
+  const pool = isPool(target) ? seal2(target) : await open3({
     ...target !== undefined ? { dataDir: target } : {},
     ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {}
   });
   return createClient(options.schema, pool, {
-    ownsPool: !isPool(target),
+    ownsPool: true,
     http: options.errors?.http,
     includeValues: options.errors?.includeValues,
     logger: options.logger,

package/dist/runtime/pg/postgresjs.js

@@ -1,22 +1,22 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
   open2
-} from "../../shared/wkme6tep.js";
+} from "../../shared/35q0n9tz.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/ae4j5f42.js";
 import {
   createClient
-} from "../../shared/j60w0dvr.js";
+} from "../../shared/bah9nbg3.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open2));
+    return import("../../shared/0wrea3jq.js").then((mod) => mod.default(target, options, open2));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open2({