turbine-orm 0.90.0 → 0.90.1-next.708c40c

package/README.md

@@ -272,7 +272,7 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **147 kB brotli** (edge entry under **116 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **146 kB brotli** (edge entry under **114 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
@@ -287,7 +287,7 @@ HTTP drivers cannot hold a cursor or a LISTEN connection, so `findManyStream` an
 
 ## Database engines
 
-Postgres is the default and primary target. The same typed API also runs on **SQLite** (Node's built-in `node:sqlite`, zero extra installs, Node ≥ 22.5), **MySQL 8** (`mysql2`), **SQL Server 2016+** (`mssql`), and **PowDB** (embedded or networked), each behind a subpath export with its driver as an optional peer. All four are **Experimental** in the [stability policy](STABILITY.md): the query API they expose is the shared one, but each engine's capability boundaries and factory options may still change in a minor release.
+Postgres is the default and primary target. The same typed API also runs on **SQLite** (Node's built-in `node:sqlite`, zero extra installs, Node ≥ 22.5), **MySQL 8** (`mysql2`), **SQL Server 2016+** (`mssql`), and **PowDB** (embedded or networked), each behind a subpath export with its driver as an optional peer. All four are **Experimental** in the [stability policy](STABILITY.md): the query API they expose is the shared one, but each engine's capability boundaries and factory options may still change in a minor release. PowDB is in maintenance mode: bug and data-safety fixes, no new features.
 
 ```bash
 npm install turbine-orm                        # SQLite needs nothing else
@@ -359,11 +359,11 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 |---|---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine | Kysely as query runner; SQL built by MikroORM (v7) |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 | `@mikro-orm/core` (0 deps) + a driver package |
-| **Main bundle (brotli)** | under 147 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small | |
+| **Main bundle (brotli)** | under 146 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small | |
 | **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | None | AdminJS integration guide (CRUD panel) |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors | |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None | Generated by diffing entities against a snapshot or the database; TS/JS classes |
-| **Edge runtime** | One import swap, under 116 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native | Cloudflare Workers and Deno (v7) |
+| **Edge runtime** | One import swap, under 114 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native | Cloudflare Workers and Deno (v7) |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual | `flush()` runs queued changes in one transaction |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None | `DriverException` subclasses (`UniqueConstraintViolationException`, ...) |
 | **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) | `populate`; default `balanced`: joins to-one, one query per to-many relation |

package/dist/cjs/client.js

@@ -50,6 +50,7 @@ const warn_registry_js_1 = require("./query/warn-registry.js");
 const query_events_js_1 = require("./query-events.js");
 const realtime_js_1 = require("./realtime.js");
 const supplied_pool_types_js_1 = require("./supplied-pool-types.js");
+const transaction_client_slot_js_1 = require("./transaction-client-slot.js");
 const transaction_state_js_1 = require("./transaction-state.js");
 const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
@@ -563,19 +564,6 @@ function resolveNonNegativeInteger(value, name, unit) {
     }
     return value;
 }
-/**
- * Refuse a dialect with no `capabilities` object (E003): every code path asks
- * it what the engine can do, so a hand-built dialect without one would fail on
- * its first query with a TypeError instead of here.
- */
-function assertDialectCapabilities(dialect) {
-    const capabilities = dialect.capabilities;
-    if (typeof capabilities === 'object' && capabilities !== null)
-        return;
-    throw new errors_js_1.ValidationError(`The dialect "${String(dialect.name)}" has no \`capabilities\` object, which says what the engine can do. ` +
-        'Build it from an engine dialect (`{ ...postgresDialect, name, capabilities: { ... } }`) and state every ' +
-        'EngineCapabilities key.');
-}
 /**
  * The statement that opens a transaction, read-only when asked. PostgreSQL and
  * MySQL both accept `READ ONLY` after their own BEGIN form (`BEGIN [ISOLATION
@@ -1027,6 +1015,10 @@ class TransactionClient {
     }
 }
 exports.TransactionClient = TransactionClient;
+// query/builder.ts opens an implicit transaction with this class but sits
+// below this module in the import graph, so the class is handed over here,
+// once, when this module is evaluated (see transaction-client-slot.ts).
+(0, transaction_client_slot_js_1.registerTransactionClient)(TransactionClient);
 /**
  * Give each multi-statement write on a transaction-scoped accessor its own
  * savepoint: `create` / `update` carrying nested relation writes, and an
@@ -1251,7 +1243,7 @@ class TurbineClient {
         // settling the process-global parser mode and then rejecting the config
         // would poison the next, valid, TurbineClient with a phantom conflict.
         const dialect = config.dialect ?? dialect_js_1.postgresDialect;
-        assertDialectCapabilities(dialect);
+        (0, dialect_js_1.assertDialectCapabilities)(dialect);
         const planCacheMode = TurbineClient.resolvePlanCacheMode(config.planCacheMode, dialect);
         const statementTimeoutMs = TurbineClient.resolveStatementTimeout(config.statementTimeoutMs, dialect);
         const maxLifetimeSeconds = resolveNonNegativeInteger(config.maxLifetimeSeconds, 'maxLifetimeSeconds', 'seconds');

package/dist/cjs/dialect.d.ts

@@ -389,10 +389,11 @@ export interface RelationSubqueryContext {
  * refuses an engine whose `capabilities` is inherited or shared.
  *
  * Code asks these questions instead of testing `dialect.name`; a source scan
- * (src/test/capabilities-guard.test.ts) refuses a new engine-name comparison
- * outside a short, commented allowlist. Rendering differences are not
- * capabilities: they belong in the dialect's hooks (a few still switch on the
- * name, allowlisted, until engines stop spreading `postgresDialect`).
+ * (src/test/capabilities-guard.test.ts) refuses a new engine-name test, of any
+ * shape, outside a short, commented allowlist that pins each site it exempts.
+ * Rendering differences are not capabilities: they belong in the dialect's
+ * hooks (a few still switch on the name, allowlisted, until engines stop
+ * spreading `postgresDialect`).
  */
 export interface EngineCapabilities {
     /** `SELECT DISTINCT ON (...)`: findMany `distinct` and groupBy `distinctOn`. Else E017. */
@@ -586,6 +587,16 @@ export interface EngineCapabilities {
      */
     readonly unboundedTextKeys: boolean;
 }
+/**
+ * Refuse a dialect with no `capabilities` object (E003). Every path that builds
+ * SQL asks it what the engine can do, so a hand-built dialect written before
+ * the object existed would otherwise fail on first use with a TypeError
+ * ("cannot read properties of undefined"). Every public entry point that takes
+ * a dialect calls this (`TurbineClient`, `QueryInterface`, `schemaToSQL`,
+ * `introspect`), so the refusal and its words are the same whichever one a
+ * caller reaches first. One `typeof`: `QueryInterface` is built per table.
+ */
+export declare function assertDialectCapabilities(dialect: Dialect): void;
 export interface Dialect {
     /** Dialect identifier. */
     readonly name: DialectName;

package/dist/cjs/dialect.js

@@ -8,11 +8,29 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.postgresDialect = void 0;
+exports.assertDialectCapabilities = assertDialectCapabilities;
 exports.maxBindParameters = maxBindParameters;
 exports.onConflictAction = onConflictAction;
 const errors_js_1 = require("./errors.js");
 const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
+/**
+ * Refuse a dialect with no `capabilities` object (E003). Every path that builds
+ * SQL asks it what the engine can do, so a hand-built dialect written before
+ * the object existed would otherwise fail on first use with a TypeError
+ * ("cannot read properties of undefined"). Every public entry point that takes
+ * a dialect calls this (`TurbineClient`, `QueryInterface`, `schemaToSQL`,
+ * `introspect`), so the refusal and its words are the same whichever one a
+ * caller reaches first. One `typeof`: `QueryInterface` is built per table.
+ */
+function assertDialectCapabilities(dialect) {
+    const capabilities = dialect.capabilities;
+    if (typeof capabilities === 'object' && capabilities !== null)
+        return;
+    throw new errors_js_1.ValidationError(`The dialect "${String(dialect.name)}" has no \`capabilities\` object, which says what the engine can do. ` +
+        'Build it from an engine dialect (`{ ...postgresDialect, name, capabilities: { ... } }`) and state every ' +
+        'EngineCapabilities key.');
+}
 /** The bind-parameter limit for one statement on this dialect, or `undefined` when it has none. */
 function maxBindParameters(dialect) {
     const limit = dialect.capabilities.maxBindParameters;

package/dist/cjs/introspect.js

@@ -485,6 +485,7 @@ function assertSafeCatalogSchema(schema) {
  */
 async function introspect(options) {
     const dialect = options.dialect ?? dialect_js_1.postgresDialect;
+    (0, dialect_js_1.assertDialectCapabilities)(dialect);
     const introspector = dialect.introspector;
     const schema = introspector
         ? await introspector.introspect(options)

package/dist/cjs/powdb.js

@@ -53,39 +53,6 @@
  *
  * @module
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -109,6 +76,7 @@ const errors_js_1 = require("./errors.js");
 const logger_js_1 = require("./logger.js");
 const optional_peer_import_cjs_1 = __importDefault(require("./optional-peer-import.cjs"));
 const powdb_shared_js_1 = require("./powdb-shared.js");
+const powql_js_1 = require("./powql.js");
 const warn_registry_js_1 = require("./query/warn-registry.js");
 const schema_js_1 = require("./schema.js");
 // The shared PowDB primitives live in a leaf module (see powdb-shared.ts): this
@@ -1861,8 +1829,8 @@ exports.PowdbEmbeddedPool = PowdbEmbeddedPool;
 // `describe`-based introspection (programmatic API; see powdb-introspect.ts).
 var powdb_introspect_js_1 = require("./powdb-introspect.js");
 Object.defineProperty(exports, "introspectPowdbDatabase", { enumerable: true, get: function () { return powdb_introspect_js_1.introspectPowdbDatabase; } });
-var powql_js_1 = require("./powql.js");
-Object.defineProperty(exports, "PowqlInterface", { enumerable: true, get: function () { return powql_js_1.PowqlInterface; } });
+var powql_js_2 = require("./powql.js");
+Object.defineProperty(exports, "PowqlInterface", { enumerable: true, get: function () { return powql_js_2.PowqlInterface; } });
 /**
  * Dynamically load `@zvndev/powdb-client`. Kept out of the static import graph so
  * `import 'turbine-orm/powdb'` never throws when the optional peer is absent.
@@ -2064,9 +2032,7 @@ async function turbinePowDB(target, schema, options = {}) {
     }
     let client;
     try {
-        // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
-        const { PowqlInterface } = await Promise.resolve().then(() => __importStar(require('./powql.js')));
-        const queryInterfaceFactory = (p, table, sch, middlewares, opts) => new PowqlInterface(p, table, sch, middlewares, opts);
+        const queryInterfaceFactory = (p, table, sch, middlewares, opts) => new powql_js_1.PowqlInterface(p, table, sch, middlewares, opts);
         // Forward every client-level option EXCEPT the ones this factory owns (they
         // configure the pool / transport above, and TurbineClient warns on a config
         // key it does not recognize). Destructured rather than hand-listed on the way

package/dist/cjs/powql.d.ts

@@ -486,7 +486,9 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `gt` / `gte` / `lt` / `lte` compile to `in` over the labels on that side of
      * the operand in DECLARATION order, which is what PostgreSQL compares; the
      * text comparison PowDB would run is alphabetical, a different answer. A null
-     * operand matches no row, as `col > NULL` does. Case-insensitive matching and
+     * operand is refused before this (assertOperatorOperands, as on the SQL
+     * engines) and again by {@link assertEnumLabel}: compiled to a constant false,
+     * `NOT` would turn it into every row. Case-insensitive matching and
      * `contains` / `startsWith` / `endsWith` are E003: PostgreSQL has no `lower`
      * or `LIKE` on an enum (42883).
      */

package/dist/cjs/powql.js

@@ -35,39 +35,6 @@
  *
  * @module
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PowqlInterface = exports.MAX_RELATION_FILTER_KEYS = exports.MAX_POWQL_DATETIME_TERMS = void 0;
 const node_crypto_1 = require("node:crypto");
@@ -99,6 +66,7 @@ const where_js_1 = require("./query/where.js");
 const where_compile_js_1 = require("./query/where-compile.js");
 const writes_js_1 = require("./query/writes.js");
 const schema_js_1 = require("./schema.js");
+const transaction_client_slot_js_1 = require("./transaction-client-slot.js");
 /**
  * Max parent keys per relation-loader `in (…)` query. A `with` over a large
  * parent set is split into batches of this size so a single query never exceeds
@@ -1083,17 +1051,15 @@ class PowqlInterface {
         // The SQL engines' operand rules and messages, so the engines agree on
         // which operator objects are valid; one naming no comparison
         // (`{ mode: 'insensitive' }`) is refused instead of compiling to nothing.
-        const operand = {
+        // JSON columns included, as on the SQL engines: skipping them let a
+        // mode-only filter fall through to the constant-false fallback below, which
+        // `NOT` turned into every non-null row (a deleteMany wrote all of them).
+        // The same call refuses a JSON `not` object made only of filter operators.
+        (0, filters_js_1.assertOperatorOperands)(op, {
             column: colMeta.name,
             table: this.table,
             kind: (0, filters_js_1.operandColumnKind)(this.meta.pgTypes[colMeta.name]),
-        };
-        if (!(0, powdb_shared_js_1.isJsonColumn)(colMeta, this.schema.enums))
-            (0, filters_js_1.assertOperatorOperands)(op, operand);
-        // On a JSON column a `not` object made only of filter operators is refused,
-        // as on the SQL engines (one spelling, one meaning on every engine).
-        else
-            (0, filters_js_1.assertJsonNotOperand)(op.not, operand);
+        });
         const insensitive = op.mode === 'insensitive';
         const lhs = insensitive ? `lower(${ref})` : ref;
         const labels = this.enumLabels(colMeta);
@@ -1179,7 +1145,14 @@ class PowqlInterface {
                     throw new errors_js_1.ValidationError(`Unsupported operator "${opName}" on PowDB.`);
             }
         }
-        return conds.length > 1 ? `(${conds.join(' and ')})` : (conds[0] ?? this.alwaysFalse());
+        // assertOperatorOperands refuses an operator object that names no
+        // comparison, and every comparison above pushes a condition or throws, so
+        // an empty list is a generator bug. It must not become a constant: under
+        // `NOT` a constant false is every row, and a mutation would write them.
+        if (!conds.length) {
+            throw new errors_js_1.InvariantError('powql-filter-empty', `the filter on "${field}" compiled to no condition.`);
+        }
+        return conds.length > 1 ? `(${conds.join(' and ')})` : conds[0];
     }
     /**
      * PowQL JSON path expression `.col->$a->$b…`, binding EVERY path segment as a
@@ -1354,7 +1327,9 @@ class PowqlInterface {
      * `gt` / `gte` / `lt` / `lte` compile to `in` over the labels on that side of
      * the operand in DECLARATION order, which is what PostgreSQL compares; the
      * text comparison PowDB would run is alphabetical, a different answer. A null
-     * operand matches no row, as `col > NULL` does. Case-insensitive matching and
+     * operand is refused before this (assertOperatorOperands, as on the SQL
+     * engines) and again by {@link assertEnumLabel}: compiled to a constant false,
+     * `NOT` would turn it into every row. Case-insensitive matching and
      * `contains` / `startsWith` / `endsWith` are E003: PostgreSQL has no `lower`
      * or `LIKE` on an enum (42883).
      */
@@ -1365,8 +1340,6 @@ class PowqlInterface {
         }
         if (opName !== 'gt' && opName !== 'gte' && opName !== 'lt' && opName !== 'lte')
             return undefined;
-        if (opVal === null)
-            return this.alwaysFalse();
         this.assertEnumLabel(col, labels, opVal);
         const at = labels.indexOf(opVal);
         const side = labels.filter((_, i) => opName === 'gt' ? i > at : opName === 'gte' ? i >= at : opName === 'lt' ? i < at : i <= at);
@@ -4102,6 +4075,9 @@ class PowqlInterface {
         // Route tx keywords through the dialect (like the SQL path) so this never
         // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
         const d = this.options.dialect;
+        // Read before the checkout, so an empty slot (client.ts never loaded in this
+        // copy of the package) refuses with no connection taken and no `begin` sent.
+        const TransactionClient = (0, transaction_client_slot_js_1.transactionClientFor)(`A nested write or lookup-first upsert on "${this.table}"`);
         const client = await this.pool.connect();
         // A no-op today (PowDB checkouts have no event surface), kept so this path
         // cannot become the one unguarded checkout if a transport ever emits 'error'.
@@ -4110,7 +4086,6 @@ class PowqlInterface {
         try {
             await client.query(d?.beginStatement?.() ?? 'begin');
             began = true;
-            const { TransactionClient } = await Promise.resolve().then(() => __importStar(require('./client.js')));
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options, 
             // Pass the PowDB pool so its read-only guard + capabilities carry into
             // the transaction-scoped proxy pool (see createTxPool).

package/dist/cjs/query/builder.js

@@ -56,6 +56,7 @@ const index_advisor_js_1 = require("../index-advisor.js");
 const logger_js_1 = require("../logger.js");
 const nested_write_js_1 = require("../nested-write.js");
 const schema_js_1 = require("../schema.js");
+const transaction_client_slot_js_1 = require("../transaction-client-slot.js");
 const transaction_state_js_1 = require("../transaction-state.js");
 const aggMod = __importStar(require("./aggregates.js"));
 const batched_loader_js_1 = require("./batched-loader.js");
@@ -833,6 +834,7 @@ class QueryInterface {
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
         this.sqlTemplateCache = new utils_js_1.LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+        (0, dialect_js_1.assertDialectCapabilities)(this.dialect);
         this.sqlCommenter =
             options?._sqlCommenter ??
                 (0, sql_comment_js_1.resolveSqlComment)(options?.sqlComment, this.logger, {
@@ -4447,6 +4449,11 @@ class QueryInterface {
         return (0, checkout_js_1.acquireConnection)(this.pool);
     }
     async runInImplicitTx(fn) {
+        // client.ts registers TransactionClient when it is evaluated (it cannot be
+        // imported from here, see transaction-client-slot.ts). Read before the
+        // checkout, so a program that never loaded client.ts gets a typed error
+        // without a connection having been touched.
+        const TransactionClient = (0, transaction_client_slot_js_1.transactionClientFor)(`A nested write or lookup-first upsert on "${this.table}"`);
         // BEGIN runs inside openCheckout, which sends it once more on a fresh
         // connection when the first one turns out to be dead and releases the
         // connection itself when BEGIN fails for good. The catch below therefore
@@ -4454,7 +4461,6 @@ class QueryInterface {
         // a connection that opened none.
         const { client, checkout } = await (0, checkout_js_1.openCheckout)(this.pool, (c) => c.query(this.dialect.beginStatement()));
         try {
-            const { TransactionClient } = await Promise.resolve().then(() => __importStar(require('../client.js')));
             const tx = new TransactionClient(
             // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
             client, this.schema, 

package/dist/cjs/schema-sql.js

@@ -113,6 +113,7 @@ function resolveDdlType(config, dialect, columnName) {
  */
 function schemaToSQL(schema, options) {
     const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    (0, dialect_js_1.assertDialectCapabilities)(dialect);
     const extensions = options?.extensions ?? 'auto';
     const statements = [];
     // Topologically sort tables by their foreign key references

package/dist/cjs/transaction-client-slot.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where the code that opens an implicit transaction finds `TransactionClient`.
+ *
+ * A nested write (or an upsert that looks its row up first) issued outside a
+ * transaction opens one of its own and runs the nested-write engine against a
+ * `TransactionClient` (query/builder.ts; powql.ts, the PowDB generator, does
+ * the same and can read this slot too). Those modules sit BELOW client.ts in
+ * the import graph: client.ts imports query/, so a static value import back
+ * would be a cycle, and scripts/check-import-cycles.mjs refuses one.
+ *
+ * builder.ts used to reach the class with a dynamic import of client.ts.
+ * That works, but a bundler that does not split code (esbuild, which is also
+ * what the size budget in .size-limit.js measures, and Wrangler) inlines the
+ * dynamic target and, to keep its evaluation lazy, wraps client.ts and every
+ * module it reaches in lazy-init closures: about 1 kB brotli on every entry,
+ * for a module that is always already loaded by the time a query runs.
+ * client.ts instead registers the class here once, when it is evaluated, and
+ * every public entry point evaluates client.ts.
+ *
+ * ## One slot per package copy, deliberately not `Symbol.for`
+ *
+ * The ESM and CJS builds can both be loaded in one process. Shared state that
+ * must agree across them (the warn-once registry, the prepared-statement
+ * budget) lives under a `Symbol.for` key; this slot must NOT. A builder has to
+ * construct the `TransactionClient` of its OWN copy, exactly as the dynamic
+ * import did: the other copy's class builds the other copy's accessors and
+ * transaction state and throws the other copy's error classes, so `instanceof`
+ * checks in the caller's copy would stop matching. Each copy's entry points
+ * load that copy's client.ts, so each copy's slot is filled.
+ *
+ * ## An empty slot
+ *
+ * Reachable only when a `QueryInterface` is built directly and client.ts was
+ * never loaded in that copy: a test or tool that deep-imports query/, or a
+ * bundled application that uses the exported `QueryInterface` without ever
+ * importing `TurbineClient` or an engine factory (with `sideEffects: false` a
+ * bundler may then drop client.ts). Only the implicit-transaction path reads
+ * the slot, so everything else keeps working; that path throws a
+ * `ValidationError` (E003) naming the fix, before any connection is checked out.
+ *
+ * The import of client.ts below is type-only, so this file adds no edge to the
+ * runtime graph. errors.ts is a leaf.
+ */
+import type { TransactionClient } from './client.js';
+/** The `TransactionClient` constructor, as client.ts registers it. */
+export type TransactionClientClass = typeof TransactionClient;
+/** @internal Called once, by client.ts, when it is evaluated. */
+export declare function registerTransactionClient(ctor: TransactionClientClass): void;
+/** @internal The registered class, or `undefined` when client.ts was never loaded in this copy. */
+export declare function registeredTransactionClient(): TransactionClientClass | undefined;
+/**
+ * @internal The registered class for an implicit transaction. Throws a
+ * `ValidationError` when client.ts was never loaded in this copy of the package.
+ * `operation` starts the message, for example `A nested write on "users"`.
+ */
+export declare function transactionClientFor(operation: string): TransactionClientClass;

package/dist/cjs/transaction-client-slot.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTransactionClient = registerTransactionClient;
+exports.registeredTransactionClient = registeredTransactionClient;
+exports.transactionClientFor = transactionClientFor;
+const errors_js_1 = require("./errors.js");
+let registered;
+/** @internal Called once, by client.ts, when it is evaluated. */
+function registerTransactionClient(ctor) {
+    registered = ctor;
+}
+/** @internal The registered class, or `undefined` when client.ts was never loaded in this copy. */
+function registeredTransactionClient() {
+    return registered;
+}
+/**
+ * @internal The registered class for an implicit transaction. Throws a
+ * `ValidationError` when client.ts was never loaded in this copy of the package.
+ * `operation` starts the message, for example `A nested write on "users"`.
+ */
+function transactionClientFor(operation) {
+    if (registered !== undefined)
+        return registered;
+    throw new errors_js_1.ValidationError(`${operation} outside a transaction opens one of its own through TurbineClient, ` +
+        'and TurbineClient was never loaded in this program. Import TurbineClient (or an engine factory such as ' +
+        "turbineHttp) from 'turbine-orm' before running it, or run the write inside db.$transaction().");
+}

package/dist/client.js

@@ -26,7 +26,7 @@ import { openCheckout, typeCheckoutTimeouts } from './checkout.js';
 import { absorbCheckedOutErrors, settleLongIdleCheckouts, watchCheckouts, } from './connection-guard.js';
 import { detectPoolerTarget, fillTargetFromEnvironment, parseConnectionTarget, statementTimeoutSetting, withStartupSetting, } from './connection-url.js';
 import { resolveDiagnostics } from './diagnostics.js';
-import { postgresDialect } from './dialect.js';
+import { assertDialectCapabilities, postgresDialect } from './dialect.js';
 import { ConnectionError, errorMessageModesDiverged, explainConnectionLoss, PipelineError, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { normalizeGlobalFilters, tableAccessorName } from './global-filters-config.js';
 import { CLIENT_LOG_CONTEXT, logTo, resolveLogger } from './logger.js';
@@ -43,6 +43,7 @@ import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { currentQueryTag, deferredIdentity, emitStatementEvent, rawIdentity, resultRowCount, runReportedStatement, runWithQueryTag, } from './query-events.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { parseInt8, rawClientOf, typedQueryPool } from './supplied-pool-types.js';
+import { registerTransactionClient } from './transaction-client-slot.js';
 import { commitTransaction, rolledBackError, TRANSACTION_STATE, TransactionState, unawaitedWorkError, } from './transaction-state.js';
 import { buildTypedSql, TypedSqlQuery, utcDateParams } from './typed-sql.js';
 export async function withRetry(fn, options) {
@@ -556,19 +557,6 @@ function resolveNonNegativeInteger(value, name, unit) {
     }
     return value;
 }
-/**
- * Refuse a dialect with no `capabilities` object (E003): every code path asks
- * it what the engine can do, so a hand-built dialect without one would fail on
- * its first query with a TypeError instead of here.
- */
-function assertDialectCapabilities(dialect) {
-    const capabilities = dialect.capabilities;
-    if (typeof capabilities === 'object' && capabilities !== null)
-        return;
-    throw new ValidationError(`The dialect "${String(dialect.name)}" has no \`capabilities\` object, which says what the engine can do. ` +
-        'Build it from an engine dialect (`{ ...postgresDialect, name, capabilities: { ... } }`) and state every ' +
-        'EngineCapabilities key.');
-}
 /**
  * The statement that opens a transaction, read-only when asked. PostgreSQL and
  * MySQL both accept `READ ONLY` after their own BEGIN form (`BEGIN [ISOLATION
@@ -1019,6 +1007,10 @@ export class TransactionClient {
         return txPool;
     }
 }
+// query/builder.ts opens an implicit transaction with this class but sits
+// below this module in the import graph, so the class is handed over here,
+// once, when this module is evaluated (see transaction-client-slot.ts).
+registerTransactionClient(TransactionClient);
 /**
  * Give each multi-statement write on a transaction-scoped accessor its own
  * savepoint: `create` / `update` carrying nested relation writes, and an

package/dist/dialect.d.ts

@@ -389,10 +389,11 @@ export interface RelationSubqueryContext {
  * refuses an engine whose `capabilities` is inherited or shared.
  *
  * Code asks these questions instead of testing `dialect.name`; a source scan
- * (src/test/capabilities-guard.test.ts) refuses a new engine-name comparison
- * outside a short, commented allowlist. Rendering differences are not
- * capabilities: they belong in the dialect's hooks (a few still switch on the
- * name, allowlisted, until engines stop spreading `postgresDialect`).
+ * (src/test/capabilities-guard.test.ts) refuses a new engine-name test, of any
+ * shape, outside a short, commented allowlist that pins each site it exempts.
+ * Rendering differences are not capabilities: they belong in the dialect's
+ * hooks (a few still switch on the name, allowlisted, until engines stop
+ * spreading `postgresDialect`).
  */
 export interface EngineCapabilities {
     /** `SELECT DISTINCT ON (...)`: findMany `distinct` and groupBy `distinctOn`. Else E017. */
@@ -586,6 +587,16 @@ export interface EngineCapabilities {
      */
     readonly unboundedTextKeys: boolean;
 }
+/**
+ * Refuse a dialect with no `capabilities` object (E003). Every path that builds
+ * SQL asks it what the engine can do, so a hand-built dialect written before
+ * the object existed would otherwise fail on first use with a TypeError
+ * ("cannot read properties of undefined"). Every public entry point that takes
+ * a dialect calls this (`TurbineClient`, `QueryInterface`, `schemaToSQL`,
+ * `introspect`), so the refusal and its words are the same whichever one a
+ * caller reaches first. One `typeof`: `QueryInterface` is built per table.
+ */
+export declare function assertDialectCapabilities(dialect: Dialect): void;
 export interface Dialect {
     /** Dialect identifier. */
     readonly name: DialectName;

package/dist/dialect.js

@@ -8,6 +8,23 @@
 import { ValidationError } from './errors.js';
 import { coerceJsonWireValue, jsonWireCoercionOid } from './query/utils.js';
 import { pgArrayType, pgTypeToTs } from './schema.js';
+/**
+ * Refuse a dialect with no `capabilities` object (E003). Every path that builds
+ * SQL asks it what the engine can do, so a hand-built dialect written before
+ * the object existed would otherwise fail on first use with a TypeError
+ * ("cannot read properties of undefined"). Every public entry point that takes
+ * a dialect calls this (`TurbineClient`, `QueryInterface`, `schemaToSQL`,
+ * `introspect`), so the refusal and its words are the same whichever one a
+ * caller reaches first. One `typeof`: `QueryInterface` is built per table.
+ */
+export function assertDialectCapabilities(dialect) {
+    const capabilities = dialect.capabilities;
+    if (typeof capabilities === 'object' && capabilities !== null)
+        return;
+    throw new ValidationError(`The dialect "${String(dialect.name)}" has no \`capabilities\` object, which says what the engine can do. ` +
+        'Build it from an engine dialect (`{ ...postgresDialect, name, capabilities: { ... } }`) and state every ' +
+        'EngineCapabilities key.');
+}
 /** The bind-parameter limit for one statement on this dialect, or `undefined` when it has none. */
 export function maxBindParameters(dialect) {
     const limit = dialect.capabilities.maxBindParameters;

package/dist/introspect.js

@@ -8,7 +8,7 @@
  * This is the foundation of `npx turbine generate`.
  */
 import pg from '#pg';
-import { postgresDialect } from './dialect.js';
+import { assertDialectCapabilities, postgresDialect } from './dialect.js';
 import { ValidationError } from './errors.js';
 import { consoleLogger, logTo } from './logger.js';
 import { isDateType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
@@ -455,6 +455,7 @@ export function assertSafeCatalogSchema(schema) {
  */
 export async function introspect(options) {
     const dialect = options.dialect ?? postgresDialect;
+    assertDialectCapabilities(dialect);
     const introspector = dialect.introspector;
     const schema = introspector
         ? await introspector.introspect(options)

package/dist/powdb.js

@@ -59,6 +59,7 @@ import { ConnectionError, malformedConnectionStringMessage, NotNullViolationErro
 import { consoleLogger, logTo } from './logger.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { ALL_POWDB_CAPABILITIES, atLeastVersion, isDateColumn, PowdbFloatParam, PowdbJsonParam, parsePowdbSemver, powqlColumnType, quotePowqlIdent, requireCapability, } from './powdb-shared.js';
+import { PowqlInterface } from './powql.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { normalizeKeyColumns } from './schema.js';
 // The shared PowDB primitives live in a leaf module (see powdb-shared.ts): this
@@ -1996,8 +1997,6 @@ export async function turbinePowDB(target, schema, options = {}) {
     }
     let client;
     try {
-        // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
-        const { PowqlInterface } = await import('./powql.js');
         const queryInterfaceFactory = (p, table, sch, middlewares, opts) => new PowqlInterface(p, table, sch, middlewares, opts);
         // Forward every client-level option EXCEPT the ones this factory owns (they
         // configure the pool / transport above, and TurbineClient warns on a config

package/dist/powql.d.ts

@@ -486,7 +486,9 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `gt` / `gte` / `lt` / `lte` compile to `in` over the labels on that side of
      * the operand in DECLARATION order, which is what PostgreSQL compares; the
      * text comparison PowDB would run is alphabetical, a different answer. A null
-     * operand matches no row, as `col > NULL` does. Case-insensitive matching and
+     * operand is refused before this (assertOperatorOperands, as on the SQL
+     * engines) and again by {@link assertEnumLabel}: compiled to a constant false,
+     * `NOT` would turn it into every row. Case-insensitive matching and
      * `contains` / `startsWith` / `endsWith` are E003: PostgreSQL has no `lower`
      * or `LIKE` on an enum (42883).
      */

package/dist/powql.js

@@ -47,7 +47,7 @@ import { unlockNestedWriteTx } from './query/builder.js';
 import { isColumnRef } from './query/column-ref.js';
 import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, uniqueKeyNames, upsertWhereMatchesCreate, whereIdentifiesOneRow, } from './query/compound-unique.js';
 import { exprNotAllowedMessage, isSqlExpr } from './query/expr.js';
-import { ARRAY_OPERATOR_KEYS, assertJsonNotOperand, assertOperatorOperands, cursorFieldValue, dedupeColumnList, isJsonFilter, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isUnmatchedPlainObject, isVectorOrderBy, normalizeOrderBy, operandColumnKind, orderByEntries, UPDATE_OPERATOR_KEYS, } from './query/filters.js';
+import { ARRAY_OPERATOR_KEYS, assertOperatorOperands, cursorFieldValue, dedupeColumnList, isJsonFilter, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isUnmatchedPlainObject, isVectorOrderBy, normalizeOrderBy, operandColumnKind, orderByEntries, UPDATE_OPERATOR_KEYS, } from './query/filters.js';
 import { isJsonValue } from './query/json-value.js';
 import { assertCursorNotEmptied, assertCursorWritten, assertWhereNotEmptiedByPruning, hasCursor, pruneUndefinedArgs, } from './query/normalize-args.js';
 import { warnUnknownQueryOptions } from './query/option-surface.js';
@@ -63,6 +63,7 @@ import { assertJsonFilterKeys, emptyMutationWhereMessage, jsonStringEntries, nor
 import { combinatorBranches, foldWhereFor, relationCardinalityProblem, relationFilterValueProblem, } from './query/where-compile.js';
 import { assertNoBulkWritePaging, assertNoOptimisticLock } from './query/writes.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
+import { transactionClientFor } from './transaction-client-slot.js';
 /**
  * Max parent keys per relation-loader `in (…)` query. A `with` over a large
  * parent set is split into batches of this size so a single query never exceeds
@@ -1047,17 +1048,15 @@ export class PowqlInterface {
         // The SQL engines' operand rules and messages, so the engines agree on
         // which operator objects are valid; one naming no comparison
         // (`{ mode: 'insensitive' }`) is refused instead of compiling to nothing.
-        const operand = {
+        // JSON columns included, as on the SQL engines: skipping them let a
+        // mode-only filter fall through to the constant-false fallback below, which
+        // `NOT` turned into every non-null row (a deleteMany wrote all of them).
+        // The same call refuses a JSON `not` object made only of filter operators.
+        assertOperatorOperands(op, {
             column: colMeta.name,
             table: this.table,
             kind: operandColumnKind(this.meta.pgTypes[colMeta.name]),
-        };
-        if (!isJsonColumn(colMeta, this.schema.enums))
-            assertOperatorOperands(op, operand);
-        // On a JSON column a `not` object made only of filter operators is refused,
-        // as on the SQL engines (one spelling, one meaning on every engine).
-        else
-            assertJsonNotOperand(op.not, operand);
+        });
         const insensitive = op.mode === 'insensitive';
         const lhs = insensitive ? `lower(${ref})` : ref;
         const labels = this.enumLabels(colMeta);
@@ -1143,7 +1142,14 @@ export class PowqlInterface {
                     throw new ValidationError(`Unsupported operator "${opName}" on PowDB.`);
             }
         }
-        return conds.length > 1 ? `(${conds.join(' and ')})` : (conds[0] ?? this.alwaysFalse());
+        // assertOperatorOperands refuses an operator object that names no
+        // comparison, and every comparison above pushes a condition or throws, so
+        // an empty list is a generator bug. It must not become a constant: under
+        // `NOT` a constant false is every row, and a mutation would write them.
+        if (!conds.length) {
+            throw new InvariantError('powql-filter-empty', `the filter on "${field}" compiled to no condition.`);
+        }
+        return conds.length > 1 ? `(${conds.join(' and ')})` : conds[0];
     }
     /**
      * PowQL JSON path expression `.col->$a->$b…`, binding EVERY path segment as a
@@ -1318,7 +1324,9 @@ export class PowqlInterface {
      * `gt` / `gte` / `lt` / `lte` compile to `in` over the labels on that side of
      * the operand in DECLARATION order, which is what PostgreSQL compares; the
      * text comparison PowDB would run is alphabetical, a different answer. A null
-     * operand matches no row, as `col > NULL` does. Case-insensitive matching and
+     * operand is refused before this (assertOperatorOperands, as on the SQL
+     * engines) and again by {@link assertEnumLabel}: compiled to a constant false,
+     * `NOT` would turn it into every row. Case-insensitive matching and
      * `contains` / `startsWith` / `endsWith` are E003: PostgreSQL has no `lower`
      * or `LIKE` on an enum (42883).
      */
@@ -1329,8 +1337,6 @@ export class PowqlInterface {
         }
         if (opName !== 'gt' && opName !== 'gte' && opName !== 'lt' && opName !== 'lte')
             return undefined;
-        if (opVal === null)
-            return this.alwaysFalse();
         this.assertEnumLabel(col, labels, opVal);
         const at = labels.indexOf(opVal);
         const side = labels.filter((_, i) => opName === 'gt' ? i > at : opName === 'gte' ? i >= at : opName === 'lt' ? i < at : i <= at);
@@ -4066,6 +4072,9 @@ export class PowqlInterface {
         // Route tx keywords through the dialect (like the SQL path) so this never
         // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
         const d = this.options.dialect;
+        // Read before the checkout, so an empty slot (client.ts never loaded in this
+        // copy of the package) refuses with no connection taken and no `begin` sent.
+        const TransactionClient = transactionClientFor(`A nested write or lookup-first upsert on "${this.table}"`);
         const client = await this.pool.connect();
         // A no-op today (PowDB checkouts have no event surface), kept so this path
         // cannot become the one unguarded checkout if a transport ever emits 'error'.
@@ -4074,7 +4083,6 @@ export class PowqlInterface {
         try {
             await client.query(d?.beginStatement?.() ?? 'begin');
             began = true;
-            const { TransactionClient } = await import('./client.js');
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options, 
             // Pass the PowDB pool so its read-only guard + capabilities carry into
             // the transaction-scoped proxy pool (see createTxPool).

package/dist/query/builder.js

@@ -13,12 +13,13 @@
 import { acquireConnection, openCheckout } from '../checkout.js';
 import { settleEventLoop } from '../connection-guard.js';
 import { resolveDiagnostics } from '../diagnostics.js';
-import { postgresDialect } from '../dialect.js';
+import { assertDialectCapabilities, postgresDialect } from '../dialect.js';
 import { explainConnectionLoss, INVARIANT_REPORT_HINT, InvariantError, isStaleConnectionError, NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
 import { consoleLogger, logTo } from '../logger.js';
 import { executeNestedCreate, executeNestedUpdate, extractRelationFields, hasRelationFields, } from '../nested-write.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
+import { transactionClientFor } from '../transaction-client-slot.js';
 import { transactionStateOf, withSavepoint } from '../transaction-state.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
@@ -796,6 +797,7 @@ export class QueryInterface {
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
         this.sqlTemplateCache = new LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? postgresDialect;
+        assertDialectCapabilities(this.dialect);
         this.sqlCommenter =
             options?._sqlCommenter ??
                 resolveSqlComment(options?.sqlComment, this.logger, {
@@ -4410,6 +4412,11 @@ export class QueryInterface {
         return acquireConnection(this.pool);
     }
     async runInImplicitTx(fn) {
+        // client.ts registers TransactionClient when it is evaluated (it cannot be
+        // imported from here, see transaction-client-slot.ts). Read before the
+        // checkout, so a program that never loaded client.ts gets a typed error
+        // without a connection having been touched.
+        const TransactionClient = transactionClientFor(`A nested write or lookup-first upsert on "${this.table}"`);
         // BEGIN runs inside openCheckout, which sends it once more on a fresh
         // connection when the first one turns out to be dead and releases the
         // connection itself when BEGIN fails for good. The catch below therefore
@@ -4417,7 +4424,6 @@ export class QueryInterface {
         // a connection that opened none.
         const { client, checkout } = await openCheckout(this.pool, (c) => c.query(this.dialect.beginStatement()));
         try {
-            const { TransactionClient } = await import('../client.js');
             const tx = new TransactionClient(
             // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
             client, this.schema, 

package/dist/schema-sql.js

@@ -7,7 +7,7 @@
 import pg from 'pg';
 import { DESTRUCTIVE_KIND_LABEL, scanDestructiveSql } from './cli/destructive.js';
 import { guardConnection } from './connection-guard.js';
-import { postgresDialect } from './dialect.js';
+import { assertDialectCapabilities, postgresDialect } from './dialect.js';
 import { UnsupportedFeatureError, ValidationError } from './errors.js';
 import { pgConfActionToReferential, stripCheckWrapper } from './introspect.js';
 import { camelToSnake } from './schema.js';
@@ -92,6 +92,7 @@ function resolveDdlType(config, dialect, columnName) {
  */
 export function schemaToSQL(schema, options) {
     const dialect = options?.dialect ?? postgresDialect;
+    assertDialectCapabilities(dialect);
     const extensions = options?.extensions ?? 'auto';
     const statements = [];
     // Topologically sort tables by their foreign key references

package/dist/transaction-client-slot.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where the code that opens an implicit transaction finds `TransactionClient`.
+ *
+ * A nested write (or an upsert that looks its row up first) issued outside a
+ * transaction opens one of its own and runs the nested-write engine against a
+ * `TransactionClient` (query/builder.ts; powql.ts, the PowDB generator, does
+ * the same and can read this slot too). Those modules sit BELOW client.ts in
+ * the import graph: client.ts imports query/, so a static value import back
+ * would be a cycle, and scripts/check-import-cycles.mjs refuses one.
+ *
+ * builder.ts used to reach the class with a dynamic import of client.ts.
+ * That works, but a bundler that does not split code (esbuild, which is also
+ * what the size budget in .size-limit.js measures, and Wrangler) inlines the
+ * dynamic target and, to keep its evaluation lazy, wraps client.ts and every
+ * module it reaches in lazy-init closures: about 1 kB brotli on every entry,
+ * for a module that is always already loaded by the time a query runs.
+ * client.ts instead registers the class here once, when it is evaluated, and
+ * every public entry point evaluates client.ts.
+ *
+ * ## One slot per package copy, deliberately not `Symbol.for`
+ *
+ * The ESM and CJS builds can both be loaded in one process. Shared state that
+ * must agree across them (the warn-once registry, the prepared-statement
+ * budget) lives under a `Symbol.for` key; this slot must NOT. A builder has to
+ * construct the `TransactionClient` of its OWN copy, exactly as the dynamic
+ * import did: the other copy's class builds the other copy's accessors and
+ * transaction state and throws the other copy's error classes, so `instanceof`
+ * checks in the caller's copy would stop matching. Each copy's entry points
+ * load that copy's client.ts, so each copy's slot is filled.
+ *
+ * ## An empty slot
+ *
+ * Reachable only when a `QueryInterface` is built directly and client.ts was
+ * never loaded in that copy: a test or tool that deep-imports query/, or a
+ * bundled application that uses the exported `QueryInterface` without ever
+ * importing `TurbineClient` or an engine factory (with `sideEffects: false` a
+ * bundler may then drop client.ts). Only the implicit-transaction path reads
+ * the slot, so everything else keeps working; that path throws a
+ * `ValidationError` (E003) naming the fix, before any connection is checked out.
+ *
+ * The import of client.ts below is type-only, so this file adds no edge to the
+ * runtime graph. errors.ts is a leaf.
+ */
+import type { TransactionClient } from './client.js';
+/** The `TransactionClient` constructor, as client.ts registers it. */
+export type TransactionClientClass = typeof TransactionClient;
+/** @internal Called once, by client.ts, when it is evaluated. */
+export declare function registerTransactionClient(ctor: TransactionClientClass): void;
+/** @internal The registered class, or `undefined` when client.ts was never loaded in this copy. */
+export declare function registeredTransactionClient(): TransactionClientClass | undefined;
+/**
+ * @internal The registered class for an implicit transaction. Throws a
+ * `ValidationError` when client.ts was never loaded in this copy of the package.
+ * `operation` starts the message, for example `A nested write on "users"`.
+ */
+export declare function transactionClientFor(operation: string): TransactionClientClass;

package/dist/transaction-client-slot.js

@@ -0,0 +1,22 @@
+import { ValidationError } from './errors.js';
+let registered;
+/** @internal Called once, by client.ts, when it is evaluated. */
+export function registerTransactionClient(ctor) {
+    registered = ctor;
+}
+/** @internal The registered class, or `undefined` when client.ts was never loaded in this copy. */
+export function registeredTransactionClient() {
+    return registered;
+}
+/**
+ * @internal The registered class for an implicit transaction. Throws a
+ * `ValidationError` when client.ts was never loaded in this copy of the package.
+ * `operation` starts the message, for example `A nested write on "users"`.
+ */
+export function transactionClientFor(operation) {
+    if (registered !== undefined)
+        return registered;
+    throw new ValidationError(`${operation} outside a transaction opens one of its own through TurbineClient, ` +
+        'and TurbineClient was never loaded in this program. Import TurbineClient (or an engine factory such as ' +
+        "turbineHttp) from 'turbine-orm' before running it, or run the write inside db.$transaction().");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.90.0",
+  "version": "0.90.1-next.708c40c",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -208,23 +208,23 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.5.14",
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@swc/core": "1.16.2",
     "@types/node": "^22.20.4",
-    "@types/pg": "^8.11.11",
+    "@types/pg": "^8.23.1",
     "@zvndev/powdb-client": "^0.20.0",
     "@zvndev/powdb-embedded": "^0.20.0",
     "c8": "^12.0.0",
     "esbuild": "^0.28.2",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.8",
-    "mssql": "^12.7.0",
-    "mysql2": "^3.22.5",
-    "publint": "^0.3.16",
+    "lint-staged": "^17.6.0",
+    "mssql": "^12.7.2",
+    "mysql2": "^3.24.5",
+    "publint": "^0.3.24",
     "size-limit": "^12.1.0",
-    "tsx": "^4.19.0",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {