turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/dialect.js

@@ -6,47 +6,107 @@
  * PostgreSQL-native by default, but query generation now depends on this
  * contract for the SQL primitives that vary across MySQL and SQLite.
  */
-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.postgresDialect = void 0;
+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");
+/** The bind-parameter limit for one statement on this dialect, or `undefined` when it has none. */
+function maxBindParameters(dialect) {
+    const limit = dialect.capabilities.maxBindParameters;
+    return Number.isFinite(limit) ? limit : undefined;
+}
+/**
+ * PostgreSQL's multi-row `INSERT INTO t (cols) ...` with no conflict clause and
+ * no RETURNING: the shared body of `createMany` and its `onConflict` form.
+ *
+ * The default is `SELECT * FROM UNNEST($1::text[], ...)`, one bound array per
+ * COLUMN. The row-major form (`requireRowValues`) is required when a target
+ * column is itself array-typed, because the UNNEST transpose flattens nested
+ * arrays: one placeholder per cell instead of per column.
+ */
+function pgBulkInsertBody(dialect, input) {
+    if (!input.columnArrayTypes || input.columnArrayTypes.length !== input.columns.length) {
+        throw new errors_js_1.ValidationError(`createMany bulk insert into "${input.table}": columnArrayTypes must supply one UNNEST cast ` +
+            `per column, got ${input.columnArrayTypes?.length ?? 0} for ${input.columns.length} columns ` +
+            `(${input.columns.join(', ')}). Schema metadata is missing a pgType for at least one column; ` +
+            'regenerate it with `npx turbine generate`.');
+    }
+    if (input.requireRowValues) {
+        const params = [];
+        const tuples = input.rowValues.map((row) => {
+            const cells = input.columns.map((_, i) => {
+                params.push(row[i]);
+                // No cast: PostgreSQL infers each parameter's type from the INSERT
+                // target column, which is what single-row `create` already relies on
+                // and is what makes arrays and enums both work here. The casts in
+                // `columnArrayTypes` are ARRAY-OF-column-type, correct for the
+                // UNNEST transpose but wrong for an individual cell.
+                return dialect.paramPlaceholder(params.length);
+            });
+            return `(${cells.join(', ')})`;
+        });
+        return { sql: `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES ${tuples.join(', ')}`, params };
+    }
+    const columnArrays = input.columns.map((_, columnIndex) => input.rowValues.map((row) => row[columnIndex]));
+    const unnestArgs = input.columns.map((_, i) => `${dialect.paramPlaceholder(i + 1)}::${input.columnArrayTypes[i]}`);
+    return {
+        sql: `INSERT INTO ${input.table} (${input.columns.join(', ')}) SELECT * FROM UNNEST(${unnestArgs.join(', ')})`,
+        params: columnArrays,
+    };
+}
+/**
+ * `DO NOTHING`, or `DO UPDATE SET ... [WHERE ...]`: the action of an
+ * `ON CONFLICT (target)` clause, shared by PostgreSQL and SQLite, whose
+ * grammars agree here. The update compiles after the row values are bound.
+ */
+function onConflictAction(input, params, refs) {
+    if (!input.update)
+        return 'DO NOTHING';
+    const update = input.update(params, refs);
+    return `DO UPDATE SET ${update.setClauses.join(', ')}${update.where ? ` WHERE ${update.where}` : ''}`;
+}
 /** PostgreSQL implementation of the dialect contract. */
 exports.postgresDialect = {
     name: 'postgresql',
+    capabilities: Object.freeze({
+        distinctOn: true,
+        positionalJson: true,
+        nullsOrderingClause: true,
+        nullsSortHigh: true,
+        insensitiveInList: true,
+        jsonDocumentEquality: 'jsonb',
+        jsonExtractTyped: false,
+        jsonExactNumericCast: true,
+        numericTextComparison: false,
+        enforcesForeignKeys: true,
+        partitionLimitPushdown: true,
+        utcTimestampRewrite: true,
+        paramTypeCasts: true,
+        namedEnumTypes: true,
+        structuredValueColumns: 'pg-scalars',
+        // Counted in a 16-bit field.
+        maxBindParameters: 65535,
+        maxInsertRows: Number.POSITIVE_INFINITY,
+        upsertConflictTarget: 'explicit',
+        setClauseOrder: 'snapshot',
+        reselectLocksRows: false,
+        integerDivision: '/',
+        updateExpressions: true,
+        bulkUpsertAppliesRepeatedKeys: false,
+        readOnlyTransactions: true,
+        connectionParameters: true,
+        backendCancel: true,
+        idleTransactionTimeout: true,
+        abortsTransactionOnError: true,
+        connectionDriver: 'pg-compatible',
+        preparesEveryStatement: false,
+        statementSyntax: 'postgresql',
+        inlineForeignKeys: true,
+        unboundedTextKeys: true,
+    }),
     resultStrategy: 'returning',
     supportsReturning: true,
     supportsUpsertUpdateWhere: true,
@@ -64,6 +124,9 @@ exports.postgresDialect = {
     supportsAdvisoryLock: true,
     supportsPlanCacheMode: true,
     supportsLateralJoin: true,
+    rowLockModes: ['update', 'noKeyUpdate', 'share', 'keyShare'],
+    supportsPercentileAggregates: true,
+    supportsBulkUpsert: true,
     explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
@@ -116,40 +179,21 @@ exports.postgresDialect = {
         return `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})${this.buildReturningClause(input.returning)}`;
     },
     buildBulkInsertStatement(input) {
-        if (!input.columnArrayTypes || input.columnArrayTypes.length !== input.columns.length) {
-            throw new errors_js_1.ValidationError(`createMany bulk insert into "${input.table}": columnArrayTypes must supply one UNNEST cast ` +
-                `per column, got ${input.columnArrayTypes?.length ?? 0} for ${input.columns.length} columns ` +
-                `(${input.columns.join(', ')}). Schema metadata is missing a pgType for at least one column; ` +
-                'regenerate it with `npx turbine generate`.');
-        }
-        // Row-major form: required when a target column is itself array-typed,
-        // because the UNNEST transpose below flattens nested arrays (see
-        // `requireRowValues`). One placeholder per cell instead of per column.
-        if (input.requireRowValues) {
-            const params = [];
-            const tuples = input.rowValues.map((row) => {
-                const cells = input.columns.map((_, i) => {
-                    params.push(row[i]);
-                    // No cast: PostgreSQL infers each parameter's type from the INSERT
-                    // target column, which is what single-row `create` already relies on
-                    // and is what makes arrays and enums both work here. The casts in
-                    // `columnArrayTypes` are ARRAY-OF-column-type, correct for the
-                    // UNNEST transpose below but wrong for an individual cell.
-                    return this.paramPlaceholder(params.length);
-                });
-                return `(${cells.join(', ')})`;
-            });
-            let rowSql = `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES ${tuples.join(', ')}`;
-            if (input.skipDuplicates)
-                rowSql += ' ON CONFLICT DO NOTHING';
-            return { sql: `${rowSql}${this.buildReturningClause(input.returning)}`, params };
-        }
-        const columnArrays = input.columns.map((_, columnIndex) => input.rowValues.map((row) => row[columnIndex]));
-        const unnestArgs = input.columns.map((_, i) => `${this.paramPlaceholder(i + 1)}::${input.columnArrayTypes[i]}`);
-        let sql = `INSERT INTO ${input.table} (${input.columns.join(', ')}) SELECT * FROM UNNEST(${unnestArgs.join(', ')})`;
-        if (input.skipDuplicates)
-            sql += ' ON CONFLICT DO NOTHING';
-        return { sql: `${sql}${this.buildReturningClause(input.returning)}`, params: columnArrays };
+        const body = pgBulkInsertBody(this, input);
+        const conflict = input.skipDuplicates ? ' ON CONFLICT DO NOTHING' : '';
+        return { sql: `${body.sql}${conflict}${this.buildReturningClause(input.returning)}`, params: body.params };
+    },
+    buildBulkUpsertStatement(input) {
+        // `INSERT ... SELECT * FROM UNNEST(...) ON CONFLICT ... DO UPDATE ... WHERE
+        // ... RETURNING` is valid as is: PostgreSQL has no parse ambiguity between
+        // the SELECT and the conflict clause.
+        const body = pgBulkInsertBody(this, input);
+        return {
+            sql: `${body.sql} ON CONFLICT (${input.conflictColumns.join(', ')}) ` +
+                onConflictAction(input, body.params, { target: input.table, incoming: 'EXCLUDED' }) +
+                this.buildReturningClause(input.returning),
+            params: body.params,
+        };
     },
     buildDefaultValuesInsertStatement(input) {
         const conflict = input.skipDuplicates ? ' ON CONFLICT DO NOTHING' : '';
@@ -382,13 +426,10 @@ exports.postgresDialect = {
             }
         }
     },
-    // Postgres introspection wraps the information_schema / pg_catalog reader in
-    // introspect.ts. A dynamic import keeps the static graph acyclic (introspect.ts
-    // imports postgresDialect) and calls the raw catalog reader (never the router).
-    introspector: {
-        async introspect(options) {
-            const { introspectPostgresCatalog } = await Promise.resolve().then(() => __importStar(require('./introspect.js')));
-            return introspectPostgresCatalog(options);
-        },
-    },
+    // No `introspector`: `introspect()` reads the PostgreSQL catalog itself when a
+    // dialect has none. A field here would have to reach introspect.ts through a
+    // dynamic import (introspect.ts imports this dialect), and a bundler without
+    // code splitting inlines that import WHOLE, which put the entire catalog
+    // reader into the serverless entry and every engine entry (4 to 6 kB brotli
+    // each) for a function none of them call at runtime.
 };

