uql-orm 0.28.1 → 0.29.0

package/README.md

@@ -32,9 +32,7 @@
 npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @tursodatabase/serverless, @libsql/client
 ```
 
-That is the whole install. Decorators are the standard TC39 ones, so there is no `reflect-metadata`
-and no compiler flag to turn on ([setup](https://uql-orm.dev/getting-started)), and the
-[imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
+That is the whole install ([setup](https://uql-orm.dev/getting-started)), and the [imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
 
 ```ts
 await pool.findMany(User, {
@@ -51,14 +49,14 @@ from the browser to the server. The same object runs on every supported database
 ## Why UQL?
 
 - **Serializable queries (JSON), not method chains.** Plain JSON in, typed rows out. No DSL to learn.
-- **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. Entities are plain classes: no `.prisma` file, no generated client, no build step.
+- **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. Entities are plain classes on the standard TC39 decorators: no `.prisma` file, no generated client, no `reflect-metadata`, no `experimentalDecorators`.
 - **One API, everywhere it runs.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
 - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) loads a to-many with one query for all parents, not one per parent. Nothing is lazy, so nothing fires behind your back in a serializer.
 - **Migrations you read before they run.** Edit an entity, run `uql-migrate generate:entities`, review the SQL in the PR like any other file. [`drift:check`](https://uql-orm.dev/migrations) catches a database that no longer matches.
 - **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [virtual fields](https://uql-orm.dev/entities/virtual-fields) are sub-queries you can filter on, and a migration can be plain SQL.
-- **Light.** Zero runtime dependencies, 269 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
+- **Light.** Zero runtime dependencies, under 280 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
 - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
-- **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark): 206µs, against 644µs for the next closest and 2,236µs for the slowest.
+- **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), by roughly 3x over the next closest and an order of magnitude over the slowest.
 
 ## Get started
 

package/dist/mongo/mongodbQuerier.d.ts

@@ -47,9 +47,14 @@ export declare class MongodbQuerier extends AbstractQuerier {
     }>;
     protected internalDeleteMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
+    /** Every read and write goes through here, which makes it where a released querier is caught. */
     collection<E extends Document>(entity: Type<E>): import("mongodb").Collection<E>;
     get db(): import("mongodb").Db;
     beginTransaction(_opts?: TransactionOptions): Promise<void>;
+    /**
+     * The driver owns the transaction state here and settles it in its own `finally`, so a failed commit
+     * or abort still leaves `inTransaction()` false and the querier releasable.
+     */
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
     internalRelease(): Promise<void>;

package/dist/mongo/mongodbQuerier.js

@@ -278,7 +278,11 @@ export class MongodbQuerier extends AbstractQuerier {
     get hasOpenTransaction() {
         return !!this.session?.inTransaction();
     }
+    /** Every read and write goes through here, which makes it where a released querier is caught. */
     collection(entity) {
+        if (this.released) {
+            throw new TypeError('querier already released');
+        }
         const { name } = getMeta(entity);
         return this.db.collection(name);
     }
@@ -296,29 +300,33 @@ export class MongodbQuerier extends AbstractQuerier {
             this.session.startTransaction();
         });
     }
+    /**
+     * The driver owns the transaction state here and settles it in its own `finally`, so a failed commit
+     * or abort still leaves `inTransaction()` false and the querier releasable.
+     */
     async commitTransaction() {
         return this.serialize(async () => {
             if (!this.hasOpenTransaction) {
                 throwNoPendingTransaction();
             }
             this.logger.logInfo('commitTransaction');
-            await this.session.commitTransaction();
+            await this.session?.commitTransaction();
         });
     }
     async rollbackTransaction() {
         return this.serialize(async () => {
             if (!this.hasOpenTransaction) {
-                throwNoPendingTransaction();
+                return;
             }
             this.logger.logInfo('rollbackTransaction');
-            await this.session.abortTransaction();
+            await this.session?.abortTransaction();
         });
     }
     async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throwPendingTransaction();
