@typed-sql/postgres 1.0.0-rc.0 → 2.0.0-rc.1

package/dist/packages/postgres/src/runtime.js

@@ -1,7 +1,28 @@
 var _a;
-import { renderQuery } from "@typed-sql/core";
+import { createHash } from "node:crypto";
+import { adapterCapabilities, assertExecutionCapabilities, createAdapterCapabilityResolver, databaseErrorCompletion, hasQueryResultValidator, observeQueryStream, QueryCardinalityError, queryResultValidationSource, renderQuery, runControlledExecution, startDatabaseObservation, validateQueryResultRows, validateQueryResultStream, } from "@typed-sql/core";
+import { createPostgresCopyCapability, postgresCopy } from "./bulk.js";
+import { createPostgresPreparedQueryState, preparePostgresQuery, } from "./prepared.js";
+import { PostgresQueryStream, validatePostgresStreamBatchSize } from "./stream.js";
 import { defaultPostgresTypePolicy } from "./type-policy.js";
+import { POSTGRES_DIALECT_VERSION } from "./version.js";
 const defaultPolicy = defaultPostgresTypePolicy;
+const emptyBatchResults = Object.freeze([]);
+function createPostgresObservationState(observer) {
+    return { observer, fingerprints: observer === undefined ? undefined : new WeakMap() };
+}
+function postgresQueryFingerprint(state, query) {
+    const key = query;
+    const cached = state.fingerprints?.get(key);
+    if (cached !== undefined)
+        return cached;
+    const text = renderQuery(query, postgresRenderer).text;
+    const fingerprint = `sha256:${createHash("sha256")
+        .update(`postgres\0${POSTGRES_DIALECT_VERSION}\0${text}`)
+        .digest("hex")}`;
+    state.fingerprints?.set(key, fingerprint);
+    return fingerprint;
+}
 const oids = {
     int8: 20,
     date: 1082,
@@ -121,61 +142,941 @@ class PostgresDatabaseImplementation {
     #client;
     #parsers;
     #ownsPool;
+    #prepared;
+    #observation;
     #transactionDepth;
-    constructor(pool, client, parsers, ownsPool, depth) {
+    #transactionScopeOpen = true;
+    #transactionOperationFailed = false;
+    #transactionOperationError;
+    #transactionState;
+    #transactionExecutes = new Set();
+    #transactionStreams = new Set();
+    executionCapabilities;
+    [adapterCapabilities];
+    constructor(pool, client, parsers, ownsPool, depth, prepared, observation, transactionState = {
+        activeBatch: undefined,
+        activeCopy: undefined,
+        activeExecutes: new Set(),
+        activePipeline: undefined,
+        activeStreams: new Set(),
+        discardLease: false,
+        leaseReleased: false,
+        firstDatabaseOperationError: undefined,
+        unsafe: false,
+        unsafeDepth: undefined,
+        unsafeError: undefined,
+        valid: true,
+    }) {
         this.#pool = pool;
         this.#client = client;
         this.#parsers = parsers;
         this.#ownsPool = ownsPool;
         this.#transactionDepth = depth;
+        this.#prepared = prepared;
+        this.#observation = observation;
+        this.#transactionState = transactionState;
+        this.executionCapabilities = Object.freeze({
+            cancellation: pool.executionCapabilities?.cancellation ?? false,
+            deadlines: pool.executionCapabilities?.deadlines ?? false,
+        });
+        const copyTransport = {
+            copyFrom: (statement, chunks, options) => this.#copyFrom(statement, chunks, options),
+            copyTo: (statement, options) => this.#copyTo(statement, options),
+        };
+        this[adapterCapabilities] = createAdapterCapabilityResolver(pool.ensureCopy === undefined ? [] : [[postgresCopy, createPostgresCopyCapability(copyTransport)]]);
     }
     async execute(query) {
-        const rendered = renderQuery(query, postgresRenderer);
-        const result = await (this.#client ?? this.#pool).query({
-            text: rendered.text,
-            values: rendered.values.map(encodeValue),
-            types: this.#parsers,
+        if (this.#observation.observer === undefined) {
+            return this.#validateRows(query, await this.#executeUnobserved(query));
+        }
+        return this.#observeQuery(query, "many", async () => this.#validateRows(query, await this.#executeUnobserved(query)));
+    }
+    async #executeUnobserved(query) {
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("execute another query");
+        this.#rejectOperationDuringTransactionBatch("execute another query");
+        this.#rejectOperationDuringTransactionCopy("execute another query");
+        this.#rejectOperationDuringTransactionPipeline("execute another query");
+        const config = this.#queryConfig(query);
+        let operation;
+        try {
+            operation = (this.#client ?? this.#pool).query(config);
+        }
+        catch (error) {
+            this.#recordTransactionOperationFailure(error);
+            throw error;
+        }
+        if (this.#client !== undefined) {
+            this.#transactionExecutes.add(operation);
+            this.#transactionState.activeExecutes.add(operation);
+        }
+        try {
+            const result = await operation;
+            return result.rows;
+        }
+        catch (error) {
+            this.#recordTransactionOperationFailure(error);
+            throw error;
+        }
+        finally {
+            this.#transactionExecutes.delete(operation);
+            this.#transactionState.activeExecutes.delete(operation);
+        }
+    }
+    async all(query, options) {
+        if (this.#observation.observer === undefined) {
+            return this.#validateRows(query, await this.#allUnobserved(query, options));
+        }
+        return this.#observeQuery(query, "many", async () => this.#validateRows(query, await this.#allUnobserved(query, options)));
+    }
+    async #allUnobserved(query, options) {
+        if (options === undefined || (options.signal === undefined && options.deadline === undefined))
+            return this.#executeUnobserved(query);
+        assertExecutionCapabilities(this.executionCapabilities, options);
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("execute another query");
+        this.#rejectOperationDuringTransactionBatch("execute another query");
+        this.#rejectOperationDuringTransactionCopy("execute another query");
+        this.#rejectOperationDuringTransactionPipeline("execute another query");
+        if (options.signal?.aborted || (options.deadline !== undefined && Number(options.deadline) <= Date.now())) {
+            return runControlledExecution(options, async () => [], () => undefined);
+        }
+        if (this.#client === undefined) {
+            const client = await this.#pool.connect();
+            let discarded = false;
+            try {
+                return await this.#executeControlledOn(client, query, options, (error) => {
+                    client.release(error);
+                    discarded = true;
+                });
+            }
+            finally {
+                if (!discarded)
+                    client.release();
+            }
+        }
+        const client = this.#client;
+        const operation = this.#executeControlledOn(client, query, options, (error) => {
+            this.#transactionState.discardLease = true;
+            this.#markTransactionStateUnsafe(error);
+            try {
+                client.release(error);
+                this.#transactionState.leaseReleased = true;
+            }
+            catch {
+                /* The transaction finalizer also owns lease cleanup. */
+            }
         });