package/dist/cjs/engine-config.d.ts

@@ -26,20 +26,21 @@ import type { TurbineConfig } from './client.js';
  *     the engine from its own SQL.
  *   - `connectionString`, `host`, `port`, `database`, `user`, `password`, `ssl`,
  *     `poolSize`, `idleTimeoutMs`, `connectionTimeoutMs`, `max`,
- *     `idleTimeoutMillis`, `connectionTimeoutMillis`: pg connection and
- *     pool-tuning fields, ignored by `TurbineClient` whenever `pool` is set (it
- *     always is here). Each engine takes its connection target as its first
- *     argument instead, in that driver's own vocabulary.
+ *     `idleTimeoutMillis`, `connectionTimeoutMillis`, `maxLifetimeSeconds`: pg
+ *     connection and pool-tuning fields, ignored by `TurbineClient` whenever
+ *     `pool` is set (it always is here). Each engine takes its connection
+ *     target as its first argument instead, in that driver's own vocabulary.
  *   - `replicas`: entries are Postgres connection strings or pg-compatible
  *     pools, which `TurbineClient` opens as `pg.Pool`s. There is no engine
  *     equivalent to route reads to.
  *
  * Everything else is forwarded, including options that are Postgres-only by
- * CAPABILITY rather than by plumbing (`jsonEncoding: 'positional'`). Those throw
+ * CAPABILITY rather than by plumbing (`jsonEncoding: 'positional'`,
+ * `statementTimeoutMs`, `planCacheMode`). Those throw
  * a typed `UnsupportedFeatureError` (E017) when used, which is a better answer
  * than an option the type system says does not exist.
  */