-        }
-        await this.session?.endSession();
+        const session = this.session;
+        // Cleared first, so a failing `endSession` cannot leave the querier holding a session it already
+        // tried to end.
         this.session = undefined;
+        await session?.endSession();
     }
 }

package/dist/mysql/mysql2Querier.d.ts

@@ -7,5 +7,5 @@ export declare class MySql2Querier extends AbstractPoolQuerier<PoolConnection> {
     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: PoolConnection): Promise<void>;
+    protected releaseConn(conn: PoolConnection, discard: boolean): Promise<void>;
 }

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

@@ -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;
@@ -121,8 +126,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.
      *
@@ -137,13 +142,12 @@ export declare abstract class AbstractQuerier implements Querier {
      * 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 +161,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

@@ -13,6 +13,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;
@@ -365,8 +370,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,9 +391,12 @@ 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;
         }
     }
@@ -419,17 +427,12 @@ export class AbstractQuerier {
             await runHooks(entity, event, payloads, { querier: this });
         }
     }
-    async releaseIfFree() {
-        if (!this.hasOpenTransaction) {
-            await this.internalRelease();
-        }
-    }
     /**
-     * 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 +460,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/abstractSqlQuerier.d.ts

@@ -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[]>;
@@ -72,4 +73,12 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     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;
 }

package/dist/querier/abstractSqlQuerier.js

@@ -35,10 +35,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         return Number.isInteger(value) && value > 0 ? value : 1;
     }
     /**
-     * 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.
      */
-    async lazyConnect() { }
+    async lazyConnect() {
+        if (this.released) {
+            throw new TypeError('querier already released');
+        }
+    }
     async all(query, values) {
         return this.serialize(async () => {
             await this.lazyConnect();
@@ -281,12 +286,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             }
             await this.lazyConnect();
             for (const sql of this.dialect.getBeginTransactionStatements(opts?.isolationLevel)) {
-                try {
-                    await this.internalRun(sql);
-                }
-                catch (err) {
-                    throw enrichError(err, this.logger, sql);
-                }
+                await this.runTransactionCommand(sql);
             }
             this.hasPendingTransaction = true;
         });
@@ -296,27 +296,32 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             if (!this.hasPendingTransaction) {
                 throwNoPendingTransaction();
             }
-            try {
-                await this.internalRun(this.dialect.commitTransactionCommand);
-            }
-            catch (err) {
-                throw enrichError(err, this.logger, this.dialect.commitTransactionCommand);
-            }
-            this.hasPendingTransaction = false;
+            await this.endTransactionWith(this.dialect.commitTransactionCommand);
         });
     }
     async rollbackTransaction() {
         return this.serialize(async () => {
-            if (!this.hasPendingTransaction) {
-                throwNoPendingTransaction();
-            }
-            try {
-                await this.internalRun(this.dialect.rollbackTransactionCommand);
-            }
-            catch (err) {
-                throw enrichError(err, this.logger, this.dialect.rollbackTransactionCommand);
+            if (this.hasPendingTransaction) {
+                await this.endTransactionWith(this.dialect.rollbackTransactionCommand);
             }
-            this.hasPendingTransaction = false;
         });
     }
+    /**
+     * 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.
+     */
+    async endTransactionWith(command) {
+        await this.runTransactionCommand(command);
+        this.hasPendingTransaction = false;
+    }
+    /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
+    async runTransactionCommand(sql) {
+        try {
+            await this.internalRun(sql);
+        }
+        catch (err) {
+            throw enrichError(err, this.logger, sql);
+        }
+    }
 }

package/dist/querier/index.d.ts

@@ -2,6 +2,4 @@ export * from './abstractQuerier.js';
 export * from './abstractQuerierPool.js';
 export * from './abstractSqlQuerier.js';
 export * from './abstractSqlQuerierPool.js';
-export * from './querierContext.js';
 export * from './queryError.js';
-export * from './transactional.js';

package/dist/querier/index.js

@@ -2,6 +2,4 @@ export * from './abstractQuerier.js';
 export * from './abstractQuerierPool.js';
 export * from './abstractSqlQuerier.js';
 export * from './abstractSqlQuerierPool.js';
