turbine-orm 0.7.0 → 0.7.1

package/dist/cli/migrate.js

@@ -260,12 +260,19 @@ async function validateChecksums(client, migrationsDir) {
  * Features:
  * - Idempotent: running twice is safe (already-applied migrations are skipped)
  * - Advisory lock: prevents concurrent migration runs
- * - Checksum validation: detects modified migration files
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
  * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
  */
 export async function migrateUp(connectionString, migrationsDir, options) {
     const client = new pg.Client({ connectionString });
     await client.connect();
+    // Treat `force` as an alias for `allowDrift` for backwards compatibility.
+    const allowDrift = options?.allowDrift === true || options?.force === true;
     try {
         // Acquire advisory lock to prevent concurrent migrations
         const gotLock = await acquireLock(client);
@@ -274,18 +281,35 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         }
         try {
             await ensureTrackingTable(client);
-            // Validate checksums of already-applied migrations (skip with --force)
-            if (!options?.force) {
+            // Validate checksums of already-applied migrations.
+            // Drift = an APPLIED migration's on-disk file has changed (or been deleted)
+            // since it was run. Either situation means the database state and the
+            // migration history no longer agree, so we BLOCK the run by default.
+            // Users can pass `allowDrift: true` (CLI: `--allow-drift`) to force past
+            // the block when they are intentionally rewriting history.
+            if (!allowDrift) {
                 const mismatches = await validateChecksums(client, migrationsDir);
                 if (mismatches.length > 0) {
                     const modified = mismatches.filter((m) => m.type === 'modified');
                     const missing = mismatches.filter((m) => m.type === 'missing');
-                    const parts = [];
-                    if (modified.length > 0)
-                        parts.push(`modified: ${modified.map((m) => m.name).join(', ')}`);
-                    if (missing.length > 0)
-                        parts.push(`deleted: ${missing.map((m) => m.name).join(', ')}`);
-                    throw new MigrationError(`[turbine] Migration integrity check failed — ${parts.join('; ')}. Applied migrations should be immutable. Use --force to skip this check.`);
+                    const lines = [
+                        '[turbine] Migration drift detected — refusing to apply pending migrations.',
+                        '',
+                        'Applied migrations should be immutable. The following files no longer match their applied state:',
+                        '',
+                    ];
+                    for (const m of modified) {
+                        lines.push(`  - ${m.name}.sql  (modified on disk)`);
+                    }
+                    for (const m of missing) {
+                        lines.push(`  - ${m.name}.sql  (deleted from disk)`);
+                    }
+                    lines.push('');
+                    lines.push('Fix one of these:');
+                    lines.push('  1. Restore the file(s) to their original content, OR');
+                    lines.push('  2. Roll back the affected migrations with `npx turbine migrate down`, OR');
+                    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced — make sure you know what you are doing).');
+                    throw new MigrationError(lines.join('\n'));
                 }
             }
             const applied = await getAppliedMigrations(client);

package/dist/cli/ui.d.ts

@@ -34,7 +34,7 @@ export declare const symbols: {
     readonly warning: "⚠" | "!";
     readonly dot: "." | "∙";
     readonly line: "─" | "-";
-    readonly vertLine: "│" | "|";
+    readonly vertLine: "|" | "│";
     readonly topLeft: "╭" | "+";
     readonly topRight: "+" | "╮";
     readonly bottomLeft: "+" | "╰";

package/dist/client.d.ts

@@ -22,6 +22,7 @@
  * ```
  */
 import pg from 'pg';
+import { type ErrorMessageMode } from './errors.js';
 import { type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query.js';
 import type { SchemaMetadata } from './schema.js';
@@ -110,6 +111,20 @@ export interface TurbineConfig {
     defaultLimit?: number;
     /** Log a warning when findMany() is called without a limit (default: false) */
     warnOnUnlimited?: boolean;
+    /**
+     * Controls how `NotFoundError` (and other where-aware errors) format their
+     * messages.
+     *
+     *   - `'safe'`    (default): the message includes only the keys of the where
+     *     clause (e.g. `where: { id, email }`). Values are redacted to avoid
+     *     leaking PII into error logs (Sentry, Datadog, etc.).
+     *   - `'verbose'`: the message includes the full JSON-serialized where
+     *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+     *
+     * The full `where` object is always available as `err.where` for
+     * programmatic access regardless of mode.
+     */
+    errorMessages?: ErrorMessageMode;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {

package/dist/client.js

@@ -22,7 +22,7 @@
  * ```
  */
 import pg from 'pg';
-import { TimeoutError, wrapPgError } from './errors.js';
+import { setErrorMessageMode, TimeoutError, wrapPgError } from './errors.js';
 import { executePipeline } from './pipeline.js';
 import { QueryInterface } from './query.js';
 /** Maps isolation level names to SQL */
@@ -188,6 +188,11 @@ export class TurbineClient {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
         };
+        // Apply NotFoundError message redaction mode (default: safe — values are
+        // stripped from messages to avoid leaking PII into error logs).
+        if (config.errorMessages) {
+            setErrorMessageMode(config.errorMessages);
+        }
         if (config.pool) {
             // External pool — use directly. Turbine doesn't manage its lifecycle.
             this.pool = config.pool;
@@ -392,6 +397,24 @@ export class TurbineClient {
     async $transaction(fn, options) {
         const client = await this.pool.connect();
         const timeout = options?.timeout;
+        /**
+         * Track whether the connection has already been released so the finally
+         * block doesn't double-release. When a timeout fires we destroy the
+         * connection eagerly to abort the in-flight backend query.
+         */
+        let released = false;
+        const releaseOnce = (err) => {
+            if (released)
+                return;
+            released = true;
+            try {
+                client.release(err);
+            }
+            catch {
+                // pg may throw if the client is already released — swallow.
+            }
+        };
+        let timedOut = false;
         try {
             // BEGIN with optional isolation level
             let beginSQL = 'BEGIN';
@@ -415,10 +438,22 @@ export class TurbineClient {
             }
             let result;
             if (timeout) {
-                // Race between the function and a timeout
+                // Race between the function and a timeout. If the timeout fires we
+                // need to actually abort the in-flight query — otherwise the backend
+                // keeps running until pg's own timeout, holding a pool slot the whole
+                // time. The simplest reliable cancellation is to destroy the
+                // connection: passing a truthy argument to client.release() tells the
+                // pg pool to discard the client (its socket is closed, which causes
+                // Postgres to abort the active query and roll back the transaction).
+                // The pool will spin up a fresh connection on the next checkout.
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
+                        timedOut = true;
+                        // Destroy the connection to abort the in-flight backend query.
+                        // We do this BEFORE rejecting so the socket is gone by the time
+                        // the caller's catch block runs.
+                        releaseOnce(new Error('[turbine] Transaction timeout — connection destroyed'));
                         reject(new TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
@@ -439,14 +474,25 @@ export class TurbineClient {
             return result;
         }
         catch (err) {
-            await client.query('ROLLBACK');
+            // If the timeout fired we already destroyed the connection — issuing a
+            // ROLLBACK on a released client would throw "Client has already been
+            // released". Skip the rollback in that case (the backend rolled back
+            // when its socket was closed).
+            if (!timedOut && !released) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             if (this.logging) {
                 console.log('[turbine] Transaction rolled back');
             }
             throw err;
         }
         finally {
-            client.release();
+            releaseOnce();
         }
     }
     // -------------------------------------------------------------------------

package/dist/errors.d.ts

@@ -17,6 +17,8 @@ export declare const TurbineErrorCode: {
     readonly FOREIGN_KEY_VIOLATION: "TURBINE_E009";
     readonly NOT_NULL_VIOLATION: "TURBINE_E010";
     readonly CHECK_VIOLATION: "TURBINE_E011";
+    readonly DEADLOCK_DETECTED: "TURBINE_E012";
+    readonly SERIALIZATION_FAILURE: "TURBINE_E013";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -26,6 +28,30 @@ export declare class TurbineError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Controls whether NotFoundError messages include the actual `where` values
+ * (`'verbose'`) or only the where-clause keys (`'safe'`, the default).
+ *
+ * Defaults to `'safe'` to avoid leaking PII into error logs (Sentry, Datadog,
+ * etc.). The full `where` object is always available as `err.where` for
+ * programmatic access — only the human-readable message is redacted.
+ *
+ * Set via `setErrorMessageMode('verbose')` or by constructing TurbineClient
+ * with `{ errorMessages: 'verbose' }`.
+ */
+export type ErrorMessageMode = 'safe' | 'verbose';
+/**
+ * Set the global NotFoundError message mode. Called from the TurbineClient
+ * constructor when `TurbineConfig.errorMessages` is provided.
+ *
+ *   - `'safe'`    (default): the message includes only the keys of the where
+ *     clause (e.g. `where: { id, email }`). Values are redacted.
+ *   - `'verbose'`: the message includes the full JSON-serialized where
+ *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ */
+export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
+/** Returns the current NotFoundError message mode. Exported for tests. */
+export declare function getErrorMessageMode(): ErrorMessageMode;
 /**
  * Thrown when a record is not found (findUniqueOrThrow, findFirstOrThrow,
  * update/delete against a non-matching row, etc.)
@@ -35,8 +61,16 @@ export declare class TurbineError extends Error {
  *   - `new NotFoundError({ table, where, operation, cause, message })`
  *
  * When called with an options object and no explicit `message`, a Prisma-style
- * message is built automatically, e.g.:
+ * message is built automatically. By default, only the where-clause keys are
+ * shown to avoid leaking PII into logs:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: { id }`
+ *
+ * Set `setErrorMessageMode('verbose')` (or pass `errorMessages: 'verbose'` to
+ * the TurbineClient constructor) to include the full where values:
  *   `[turbine] 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.
  */
 export declare class NotFoundError extends TurbineError {
     readonly table?: string;
@@ -111,6 +145,57 @@ export declare class NotNullViolationError extends TurbineError {
         cause?: unknown;
     });
 }
+/**
+ * Thrown when Postgres detects a deadlock (pg code 40P01).
+ *
+ * This error is **retryable** — when caught, callers can safely retry the
+ * transaction (typically with backoff). Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... });
+ * } catch (err) {
+ *   if (err instanceof DeadlockError) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export declare class DeadlockError extends TurbineError {
+    /** Marks this error as safe to retry */
+    readonly isRetryable: true;
+    readonly constraint?: string;
+    constructor(opts?: {
+        message?: string;
+        constraint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a Serializable transaction fails due to a serialization
+ * conflict (pg code 40001 — `could not serialize access due to ...`).
+ *
+ * This error is **retryable** — by Postgres documentation, the recommended
+ * response is to re-run the entire transaction. Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... }, { isolationLevel: 'Serializable' });
+ * } catch (err) {
+ *   if (err instanceof SerializationFailureError) {
+ *     // safe to retry the whole transaction
+ *   }
+ * }
+ * ```
+ */
+export declare class SerializationFailureError extends TurbineError {
+    /** Marks this error as safe to retry */
+    readonly isRetryable: true;
+    constructor(opts?: {
+        message?: string;
+        cause?: unknown;
+    });
+}
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 export declare class CheckConstraintError extends TurbineError {
     readonly constraint?: string;
@@ -131,6 +216,8 @@ export declare class CheckConstraintError extends TurbineError {
  *   23503 (foreign_key_violation) -> ForeignKeyError
  *   23502 (not_null_violation)    -> NotNullViolationError
  *   23514 (check_violation)       -> CheckConstraintError
+ *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
+ *   40001 (serialization_failure) -> SerializationFailureError (retryable)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */

package/dist/errors.js

@@ -17,6 +17,8 @@ export const TurbineErrorCode = {
     FOREIGN_KEY_VIOLATION: 'TURBINE_E009',
     NOT_NULL_VIOLATION: 'TURBINE_E010',
     CHECK_VIOLATION: 'TURBINE_E011',
+    DEADLOCK_DETECTED: 'TURBINE_E012',
+    SERIALIZATION_FAILURE: 'TURBINE_E013',
 };
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
@@ -27,6 +29,47 @@ export class TurbineError extends Error {
         this.code = code;
     }
 }
+let errorMessageMode = 'safe';
+/**
+ * Set the global NotFoundError message mode. Called from the TurbineClient
+ * constructor when `TurbineConfig.errorMessages` is provided.
+ *
+ *   - `'safe'`    (default): the message includes only the keys of the where
+ *     clause (e.g. `where: { id, email }`). Values are redacted.
+ *   - `'verbose'`: the message includes the full JSON-serialized where
+ *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ */
+export function setErrorMessageMode(mode) {
+    errorMessageMode = mode;
+}
+/** Returns the current NotFoundError message mode. Exported for tests. */
+export function getErrorMessageMode() {
+    return errorMessageMode;
+}
+/**
+ * Render a `where` clause for error messages. In 'safe' mode (the default),
+ * only the keys are shown; values are stripped to avoid leaking PII into logs.
+ * Nested AND/OR/NOT combinators are recursively rendered.
+ */
+function renderWhereForMessage(where, mode) {
+    if (mode === 'verbose') {
+        try {
+            return JSON.stringify(where);
+        }
+        catch {
+            return '[unserializable]';
+        }
+    }
+    // safe mode: keys only
+    if (where === null || where === undefined)
+        return '';
+    if (typeof where !== 'object')
+        return '';
+    const keys = Object.keys(where);
+    if (keys.length === 0)
+        return '{}';
+    return `{ ${keys.join(', ')} }`;
+}
 /**
  * Thrown when a record is not found (findUniqueOrThrow, findFirstOrThrow,
  * update/delete against a non-matching row, etc.)
@@ -36,8 +79,16 @@ export class TurbineError extends Error {
  *   - `new NotFoundError({ table, where, operation, cause, message })`
  *
  * When called with an options object and no explicit `message`, a Prisma-style
- * message is built automatically, e.g.:
+ * message is built automatically. By default, only the where-clause keys are
+ * shown to avoid leaking PII into logs:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: { id }`
+ *
+ * Set `setErrorMessageMode('verbose')` (or pass `errorMessages: 'verbose'` to
+ * the TurbineClient constructor) to include the full where values:
  *   `[turbine] 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.
  */
 export class NotFoundError extends TurbineError {
     table;
@@ -54,11 +105,11 @@ export class NotFoundError extends TurbineError {
         let message = input.message;
         if (!message) {
             if (operation && table) {
-                const wherePart = where !== undefined ? ` matching where: ${JSON.stringify(where)}` : '';
+                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, errorMessageMode)}` : '';
                 message = `[turbine] ${operation} on "${table}" found no record${wherePart}`;
             }
             else if (table) {
-                const wherePart = where !== undefined ? ` matching where ${JSON.stringify(where)}` : '';
+                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, errorMessageMode)}` : '';
                 message = `[turbine] No record found in "${table}"${wherePart}`;
             }
             else {
@@ -194,6 +245,71 @@ export class NotNullViolationError extends TurbineError {
         this.table = table;
     }
 }
+/**
+ * Thrown when Postgres detects a deadlock (pg code 40P01).
+ *
+ * This error is **retryable** — when caught, callers can safely retry the
+ * transaction (typically with backoff). Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... });
+ * } catch (err) {
+ *   if (err instanceof DeadlockError) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export class DeadlockError extends TurbineError {
+    /** Marks this error as safe to retry */
+    isRetryable = true;
+    constraint;
+    constructor(opts = {}) {
+        const { constraint, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const pgMessage = cause?.message;
+            message = pgMessage ? `[turbine] Deadlock detected: ${pgMessage}` : '[turbine] Deadlock detected';
+        }
+        super(TurbineErrorCode.DEADLOCK_DETECTED, message, { cause });
+        this.name = 'DeadlockError';
+        this.constraint = constraint;
+    }
+}
+/**
+ * Thrown when a Serializable transaction fails due to a serialization
+ * conflict (pg code 40001 — `could not serialize access due to ...`).
+ *
+ * This error is **retryable** — by Postgres documentation, the recommended
+ * response is to re-run the entire transaction. Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... }, { isolationLevel: 'Serializable' });
+ * } catch (err) {
+ *   if (err instanceof SerializationFailureError) {
+ *     // safe to retry the whole transaction
+ *   }
+ * }
+ * ```
+ */
+export class SerializationFailureError extends TurbineError {
+    /** Marks this error as safe to retry */
+    isRetryable = true;
+    constructor(opts = {}) {
+        const { cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const pgMessage = cause?.message;
+            message = pgMessage
+                ? `[turbine] Serializable transaction conflict: ${pgMessage}`
+                : '[turbine] Serializable transaction conflict';
+        }
+        super(TurbineErrorCode.SERIALIZATION_FAILURE, message, { cause });
+        this.name = 'SerializationFailureError';
+    }
+}
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 export class CheckConstraintError extends TurbineError {
     constraint;
@@ -234,6 +350,8 @@ function parseColumnsFromDetail(detail) {
  *   23503 (foreign_key_violation) -> ForeignKeyError
  *   23502 (not_null_violation)    -> NotNullViolationError
  *   23514 (check_violation)       -> CheckConstraintError
+ *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
+ *   40001 (serialization_failure) -> SerializationFailureError (retryable)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */
@@ -271,6 +389,15 @@ export function wrapPgError(err) {
                 table: e.table,
                 cause: err,
             });
+        case '40P01':
+            return new DeadlockError({
+                constraint: e.constraint,
+                cause: err,
+            });
+        case '40001':
+            return new SerializationFailureError({
+                cause: err,
+            });
         default:
             return err;
     }

package/dist/generate.d.ts

@@ -21,4 +21,10 @@ export declare function generate(options: GenerateOptions): {
     outDir: string;
     files: string[];
 };
+/**
+ * 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.
+ */
+export declare function generateTypes(schema: SchemaMetadata): string;
 //# sourceMappingURL=generate.d.ts.map