-type EngineOwnedConfigKey = 'pool' | 'dialect' | 'preparedStatements' | 'connectionString' | 'host' | 'port' | 'database' | 'user' | 'password' | 'ssl' | 'poolSize' | 'idleTimeoutMs' | 'connectionTimeoutMs' | 'max' | 'idleTimeoutMillis' | 'connectionTimeoutMillis' | 'replicas';
+type EngineOwnedConfigKey = 'pool' | 'dialect' | 'preparedStatements' | 'connectionString' | 'host' | 'port' | 'database' | 'user' | 'password' | 'ssl' | 'poolSize' | 'idleTimeoutMs' | 'connectionTimeoutMs' | 'max' | 'idleTimeoutMillis' | 'connectionTimeoutMillis' | 'maxLifetimeSeconds' | 'replicas';
 /**
  * The client-level options every engine factory accepts and forwards to
  * `TurbineClient` unchanged: all of {@link TurbineConfig} minus the connection

package/dist/cjs/errors.d.ts

@@ -24,6 +24,8 @@ export declare const TurbineErrorCode: {
     readonly EXCLUSION_VIOLATION: "TURBINE_E016";
     readonly UNSUPPORTED_FEATURE: "TURBINE_E017";
     readonly READ_ONLY: "TURBINE_E018";
+    readonly TRANSACTION_ROLLED_BACK: "TURBINE_E019";
+    readonly INVARIANT_VIOLATION: "TURBINE_E020";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -198,7 +200,10 @@ export declare function describeTargetForMessage(target: unknown): string;
  *   `[TURBINE_E001] findUniqueOrThrow on "users" found no record matching where: {"id":1}`
  *
  * The full `where` object, `table`, and `operation` are always available as
- * structured properties on the error instance regardless of mode.
+ * structured properties on the error instance regardless of mode. `where`
+ * carries the caller's raw values, so under 'safe' it is NON-ENUMERABLE:
+ * `err.where` reads it, while `JSON.stringify`, `util.inspect` and error
+ * serializers that copy own enumerable fields leave it out.
  */
 export declare class NotFoundError extends TurbineError {
     static readonly CODE: "TURBINE_E001";
@@ -213,21 +218,37 @@ export declare class NotFoundError extends TurbineError {
         message?: string;
     });
 }
