okmodel 0.1.0 → 0.2.1

package/README.md

@@ -1,44 +1,262 @@
 # OKModel
 
-Catalog-first TypeScript ORM for PostgreSQL. Version 0.1.
+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)
+- [Keys](#keys)
+- [Commands](#commands)
+- [Roadmap](#roadmap)
+- [Size](#size)
+- [Docs](#docs)
 
 ## Install
 
+Four Postgres drivers. Pick the one the runtime already has. postgres.js is the default, on Node and Bun. node-postgres is the other choice on Node and Bun when `pg` is already installed. Bun.sql is built into Bun and runs only there. PGlite is in-process, on Node and Bun.
+
 ```sh
-bun add okmodel
+bun add okmodel postgres
+bun add okmodel pg
+bun add okmodel @electric-sql/pglite
 ```
 
-postgres.js and PGlite are optional peers. Install the one you connect with.
+Bun.sql needs no extra package: `import { connect } from "okmodel/pg/bun"`. okmodel has no runtime dependencies. Each installed driver is an optional peer.
 
-```sh
-bun add postgres
-# or
-bun add @electric-sql/pglite
-```
+## Quickstart
 
-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.
+`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 { schema, table, t } from "okmodel/pg";
 import { defineConfig } from "okmodel/migrate";
 
-export const notes = table("notes", {
-  id: t.uuid(),
-  title: t.text(),
+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.
+
+Ids can also be generated in the application. Import `uuidv4`, `uuidv7`, or `okid` from `okmodel/ids` and pass one to `.default()`, or set `defaults.id` on `schema()` for every id column that does not choose its own. A column choice wins. A literal stays a database default. A generator is not stored in the catalog, so changing it does not create a migration, and an insert that bypasses okmodel has to supply the value. An OKID column is text with collation C, so a sortable id orders the same everywhere. Sortable ids include the time they were created.
+
+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(),
 });
 
-export const app = schema({ tables: [notes] });
+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.
 
-export default defineConfig({ schema: "./schema.ts" });
+```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 build
 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 });
 ```
 
-`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.
+### 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");
+}
+```
+
+A jsonb filter uses `contains`, and the fragment stays a parameter: `{ meta: contains({ published: true }) }`. `json.set(["published"], true)` writes that path inside `update`. The column builder is `t.json()`; the `json` import is this write namespace.
+
+An array column uses `contains` and `overlaps` the same way. `arr.append("news")` and `arr.remove("news")` add or remove one element inside `update`.
+
+### 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();
+```
+
+## Keys
+
+`t.identity()` is a bigint identity primary key. Insert and update omit it. It works on every supported Postgres version. The quickstart uses it.
+
+`t.id()` is a uuid primary key. The default is `uuidv7()`, which needs Postgres 18; on an older server `okm migrate apply` stops with OKM1812 before it runs any statement. `t.id({ default: "uuidv4" })` uses `gen_random_uuid()`, built in from Postgres 13. `t.id({ default: "none" })` takes the id on insert and omits it from update.
+
+`.primaryKey()` on a column is a natural key. Insert supplies it. Update cannot change it. A composite key is the `primaryKey` option on the table, naming the columns in order.
+
+## 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
+
+Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each release is a milestone.
+
+- [x] [0.1](https://github.com/omqkhafi/okmodel/milestone/1) — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
+- [ ] [0.2](https://github.com/omqkhafi/okmodel/milestone/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](https://github.com/omqkhafi/okmodel/milestone/3) — Extensions, domains, functions, triggers, views, roles, and grants.
+- [ ] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
+- [ ] [0.5](https://github.com/omqkhafi/okmodel/milestone/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,288 |  2,026 |    1.991 ms |
+| App startup (10 tables, one find)            |   88,938 | 29,778 |   10.380 ms |
+| App startup, every 0.2 feature in use (full) |  113,705 | 37,506 |   12.068 ms |
+
+The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 24,767 minified and 7,728 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated.
+
+The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 
-A production target sets `protected: true`. A production `connect` sets `requireMeta: true`. `prepared: "named"` is not for a transaction-mode pooler.
+## Docs
 
-Apache-2.0.
+- [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

@@ -41,6 +41,40 @@ export declare const PGLITE_CAPABILITIES: {
     readonly prepared: "unnamed";
     readonly describe: true;
 };
+/**
+ * node-postgres execution flags.
+ *
+ * Interactive transactions, cursor streaming, listen, and cancel are set
+ * because the conformance suite passes them. Describe is false: `pg` cannot
+ * describe a statement without running it, and that case is skipped.
+ * Parameterized queries use the unnamed extended protocol.
+ */
+export declare const NODE_POSTGRES_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: true;
+    readonly listen: true;
+    readonly cancel: true;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
+/**
+ * Bun.sql execution flags.
+ *
+ * Interactive transactions, cursor streaming, and listen pass the conformance
+ * suite. `cancel` is false: `Query.cancel()` does not abort the backend
+ * (Bun 1.4), so the cancel and in-flight timeout cases are skipped.
+ * `describe` is false: Bun.sql has no describe API. RAISE NOTICE is not
+ * surfaced, so the notice case is skipped. `prepare` is off, so a
+ * parameterized query does not leave a named statement.
+ */
+export declare const BUNSQL_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: true;
+    readonly listen: true;
+    readonly cancel: false;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
 /**
  * Reads one capability flag.
  *

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

@@ -0,0 +1,17 @@
+/**
+ * Reserved connections for Bun.sql.
+ *
+ * Loaded on the first reserve, batch, or stream. A read does not use it.
+ */
+import type { DriverConnection } 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.
+ *
+ * @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/bunsql.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Bun.sql adapter (`okmodel/pg/bun`).
+ *
+ * Bun's built-in client. There is no package to install. This module is the
+ * only place that imports `bun`. It runs on Bun; another runtime cannot load
+ * that import.
+ *
+ * `idleTimeout` stays 0, which is Bun's default: no idle timer, and a
+ * 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 { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { BUNSQL_CAPABILITIES as capabilities, hasCapability, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** TLS values Bun.sql accepts that this adapter forwards. */
+export type BunSqlTls = boolean | "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+/** Options for {@link open}. */
+export type BunSqlConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * Named prepared statements, or the unnamed protocol.
+     *
+     * Unnamed is the default (`prepare: false`). `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 Bun.sql. */
+    readonly ssl?: BunSqlTls;
+};
+/** 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>;
+    readonly isClosed: () => boolean;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/**
+ * Opens a Bun.sql pool for one endpoint.
+ *
+ * @param config - URL, pool size, and acquire timeout
+ * @returns The pool
+ */
+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>;

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

@@ -28,24 +28,14 @@ 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.
+ * `BEGIN` may carry modes (`begin isolation level serializable`). `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.
  *

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

@@ -0,0 +1,18 @@
+/**
+ * Reserved connections for node-postgres.
+ *
+ * Loaded on the first reserve, batch, or stream. A read does not use it.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type HeldPool } from "./nodepostgres.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/nodepostgres.d.ts

@@ -0,0 +1,57 @@
+/**
+ * node-postgres adapter (`okmodel/pg/pg`).
+ *
+ * One pool per `open` call. `pg` is an optional peer of this entry.
+ * Idle clients are unref'd (`allowExitOnIdle`) and are not closed on a timer
+ * (`idleTimeoutMillis: 0`), so a finished script exits and a live process
+ * keeps its connection. Cancel sends a Postgres CancelRequest on a side
+ * socket. That socket is unref'd.
+ */
+import pg, { type PoolClient, type QueryConfig, type QueryResult } from "pg";
+import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { hasCapability, NODE_POSTGRES_CAPABILITIES as capabilities, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** Options for {@link open}. */
+export type NodePostgresConfig = 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 node-postgres. */
+    readonly ssl?: boolean | "require" | "allow" | "prefer" | "verify-full" | object;
+};
+/** What a checkout needs from the pool that opened it. */
+export type HeldPool = {
+    readonly pool: InstanceType<typeof pg.Pool>;
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly notices: ReturnType<typeof noticeBuffer>;
+    readonly named: boolean;
+    readonly isClosed: () => boolean;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/**
+ * Opens a node-postgres pool for one endpoint.
+ *
+ * @param config - URL, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: NodePostgresConfig): DriverPool;
+export declare function send(runner: {
+    query(config: QueryConfig): Promise<QueryResult>;
+}, text: string, params: readonly WireValue[] | undefined, named: boolean, client: PoolClient | undefined): WireQuery;
+export declare function connectClient(pool: InstanceType<typeof pg.Pool>, acquireMs: number | undefined, counters: Counters): Promise<PoolClient>;

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

@@ -4,7 +4,8 @@
  * 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 { DescribeResult, DriverConnection, ExecuteResult, WireValue } from "../../contracts/driver.js";
+import { type Watch } from "./call.js";
 import { type Canceller, type Counters, type NoticeBuffer } from "./postgresjs.js";
 /** State `open` shares with a checkout. */
 export type HeldPool = {
@@ -41,3 +42,51 @@ export declare function describe(sql: Sql, text: string, params?: readonly WireV
  * @returns Chunks of wire rows
  */
 export declare function stream(sql: Sql, text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;
+/** Refcount a checkout or a listener borrows from the pool. */
+type Gate = {
+    enter(): void;
+    leave(): void;
+};
+/**
+ * Keeps sockets referenced until `release` finishes.
+ *
+ * The caller has already entered `gate`. A second `release` does not change
+ * the count. Checkout failure leaves the gate.
+ *
+ * @param gate - Refcount already entered for this checkout
+ * @param checkout - Reserves the connection
+ * @returns The connection, with release counted once
+ */
+export declare function holdCheckout<T extends {
+    release(): Promise<void>;
+}>(gate: Gate, checkout: () => Promise<T>): Promise<T>;
+/**
+ * Keeps sockets referenced for as long as the listener is active.
+ *
+ * The caller has already entered `gate`.
+ *
+ * @param gate - Listener refcount already entered
+ * @param start - Subscribes and returns the stop function
+ * @returns A stop function that can be called again
+ */
+export declare function holdListener(gate: Gate, start: () => Promise<() => Promise<void>>): Promise<() => Promise<void>>;
+/**
+ * Finishes a query that can be aborted by a signal or a timeout.
+ *
+ * The caller has already tracked `pending` and attached `onAbort`.
+ *
+ * @param pending - The in-flight statement
+ * @param watch - Abort signal and the reason it fired
+ * @param onAbort - Listener the caller attached
+ * @param ctx - Notice slice and the session counters the plain path also uses
+ * @returns The wire result, or a rejected driver error
+ */
+export declare function watchQuery(pending: Canceller & Promise<unknown>, watch: Watch, onAbort: () => void, ctx: {
+    readonly start: number;
+    readonly text: string;
+    readonly notices: NoticeBuffer;
+    leave(): void;
+    note(text: string): void;
+    untrack(pending: Canceller): void;
+}): Promise<ExecuteResult>;
+export {};

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

@@ -88,8 +88,4 @@ export declare class PgSession implements BatchSession {
     private note;
     private enter;
     private leave;
-    private track;
-    private untrack;
-    private watched;
-    private finishWatched;
 }

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

@@ -0,0 +1,94 @@
+/**
+ * Shared interactive session for drivers that speak wire text.
+ *
+ * The postgres.js adapter keeps its own session. node-postgres and Bun.sql
+ * share this one: transaction depth, notices, and a watched cancel.
+ */
+import type { ExecuteResult, Notice, WireValue } from "../../contracts/driver.js";
+import type { BatchSession } from "./batch.js";
+import type { Watch } from "./call.js";
+/** A query the session can abort when the driver supports it. */
+export type WireQuery = Promise<unknown> & {
+    cancel?(): void;
+};
+/** Sends one statement and returns the driver's own result. */
+export type WireSender = (text: string, params: readonly WireValue[] | undefined) => WireQuery;
+/** Notice slice shared by a pool. */
+export type NoticeBuffer = {
+    start(): number;
+    since(start: number): readonly Notice[];
+    push(notice: {
+        readonly severity?: string | undefined;
+        readonly message?: string | undefined;
+        readonly code?: string | undefined;
+    }): void;
+};
+/**
+ * Quotes one identifier.
+ *
+ * @param name - Channel or cursor name
+ * @returns A double-quoted identifier
+ */
+export declare function quoteIdent(name: string): string;
+/**
+ * An empty notice buffer the pool fills as the server sends notices.
+ *
+ * @returns The buffer
+ */
+export declare function noticeBuffer(): NoticeBuffer;
+/**
+ * One connection's statement runner.
+ *
+ * `send` is the driver. This class owns depth, notices, and cancel tracking.
+ */
+export declare class WireSession implements BatchSession {
+    readonly canCancel: boolean;
+    private transactionDepth;
+    private readonly local;
+    private readonly send;
+    private readonly notices;
+    private readonly isClosed;
+    private readonly onEnter;
+    private readonly onLeave;
+    private readonly shared;
+    /**
+     * @param send - Runs one statement on this connection
+     * @param notices - Pool notice buffer
+     * @param isClosed - Pool closed flag
+     * @param canCancel - The driver aborts an in-flight statement
+     * @param onEnter - Marks one statement in flight
+     * @param onLeave - Marks that statement finished
+     * @param shared - Pool-wide in-flight set, when this connection is reserved
+     */
+    constructor(send: WireSender, notices: NoticeBuffer, isClosed: () => boolean, canCancel: boolean, onEnter: () => void, onLeave: () => void, shared?: Set<WireQuery>);
+    /** @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 track;
+    private untrack;
+    private watched;
+    private finishWatched;
+}
+/**
+ * Yields cursor chunks from one connection that is already checked out.
+ *
+ * The cursor is session-local. `ROLLBACK` in the end drops it.
+ *
+ * @param run - Executes on the checked-out connection
+ * @param text - Query to stream
+ * @param params - Wire parameters
+ * @returns Chunks of wire rows
+ */
+export declare function cursorStream(run: (text: string, params?: readonly WireValue[]) => Promise<ExecuteResult>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;