+        this.#transactionExecutes.add(operation);
+        this.#transactionState.activeExecutes.add(operation);
+        try {
+            return await operation;
+        }
+        catch (error) {
+            this.#recordTransactionOperationFailure(error);
+            throw error;
+        }
+        finally {
+            this.#transactionExecutes.delete(operation);
+            this.#transactionState.activeExecutes.delete(operation);
+        }
+    }
+    async #executeControlledOn(client, query, options, cancel) {
+        const result = await runControlledExecution(options, () => client.query(this.#queryConfig(query)), cancel);
         return result.rows;
     }
-    async transaction(fn) {
-        if (this.#client !== undefined)
-            return this.#nestedTransaction(fn);
+    async one(query, options) {
+        if (this.#observation.observer === undefined) {
+            const rows = await this.#validateRows(query, await this.#allUnobserved(query, options));
+            if (rows.length !== 1)
+                throw new QueryCardinalityError("one", rows.length);
+            return rows[0];
+        }
+        const rows = await this.#observeQuery(query, "one", async () => {
+            const result = await this.#validateRows(query, await this.#allUnobserved(query, options));
+            if (result.length !== 1)
+                throw new QueryCardinalityError("one", result.length);
+            return result;
+        });
+        return rows[0];
+    }
+    async maybeOne(query, options) {
+        if (this.#observation.observer === undefined) {
+            const rows = await this.#validateRows(query, await this.#allUnobserved(query, options));
+            if (rows.length > 1)
+                throw new QueryCardinalityError("maybeOne", rows.length);
+            return rows[0];
+        }
+        const rows = await this.#observeQuery(query, "maybeOne", async () => {
+            const result = await this.#validateRows(query, await this.#allUnobserved(query, options));
+            if (result.length > 1)
+                throw new QueryCardinalityError("maybeOne", result.length);
+            return result;
+        });
+        return rows[0];
+    }
+    async #observeQuery(query, cardinality, operation) {
+        if (this.#observation.observer === undefined)
+            return operation();
+        const observation = startDatabaseObservation(this.#observation.observer, {
+            kind: "query",
+            dialect: "postgres",
+            grammarVersion: POSTGRES_DIALECT_VERSION,
+            transactionDepth: this.#transactionDepth,
+            fingerprint: postgresQueryFingerprint(this.#observation, query),
+            cardinality,
+            prepared: this.#prepared.queries.has(queryResultValidationSource(query)),
+        });
+        if (observation === undefined)
+            return operation();
+        try {
+            const rows = await observation.run(operation);
+            observation.end({ status: "success", rowCount: rows.length });
+            return rows;
+        }
+        catch (error) {
+            observation.end(databaseErrorCompletion(error), error);
+            throw error;
+        }
+    }
+    async batch(queries) {
+        if (queries.length === 0)
+            return emptyBatchResults;
+        if (this.#observation.observer === undefined) {
+            return this.#validateBatch(queries, await this.#batchUnobserved(queries));
+        }
+        return this.#observeGroup("batch", queries, async () => this.#validateBatch(queries, await this.#batchUnobserved(queries)));
+    }
+    async #batchUnobserved(queries) {
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("execute a query batch");
+        this.#rejectOperationDuringTransactionBatch("execute another query batch");
+        this.#rejectOperationDuringTransactionCopy("execute a query batch");
+        this.#rejectOperationDuringTransactionPipeline("execute a query batch");
+        if (queries.length === 0)
+            return emptyBatchResults;
+        const querySnapshot = [...queries];
+        if (this.#client !== undefined) {
+            const operation = this.#executeBatch(this.#client, querySnapshot);
+            this.#transactionState.activeBatch = operation;
+            try {
+                return await operation;
+            }
+            catch (error) {
+                this.#recordTransactionOperationFailure(error);
+                throw error;
+            }
+            finally {
+                if (this.#transactionState.activeBatch === operation)
+                    this.#transactionState.activeBatch = undefined;
+            }
+        }
         const client = await this.#pool.connect();
+        let results;
         try {
-            await client.query("BEGIN");
-            const result = await fn(new _a(this.#pool, client, this.#parsers, false, 1));
-            await client.query("COMMIT");
-            return result;
+            results = await this.#executeBatch(client, querySnapshot);
         }
         catch (error) {
             try {
-                await client.query("ROLLBACK");
+                client.release(error instanceof Error ? error : true);
             }
             catch {
-                /* Preserve the original error. */
+                /* Preserve the first query failure. */
             }
             throw error;
         }
-        finally {
+        client.release();
+        return results;
+    }
+    async pipeline(queries) {
+        if (queries.length === 0)
+            return emptyBatchResults;
+        if (this.#observation.observer === undefined) {
+            return this.#validateBatch(queries, await this.#pipelineUnobserved(queries));
+        }
+        return this.#observeGroup("pipeline", queries, async () => this.#validateBatch(queries, await this.#pipelineUnobserved(queries)));
+    }
+    async #pipelineUnobserved(queries) {
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("execute a query pipeline");
+        this.#rejectOperationDuringTransactionBatch("execute a query pipeline");
+        this.#rejectOperationDuringTransactionCopy("execute a query pipeline");
+        this.#rejectOperationDuringTransactionExecute("execute a query pipeline");
+        this.#rejectOperationDuringTransactionPipeline("execute another query pipeline");
+        if (queries.length === 0)
+            return emptyBatchResults;
+        const configs = [...queries].map((value) => this.#queryConfig(value));
+        if (this.#client !== undefined) {
+            this.#assertPipelineClient(this.#client);
+            const operation = this.#executePipeline(this.#client, configs);
+            this.#transactionState.activePipeline = operation;
+            try {
+                return await operation;
+            }
+            catch (error) {
+                this.#recordTransactionOperationFailure(error);
+                throw error;
+            }
+            finally {
+                if (this.#transactionState.activePipeline === operation)
+                    this.#transactionState.activePipeline = undefined;
+            }
+        }
+        const client = await this.#pool.connect();
+        try {
+            this.#assertPipelineClient(client);
+        }
+        catch (error) {
+            try {
+                client.release();
+            }
+            catch {
+                /* Preserve the missing pipeline-capability error. */
+            }
+            throw error;
+        }
+        try {
+            const results = await this.#executePipeline(client, configs);
             client.release();
+            return results;
+        }
+        catch (error) {
+            try {
+                client.release(error instanceof Error ? error : true);
+            }
+            catch {
+                /* Preserve the first pipeline failure. */
+            }
+            throw error;
         }
     }
+    async #observeGroup(kind, queries, operation) {
+        if (this.#observation.observer === undefined)
+            return operation();
+        const fingerprints = Object.freeze([...queries].map((query) => postgresQueryFingerprint(this.#observation, query)));
+        const observation = startDatabaseObservation(this.#observation.observer, {
+            kind,
+            dialect: "postgres",
+            grammarVersion: POSTGRES_DIALECT_VERSION,
+            transactionDepth: this.#transactionDepth,
+            fingerprints,
+            size: queries.length,
+        });
+        if (observation === undefined)
+            return operation();
+        try {
+            const results = await observation.run(operation);
+            observation.end({ status: "success" });
+            return results;
+        }
+        catch (error) {
+            observation.end(databaseErrorCompletion(error), error);
+            throw error;
+        }
+    }
+    stream(query, options = {}) {
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("start another query stream");
+        this.#rejectOperationDuringTransactionBatch("start a query stream");
+        this.#rejectOperationDuringTransactionCopy("start a query stream");
+        this.#rejectOperationDuringTransactionPipeline("start a query stream");
+        const batchSize = validatePostgresStreamBatchSize(options.batchSize);
+        const config = this.#queryConfig(query);
+        let exposedStream;
+        const stream = new PostgresQueryStream({
+            batchSize,
+            start: async () => {
+                await this.#pool.ensureCursor?.();
+                const client = this.#client ?? (await this.#pool.connect());
+                const release = this.#client === undefined
+                    ? (cleanupError) => client.release(cleanupError === undefined ? undefined : cleanupError instanceof Error ? cleanupError : true)
+                    : undefined;
+                if (client.openCursor === undefined) {
+                    try {
+                        release?.();
+                    }
+                    catch {
+                        /* The missing-capability failure remains primary. */
+                    }
+                    throw new Error("PostgreSQL streaming requires the application-owned pg-cursor package. Install it with: pnpm add pg-cursor");
+                }
+                try {
+                    const cursor = await client.openCursor(config);
+                    return { cursor: cursor, ...(release === undefined ? {} : { release }) };
+                }
+                catch (error) {
+                    this.#recordTransactionOperationFailure(error);
+                    try {
+                        release?.(error);
+                    }
+                    catch {
+                        /* Preserve cursor creation or optional-dependency failures. */
+                    }
+                    throw error;
+                }
+            },
+            ...(this.#client === undefined
+                ? {}
+                : {
+                    onStart: () => {
+                        this.#assertTransactionScopeOpen();
+                        this.#rejectOperationDuringTransactionStream("start another query stream");
+                        this.#rejectOperationDuringTransactionBatch("start a query stream");
+                        this.#rejectOperationDuringTransactionCopy("start a query stream");
+                        this.#rejectOperationDuringTransactionPipeline("start a query stream");
+                        this.#transactionState.activeStreams.add(exposedStream);
+                    },
+                    onClose: () => {
+                        this.#transactionState.activeStreams.delete(exposedStream);
+                        this.#transactionStreams.delete(exposedStream);
+                    },
+                    onError: (error) => this.#recordTransactionOperationFailure(error),
+                }),
+        });
+        const validatedStream = hasQueryResultValidator(query)
+            ? validateQueryResultStream(query, stream, postgresQueryFingerprint(this.#observation, query))
+            : stream;
+        exposedStream =
+            this.#observation.observer === undefined
+                ? validatedStream
+                : observeQueryStream(validatedStream, this.#observation.observer, {
+                    kind: "stream",
+                    dialect: "postgres",
+                    grammarVersion: POSTGRES_DIALECT_VERSION,
+                    transactionDepth: this.#transactionDepth,
+                    fingerprint: postgresQueryFingerprint(this.#observation, query),
+                    prepared: this.#prepared.queries.has(queryResultValidationSource(query)),
+                });
+        if (this.#client !== undefined)
+            this.#transactionStreams.add(exposedStream);
+        return exposedStream;
+    }
+    async #validateRows(query, rows) {
+        if (!hasQueryResultValidator(query))
+            return rows;
+        return validateQueryResultRows(query, rows, postgresQueryFingerprint(this.#observation, query));
+    }
+    async #validateBatch(queries, results) {
+        let validated;
+        const queryList = queries;
+        const resultList = results;
+        for (let index = 0; index < queryList.length; index += 1) {
+            const query = queryList[index];
+            if (!hasQueryResultValidator(query))
+                continue;
+            validated ??= [...resultList];
+            validated[index] = await validateQueryResultRows(query, resultList[index], postgresQueryFingerprint(this.#observation, query));
+        }
+        return (validated ?? results);
+    }
+    async #copyFrom(statement, chunks, options) {
+        assertExecutionCapabilities(this.executionCapabilities, options);
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("start COPY FROM");
+        this.#rejectOperationDuringTransactionBatch("start COPY FROM");
+        this.#rejectOperationDuringTransactionCopy("start another COPY operation");
+        this.#rejectOperationDuringTransactionExecute("start COPY FROM");
+        this.#rejectOperationDuringTransactionPipeline("start COPY FROM");
+        await this.#pool.ensureCopy?.();
+        const client = this.#client ?? (await this.#pool.connect());
+        let sink;
+        const operation = runControlledExecution(options, async () => {
+            if (client.openCopyFrom === undefined) {
+                throw new Error("PostgreSQL COPY requires the application-owned pg-copy-streams package. Install it with: pnpm add pg-copy-streams");
+            }
+            sink = await client.openCopyFrom(statement);
+            try {
+                for await (const chunk of chunks)
+                    await sink.write(chunk);
+                await sink.finish();
+            }
+            catch (error) {
+                try {
+                    await sink.abort(error);
+                }
+                catch {
+                    /* Preserve the producer or database failure. */
+                }
+                throw error;
+            }
+        }, (error) => {
+            void sink?.abort(error).catch(() => undefined);
+        });
+        if (this.#client !== undefined)
+            this.#transactionState.activeCopy = operation;
+        try {
+            await operation;
+            if (this.#client === undefined)
+                client.release();
+        }
+        catch (error) {
+            this.#recordTransactionOperationFailure(error);
+            if (this.#client === undefined) {
+                try {
+                    client.release(error instanceof Error ? error : true);
+                }
+                catch {
+                    /* Preserve the COPY failure. */
+                }
+            }
+            throw error;
+        }
+        finally {
+            if (this.#transactionState.activeCopy === operation)
+                this.#transactionState.activeCopy = undefined;
+        }
+    }
+    #copyTo(statement, options) {
+        assertExecutionCapabilities(this.executionCapabilities, options);
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("start COPY TO");
+        this.#rejectOperationDuringTransactionBatch("start COPY TO");
+        this.#rejectOperationDuringTransactionCopy("start COPY TO");
+        this.#rejectOperationDuringTransactionPipeline("start COPY TO");
+        let exposedStream;
+        const stream = new PostgresQueryStream({
+            batchSize: 1,
+            start: async () => {
+                await this.#pool.ensureCopy?.();
+                const client = this.#client ?? (await this.#pool.connect());
+                const release = this.#client === undefined
+                    ? (cleanupError) => client.release(cleanupError === undefined ? undefined : cleanupError instanceof Error ? cleanupError : true)
+                    : undefined;
+                if (client.openCopyTo === undefined) {
+                    try {
+                        release?.();
+                    }
+                    catch {
+                        /* The missing optional dependency remains primary. */
+                    }
+                    throw new Error("PostgreSQL COPY requires the application-owned pg-copy-streams package. Install it with: pnpm add pg-copy-streams");
+                }
+                try {
+                    const source = await client.openCopyTo(statement);
+                    return {
+                        cursor: {
+                            async read() {
+                                const result = await runControlledExecution(options, () => source.next(), (error) => {
+                                    void source.abort(error).catch(() => undefined);
+                                });
+                                return result.done === true ? [] : [result.value];
+                            },
+                            close: () => source.close(),
+                        },
+                        ...(release === undefined ? {} : { release }),
+                    };
+                }
+                catch (error) {
+                    this.#recordTransactionOperationFailure(error);
+                    try {
+                        release?.(error);
+                    }
+                    catch {
+                        /* Preserve source creation or optional-dependency failures. */
+                    }
+                    throw error;
+                }
+            },
+            ...(this.#client === undefined
+                ? {}
+                : {
+                    onStart: () => {
+                        this.#assertTransactionScopeOpen();
+                        this.#rejectOperationDuringTransactionStream("start COPY TO");
+                        this.#rejectOperationDuringTransactionBatch("start COPY TO");
+                        this.#rejectOperationDuringTransactionCopy("start COPY TO");
+                        this.#rejectOperationDuringTransactionPipeline("start COPY TO");
+                        this.#transactionState.activeStreams.add(exposedStream);
+                    },
+                    onClose: () => {
+                        this.#transactionState.activeStreams.delete(exposedStream);
+                        this.#transactionStreams.delete(exposedStream);
+                    },
+                    onError: (error) => this.#recordTransactionOperationFailure(error),
+                }),
+        });
+        exposedStream = stream;
+        if (this.#client !== undefined)
+            this.#transactionStreams.add(exposedStream);
+        return exposedStream;
+    }
+    prepare(statementName, factory) {
+        this.#assertTransactionScopeOpen();
+        return preparePostgresQuery(this.#prepared, postgresRenderer, statementName, factory);
+    }
+    async transaction(fn) {
+        if (this.#observation.observer === undefined)
+            return this.#transactionUnobserved(fn);
+        const observation = startDatabaseObservation(this.#observation.observer, {
+            kind: "transaction",
+            dialect: "postgres",
+            grammarVersion: POSTGRES_DIALECT_VERSION,
+            transactionDepth: this.#transactionDepth + 1,
+        });
+        if (observation === undefined)
+            return this.#transactionUnobserved(fn);
+        try {
+            const result = await observation.run(() => this.#transactionUnobserved(fn));
+            observation.end({ status: "success" });
+            return result;
+        }
+        catch (error) {
+            observation.end(databaseErrorCompletion(error), error);
+            throw error;
+        }
+    }
+    async #transactionUnobserved(fn) {
+        this.#assertTransactionScopeOpen();
+        this.#rejectOperationDuringTransactionStream("start a nested transaction");
+        this.#rejectOperationDuringTransactionBatch("start a nested transaction");
+        this.#rejectOperationDuringTransactionCopy("start a nested transaction");
+        this.#rejectOperationDuringTransactionPipeline("start a nested transaction");
+        if (this.#client !== undefined)
+            return this.#nestedTransaction(fn);
+        const client = await this.#pool.connect();
+        const scope = new _a(this.#pool, client, this.#parsers, false, 1, this.#prepared, this.#observation, {
+            activeBatch: undefined,
+            activeCopy: undefined,
+            activeExecutes: new Set(),
+            activePipeline: undefined,
+            activeStreams: new Set(),
+            discardLease: false,
+            leaseReleased: false,
+            firstDatabaseOperationError: undefined,
+            unsafe: false,
+            unsafeDepth: undefined,
+            unsafeError: undefined,
+            valid: true,
+        });
+        let result;
+        try {
+            try {
+                await client.query("BEGIN");
+            }
+            catch (error) {
+                scope.#recordTransactionOperationFailure(error);
+                throw error;
+            }
+            try {
+                result = await fn(scope);
+            }
+            finally {
+                scope.#transactionScopeOpen = false;
+                scope.#transactionState.valid = false;
+            }
+            scope.#throwIfTransactionCannotCommit();
+            await scope.#rejectLeakedTransactionWork();
+            try {
+                await client.query("COMMIT");
+            }
+            catch (error) {
+                scope.#recordTransactionOperationFailure(error);
+                throw error;
+            }
+        }
+        catch (error) {
+            scope.#transactionScopeOpen = false;
+            scope.#transactionState.valid = false;
+            await scope.#settleTransactionExecutesPreservingError();
+            await scope.#closeTransactionStreamsPreservingError();
+            await scope.#settleTransactionPipelinePreservingError();
+            await scope.#settleTransactionBatchPreservingError();
+            await scope.#settleTransactionCopyPreservingError();
+            if (!scope.#transactionState.leaseReleased) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch (cleanupError) {
+                    scope.#markTransactionStateUnsafe(cleanupError);
+                    /* Preserve the original error. */
+                }
+                try {
+                    client.release(scope.#transactionLeaseReleaseError());
+                }
+                catch {
+                    /* Preserve the original error. */
+                }
+            }
+            throw error;
+        }
+        client.release(scope.#transactionLeaseReleaseError());
+        return result;
+    }
     async #nestedTransaction(fn) {
         const client = this.#client;
         const depth = this.#transactionDepth + 1;
         const savepoint = `typed_sql_${depth}`;
-        await client.query(`SAVEPOINT ${savepoint}`);
         try {
-            const result = await fn(new _a(this.#pool, client, this.#parsers, false, depth));
-            await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+            await client.query(`SAVEPOINT ${savepoint}`);
+        }
+        catch (error) {
+            this.#recordTransactionOperationFailure(error);
+            throw error;
+        }
+        const scope = new _a(this.#pool, client, this.#parsers, false, depth, this.#prepared, this.#observation, this.#transactionState);
+        try {
+            let result;
+            try {
+                result = await fn(scope);
+            }
+            finally {
+                scope.#transactionScopeOpen = false;
+            }
+            if (!scope.#transactionState.valid) {
+                throw new Error("The parent PostgreSQL transaction scope ended before its nested transaction completed");
+            }
+            scope.#throwIfTransactionCannotCommit();
+            await scope.#rejectLeakedTransactionWork();
+            try {
+                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+            }
+            catch (error) {
+                scope.#recordTransactionOperationFailure(error);
+                throw error;
+            }
             return result;
         }
         catch (error) {
-            await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+            await scope.#settleTransactionExecutesPreservingError();
+            await scope.#closeTransactionStreamsPreservingError();
+            await scope.#settleTransactionPipelinePreservingError();
+            await scope.#settleTransactionBatchPreservingError();
+            await scope.#settleTransactionCopyPreservingError();
+            if (scope.#transactionState.valid && !scope.#transactionState.leaseReleased) {
+                try {
+                    await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    scope.#recoverTransactionStateAfterSavepoint(depth);
+                }
+                catch (cleanupError) {
+                    scope.#markTransactionStateUnsafe(cleanupError);
+                    /* Preserve the original callback, query, or release error. */
+                }
+            }
             throw error;
         }
     }
+    #queryConfig(query) {
+        const prepared = this.#prepared.queries.get(queryResultValidationSource(query));
+        const rendered = prepared?.rendered ?? renderQuery(query, postgresRenderer);
+        return {
+            ...(prepared === undefined ? {} : { name: prepared.statementName }),
+            text: rendered.text,
+            values: rendered.values.map(encodeValue),
+            types: this.#parsers,
+        };
+    }
+    async #executeBatch(client, queries) {
+        const results = [];
+        for (const value of queries) {
+            this.#assertTransactionScopeOpen();
+            const query = value;
+            const result = await client.query(this.#queryConfig(query));
+            results.push(result.rows);
+        }
+        return results;
+    }
+    async #executePipeline(client, configs) {
+        const operations = [];
+        let dispatchFailed = false;
+        let dispatchError;
+        for (const config of configs) {
+            try {
+                operations.push(client.query(config));
+            }
+            catch (error) {
+                dispatchFailed = true;
+                dispatchError = error;
+                break;
+            }
+        }
+        const settlements = await Promise.allSettled(operations);
+        if (dispatchFailed)
+            throw dispatchError;
+        const results = [];
+        for (const settlement of settlements) {
+            if (settlement.status === "rejected")
+                throw settlement.reason;
+            results.push(settlement.value.rows);
+        }
+        return results;
+    }
+    #assertPipelineClient(client) {
+        if (client.pipeline !== true) {
+            throw new Error("PostgreSQL query pipelining requires pg 8.23.0 or newer and pipeline mode. Create the application-owned Pool with { pipeline: true }");
+        }
+    }
+    async #rejectLeakedTransactionWork() {
+        const leakedStreams = this.#transactionStreams.size > 0 || this.#transactionState.activeStreams.size > 0;
+        const leakedExecutes = this.#transactionExecutes.size > 0 || this.#transactionState.activeExecutes.size > 0;
+        const leakedPipeline = this.#transactionState.activePipeline !== undefined;
+        const leakedBatch = this.#transactionState.activeBatch !== undefined;
+        const leakedCopy = this.#transactionState.activeCopy !== undefined;
+        if (!leakedStreams && !leakedExecutes && !leakedPipeline && !leakedBatch && !leakedCopy)
+            return;
+        await this.#settleTransactionExecutesPreservingError();
+        await this.#closeTransactionStreamsPreservingError();
+        await this.#settleTransactionPipelinePreservingError();
+        await this.#settleTransactionBatchPreservingError();
+        await this.#settleTransactionCopyPreservingError();
+        if (leakedExecutes) {
+            throw new Error("A PostgreSQL transaction callback returned before an execute operation completed; await execute before returning");
+        }
+        if (leakedBatch) {
+            throw new Error("A PostgreSQL transaction callback returned before its query batch completed; await the batch before returning");
+        }
+        if (leakedPipeline) {
+            throw new Error("A PostgreSQL transaction callback returned before its query pipeline completed; await the pipeline before returning");
+        }
+        if (leakedCopy) {
+            throw new Error("A PostgreSQL transaction callback returned before its COPY operation completed; await COPY before returning");
+        }
+        throw new Error("A PostgreSQL transaction callback returned before all query streams were completed or closed");
+    }
+    async #settleTransactionExecutesPreservingError() {
+        const operations = new Set([...this.#transactionExecutes, ...this.#transactionState.activeExecutes]);
+        for (const operation of operations) {
+            try {
+                await operation;
+            }
+            catch {
+                /* The callback or transaction misuse error remains primary. */
+            }
+        }
+    }
+    async #closeTransactionStreamsPreservingError() {
+        const streams = new Set([...this.#transactionStreams, ...this.#transactionState.activeStreams]);
+        for (const stream of streams) {
+            try {
+                await stream.close();
+            }
+            catch {
+                /* The callback or transaction misuse error remains primary. */
+            }
+        }
+    }
+    async #settleTransactionBatchPreservingError() {
+        const operation = this.#transactionState.activeBatch;
+        if (operation === undefined)
+            return;
+        try {
+            await operation;
+        }
+        catch {
+            /* The callback or transaction misuse error remains primary. */
+        }
+    }
+    async #settleTransactionPipelinePreservingError() {
+        const operation = this.#transactionState.activePipeline;
+        if (operation === undefined)
+            return;
+        try {
+            await operation;
+        }
+        catch {
+            /* The callback or transaction misuse error remains primary. */
+        }
+    }
+    async #settleTransactionCopyPreservingError() {
+        const operation = this.#transactionState.activeCopy;
+        if (operation === undefined)
+            return;
+        try {
+            await operation;
+        }
+        catch {
+            /* The callback or transaction misuse error remains primary. */
+        }
+    }
+    #rejectOperationDuringTransactionStream(operation) {
+        if (this.#client !== undefined && this.#transactionState.activeStreams.size > 0) {
+            throw new Error(`Cannot ${operation} while a PostgreSQL transaction query stream is still open; complete or close the stream first`);
+        }
+    }
+    #rejectOperationDuringTransactionBatch(operation) {
+        if (this.#client !== undefined && this.#transactionState.activeBatch !== undefined) {
+            throw new Error(`Cannot ${operation} while a PostgreSQL transaction query batch is still running; await the batch first`);
+        }
+    }
+    #rejectOperationDuringTransactionCopy(operation) {
+        if (this.#client !== undefined && this.#transactionState.activeCopy !== undefined) {
+            throw new Error(`Cannot ${operation} while a PostgreSQL transaction COPY operation is still running; await COPY first`);
+        }
+    }
+    #rejectOperationDuringTransactionExecute(operation) {
+        if (this.#client !== undefined && this.#transactionState.activeExecutes.size > 0) {
+            throw new Error(`Cannot ${operation} while a PostgreSQL transaction execute operation is still running; await execute first`);
+        }
+    }
+    #rejectOperationDuringTransactionPipeline(operation) {
+        if (this.#client !== undefined && this.#transactionState.activePipeline !== undefined) {
+            throw new Error(`Cannot ${operation} while a PostgreSQL transaction query pipeline is still running; await the pipeline first`);
+        }
+    }
+    #recordTransactionOperationFailure(error) {
+        if (this.#client === undefined)
+            return;
+        if (!this.#transactionOperationFailed) {
+            this.#transactionOperationFailed = true;
+            this.#transactionOperationError = error;
+        }
+        this.#markTransactionStateUnsafe(error);
+    }
+    #markTransactionStateUnsafe(error) {
+        if (!this.#transactionState.discardLease) {
+            this.#transactionState.discardLease = true;
+            this.#transactionState.firstDatabaseOperationError = error;
+        }
+        if (!this.#transactionState.unsafe ||
+            this.#transactionState.unsafeDepth === undefined ||
+            this.#transactionDepth < this.#transactionState.unsafeDepth) {
+            this.#transactionState.unsafe = true;
+            this.#transactionState.unsafeDepth = this.#transactionDepth;
+            this.#transactionState.unsafeError = error;
+        }
+    }
+    #recoverTransactionStateAfterSavepoint(depth) {
+        if (this.#transactionState.unsafeDepth === undefined || this.#transactionState.unsafeDepth < depth)
+            return;
+        this.#transactionState.unsafe = false;
+        this.#transactionState.unsafeDepth = undefined;
+        this.#transactionState.unsafeError = undefined;
+    }
+    #transactionLeaseReleaseError() {
+        if (!this.#transactionState.discardLease)
+            return undefined;
+        return this.#transactionState.firstDatabaseOperationError instanceof Error
+            ? this.#transactionState.firstDatabaseOperationError
+            : true;
+    }
+    #throwIfTransactionCannotCommit() {
+        if (this.#transactionOperationFailed) {
+            if (this.#transactionOperationError !== undefined)
+                throw this.#transactionOperationError;
+            throw new Error("A PostgreSQL transaction operation failed and the transaction cannot be committed");
+        }
+        if (this.#transactionState.unsafe) {
+            throw new Error("The PostgreSQL transaction connection did not complete recovery and cannot be committed", {
+                cause: this.#transactionState.unsafeError,
+            });
+        }
+    }
+    #assertTransactionScopeOpen() {
+        if (this.#client === undefined)
+            return;
+        if (!this.#transactionScopeOpen || !this.#transactionState.valid) {
+            throw new Error("This PostgreSQL transaction scope has ended and can no longer be used");
+        }
+        if (this.#transactionOperationFailed) {
+            throw new Error("This PostgreSQL transaction scope cannot continue after a database operation failed", {
+                cause: this.#transactionOperationError,
+            });
+        }
+        if (this.#transactionState.unsafe) {
+            throw new Error("The PostgreSQL transaction cannot continue until its failed operation is rolled back", {
+                cause: this.#transactionState.unsafeError,
+            });
+        }
+    }
     async close() {
         if (this.#client !== undefined)
             throw new Error("Cannot close a database from inside a transaction");
@@ -185,6 +1086,6 @@ class PostgresDatabaseImplementation {
 }
 _a = PostgresDatabaseImplementation;
 export function createPostgresDatabase(options) {
-    return new PostgresDatabaseImplementation(options.pool, undefined, createPostgresTypeParsers(options.typePolicy ?? defaultPolicy, options.decimal, options.fallbackTypeParsers), options.ownsPool ?? false, 0);
+    return new PostgresDatabaseImplementation(options.pool, undefined, createPostgresTypeParsers(options.typePolicy ?? defaultPolicy, options.decimal, options.fallbackTypeParsers), options.ownsPool ?? false, 0, createPostgresPreparedQueryState(), createPostgresObservationState(options.observer));
 }
 //# sourceMappingURL=runtime.js.map