-export * from './querierContext.js';
 export * from './queryError.js';
-export * from './transactional.js';

package/dist/sqlite/abstractSqliteQuerier.d.ts

@@ -30,8 +30,7 @@ export type SqlitePreparedStatement = {
 export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
-     * a querier returns nothing; it only asserts the unit of work was finished. Drivers owning a
-     * closable per-querier connection override this.
+     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
     internalRelease(): Promise<void>;
 }

package/dist/sqlite/abstractSqliteQuerier.js

@@ -1,5 +1,4 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
-import { throwPendingTransaction } from '../util/index.js';
 /** Bound parameters reach a driver as `unknown[]` from the compiler; every driver types them narrowly. */
 export function toSqliteBindValues(values) {
     return (values || []);
@@ -7,14 +6,9 @@ export function toSqliteBindValues(values) {
 export class AbstractSqliteQuerier extends AbstractSqlQuerier {
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
-     * a querier returns nothing; it only asserts the unit of work was finished. Drivers owning a
-     * closable per-querier connection override this.
+     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
-    async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throwPendingTransaction();
-        }
-    }
+    async internalRelease() { }
 }
 /**
  * Querier for the SQLite drivers that expose prepared statements: `better-sqlite3`, `bun:sqlite`

package/dist/sqlite/hranaQuerier.d.ts

@@ -48,6 +48,11 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     get hasOpenTransaction(): boolean;
     beginTransaction(_opts?: TransactionOptions): Promise<void>;
+    /**
+     * Both drop the handle before the call, not after: one that outlived a failed commit or rollback left
+     * the querier unreleasable. The optional call in the rollback is also what makes it a no-op when
+     * there is nothing open.
+     */
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
     internalRelease(): Promise<void>;

package/dist/sqlite/hranaQuerier.js

@@ -41,22 +41,26 @@ export class HranaQuerier extends AbstractSqliteQuerier {
             this.tx = await this.client.transaction('write');
         });
     }
