palgres 0.0.0-stage → 0.1.0

package/types/palgres/src/query/client.d.ts

@@ -0,0 +1,154 @@
+import type { DatabaseDiagnostics } from './diagnostics.js';
+import type { AtomicOptions, InsertManyOptions, Page, RawPageOptions } from './options.js';
+import type { TxPlanBody, TxPlanResponse } from './tx-plan.js';
+export interface FindManyOptions {
+    /** One ordering or an ordered list. `nulls` pins where NULLs go — Postgres' default changes with the direction. */
+    orderBy?: {
+        column: string;
+        direction?: 'asc' | 'desc';
+        nulls?: 'first' | 'last';
+    } | {
+        column: string;
+        direction?: 'asc' | 'desc';
+        nulls?: 'first' | 'last';
+    }[];
+    /** Only these columns; an unknown name is refused before SQL. */
+    select?: string[];
+    /** Related rows too, in the same statement (LATERAL): `has` filters through a relation, `with` fetches it. */
+    with?: Record<string, unknown>;
+    limit?: number;
+    /** Only with `limit`: an offset into an unbounded result is not a page. */
+    offset?: number;
+}
+/**
+ * A row lock, held until the transaction ends: `update` FOR UPDATE (the row
+ * is about to change or go), `noKeyUpdate` FOR NO KEY UPDATE (it changes,
+ * its key stays — what updateMany takes), `share` FOR SHARE (it must not
+ * change while this transaction reads on). Postgres applies the table's
+ * UPDATE policies to a locking read, so a row the caller may read but not
+ * update is not returned locked.
+ */
+export type RowLock = 'update' | 'share' | 'noKeyUpdate';
+/** How a table's rows are searched. */
+export interface SearchOptions {
+    /** How many rows at most (default 20; 1 to 100). */
+    limit?: number;
+    /** Only rows this filter matches — findMany's filter. */
+    where?: Record<string, unknown>;
+    /** "hybrid" (default): by meaning and by word, fused; "text": by word alone; "vector": by meaning alone. */
+    mode?: 'hybrid' | 'text' | 'vector';
+    /** Only rows whose _score is at least this. */
+    minScore?: number;
+}
+/** The operations a request's transaction, a savepoint and an $atomic scope all have. */
+export interface DBOps {
+    /** Null unless the request asked for diagnostics or a budget. Parameter values are never in it. */
+    diagnostics(): DatabaseDiagnostics | null;
+    /** One row by exactly one declared unique key; null never stands for a unique value. With `lock`, the row is locked in the same statement, until the transaction ends. */
+    findUnique(table: string, where: Record<string, unknown>, opts?: {
+        select?: readonly string[];
+        with?: Record<string, unknown>;
+        lock?: RowLock;
+    }): Promise<Record<string, unknown> | null>;
+    /** Keyset pagination: opaque cursors sealed to the query and the caller, a unique ordering. */
+    page(table: string, query?: Record<string, unknown>, opts?: RawPageOptions): Promise<Page<Record<string, unknown>>>;
+    /**
+     * Raw SQL on this transaction — the request's own, a savepoint's or an
+     * $atomic scope's. Not read-only: a write here commits with it, and what
+     * stands between it and the data is RLS and the role. Parameters are $1…$n;
+     * an array of scalars is a Postgres array (`= ANY($1::uuid[])`), an object
+     * is JSON, JSON text for a jsonb parameter is that JSON. Rows are plain
+     * objects; bigint and numeric are strings, a timestamp an ISO string.
+     * Without a type argument the rows are `unknown`: only the author knows
+     * what raw SQL returns.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    insert(table: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * sum/avg (always text: exact), min/max, count, optionally grouped. `count`
+     * is `true` for the rows, or named filters — `{ open: { done: false } }` —
+     * each counted in the same statement (count(*) FILTER (WHERE …)).
+     */
+    aggregate(table: string, q: {
+        where?: Record<string, unknown>;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean | Readonly<Record<string, Record<string, unknown>>>;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
+    /** Many rows, ONE statement; every row has the same keys — the column list is shared. `action: "ignore"` alone skips a row that collides with any unique key. */
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts: InsertManyOptions & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: InsertManyOptions & {
+        returning?: true;
+    }): Promise<Record<string, unknown>[]>;
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: InsertManyOptions): Promise<Record<string, unknown>[] | number>;
+    /** Insert, or update on a collision of `onConflict` — one statement, so two racing callers cannot both lose. */
+    put(table: string, data: Record<string, unknown>, opts: {
+        onConflict: readonly string[];
+    }): Promise<Record<string, unknown>>;
+    /** The row with this id updated, or null when none matched (absent, or hidden by RLS). */
+    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    delete(table: string, id: string): Promise<void>;
+    findById(table: string, id: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Every row the filter matches, updated in one statement; an empty filter is
+     * refused. Zero rows is neither an error nor a success: with the condition
+     * in `where` (`{ id, balance: { gte: amount } }`), the returned array is the
+     * only thing that says whether it applied.
+     */
+    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>, opts?: {
+        returning?: boolean;
+    }): Promise<Record<string, unknown>[] | number>;
+    /**
+     * Claims an idempotency key: `{ inserted: true }` this call wrote the row,
+     * `{ inserted: false, row }` someone did first and `row` is theirs — both
+     * successes. `unique` finds the row, `extra` is only written.
+     */
+    claim(table: string, unique: Record<string, unknown>, extra?: Record<string, unknown>): Promise<{
+        inserted: boolean;
+        row: Record<string, unknown>;
+    }>;
+    /** Locks these rows in an order the engine sets (by primary key), not the caller's: two callers cannot take them in opposite orders. */
+    lockRows(table: string, ids: readonly string[]): Promise<void>;
+    /** Locks the rows a filter matches, selected and locked in one statement, ordered by primary key. An empty filter is refused. */
+    lockRowsWhere(table: string, where: Record<string, unknown>, opts?: {
+        mode?: RowLock;
+    }): Promise<void>;
+    /** Locks a NAME, not a row, until this transaction ends — "one invoice run at a time". Never session-scoped: that would outlive the request. */
+    advisoryXactLock(key: string): Promise<void>;
+    /** Deletes every row the filter matches; how many. An empty filter is refused. */
+    deleteMany(table: string, where: Record<string, unknown>): Promise<number>;
+    /** How many rows match; an empty filter counts the table. */
+    count(table: string, where?: Record<string, unknown>): Promise<number>;
+    findMany(table: string, query?: Record<string, unknown>, opts?: FindManyOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * The rows of a table that declares search nearest to `query` — by meaning
+     * (its embedding against the rows') and by word (full text), fused — each
+     * with its `_score`, best first. It runs as the caller: a row their
+     * policies hide is never found. A row not embedded yet is found by its
+     * words; when the query cannot be embedded, so is every row ("hybrid").
+     */
+    search(table: string, query: string, opts?: SearchOptions): Promise<(Record<string, unknown> & {
+        _score: number;
+    })[]>;
+}
+export interface DBClient extends DBOps {
+    /** An independent transaction: resolves after its COMMIT, retries the whole callback on a fresh one. One identity throughout. */
+    atomic<T>(fn: (tx: AtomicClient) => Promise<T>, options?: AtomicOptions): Promise<T>;
+    /** A plan (`$transaction`) run on this transaction inside one savepoint. */
+    txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
+    /**
+     * `fn` in a SAVEPOINT of this transaction: a failure in it rolls back only
+     * what its handle wrote. The handle is a parameter, not an ambient swap — a
+     * concurrent Promise.all branch's writes must stay outside the boundary.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
+    /** The same operations as service_role, which passes row-level security — its own transaction on its own connection. No asService of its own. */
+    asService(): Omit<DBClient, 'asService'>;
+}
+/** A root transaction cannot change identity or open another root. */
+export type AtomicClient = Omit<DBClient, 'asService' | 'atomic'>;

package/types/palgres/src/query/data-mark.d.ts

@@ -0,0 +1,7 @@
+export { carryMark, isData, isValue, markData, markRows } from '../../../internal/src/data.js';
+/**
+ * The 400 for data where structure goes. `field` is where in the call it
+ * stood (`where.token`, `orderBy`); the words reach the caller, so they name
+ * the field, never the table.
+ */
+export declare function refuseDataAsStructure(v: unknown, field: string, what: string): void;

package/types/palgres/src/query/diagnostics.d.ts

@@ -0,0 +1,76 @@
+export interface DatabaseBudget {
+    /** Statements, failed ones and retries included. */
+    maxQueries?: number;
+    /** Rows returned; nested relation rows count in bytes. */
+    maxRows?: number;
+    /** Estimated JSON bytes of the results — not protocol traffic. */
+    maxBytes?: number;
+}
+export interface DatabaseQueryEvent {
+    ordinal: number;
+    fingerprint: string;
+    name?: string;
+    sql?: string;
+    source?: string;
+    durationMs: number;
+    rows: number;
+    bytes: number;
+    errorCode?: string;
+}
+export interface DatabaseDiagnostics {
+    endpoint?: string;
+    requestId?: string;
+    outcome: 'active' | 'committed' | 'failed';
+    elapsedMs: number;
+    queries: number;
+    rows: number;
+    bytes: number;
+    queueMs: number;
+    /** Until the driver's transaction callback starts; includes BEGIN. */
+    poolMs: number;
+    /** From the transaction callback through the acknowledged COMMIT/ROLLBACK. */
+    connectionMs?: number;
+    setupMs: number;
+    /** Waiting on the driver: Postgres' execution, locks, the network. */
+    sqlMs: number;
+    commitMs: number;
+    rollbackMs: number;
+    commits: number;
+    commitFailures: number;
+    rollbackRequests: number;
+    retries: number;
+    /** The first 200 statements; the totals count every one. */
+    statements: readonly DatabaseQueryEvent[];
+}
+export interface DatabaseDiagnosticsOptions extends DatabaseBudget {
+    endpoint?: string;
+    requestId?: string;
+    /** A stack capture costs work on every statement, so it is asked for. */
+    captureSource?: boolean;
+    /** Parameters are never recorded; raw SQL text can carry inline literals. */
+    includeSql?: boolean;
+    onQuery?: (event: DatabaseQueryEvent) => void | Promise<void>;
+    onComplete?: (diagnostics: DatabaseDiagnostics) => void | Promise<void>;
+}
+type Timing = 'queueMs' | 'poolMs' | 'setupMs' | 'sqlMs' | 'commitMs' | 'rollbackMs' | 'connectionMs';
+export declare class DatabaseTrace {
+    private readonly start;
+    private readonly options;
+    private ended?;
+    private failure?;
+    private readonly state;
+    constructor(options: DatabaseDiagnosticsOptions);
+    check(): void;
+    time(key: Timing, started: number): void;
+    retry(): void;
+    committed(): void;
+    commitFailed(): void;
+    failed(): void;
+    rolledBack(): void;
+    private refuse;
+    private emit;
+    query(sql: string, run: () => PromiseLike<unknown>): Promise<unknown>;
+    get snapshot(): DatabaseDiagnostics;
+    complete(outcome: 'committed' | 'failed'): void;
+}
+export {};

package/types/palgres/src/query/driver.d.ts

@@ -0,0 +1,299 @@
+/** A statement in flight. */
+export type Statement = PromiseLike<unknown>;
+/** What the engine says of a statement it wrote itself. */
+export interface StatementHint {
+    /**
+     * Every $n in the text is the engine's own placeholder, and no part of the
+     * text came from outside the engine: the statement may travel in the round
+     * trip that opens its transaction, its values as literals (inlineParams).
+     */
+    inline?: boolean;
+    /**
+     * A plain read — a SELECT without a locking clause, no function the
+     * engine calls writes. A transaction of nothing else has nothing to commit.
+     */
+    read?: boolean;
+}
+export interface SqlTx {
+    unsafe(sql: string, params?: unknown[], hint?: StatementHint): Statement;
+    savepoint<T>(fn: (sp: SqlTx) => Promise<T>): Promise<T>;
+    /**
+     * Gives the transaction's connection up: closed now, whatever is in flight
+     * on it — the server rolls back what it held — and never lent again; the
+     * transaction ends without a word more on it. For a connection that stopped
+     * answering (control.ts' CANCEL_GRACE_MS). A driver that cannot close one
+     * connection of its pool has none.
+     */
+    abandon?(): void;
+}
+/** How a transaction starts. */
+export interface Opening {
+    /** Statements separated by ";", without parameters: what the transaction runs first. */
+    sql: string;
+    /** Gets the rows of the opening's last statement, before any statement after it is answered. */
+    opened?(rows: Record<string, unknown>[]): void;
+    /**
+     * A name of its own for the round trip that carries the opening, said in
+     * it as a comment: cancelOpening(tag) stops that round trip while it runs,
+     * before its backend is known by anything else.
+     */
+    tag?: string;
+}
+export interface SqlDriver {
+    /**
+     * A statement on its own. It goes on a connection that has just answered,
+     * and once: a connection the server closed while it sat idle in the pool —
+     * a database that slept, restarted or moved (a switchover terminates every
+     * backend, 57P01) — is dropped before the statement is sent, and another
+     * taken; a connection lost after it was sent is the statement's failure,
+     * never a second run.
+     */
+    unsafe(sql: string, params?: unknown[]): Statement;
+    /**
+     * A transaction: commits when `fn` resolves, rolls back when it rejects.
+     * It runs `opening` first, in as few round trips as the driver can: Bun's
+     * sends it with the BEGIN, and with the transaction's first statement when
+     * the engine wrote that one (StatementHint) — one round trip for all three.
+     */
+    begin<T>(fn: (tx: SqlTx) => Promise<T>, opening?: Opening): Promise<T>;
+    /**
+     * Cancels one backend's statement through a connection of its own. The
+     * ticket names the backend (pid, backend_start) and its transaction
+     * (xact_start): a pooler hands the same server connection to the next
+     * client, and a late cancel must never reach that client's query.
+     */
+    cancelBackend?(pid: number, startedAt: string, xactStartedAt: string): Promise<void>;
+    /** Cancels the round trip that opens a transaction, by its tag, while it runs: true when it found it running. */
+    cancelOpening?(tag: string): Promise<boolean>;
+}
+/** A parameter as the text Postgres reads, or null. */
+export declare function encodeParam(value: unknown): string | null;
+/** A JS array as a Postgres array literal. Unquoted NULL is the null element; "NULL" would be the four-letter string. */
+export declare function encodePgArray(value: readonly unknown[]): string;
+/**
+ * postgres.js' `types` option for a pool the engine uses: postgres.js
+ * serializes a parameter by the type the server describes, and its json,
+ * boolean, date and bytea serializers would re-encode the text the engine
+ * already wrote. Parsing (results) is postgres.js' own.
+ */
+export declare const POSTGRES_JS_TYPES: {
+    json: {
+        to: number;
+        from: number[];
+        serialize: (x: unknown) => unknown;
+        parse: (x: string) => unknown;
+    };
+    boolean: {
+        to: number;
+        from: number[];
+        serialize: (x: unknown) => unknown;
+        parse: (x: string) => x is "t";
+    };
+    date: {
+        to: number;
+        from: number[];
+        serialize: (x: unknown) => unknown;
+        parse: (x: string) => Date;
+    };
+    bytea: {
+        to: number;
+        from: number[];
+        serialize: (x: unknown) => unknown;
+        parse: (x: string) => Buffer<ArrayBuffer>;
+    };
+};
+/** Bun's SQL as the engine sees it (structural: this package does not depend on Bun's types). */
+export interface BunPool {
+    unsafe(sql: string, params?: unknown[]): Statement;
+    reserve(): Promise<BunReserved>;
+    /**
+     * A connection it lent has none under it (bunSlotWithoutConnection), and
+     * nothing was sent on it. Told so, a pool that can (renewingBunPool) takes
+     * it back and opens itself anew. One that cannot — Bun's own — is not given
+     * it back: it would lend it again.
+     */
+    discard?(reserved: BunReserved): void;
+}
+/** One of the pool's connections, held. */
+export interface BunReserved {
+    unsafe(sql: string, params?: unknown[]): Statement & {
+        simple(): PromiseLike<unknown>;
+    };
+    /** Back to the pool, as it is. */
+    release(): void;
+    /** Closed: the pool opens another in its place. It waits for what is in flight on it unless told `timeout: 0`. */
+    close(options?: {
+        timeout?: number;
+    }): PromiseLike<unknown> | void;
+}
+/** The rows of a simple query's last statement: Bun answers several statements with one array per statement. */
+export declare function lastRows(result: unknown): Record<string, unknown>[];
+/**
+ * `text` with each $n as its value's literal: what lets a statement travel in
+ * a round trip that takes no parameters. Only for a statement the engine
+ * wrote (StatementHint.inline): its quotes are the engine's own — "…"
+ * identifiers, '…' and E'…' literals, every quote in them doubled — and its
+ * only $ are its placeholders, each bound once. Whatever else is in it — a
+ * comment, a second statement, a backslash, a $ that is no placeholder, a
+ * placeholder without a value or a value without one — answers undefined,
+ * and the statement goes on its own with its parameters. A value is an
+ * untyped literal, which Postgres reads as it reads an untyped parameter: by
+ * its context.
+ */
+export declare function inlineParams(text: string, params: readonly unknown[]): string | undefined;
+/**
+ * Tries to open a transaction — or send a statement on its own — on a live
+ * connection. A server that closed the pool's connections leaves as many dead
+ * ones as the pool held, each failing at once: the next one is tried, up to
+ * this many — and so is a connection lent with none under it, each such
+ * counted among them. A connection that does not open says the database is
+ * not reachable: one more try, then the failure.
+ */
+export declare const OPEN_ATTEMPTS = 10;
+export declare const OPEN_ATTEMPTS_UNREACHABLE = 2;
+/**
+ * A Bun SQL pool as a driver. A transaction is a connection held for it
+ * (reserve), not Bun's begin(): Bun sends statements without prepared
+ * statements one round trip at a time, so the BEGIN, the transaction's
+ * opening and — when the engine wrote it — its first statement go as ONE
+ * simple query: a request of one statement is two round trips (that one and
+ * its COMMIT) where begin() takes four.
+ *
+ * Nothing is sent until the transaction's first statement. A connection the
+ * server had closed fails in that first round trip, and it is sent again on
+ * another: no COMMIT was in it, so whatever of it ran on a connection that
+ * was then lost is rolled back by the server.
+ *
+ * A statement on its own (unsafe) is a transaction of one, its BEGIN sent
+ * alone first. Bun's pool learns that the server closed an idle connection
+ * only when it reads the server's FATAL, and a statement given it before
+ * then fails with that FATAL (57P01) — the error a statement the server
+ * terminated while it ran gets too, so nothing in it says the statement did
+ * not run. The BEGIN is what meets the dead connection: it fails, the
+ * connection is dropped, and the statement goes on another. What fails after
+ * the statement went is its failure, never sent again — on its own it would
+ * have committed as it ended, and a nextval() is never rolled back. Two
+ * round trips more than the pool's own unsafe (the BEGIN, the COMMIT): it is
+ * the engine's checks and its cancels, never a request's statements.
+ *
+ * A connection Bun lent with no connection under it — the server ended it in
+ * the read that opened it (bunSlotWithoutConnection) — refuses the first
+ * round trip before anything is written. The round trip goes on another, and
+ * the pool is told (BunPool.discard): renewingBunPool opens itself anew, so
+ * that it lends its full count again. Bun's own pool cannot be told: the
+ * connection is kept, never given back — it would be lent again — and that
+ * pool lends one fewer from then on.
+ *
+ * The connection goes back to the pool only with its transaction ended: one
+ * released inside a transaction hands it to the next borrower (measured, Bun
+ * 1.4.2). One whose end did not answer is closed instead. `control`, a second
+ * small pool, carries cancellation: a cancel sent on the application pool
+ * would wait behind the statement it is meant to stop.
+ */
+export declare function bunDriver(pool: BunPool, control?: BunPool): SqlDriver;
+/**
+ * How long a Bun pool's close() may take past its own timeout. Past its
+ * timeout it has closed every connection it holds, each telling the pool at
+ * once; what it may still wait for is a connection lent with none under it
+ * (bunSlotWithoutConnection), whose close never comes — there is no socket
+ * left to close.
+ */
+export declare const BUN_CLOSE_GRACE_MS = 1000;
+/**
+ * Closes a Bun pool: its work given `timeout` seconds to end, then every
+ * connection closed — and settled by then, BUN_CLOSE_GRACE_MS later at the
+ * latest: Bun 1.4.2's close() never settles once it has lent a connection
+ * with none under it (oven-sh/bun#42804).
+ */
+export declare function closeBunPool(pool: {
+    close(options?: {
+        timeout?: number;
+    }): PromiseLike<unknown>;
+}, timeout: number): Promise<void>;
+/** Bun's SQL client as renewingBunPool opens it. */
+export interface BunSqlPool extends BunPool {
+    close(options?: {
+        timeout?: number;
+    }): PromiseLike<unknown>;
+}
+/** A Bun pool that opens itself anew when it lent a connection with none under it. */
+export interface RenewingBunPool<P extends BunSqlPool = BunSqlPool> extends BunPool {
+    /** The pool it lends from now. */
+    readonly current: P;
+    /** How many times it opened itself anew. */
+    readonly renewals: number;
+    discard(reserved: BunReserved): void;
+    /** Closes the pool it lends from and the ones it left, settled by `timeout` and BUN_CLOSE_GRACE_MS at the latest (closeBunPool). */
+    close(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+/**
+ * A Bun pool that stays whole when Bun's is not (Bun 1.4.2): told that a
+ * connection it lent has none under it (bunSlotWithoutConnection), it lends
+ * from then on from a pool it opens anew — `open()`, as many connections —
+ * and leaves the old one: that one lends nothing more, its connections lent
+ * go on to their end, and once they have it closes them all. The connection
+ * with none under it goes back to it, which is what it waits for. The pool
+ * Bun cannot mend is replaced, never shrunk: however many times it happens,
+ * the app has its full count of connections again, and no more than that
+ * beside the ones still at work in the pools it left.
+ */
+export declare function renewingBunPool<P extends BunSqlPool>(open: () => P): RenewingBunPool<P>;
+/**
+ * cancelOpening through a pool of its own: the backend whose statement in
+ * flight starts with the tag's comment — this login's, in this database. A
+ * tag names one round trip, so a cancel that arrives late finds nothing: the
+ * backend is idle, or runs a statement that does not start with it.
+ */
+export declare function cancelOpeningThrough(control: {
+    unsafe(sql: string, params?: unknown[]): PromiseLike<unknown>;
+}): NonNullable<SqlDriver['cancelOpening']>;
+/**
+ * cancelBackend through a pool of its own (logged in as the app): it matches
+ * pid, backend_start AND xact_start, this login and this database — a ticket
+ * of a transaction that has ended cancels nothing.
+ */
+export declare function cancelBackendThrough(control: {
+    unsafe(sql: string, params?: unknown[]): PromiseLike<unknown>;
+}): NonNullable<SqlDriver['cancelBackend']>;
+export declare class DriverRefused extends Error {
+    constructor(what: string);
+}
+/** Asks Postgres what it received for each kind of text the engine sends, and refuses a driver that changed it. */
+export declare function verifyDriver(sql: SqlDriver): Promise<void>;
+/** What postgresJsDriver needs of postgres.js: its pool, as `postgres(url, { types: POSTGRES_JS_TYPES })` makes it. */
+export interface PostgresJs {
+    unsafe(text: string, params?: unknown[]): PromiseLike<unknown> & {
+        simple(): PromiseLike<unknown>;
+    };
+    begin<T>(fn: (tx: PostgresJsTx) => Promise<T>): Promise<T>;
+}
+interface PostgresJsTx {
+    unsafe(text: string, params?: unknown[]): PromiseLike<unknown> & {
+        simple(): PromiseLike<unknown>;
+    };
+    savepoint<T>(fn: (tx: PostgresJsTx) => Promise<T>): Promise<T>;
+}
+/**
+ * postgres.js as the engine's driver: its transaction runs the opening after
+ * its own BEGIN, before the work — a round trip more than Bun's, the same
+ * transaction. `control`, a pool of one, is what a cancel goes through.
+ *
+ * postgres.js sends a statement on a connection whose close it has not read
+ * yet, and fails it then (CONNECTION_CLOSED). A transaction whose BEGIN or
+ * opening failed so — before the work was handed the transaction — goes on
+ * another connection; a statement on its own is a transaction of one, so
+ * the same holds for it. Nothing that reached the work is sent again.
+ *
+ * Once postgres.js has seen a transaction's connection close, nothing more
+ * is given to it. postgres.js 3.4.9 writes what it is given next — the
+ * ROLLBACK of the transaction the failure ended, its COMMIT, a statement —
+ * to the closed socket, and throws where no caller can catch it
+ * (porsager/postgres#1133): a Node app would stop on every transaction a
+ * database that moved cut. So a statement after the close is refused with
+ * it, and the transaction's end — or a savepoint's — is never asked for:
+ * postgres.js has already rejected the transaction's begin() with the close.
+ */
+export declare function postgresJsDriver(pool: PostgresJs, control: PostgresJs): SqlDriver;
+export {};

package/types/palgres/src/query/env-gen.d.ts

@@ -0,0 +1,14 @@
+import { type SchemaDef } from '../dsl/schema.js';
+/** The lines that wrap the generated block, so a tool can replace it in a file that holds more. */
+export declare const ENV_BLOCK_START = "// palbase:env:begin";
+export declare const ENV_BLOCK_END = "// palbase:env:end";
+/**
+ * The palbase-env.d.ts text for a project's schemas (db/public.ts,
+ * db/billing.ts, …), augmenting `module`'s `Tables` and `Schemas`. It ends in
+ * `export {};`: without it the file is a global script and `declare module`
+ * there would DECLARE a module that shadows the real one instead of
+ * augmenting it.
+ */
+export declare function makeEnvDts(schemas: readonly SchemaDef[], options?: {
+    module?: string;
+}): string;