+/**
+ * What a {@link TimeoutError} says about the statement it interrupted.
+ *
+ *   - `'not-executed'`: the statement made no change. It was never sent (the
+ *     deadline passed while waiting for a connection), or the server confirmed
+ *     it was cancelled. Safe to retry.
+ *   - `'unknown'`: the statement may still have completed. A write retried on
+ *     this outcome can be applied twice; check the database first.
+ *
+ * A read changes nothing whatever this says, so a read is always safe to retry.
+ */
+export type TimeoutOutcome = 'not-executed' | 'unknown';
 /** Thrown when a query or transaction exceeds the configured timeout */
 export declare class TimeoutError extends TurbineError {
     static readonly CODE: "TURBINE_E002";
     readonly timeoutMs: number;
+    /** Whether the interrupted statement can have taken effect. See {@link TimeoutOutcome}. */
+    readonly outcome: TimeoutOutcome;
     /**
      * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
      *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
      *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
      * @param context human label for the operation ("Query", "Transaction").
      * @param options optional `message` override and pg `cause` to preserve, used
-     *   when wrapping a driver error rather than a client-side timer expiry.
+     *   when wrapping a driver error rather than a client-side timer expiry, and
+     *   the `outcome` (default `'unknown'`, the only answer that is never wrong).
      */
     constructor(timeoutMs: number, context?: string, options?: {
         message?: string;
         cause?: unknown;
+        outcome?: TimeoutOutcome;
     });
 }
 /** Thrown when query arguments fail validation (unknown column, invalid operator, etc.) */
@@ -421,6 +442,33 @@ export declare class SerializationFailureError extends TurbineError {
         cause?: unknown;
     });
 }
