uql-orm 0.28.2 → 0.30.0

package/dist/mysql/mysql2Querier.js

@@ -27,7 +27,13 @@ export class MySql2Querier extends AbstractPoolQuerier {
             stream.destroy();
         }
     }
-    async releaseConn(conn) {
+    async releaseConn(conn, discard) {
+        // mysql2 resets nothing on release, so a connection the pool takes back after a failed rollback
+        // hands the next caller someone else's open transaction. `destroy` drops it from the pool instead.
+        if (discard) {
+            conn.destroy();
+            return;
+        }
         await conn.release();
     }
 }

package/dist/nestjs/uqlContextInterceptor.d.ts

@@ -3,8 +3,8 @@ import { Observable } from 'rxjs';
 import type { UqlContext } from '../type/index.js';
 /**
  * Runs each request inside `withContext`, so parameterized/`security` filters (multi-tenancy, RLS)
- * are scoped automatically for every query in the request - including relations, cascades, and
- * `@Transactional` services. Wired for you by {@link UqlModule.forRoot} when you pass `getContext`.
+ * are scoped automatically for every query in the request - including relations, cascades, and the
+ * queries a transaction runs. Wired for you by {@link UqlModule.forRoot} when you pass `getContext`.
  */
 export declare class UqlContextInterceptor<Req = unknown> implements NestInterceptor {
     private readonly getContext;

package/dist/nestjs/uqlContextInterceptor.js

@@ -37,8 +37,8 @@ import { Observable } from 'rxjs';
 import { withContext } from '../context/context.js';
 /**
  * Runs each request inside `withContext`, so parameterized/`security` filters (multi-tenancy, RLS)
- * are scoped automatically for every query in the request - including relations, cascades, and
- * `@Transactional` services. Wired for you by {@link UqlModule.forRoot} when you pass `getContext`.
+ * are scoped automatically for every query in the request - including relations, cascades, and the
+ * queries a transaction runs. Wired for you by {@link UqlModule.forRoot} when you pass `getContext`.
  */
 let UqlContextInterceptor = (() => {
     let _classDecorators = [Injectable()];

package/dist/nestjs/uqlModule.d.ts

@@ -2,9 +2,9 @@ import { type DynamicModule, type FactoryProvider } from '@nestjs/common';
 import type { QuerierPool, UqlContext } from '../type/index.js';
 /**
  * Injection token for the configured {@link QuerierPool} - for injecting into your own
- * providers. UQL's own machinery (`getQuerier`, `querierMiddleware`, `createFetchHandler`,
- * `@Transactional`) reads the default pool set by {@link UqlModule.forRoot}, not this token,
- * so overriding the provider does not redirect UQL internals.
+ * providers. UQL's own machinery (`getQuerier`, `querierMiddleware`, `createFetchHandler`) reads
+ * the default pool set by {@link UqlModule.forRoot}, not this token, so overriding the provider
+ * does not redirect UQL internals.
  */
 export declare const UQL_QUERIER_POOL: unique symbol;
 /** Shared by {@link UqlModuleOptions} and {@link UqlModuleAsyncOptions}. */

package/dist/nestjs/uqlModule.js

@@ -38,16 +38,15 @@ import { setQuerierPool } from '../options.js';
 import { UqlContextInterceptor } from './uqlContextInterceptor.js';
 /**
  * Injection token for the configured {@link QuerierPool} - for injecting into your own
- * providers. UQL's own machinery (`getQuerier`, `querierMiddleware`, `createFetchHandler`,
- * `@Transactional`) reads the default pool set by {@link UqlModule.forRoot}, not this token,
- * so overriding the provider does not redirect UQL internals.
+ * providers. UQL's own machinery (`getQuerier`, `querierMiddleware`, `createFetchHandler`) reads
+ * the default pool set by {@link UqlModule.forRoot}, not this token, so overriding the provider
+ * does not redirect UQL internals.
  */
 export const UQL_QUERIER_POOL = Symbol('UQL_QUERIER_POOL');
 /**
  * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
- * `querierMiddleware` (express platform), `createFetchHandler`, and `@Transactional` work unchanged),
- * optionally scopes every request to a {@link UqlContext} (multi-tenancy), and ends the pool on
- * application shutdown.
+ * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
+ * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
  */
 /**
  * Ends the pool when Nest shuts down.

package/dist/postgres/abstractPgQuerier.d.ts

@@ -9,7 +9,8 @@ export interface PgAnyClient {
     query(stream: object): AsyncIterable<RawRow> & {
         destroy(): void;
     };
-    release(): void | Promise<void>;
+    /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
+    release(discard?: boolean): void | Promise<void>;
 }
 /**
  * Shared base class for Postgres-compatible queriers (standard pg, CockroachDB, Neon).
@@ -19,5 +20,5 @@ export declare abstract class AbstractPgQuerier<C extends PgAnyClient, D extends
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
-    protected releaseConn(conn: C): Promise<void>;
+    protected releaseConn(conn: C, discard: boolean): Promise<void>;
 }

package/dist/postgres/abstractPgQuerier.js

@@ -26,7 +26,7 @@ export class AbstractPgQuerier extends AbstractPoolQuerier {
             stream.destroy();
         }
     }
-    async releaseConn(conn) {
-        await conn.release();
+    async releaseConn(conn, discard) {
+        await conn.release(discard);
     }
 }

package/dist/querier/abstractPoolQuerier.d.ts

@@ -8,6 +8,6 @@ export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier
     protected getConn(): C;
     constructor(dialect: AbstractSqlDialect, connect: () => Promise<C>, extra?: ExtraOptions | undefined);
     protected lazyConnect(): Promise<void>;
-    internalRelease(): Promise<void>;
-    protected abstract releaseConn(conn: C): Promise<void>;
+    internalRelease(discard: boolean): Promise<void>;
+    protected abstract releaseConn(conn: C, discard: boolean): Promise<void>;
 }

package/dist/querier/abstractPoolQuerier.js

@@ -1,4 +1,3 @@
-import { throwPendingTransaction } from '../util/index.js';
 import { AbstractSqlQuerier } from './abstractSqlQuerier.js';
 export class AbstractPoolQuerier extends AbstractSqlQuerier {
     connect;
@@ -15,16 +14,17 @@ export class AbstractPoolQuerier extends AbstractSqlQuerier {
         this.extra = extra;
     }
     async lazyConnect() {
+        await super.lazyConnect();
         this.conn ??= await this.connect();
     }
-    async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throwPendingTransaction();
-        }
-        if (!this.conn) {
+    async internalRelease(discard) {
+        const conn = this.conn;
+        if (!conn) {
             return;
         }
-        await this.releaseConn(this.conn);
+        // Cleared even when the hand-back fails: keeping a connection the pool has already been given
+        // back means the next `release()` returns it twice, which pg reports as an already-released client.
         this.conn = undefined;
+        await this.releaseConn(conn, discard);
     }
 }

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { ExtraOptions, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QueryPopulate, QuerySearch, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QueryPopulate, QuerySearch, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 /**
  * Base class for all database queriers.
@@ -12,6 +12,11 @@ export declare abstract class AbstractQuerier implements Querier {
      * and ensuring that the database connection is used safely across concurrent calls.
      */
     private taskQueue;
+    /**
+     * A querier is one unit of work, so releasing ends it. Checked where each backend reaches for its
+     * connection, on every driver and not just the pooled ones.
+     */
+    protected released: boolean;
     protected readonly logger: LoggerWrapper;
     constructor(extra?: ExtraOptions | undefined);
     protected validateProjectionQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
@@ -80,16 +85,16 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     protected abstract internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
-    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
+    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Delete records matching the query. Soft-deletes when the entity has a soft-delete field (unless
@@ -99,9 +104,18 @@ export declare abstract class AbstractQuerier implements Querier {
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
+    /**
+     * The rows a delete is about to take, loaded only when a hook or listener is there to receive
+     * them: the round trip is pure overhead for the (common) delete nobody is watching, and
+     * `internalDeleteMany` has its own fast path that never reads the rows at all.
+     *
+     * `undefined` means nobody was watching, which is not the same as the empty array meaning nothing
+     * matched - the caller deletes by `q` for the first and skips the statement entirely for the second.
+     */
+    private findDoomed;
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
@@ -121,8 +135,8 @@ export declare abstract class AbstractQuerier implements Querier {
      * below were got wrong by code that hand-rolled it:
      *
      * - `beginTransaction` connects before it begins, so a refused connection lands in the catch with no
-     *   transaction open. Rolling back regardless threw `not a pending transaction`, and that replaced the
-     *   real cause: a wrong password surfaced as a transaction-state error.
+     *   transaction open. `rollbackTransaction` is a no-op there rather than an error, which is why a
+     *   wrong password no longer surfaces as a transaction-state error.
      * - A rollback that fails too is a consequence of the original failure, not news, so it must not
      *   replace it either.
      *
@@ -132,18 +146,19 @@ export declare abstract class AbstractQuerier implements Querier {
      * one afterwards.
      */
     transaction<T>(callback: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    /** Whether anything at all - a global listener or the entity itself - handles `event`. */
+    private hasHook;
     /**
      * Emit a lifecycle hook event for the given entity.
      * Fires global listeners first, then entity-level hooks.
      */
     private emitHook;
-    releaseIfFree(): Promise<void>;
     /**
-     * Schedules a task to be executed serially in the querier instance.
-     * This is used by the @Serialized decorator to protect database-level operations.
+     * Runs `task` after everything already queued on this querier, one at a time.
      *
-     * @param task - The async task to execute.
-     * @returns A promise that resolves with the task's result.
+     * @remarks Not re-entrant: only one task runs at a time, so a serialized method awaited from inside
+     * another one would wait for a task queued behind itself. Callers below keep their `serialize` calls
+     * sequential rather than nested.
      */
     protected serialize<T>(task: () => Promise<T>): Promise<T>;
     /**
@@ -157,9 +172,23 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     protected timed<T>(query: string, values: unknown[] | undefined, task: () => Promise<T>): Promise<T>;
     abstract beginTransaction(opts?: TransactionOptions): Promise<void>;
+    /** Strict: this is the check that catches a forgotten `beginTransaction`. */
     abstract commitTransaction(): Promise<void>;
+    /**
+     * Rolls the open transaction back, or does nothing when there is none: it is called from `catch` and
+     * `finally`, where the caller cannot know whether `beginTransaction` got far enough to open one.
+     */
     abstract rollbackTransaction(): Promise<void>;
-    protected abstract internalRelease(): Promise<void>;
+    /**
+     * Rolls back an unfinished transaction, then hands the connection back.
+     *
+     * @remarks Refusing to release was the opposite of safe: the throw came *before* the connection went
+     * back, so it destroyed the error that got here and cost the pool a connection with a live `BEGIN` on
+     * it. It is also the only option `await using` can reach, which calls `Symbol.asyncDispose` with no
+     * arguments and discards what it returns.
+     */
     release(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
+    /** `discard` means the connection must not be reused; backends with a pool evict it instead. */
+    protected abstract internalRelease(discard: boolean): Promise<void>;
 }

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,20 @@
 import { getMeta } from '../entity/index.js';
-import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, } from '../util/index.js';
+import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
+/**
+ * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
+ * `{ $where: id }`, and a nullish `$where` is *no filter*, so an unchecked one addresses the whole
+ * table. An entity declares its id optional, which puts `undefined` inside `IdValue<E>`, and the
+ * HTTP layer reaches these methods with parsed JSON regardless, so the guard belongs at runtime.
+ *
+ * Its callers are all `async` so this surfaces as a rejection on every one of them: a guard that
+ * threw synchronously from some and rejected from others would escape a caller's `.catch()`.
+ */
+function assertIdValue(entity, id) {
+    if (id === undefined || id === null) {
+        throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
+    }
+}
 /**
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
@@ -13,6 +27,11 @@ export class AbstractQuerier {
      * and ensuring that the database connection is used safely across concurrent calls.
      */
     taskQueue = Promise.resolve();
+    /**
+     * A querier is one unit of work, so releasing ends it. Checked where each backend reaches for its
+     * connection, on every driver and not just the pooled ones.
+     */
+    released = false;
     logger;
     constructor(extra) {
         this.extra = extra;
@@ -60,6 +79,7 @@ export class AbstractQuerier {
         return [$entity, query, maybeQueryOrOpts];
     }
     async findOneById(entity, id, q = {}, opts) {
+        assertIdValue(entity, id);
         return this.findOne(entity, { ...q, $where: augmentWhere(getMeta(entity), q.$where, id) }, opts);
     }
     async findOne(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
@@ -110,7 +130,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterInsert', payload);
         return ids;
     }
-    updateOneById(entity, id, payload, opts) {
+    async updateOneById(entity, id, payload, opts) {
+        assertIdValue(entity, id);
         return this.updateMany(entity, { $where: id }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
@@ -119,7 +140,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterUpdate', [payload]);
         return changes;
     }
-    restoreOneById(entity, id) {
+    async restoreOneById(entity, id) {
+        assertIdValue(entity, id);
         return this.restoreMany(entity, { $where: id });
     }
     async restoreMany(entity, q) {
@@ -132,16 +154,41 @@ export class AbstractQuerier {
             filters: { softDelete: false },
         });
     }
-    deleteOneById(entity, id, opts) {
+    async deleteOneById(entity, id, opts) {
+        assertIdValue(entity, id);
         return this.deleteMany(entity, { $where: id }, opts);
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
-        await this.emitHook(entity, 'beforeDelete', []);
-        const changes = await this.internalDeleteMany(entity, q, opts);
-        await this.emitHook(entity, 'afterDelete', []);
+        const doomed = await this.findDoomed(entity, q, opts);
+        if (doomed?.length === 0) {
+            return 0;
+        }
+        // Where a snapshot was taken, the statement names those rows rather than resolving `q` a second
+        // time. Two reads of one `$limit` with no total order are free to disagree, which would fire the
+        // hooks for one row and delete another; naming them also spares the second read.
+        const target = doomed ? { $where: doomed.map((it) => it[getMeta(entity).id]) } : q;
+        await this.emitHook(entity, 'beforeDelete', doomed ?? []);
+        const changes = await this.internalDeleteMany(entity, target, opts);
+        await this.emitHook(entity, 'afterDelete', doomed ?? []);
         return changes;
     }
+    /**
+     * The rows a delete is about to take, loaded only when a hook or listener is there to receive
+     * them: the round trip is pure overhead for the (common) delete nobody is watching, and
+     * `internalDeleteMany` has its own fast path that never reads the rows at all.
+     *
+     * `undefined` means nobody was watching, which is not the same as the empty array meaning nothing
+     * matched - the caller deletes by `q` for the first and skips the statement entirely for the second.
+     */
+    async findDoomed(entity, q, opts) {
+        if (!this.hasHook(entity, 'beforeDelete') && !this.hasHook(entity, 'afterDelete')) {
+            return undefined;
+        }
+        // A hard delete takes already-soft-deleted rows too, so reading them back has to see them.
+        const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
+        return this.internalFindMany(entity, q, findOpts);
+    }
     async saveOne(entity, payload) {
         const [id] = await this.saveMany(entity, [payload]);
         return id;
@@ -365,8 +412,8 @@ export class AbstractQuerier {
      * below were got wrong by code that hand-rolled it:
      *
      * - `beginTransaction` connects before it begins, so a refused connection lands in the catch with no
-     *   transaction open. Rolling back regardless threw `not a pending transaction`, and that replaced the
-     *   real cause: a wrong password surfaced as a transaction-state error.
+     *   transaction open. `rollbackTransaction` is a no-op there rather than an error, which is why a
+     *   wrong password no longer surfaces as a transaction-state error.
      * - A rollback that fails too is a consequence of the original failure, not news, so it must not
      *   replace it either.
      *
@@ -386,50 +433,42 @@ export class AbstractQuerier {
             return res;
         }
         catch (err) {
-            if (this.hasOpenTransaction) {
-                await this.rollbackTransaction().catch(() => { });
-            }
+            // Reported rather than thrown: the error being unwound is the useful one. Inline rather than
+            // shared with `release` below, because this method is grafted onto plain objects in tests and
+            // every `this.x` it reaches for has to exist there too.
+            await this.rollbackTransaction().catch((rollbackErr) => {
+                this.logger.logError('rollback failed', rollbackErr);
+            });
             throw err;
         }
     }
+    /** Whether anything at all - a global listener or the entity itself - handles `event`. */
+    hasHook(entity, event) {
+        return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
+    }
     /**
      * Emit a lifecycle hook event for the given entity.
      * Fires global listeners first, then entity-level hooks.
      */
     async emitHook(entity, event, payloads) {
-        const listeners = this.extra?.listeners;
-        const meta = getMeta(entity);
-        const registrations = meta.hooks?.[event];
-        // Fast bail-out: skip if no listeners and no entity hooks
-        if (!listeners?.length && !registrations?.length)
+        if (!this.hasHook(entity, event))
             return;
-        // Fire global listeners first
-        if (listeners?.length) {
-            for (const listener of listeners) {
-                const fn = listener[event];
-                if (fn) {
-                    const result = fn({ entity, querier: this, payloads, event });
-                    if (result instanceof Promise)
-                        await result;
-                }
+        for (const listener of this.extra?.listeners ?? []) {
+            const fn = listener[event];
+            if (fn) {
+                const result = fn({ entity, querier: this, payloads, event });
+                if (result instanceof Promise)
+                    await result;
             }
         }
-        // Fire entity-level hooks
-        if (registrations?.length) {
-            await runHooks(entity, event, payloads, { querier: this });
-        }
-    }
-    async releaseIfFree() {
-        if (!this.hasOpenTransaction) {
-            await this.internalRelease();
-        }
+        await runHooks(entity, event, payloads, { querier: this });
     }
     /**
-     * Schedules a task to be executed serially in the querier instance.
-     * This is used by the @Serialized decorator to protect database-level operations.
+     * Runs `task` after everything already queued on this querier, one at a time.
      *
-     * @param task - The async task to execute.
-     * @returns A promise that resolves with the task's result.
+     * @remarks Not re-entrant: only one task runs at a time, so a serialized method awaited from inside
+     * another one would wait for a task queued behind itself. Callers below keep their `serialize` calls
+     * sequential rather than nested.
      */
     async serialize(task) {
         const res = this.taskQueue.then(task);
@@ -457,8 +496,28 @@ export class AbstractQuerier {
             this.logger.logQuery(query, values, Math.round(performance.now() - startTime));
         }
     }
+    /**
+     * Rolls back an unfinished transaction, then hands the connection back.
+     *
+     * @remarks Refusing to release was the opposite of safe: the throw came *before* the connection went
+     * back, so it destroyed the error that got here and cost the pool a connection with a live `BEGIN` on
+     * it. It is also the only option `await using` can reach, which calls `Symbol.asyncDispose` with no
+     * arguments and discards what it returns.
+     */
     async release() {
-        return this.serialize(() => this.internalRelease());
+        let discard = false;
+        if (this.hasOpenTransaction) {
+            this.logger.logWarn('rolling back a transaction left open at release');
+            // The rollback doubles as a health check. One that succeeds proves the connection round-trips and
+            // left no transaction behind, so it is safe to reuse. One that fails leaves a session state
+            // nothing here can name, and the next borrower would inherit it.
+            await this.rollbackTransaction().catch((err) => {
+                this.logger.logError('rollback failed; discarding the connection', err);
+                discard = true;
+            });
+        }
+        this.released = true;
+        return this.serialize(() => this.internalRelease(discard));
     }
     async [Symbol.asyncDispose]() {
         return this.release();

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -35,14 +35,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -27,8 +27,9 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     protected loadInsertIdIncrement(): Promise<number>;
     /**
-     * Hook for subclasses (e.g. pool queriers) to establish a connection.
-     * Called before every query but outside the timing window.
+     * Hook for subclasses (e.g. pool queriers) to establish a connection. Called before every query and
+     * before `BEGIN`, outside the timing window, which makes it the one place a released querier is
+     * caught for every SQL backend.
      */
     protected lazyConnect(): Promise<void>;
     all<T>(query: string, values?: unknown[]): Promise<T[]>;
@@ -63,13 +64,23 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
+    private settleIds;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
     beginTransaction(opts?: TransactionOptions): Promise<void>;
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
+    /**
+     * Only a statement that succeeded ends the transaction. A `COMMIT` that fails can leave it open
+     * (SQLite answers `SQLITE_BUSY` and keeps it), so the flag has to stay set for the `catch` in
+     * {@link AbstractQuerier.transaction} or {@link AbstractQuerier.release} to roll it back.
+     */
+    private endTransactionWith;
+    /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
+    private runTransactionCommand;
 }