+    /**
+     * Both drop the handle before the call, not after: one that outlived a failed commit or rollback left
+     * the querier unreleasable. The optional call in the rollback is also what makes it a no-op when
+     * there is nothing open.
+     */
     async commitTransaction() {
         return this.serialize(async () => {
-            if (!this.tx) {
+            const tx = this.tx;
+            if (!tx) {
                 throwNoPendingTransaction();
             }
-            await this.tx.commit();
             this.tx = undefined;
+            await tx.commit();
         });
     }
     async rollbackTransaction() {
         return this.serialize(async () => {
-            if (!this.tx) {
-                throwNoPendingTransaction();
-            }
-            await this.tx.rollback();
+            const tx = this.tx;
             this.tx = undefined;
+            await tx?.rollback();
         });
     }
     async internalRelease() {

package/dist/type/querier.d.ts

@@ -15,6 +15,13 @@ export type IsolationLevel = 'read uncommitted' | 'read committed' | 'repeatable
  * Options for starting a transaction.
  */
 export type TransactionOptions = {
+    /**
+     * Applies to this transaction only.
+     *
+     * @remarks MySQL and MariaDB set it as a statement of its own ahead of `START TRANSACTION`, so a
+     * `START TRANSACTION` that then fails leaves the level applied to whatever the pooled connection
+     * runs next. Set it per transaction that needs it rather than relying on what a connection carries.
+     */
     readonly isolationLevel?: IsolationLevel;
 };
 export type DialectName = SqlDialectName | 'mongodb';
@@ -80,11 +87,14 @@ export interface Querier extends UniversalQuerier {
      */
     commitTransaction(): Promise<void>;
     /**
-     * aborts the currently active transaction in this querier.
+     * aborts the currently active transaction, or does nothing when there is none, so it is safe from a
+     * `catch` / `finally` without checking {@link hasOpenTransaction} first. `commitTransaction` is strict
+     * instead: a caller who believes their work was committed has to hear that it was not.
      */
     rollbackTransaction(): Promise<void>;
     /**
-     * release the querier to the pool.
+     * rolls back any unfinished transaction and releases the querier to the pool. A pooled querier is
+     * finished afterwards: using it again throws rather than taking a second connection nothing owns.
      */
     release(): Promise<void>;
     /**

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "JSON-native TypeScript ORM: queries are plain JSON, typed to the leaf. One API for SQL databases and MongoDB.",
+  "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -12,8 +12,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "browser": {
-    "./dist/context/context.js": "./dist/context/context.browser.js",
-    "./dist/querier/querierContext.js": "./dist/querier/querierContext.browser.js"
+    "./dist/context/context.js": "./dist/context/context.browser.js"
   },
   "bin": {
     "uql-migrate": "./dist/migrate/bin.js"
@@ -158,40 +157,45 @@
   },
   "keywords": [
     "orm",
+    "uql",
+    "sql",
     "query-builder",
     "data-mapper",
-    "persistence",
     "database",
     "db",
+    "typescript",
+    "ts",
+    "javascript",
     "typesafe",
-    "typescript-orm",
-    "javascript-orm",
-    "mariadb",
-    "mariadb-orm",
-    "mysql",
-    "mysql-orm",
+    "type-safe",
+    "json",
+    "postgres",
     "postgresql",
-    "postgresql-orm",
+    "pg",
+    "mysql",
+    "mariadb",
     "sqlite",
-    "sqlite-orm",
+    "sqlite3",
     "cockroachdb",
-    "cockroachdb-orm",
     "mongodb",
-    "mongodb-orm",
+    "mongo",
     "libsql",
     "turso",
     "neon",
     "d1",
     "cloudflare",
     "bun",
+    "deno",
+    "node",
+    "nodejs",
     "edge",
+    "serverless",
     "entity",
-    "dao",
-    "transaction",
-    "repository",
-    "service",
+    "transactions",
     "migrations",
     "vector-search",
+    "semantic-search",
+    "embeddings",
     "nestjs",
     "express"
   ],

package/dist/querier/querierContext.browser.d.ts

@@ -1,12 +0,0 @@
-import type { Querier } from '../type/index.js';
-/**
- * Browser build of the transactional querier context: bundlers targeting the browser resolve
- * `querierContext.ts` to this file (see the `browser` map in package.json), keeping the root entrypoint
- * free of `node:async_hooks`.
- *
- * Nothing in a browser bundle opens a transaction. The browser querier serializes queries over HTTP and
- * the server owns the transaction, so there is no ambient querier to hand out and no flow to track.
- */
-export declare function withQuerierContext<T>(_querier: Querier, callback: () => T): T;
-export declare function currentQuerier(): Querier;
-export declare function currentQuerierIfAny(): Querier | undefined;

package/dist/querier/querierContext.browser.js

@@ -1,18 +0,0 @@
-/**
- * Browser build of the transactional querier context: bundlers targeting the browser resolve
- * `querierContext.ts` to this file (see the `browser` map in package.json), keeping the root entrypoint
- * free of `node:async_hooks`.
- *
- * Nothing in a browser bundle opens a transaction. The browser querier serializes queries over HTTP and
- * the server owns the transaction, so there is no ambient querier to hand out and no flow to track.
- */
-export function withQuerierContext(_querier, callback) {
-    return callback();
-}
-export function currentQuerier() {
-    throw new TypeError('currentQuerier() is server-only: transactions run on the server, and the browser querier sends each ' +
-        'request over HTTP. Call it from server code, or use the querier you already have.');
-}
-export function currentQuerierIfAny() {
-    return undefined;
-}

package/dist/querier/querierContext.d.ts

@@ -1,22 +0,0 @@
-import type { Querier } from '../type/index.js';
-/** Runs `callback` with `querier` as the ambient one, for the whole async flow beneath it. */
-export declare function withQuerierContext<T>(querier: Querier, callback: () => T): T;
-/**
- * The querier of the enclosing `@Transactional()` method.
- *
- * This is what replaced `@InjectQuerier()`: the standard decorator spec has no parameter decorators, so
- * the querier can no longer be injected into an argument and is read from the ambient flow instead.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export declare function currentQuerier(): Querier;
-/** The ambient querier, or `undefined` outside a transaction. For callers that can work without one. */
-export declare function currentQuerierIfAny(): Querier | undefined;

package/dist/querier/querierContext.js

@@ -1,42 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-/**
- * The querier `@Transactional()` opened for the current async flow.
- *
- * Separate from the `UqlContext` storage in `context/context.ts` on purpose: that one is remapped to a
- * synchronous browser shim which cannot propagate across `await`, and a querier handle must. Nothing in
- * a browser bundle opens a transaction, so this stays server-only and `verify-dist` keeps it out of the
- * browser-facing graph.
- */
-const querierStorage = new AsyncLocalStorage();
-/** Runs `callback` with `querier` as the ambient one, for the whole async flow beneath it. */
-export function withQuerierContext(querier, callback) {
-    return querierStorage.run(querier, callback);
-}
-/**
- * The querier of the enclosing `@Transactional()` method.
- *
- * This is what replaced `@InjectQuerier()`: the standard decorator spec has no parameter decorators, so
- * the querier can no longer be injected into an argument and is read from the ambient flow instead.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export function currentQuerier() {
-    const querier = querierStorage.getStore();
-    if (!querier) {
-        throw new TypeError('currentQuerier() found no active querier. Call it inside a @Transactional() method, or take a querier ' +
-            'from the pool yourself with `await using querier = await pool.getQuerier()`.');
-    }
-    return querier;
-}
-/** The ambient querier, or `undefined` outside a transaction. For callers that can work without one. */
-export function currentQuerierIfAny() {
-    return querierStorage.getStore();
-}

package/dist/querier/transactional.d.ts

@@ -1,26 +0,0 @@
-import type { IsolationLevel, QuerierPool } from '../type/index.js';
-export type TransactionalOptions = {
-    /** `required` opens a transaction when none is active; `supported` joins one but never starts one. */
-    readonly propagation?: 'supported' | 'required';
-    readonly pool?: QuerierPool;
-    readonly isolationLevel?: IsolationLevel;
-};
-/**
- * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
- *
- * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
- * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
- * so the querier travels through async-local storage instead. A nested call joins the transaction
- * already in flight rather than opening a second one.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export declare function Transactional({ propagation, pool, isolationLevel }?: TransactionalOptions): <This, Args extends unknown[], R>(original: (this: This, ...args: Args) => Promise<R>, context: ClassMethodDecoratorContext<This>) => (this: This, ...args: Args) => Promise<R>;

package/dist/querier/transactional.js

@@ -1,43 +0,0 @@
-import { getQuerierPool } from '../options.js';
-import { currentQuerierIfAny, withQuerierContext } from './querierContext.js';
-/**
- * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
- *
- * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
- * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
- * so the querier travels through async-local storage instead. A nested call joins the transaction
- * already in flight rather than opening a second one.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export function Transactional({ propagation = 'required', pool, isolationLevel } = {}) {
-    return (original, context) => {
-        // Checked at decoration time rather than on the first call: a synchronous method cannot be wrapped in
-        // a transaction, and finding that out at startup beats finding out mid-request.
-        if (original.constructor.name !== 'AsyncFunction') {
-            throw new TypeError(`@Transactional() needs an async method, but '${String(context.name)}' is not one.`);
-        }
-        return async function (...args) {
-            // Already inside a transactional flow: join it and let the outermost call own commit and release.
-            if (currentQuerierIfAny()) {
-                return original.apply(this, args);
-            }
-            // `withQuerier` releases; `transaction` commits or rolls back. `supported` joins a transaction but
-            // never starts one, so it takes only the first half.
-            return (pool ?? getQuerierPool()).withQuerier((querier) => {
-                const run = () => original.apply(this, args);
-                return withQuerierContext(querier, () => propagation === 'supported'
-                    ? run()
-                    : querier.transaction(run, isolationLevel ? { isolationLevel } : undefined));
-            });
-        };
-    };
-}