+/**
+ * A row lock could not be taken. A locking read with `noWait` found a row
+ * locked by another transaction (PostgreSQL 55P03, MySQL 3572), or a lock wait
+ * outlasted the server's lock timeout (PostgreSQL 55P03 under `lock_timeout`,
+ * MySQL 1205, SQL Server 1222).
+ *
+ * A {@link SerializationFailureError}: same code (E013) and `isRetryable`, so
+ * code that already retries E013 retries this too. Retry after a backoff, or
+ * read with `skipLocked` to move on to the rows that are free.
+ *
+ * On PostgreSQL the failed statement aborts the transaction it ran in. To keep
+ * the outer transaction alive, take the lock in a nested `tx.$transaction(...)`
+ * (a savepoint) and catch the error outside it.
+ */
+export declare class LockNotAvailableError extends SerializationFailureError {
+    constructor(opts?: {
+        message?: string;
+        cause?: unknown;
+    });
+    /**
+     * `instanceof` across two copies of this module. The code alone cannot tell
+     * this class from its parent (both E013), so another copy's instance must
+     * also carry this class's own brand. A caller's subclass answers only for
+     * its own instances, as {@link TurbineError[Symbol.hasInstance]} does.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 export declare class CheckConstraintError extends TurbineError {
     static readonly CODE: "TURBINE_E011";
@@ -542,18 +590,86 @@ export declare class ReadOnlyError extends TurbineError {
      * fail-fast flag), so NOTHING can write here and writes must route to the
      * primary. `'rbac'`: the database is writable but THIS connection's role may
      * not write (per-connection permission), so re-authenticating may suffice.
+     * `'transaction'`: the transaction is read-only (`$transaction({ readOnly:
+     * true })`, `BEGIN READ ONLY`, or a read replica, where every transaction
+     * is), so the write belongs in a read-write transaction on the primary.
      */
-    readonly reason: 'snapshot' | 'rbac';
+    readonly reason: ReadOnlyReason;
     /**
      * @param detail human-readable description of the refused write (the engine
-     *   message, or a local fail-fast description). A "route writes to a writable
-     *   primary" hint is always appended.
+     *   message, or a local fail-fast description). A hint naming where the
+     *   write belongs is always appended.
      * @param options optional driver `cause` to preserve when wrapping a refusal,
      *   and the refusal `reason` (default `'snapshot'`).
      */
     constructor(detail: string, options?: {
         cause?: unknown;
-        reason?: 'snapshot' | 'rbac';
+        reason?: ReadOnlyReason;
+    });
+}
+/** Why a {@link ReadOnlyError} write was refused. */
+export type ReadOnlyReason = 'snapshot' | 'rbac' | 'transaction';
+/**
+ * Thrown when work the caller expected to be saved was rolled back instead:
+ * a `$transaction` or `transaction()` whose COMMIT the server answered with
+ * ROLLBACK, a transaction that cannot commit because a statement inside it was
+ * cut short by its `timeout`, or a nested `tx.$transaction(...)` block that
+ * could not be kept for the same reasons.
+ *
+ * PostgreSQL aborts a transaction at its first error. Catching that error
+ * inside the callback does not undo the abort, so the callback returns, the
+ * COMMIT ends as a ROLLBACK, and none of the transaction's writes are saved.
+ * The first failure is attached as `cause`. Nothing was committed, so the
+ * whole transaction can be run again once the cause is dealt with; to keep the
+ * rest of the work after an expected failure, run the statement that can fail
+ * in its own nested `tx.$transaction(...)`.
+ *
+ * NOT retryable on its own: the failure that caused it is not known to be
+ * transient. When that first failure WAS a deadlock or a serialization
+ * conflict, the retryable class (`DeadlockError`, `SerializationFailureError`)
+ * is thrown instead, so `$retry` re-runs the transaction.
+ */
+export declare class TransactionRolledBackError extends TurbineError {
+    static readonly CODE: "TURBINE_E019";
+    /**
+     * @param message what was rolled back and how to keep the work next time.
+     * @param options the first failure inside the transaction, as `cause`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The sentence every {@link InvariantError} message ends with, before the docs
+ * link. Exported so a test can assert it without restating it.
+ */
+export declare const INVARIANT_REPORT_HINT: string;
+/**
+ * Turbine detected a bug in itself: a branch that no argument can reach was
+ * reached, or two internal paths that must agree did not (the SQL-template
+ * cache's build and param-collect paths, for example).
+ *
+ * Not caused by the arguments, so rewriting the call is not the fix, and not
+ * retryable: the same call fails the same way. `invariant` is a stable id for
+ * the broken rule (`'sql-cache-lockstep'`, `'sql-cache-param-count'`, ...), so
+ * a report or an alert can group on it. The message names no row or parameter
+ * value.
+ *
+ * Thrown in place of executing a statement Turbine knows is wrong, which is
+ * what makes the checks behind it safe to run in production.
+ */
+export declare class InvariantError extends TurbineError {
+    static readonly CODE: "TURBINE_E020";
+    /** Stable id of the broken invariant, e.g. `'sql-cache-lockstep'`. */
+    readonly invariant: string;
+    /**
+     * @param invariant stable id of the broken rule.
+     * @param message what disagreed, with no row or parameter value in it. The
+     *   report hint is appended once.
+     * @param options the error that exposed the broken rule, as `cause`.
+     */
+    constructor(invariant: string, message: string, options?: {
+        cause?: unknown;
     });
 }
 /**
@@ -593,9 +709,13 @@ export declare function isStaleConnectionError(err: unknown): boolean;
  *   23P01 (exclusion_violation)   -> ExclusionConstraintError
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   55P03 (lock_not_available)    -> LockNotAvailableError (retryable, E013); also
+ *                                    MySQL 3572 / 1205 and SQL Server 1222
  *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
  *   28P01 / 28000 (auth refused)  -> ConnectionError, with a remediation hint
  *   3D000 (no such database)      -> ConnectionError, with a remediation hint
+ *   42P05 / 26000 (prepared statement name clash or miss, a transaction-mode
+ *                                    pooler) -> ConnectionError, with a remediation hint
  *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *   22xxx (data exception)        -> ValidationError naming the column (when the
  *                                    server did) and the SQLSTATE; driver text