turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.REDACTED_DETAIL = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.InvariantError = exports.INVARIANT_REPORT_HINT = exports.TransactionRolledBackError = exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.LockNotAvailableError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.REDACTED_DETAIL = exports.TurbineError = exports.TurbineErrorCode = void 0;
 exports.registerClientErrorMessageMode = registerClientErrorMessageMode;
 exports.errorMessageModesDiverged = errorMessageModesDiverged;
 exports.runWithErrorMessageMode = runWithErrorMessageMode;
@@ -39,6 +39,8 @@ exports.TurbineErrorCode = {
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
     READ_ONLY: 'TURBINE_E018',
+    TRANSACTION_ROLLED_BACK: 'TURBINE_E019',
+    INVARIANT_VIOLATION: 'TURBINE_E020',
 };
 /**
  * The docs page anchor for a code: `TURBINE_E003` -> `.../errors#e003`.
@@ -622,12 +624,14 @@ function renderWhereForMessage(where, mode) {
  *   `[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.
  */
 class NotFoundError extends TurbineError {
     static CODE = exports.TurbineErrorCode.NOT_FOUND;
     table;
-    where;
     operation;
     constructor(input) {
         // Back-compat: string argument (or undefined), replicate legacy behavior.
@@ -654,7 +658,12 @@ class NotFoundError extends TurbineError {
         super(exports.TurbineErrorCode.NOT_FOUND, message, { cause });
         this.name = 'NotFoundError';
         this.table = table;
-        this.where = where;
+        Object.defineProperty(this, 'where', {
+            value: where,
+            enumerable: currentErrorMessageMode() === 'verbose',
+            writable: false,
+            configurable: true,
+        });
         this.operation = operation;
     }
 }
@@ -663,18 +672,22 @@ exports.NotFoundError = NotFoundError;
 class TimeoutError extends TurbineError {
     static CODE = exports.TurbineErrorCode.TIMEOUT;
     timeoutMs;
+    /** Whether the interrupted statement can have taken effect. See {@link TimeoutOutcome}. */
+    outcome;
     /**
      * @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, context = 'Query', options) {
         super(exports.TurbineErrorCode.TIMEOUT, options?.message ?? `${context} timed out after ${timeoutMs}ms`, options);
         this.name = 'TimeoutError';
         this.timeoutMs = timeoutMs;
+        this.outcome = options?.outcome ?? 'unknown';
     }
 }
 exports.TimeoutError = TimeoutError;
@@ -975,6 +988,75 @@ class SerializationFailureError extends TurbineError {
     }
 }
 exports.SerializationFailureError = SerializationFailureError;
+/** Marks a {@link LockNotAvailableError} across copies of this module (it shares E013 with its parent). */
+const LOCK_NOT_AVAILABLE_BRAND = Symbol.for('turbine-orm.lockNotAvailable');
+/**
+ * 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.
+ */
+class LockNotAvailableError extends SerializationFailureError {
+    constructor(opts = {}) {
+        const { cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const driverMessage = cause?.message;
+            message =
+                `Row lock not available${driverMessage ? `: ${driverMessage}` : ''}. Another transaction holds the lock. ` +
+                    'Retry after a backoff, or read with skipLocked to take only the rows that are free.';
+        }
+        super({ message, cause });
+        this.name = 'LockNotAvailableError';
+        Object.defineProperty(this, LOCK_NOT_AVAILABLE_BRAND, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    /**
+     * `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) {
+        // biome-ignore lint/complexity/noThisInStatic: the receiver may be a caller's subclass, see TurbineError
+        // biome-ignore lint/complexity/noUselessThisAlias: one alias carries one suppression
+        const cls = this;
+        if (Function.prototype[Symbol.hasInstance].call(cls, value))
+            return true;
+        if (cls !== LockNotAvailableError)
+            return false;
+        return (SerializationFailureError[Symbol.hasInstance](value) &&
+            value[LOCK_NOT_AVAILABLE_BRAND] === true);
+    }
+}
+exports.LockNotAvailableError = LockNotAvailableError;
+/**
+ * A lock that could not be taken: PostgreSQL 55P03 (`NOWAIT`, or
+ * `lock_timeout`), MySQL 3572 (`NOWAIT`) and 1205 (lock wait timeout), SQL
+ * Server 1222 (lock request timeout). The MySQL and SQL Server shapes arrive
+ * with `.code` already set to 40001 by their engine modules, so the driver's
+ * own number decides.
+ */
+function isLockNotAvailableError(err, code) {
+    if (code === '55P03' || code === 'ER_LOCK_NOWAIT')
+        return true;
+    const e = err;
+    if (e.errno === 3572)
+        return true;
+    return code === '40001' && (e.errno === 1205 || e.number === 1222);
+}
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 class CheckConstraintError extends TurbineError {
     static CODE = exports.TurbineErrorCode.CHECK_VIOLATION;
@@ -1146,24 +1228,114 @@ 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.
      */
     reason;
     /**
      * @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, options) {
-        super(exports.TurbineErrorCode.READ_ONLY, `${detail} Route writes to a writable primary.`, {
+        const reason = options?.reason ?? 'snapshot';
+        super(exports.TurbineErrorCode.READ_ONLY, `${detail} ${READ_ONLY_HINTS[reason]}`, {
             cause: options?.cause,
         });
         this.name = 'ReadOnlyError';
-        this.reason = options?.reason ?? 'snapshot';
+        this.reason = reason;
     }
 }
 exports.ReadOnlyError = ReadOnlyError;
+const READ_ONLY_HINTS = {
+    snapshot: 'Route writes to a writable primary.',
+    rbac: 'Route writes to a writable primary.',
+    transaction: 'Run the write in a read-write transaction (not `readOnly: true` or BEGIN READ ONLY) on the primary, ' +
+        'not a read replica.',
+};
+/**
+ * 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.
+ */
+class TransactionRolledBackError extends TurbineError {
+    static CODE = exports.TurbineErrorCode.TRANSACTION_ROLLED_BACK;
+    /**
+     * @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, options) {
+        super(exports.TurbineErrorCode.TRANSACTION_ROLLED_BACK, message, options);
+        this.name = 'TransactionRolledBackError';
+    }
+}
+exports.TransactionRolledBackError = TransactionRolledBackError;
+/**
+ * The sentence every {@link InvariantError} message ends with, before the docs
+ * link. Exported so a test can assert it without restating it.
+ */
+exports.INVARIANT_REPORT_HINT = 'This is a bug in turbine-orm, not in your code. Please report it at ' +
+    'https://github.com/zvndev/turbine-orm/issues with this message.';
+/**
+ * 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.
+ */
+class InvariantError extends TurbineError {
+    static CODE = exports.TurbineErrorCode.INVARIANT_VIOLATION;
+    /** Stable id of the broken invariant, e.g. `'sql-cache-lockstep'`. */
+    invariant;
+    /**
+     * @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, message, options) {
+        const body = message.includes(exports.INVARIANT_REPORT_HINT) ? message : `${message} ${exports.INVARIANT_REPORT_HINT}`;
+        super(exports.TurbineErrorCode.INVARIANT_VIOLATION, body, options);
+        this.name = 'InvariantError';
+        this.invariant = invariant;
+    }
+}
+exports.InvariantError = InvariantError;
+/**
+ * A write refused because its transaction is read-only: PostgreSQL SQLSTATE
+ * 25006, or MySQL's error 1792 (which carries the same SQLSTATE).
+ */
+function isReadOnlyTransactionError(err, code) {
+    if (code === '25006' || code === 'ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION')
+        return true;
+    const e = err;
+    return e.errno === 1792 && e.sqlState === '25006';
+}
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."
@@ -1195,6 +1367,11 @@ const CONNECTION_ERROR_CODES = new Set([
     '08006', // connection_failure
     '08007', // transaction_resolution_unknown
     '08P01', // protocol_violation
+    // A named prepared statement met a server connection that did not prepare it
+    // (26000) or already holds it (42P05). Turbine names its own statements, so
+    // the usual cause is a transaction-pooling endpoint switching backends.
+    '42P05', // duplicate_prepared_statement
+    '26000', // invalid_sql_statement_name
     // pg SQLSTATE class 28: the server answered and REFUSED us. These are the
     // most common first-run failures there are (wrong password, a pg_hba rule
     // that does not cover this user/host), and they used to fall through
@@ -1214,6 +1391,11 @@ const CONNECTION_ERROR_CODES = new Set([
     '57P01', // admin_shutdown
     '57P02', // crash_shutdown
     '57P03', // cannot_connect_now
+    // The server ended a session that sat idle inside an open transaction past
+    // idle_in_transaction_session_timeout (a FATAL: the connection is gone).
+    // A cursor stream sets that limit on its own transaction, see
+    // query/stream-idle.ts, so this is how a frozen process's stream ends.
+    '25P03', // idle_in_transaction_session_timeout
     // Node driver-level socket errors (surface on err.code too)
     'ECONNREFUSED',
     'ECONNRESET',
@@ -1253,6 +1435,11 @@ const PG_CONNECTION_LOSS_MESSAGES = new Set([
     'Connection terminated',
     'Connection terminated due to connection timeout',
 ]);
+/** pg-pool's own words for a checkout that waited longer than `connectionTimeoutMillis`. */
+const PG_POOL_CHECKOUT_TIMEOUT_MESSAGE = 'timeout exceeded when trying to connect';
+const POOL_CHECKOUT_TIMEOUT_HINT = "Timed out waiting for a free connection from the pool. Something is holding connections for longer than the pool's " +
+    'connection timeout: long transactions or streams, or a query on the outer client inside a `$transaction` ' +
+    'callback, which needs a second connection (use `tx` there). Raise the pool size if the load is genuine.';
 /** The follow-on errors pg raises for a query sent to a client already known to be dead. */
 const PG_NOT_QUERYABLE_MESSAGES = new Set([
     'Client has encountered a connection error and is not queryable',
@@ -1311,6 +1498,11 @@ function isStaleConnectionError(err) {
 }
 const CONNECTION_LOSS_HINT = 'The server or the network closed it (a restart, failover, idle timeout, compute suspend, or ' +
     'pg_terminate_backend). The pool discards the connection, so retrying the operation opens a fresh one.';
+const PREPARED_STATEMENT_POOLER_HINT = 'A named prepared statement met a server connection that did not prepare it, or that already holds it. A ' +
+    'transaction-pooling endpoint (PgBouncer in transaction mode, a managed "-pooler" host, port 6432 or 6543) ' +
+    'gives each transaction to a different server connection, which is the usual cause. Connect to the direct ' +
+    'endpoint, set `preparedStatements: false`, or turn on prepared-statement support in the pooler (PgBouncer ' +
+    '1.21 or later, `max_prepared_statements` above 0).';
 /**
  * Actionable next step per connection-class code, appended to the driver's own
  * message. The driver message states WHAT happened ("password authentication
@@ -1320,11 +1512,18 @@ const CONNECTION_LOSS_HINT = 'The server or the network closed it (a restart, fa
  * A code with no entry here simply gets no hint appended.
  */
 const CONNECTION_ERROR_HINTS = {
+    '42P05': PREPARED_STATEMENT_POOLER_HINT,
+    '26000': PREPARED_STATEMENT_POOLER_HINT,
     '28P01': 'The server rejected the credentials. Check the password in your connection string (or DATABASE_URL), including any URL-encoding of special characters.',
     '28000': "The server refused this user/host combination. Check the user name and the server's pg_hba.conf rules for the client address.",
     '3D000': 'The database named in the connection string does not exist. Check the path segment after the host, and create the database if needed.',
     '53300': "The server has no free connection slots. Lower `poolSize` or raise the server's max_connections.",
     '57P03': 'The server is still starting up (or shutting down) and is not accepting connections yet.',
+    '25P03': 'The server ended the session because it sat idle inside an open transaction for longer than ' +
+        '`idle_in_transaction_session_timeout`. A cursor stream sets that limit to its idle timeout plus 10 s, so for ' +
+        'a stream this means the process ran nothing for that long (a frozen serverless instance, a blocked event ' +
+        'loop); for a transaction, that the callback awaited something else for longer than the server allows. The ' +
+        'connection is discarded and the pool opens a fresh one.',
     ECONNREFUSED: 'Nothing is listening on that host and port. Check the server is running and the port is right.',
     ENOTFOUND: 'The host in the connection string could not be resolved. Check the host name, and that the connection string itself is well formed.',
     EAI_AGAIN: 'DNS lookup for the host failed temporarily. Check network/DNS availability, then retry.',
@@ -1556,9 +1755,13 @@ function scrubUnclassifiedServerError(err, code) {
  *   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
@@ -1587,8 +1790,26 @@ function wrapPgError(err) {
         if (err instanceof Error && PG_CONNECTION_LOSS_MESSAGES.has(err.message)) {
             return new ConnectionError(`Database connection lost: ${err.message}. ${CONNECTION_LOSS_HINT}`, { cause: err });
         }
+        // pg-pool's checkout timeout carries no code either. A pool Turbine owns
+        // types it at checkout (checkout.ts); this covers a caller's own pg.Pool.
+        if (err instanceof Error && err.message === PG_POOL_CHECKOUT_TIMEOUT_MESSAGE) {
+            return new ConnectionError(POOL_CHECKOUT_TIMEOUT_HINT, { cause: err });
+        }
         return err;
     }
+    if (isReadOnlyTransactionError(err, e.code)) {
+        const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? e.message : 'write refused';
+        return new ReadOnlyError(`${pgMessage} (SQLSTATE 25006).`, { cause: err, reason: 'transaction' });
+    }
+    if (isLockNotAvailableError(err, e.code))
+        return new LockNotAvailableError({ cause: err });
+    // A protocol violation answered with ERROR rather than FATAL concerns one
+    // message, and the connection stays usable. The common cause is a Buffer
+    // bound to a column that is not bytea: node-postgres sends a Buffer as
+    // binary data, which the server cannot read as an integer or a date.
+    if (e.code === '08P01' && e.severity === 'ERROR') {
+        return wrapValueBearingPgError(err, e, 'Invalid input', 'a bound value could not be read as the type the statement expects', ' A Buffer is sent as binary data and fits only a bytea column; pass a number, string or Date for any other type.');
+    }
     switch (e.code) {
         case '23505': {
             const cols = e.detail ? parseColumnsFromDetail(e.detail) : undefined;
@@ -1633,13 +1854,27 @@ function wrapPgError(err) {
                 cause: err,
             });
         case '57014':
-            // query_canceled: a server-side statement_timeout cancelled the query.
-            // Turbine did not set the deadline (that lives in Postgres config), so
-            // there is no client-side budget to report → timeoutMs = 0.
+            // query_canceled: the statement was stopped, so it made no change. A
+            // cancel request (what Turbine sends when a query or transaction
+            // `timeout` expires) reads "due to user request"; anything else is the
+            // server's own statement_timeout.
             return new TimeoutError(0, 'Query', {
-                message: 'Query canceled by server-side statement_timeout',
+                message: typeof e.message === 'string' && /user request/i.test(e.message)
+                    ? 'Query cancelled on the server by a cancel request, which Turbine sends when a query or ' +
+                        'transaction `timeout` expires. It made no change.'
+                    : 'Query canceled by server-side statement_timeout',
                 cause: err,
+                outcome: 'not-executed',
             });
+        case '25P02':
+            // in_failed_sql_transaction: a statement sent after an earlier one failed. Turbine's own
+            // transactions refuse it first, with the failure attached (transaction-state.ts); this is
+            // the driver's answer on a path that sent it anyway (a connection used outside Turbine).
+            return new TransactionRolledBackError('A statement was sent after an earlier statement in the same transaction failed. PostgreSQL ignores ' +
+                'every statement after a failure until the transaction, or the savepoint it ran in, is rolled back, ' +
+                'so nothing more can be saved in it. Catching the error does not undo the abort: let it leave the ' +
+                'transaction, or run the statement that can fail in its own nested `tx.$transaction(...)`, which ' +
+                'rolls back only that savepoint. The earlier failure is the error that statement threw.', { cause: err });
         default:
             if (CONNECTION_ERROR_CODES.has(e.code)) {
                 const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? e.message : undefined;
@@ -1662,6 +1897,14 @@ function wrapPgError(err) {
                     : DATA_EXCEPTION_FALLBACK;
                 return wrapValueBearingPgError(err, e, subject, phrase);
             }
+            // 42883: no operator or function for these argument types, e.g. a bigint
+            // column compared with text. PostgreSQL's message names types, never
+            // values, so it is kept in both modes.
+            if (e.code === '42883') {
+                const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? `${e.message} ` : '';
+                return new ValidationError(`${pgMessage}(SQLSTATE 42883). A value of one type was compared with or passed to something that takes ` +
+                    "another, usually a value bound to a column of a different type. Pass a value of the column's type.", { cause: err, sqlstate: e.code });
+            }
             // 42601 is any syntax error. Only the to_tsquery parse failure is a
             // caller-input problem Turbine can name (the `search` operator), so the
             // message text is the discriminator; every other 42601 takes the generic

package/dist/cjs/generate.d.ts

@@ -8,10 +8,36 @@
  *
  * Output goes to the specified directory (default: ./generated/turbine/).
  */
-import { type PrismaCompatMap, type SchemaMetadata } from './schema.js';
+import { type TurbineLogger } from './logger.js';
+import { type ColumnMetadata, type PrismaCompatMap, type SchemaMetadata } from './schema.js';
+/**
+ * Per-column TypeScript overrides from {@link GenerateOptions.columnTypes},
+ * keyed by database table name, then database column name.
+ */
+type ColumnTypeOverrides = ReadonlyMap<string, ReadonlyMap<string, string>>;
+/**
+ * Resolve the TypeScript type for a column, mapping enum-typed columns to their
+ * generated string-literal union (PascalCase enum name) instead of the
+ * `unknown` that {@link pgTypeToTs} yields for user-defined types. A
+ * `columnTypes` override replaces the type outright (nullability is still
+ * added). Falls back to the introspected `col.tsType` for everything else.
+ */
+export declare function columnTsType(col: ColumnMetadata, enums: Record<string, string[]>, override?: string): string;
+/**
+ * Validate {@link GenerateOptions.columnTypes} against the schema and index it.
+ * A key naming no table or column is a `ValidationError`, not a silent no-op,
+ * since an override that applies to nothing leaves the column typed `unknown`.
+ */
+export declare function resolveColumnTypeOverrides(schema: SchemaMetadata, columnTypes: Readonly<Record<string, string>> | undefined): ColumnTypeOverrides | undefined;
 export interface GenerateOptions {
     /** The introspected schema to generate from */
     schema: SchemaMetadata;
+    /**
+     * Where generation notes go (a relation omitted from the generated types
+     * because it shadows a column). Defaults to the console logger. Never
+     * affects the generated files.
+     */
+    logger?: TurbineLogger;
     /** Output directory (default: './generated/turbine') */
     outDir?: string;
     /** Redact connection string from generated comments */
@@ -36,6 +62,10 @@ export interface GenerateOptions {
      *
      *   - `'js'`: always `./types.js` (required by NodeNext `tsc` and by
      *     tsc-compiled ESM run on Node; the pre-0.41 behavior).
+     *   - `'ts'`: always `./types.ts`, so Node's native type stripping can run the
+     *     generated files directly (`node app.ts`). A type checker needs
+     *     `allowImportingTsExtensions` or `rewriteRelativeImportExtensions` to
+     *     accept it. `'auto'` never picks this.
      *   - `'none'`: always `./types` (correct for bundlers / `moduleResolution
      *     bundler | node10`: webpack, Next.js/SWC, Vite/esbuild).
      *   - `'auto'` (default): walk up from `outDir` to the nearest `tsconfig.json`
@@ -44,7 +74,7 @@ export interface GenerateOptions {
      *     neither is, and fall back to `'.js'` when the tsconfig is missing,
      *     unparseable, or ambiguous (so NodeNext consumers can never regress).
      */
-    importExtension?: 'js' | 'none' | 'auto';
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     /**
      * Rewrite generated column FIELD names to the raw database column names
      * (snake_case) instead of camelCase (F4). Opt-in; when unset the output is
@@ -54,18 +84,36 @@ export interface GenerateOptions {
      * names are unaffected.
      */
     keepColumnNames?: boolean;
+    /**
+     * TypeScript types for specific columns, keyed `"<table>.<column>"` with
+     * database names. The value is emitted as written into the row type and the
+     * `*Create` / `*Update` input types (`| null` is added for a nullable
+     * column), so a json/jsonb column can carry its real shape instead of
+     * `unknown`:
+     *
+     *   columnTypes: { 'users.settings': "import('../src/settings.js').Settings" }
+     *
+     * A relative `import()` resolves from the output directory. The type is a
+     * compile-time claim: nothing checks stored values against it. A key naming
+     * no table or column is an error.
+     */
+    columnTypes?: Readonly<Record<string, string>>;
 }
 /** Per-file generator options (subset of {@link GenerateOptions} the emitters need). */
 export interface GenerateFileOptions {
     /** Omit the `Generated at:` header line for reproducible output. */
     noTimestamp?: boolean;
     /**
-     * Resolved sibling-import extension for `generateIndex` (`'.js'` or `''`).
+     * Resolved sibling-import extension for `generateIndex` (`'.js'`, `'.ts'` or `''`).
      * Defaults to `'.js'` when unset so direct callers stay byte-stable.
      */
     importExt?: string;
     /** Human-readable resolved import mode, recorded as a comment in `index.ts`. */
     importMode?: string;
+    /** {@link GenerateOptions.columnTypes}; validated against the schema by the emitter. */
+    columnTypes?: Readonly<Record<string, string>>;
+    /** {@link GenerateOptions.logger}. */
+    logger?: TurbineLogger;
 }
 export declare function generate(options: GenerateOptions): {
     outDir: string;
@@ -77,12 +125,13 @@ export declare function generate(options: GenerateOptions): {
  * mode label for the generated comment.
  *
  *   - `'js'`   → `.js`
+ *   - `'ts'`   → `.ts`
  *   - `'none'` → `''`
  *   - `'auto'` → tsconfig-driven ({@link detectTsconfigExtension}); falls back
  *     to `.js` (the pre-0.41 default) when detection is uncertain, so NodeNext
  *     consumers can never regress.
  */
-export declare function resolveImportExtension(outDir: string, requested: 'js' | 'none' | 'auto'): {
+export declare function resolveImportExtension(outDir: string, requested: 'js' | 'ts' | 'none' | 'auto'): {
     ext: string;
     mode: string;
 };
@@ -137,10 +186,10 @@ export declare function isEmittableIdentifier(name: string): boolean;
 export declare function assertEmittableSchema(schema: SchemaMetadata): void;
 /**
  * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
- * and *Relations brand-field interfaces). Exported so tests can pin the
- * generator output without writing files to disk.
+ * *Relations brand-field interfaces, and the write input types). Exported so
+ * tests can pin the generator output without writing files to disk.
  */
-export declare function generateTypes(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateTypes(input: SchemaMetadata, options?: GenerateFileOptions): string;
 /**
  * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
  * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
@@ -161,3 +210,4 @@ export declare function generateIndex(schema: SchemaMetadata, options?: Generate
  * stable input regenerates byte-identical output under `noTimestamp`.
  */
 export declare function generatePrismaMap(map: PrismaCompatMap, options?: GenerateFileOptions): string;
+export {};