turbine-orm 0.77.1 → 0.78.0

package/dist/cjs/errors.d.ts

@@ -28,12 +28,40 @@ export declare const TurbineErrorCode: {
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
 export declare class TurbineError extends Error {
+    /**
+     * The code every instance of this class passes to `super()`, declared once
+     * per subclass on the line above the constructor that names it, so the two
+     * are read together. It exists for {@link TurbineError[Symbol.hasInstance]}:
+     * a subclass recognises a branded error from another copy of this module
+     * when the codes agree. `undefined` here on the base class, which therefore
+     * recognises any branded error.
+     *
+     * A static per class rather than a class-to-code map because the code is
+     * already written once per class; this puts the second mention next to the
+     * first instead of in a table at the bottom of the file, and a unit test
+     * asserts the two agree for every exported class.
+     */
+    static readonly CODE: TurbineErrorCode | undefined;
     readonly code: TurbineErrorCode;
     /** Docs page for this code, e.g. `https://turbineorm.dev/errors#e003`. */
     readonly docsUrl: string;
     constructor(code: TurbineErrorCode, message: string, options?: {
         cause?: unknown;
     });
+    /**
+     * `instanceof` that survives two copies of this module in one process.
+     *
+     * The ordinary prototype-chain answer is taken first, so a single-copy
+     * process behaves exactly as before, user subclasses included. Only when that
+     * says no is the brand consulted: a branded object is an instance of the base
+     * class outright, and of a coded subclass when its `code` equals that class's
+     * {@link CODE}. The `hasOwn` guard restricts the code match to classes that
+     * declare their own CODE, i.e. the ones in this module: a user subclass such
+     * as `class MyError extends ValidationError {}` inherits E003 without
+     * declaring it, and every ValidationError must not become an instance of the
+     * user's narrower class.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
 }
 /**
  * Controls whether NotFoundError messages include the actual `where` values
@@ -91,17 +119,28 @@ export declare function runWithErrorMessageMode<R>(mode: ErrorMessageMode, fn: (
  *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
  *
  * SCOPE, stated precisely because the useful version of this contract is the
- * one that is true. 'safe' mode redacts row values from the surfaces Turbine
- * OWNS: its own error messages, and the `detail` field of a driver error it
- * wraps and attaches as `.cause` (see redactCauseForMode).
- *
- * It is NOT a blanket guarantee that no row value can be reached from a thrown
- * error. A driver error whose SQLSTATE {@link wrapPgError} does not classify is
- * returned UNCHANGED, and some of those carry a value in the `message` field
- * itself, where nothing can be removed without destroying the diagnosis:
- * `22P02 invalid input syntax for type integer: "alice@example.com"` is the
- * common one. Treat 'safe' mode as removing Turbine's own contribution to the
- * leak, not as a log-scrubbing boundary.
+ * one that is true. 'safe' mode redacts row and parameter values from every
+ * error Turbine raises or wraps:
+ *   - its own messages;
+ *   - the `detail`, `hint`, `where` (the CONTEXT field, which carries the bound
+ *     PARAMETERS when `log_parameter_max_length_on_error` is non-zero) and
+ *     `internalQuery` fields of a driver error it attaches as `.cause`, and of
+ *     the error it hands back. See {@link VALUE_BEARING_FIELDS} for what puts a
+ *     value in each of them;
+ *   - the driver MESSAGE where that is what carries the value, so `22P02
+ *     invalid input syntax for type integer: "alice@example.com"` becomes a
+ *     ValidationError whose safe-mode text names the column and the SQLSTATE
+ *     and nothing else (see {@link wrapPgError});
+ *   - the message of a PostgreSQL server error whose SQLSTATE wrapPgError has
+ *     no class for AND whose SQLSTATE class can hold a value in its message
+ *     text (`P0001`, say, whose text the function author wrote), replaced by a
+ *     sentence naming the SQLSTATE and saying the text was withheld. A class
+ *     whose grammar is written over schema object names keeps its text, because
+ *     withholding what cannot leak protects nothing: see
+ *     {@link messageTextIsValueFree}.
+ * It is not a log-scrubbing boundary for errors that never pass through
+ * Turbine, and an unclassified NATIVE error code from one of the non-Postgres
+ * engines is left to that engine's own classifier.
  */
 export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
 /**
@@ -162,6 +201,7 @@ export declare function describeTargetForMessage(target: unknown): string;
  * structured properties on the error instance regardless of mode.
  */
 export declare class NotFoundError extends TurbineError {
+    static readonly CODE: "TURBINE_E001";
     readonly table?: string;
     readonly where?: unknown;
     readonly operation?: string;
@@ -175,6 +215,7 @@ export declare class NotFoundError extends TurbineError {
 }
 /** Thrown when a query or transaction exceeds the configured timeout */
 export declare class TimeoutError extends TurbineError {
+    static readonly CODE: "TURBINE_E002";
     readonly timeoutMs: number;
     /**
      * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
@@ -191,6 +232,23 @@ export declare class TimeoutError extends TurbineError {
 }
 /** Thrown when query arguments fail validation (unknown column, invalid operator, etc.) */
 export declare class ValidationError extends TurbineError {
+    static readonly CODE: "TURBINE_E003";
+    /**
+     * For an E003 that wraps a PostgreSQL data exception (SQLSTATE class 22) or a
+     * `search` operand `to_tsquery` rejected (42601): the column the server named,
+     * when it named one, and the SQLSTATE that classified the error. Undefined
+     * for validation Turbine performed itself, which never reaches the server.
+     */
+    readonly column?: string;
+    readonly sqlstate?: string;
+    /**
+     * The driver's own text for a wrapped data exception. PostgreSQL puts the
+     * offending VALUE in that text (`invalid input syntax for type integer:
+     * "alice@example.com"`), so under `errorMessages: 'safe'` this is
+     * {@link REDACTED_DETAIL} and under `'verbose'` the driver text in full, the
+     * same split the constraint classes apply to `.cause.detail`.
+     */
+    readonly detail?: string;
     /**
      * `options.cause` is for the engines, not for the query builder. Turbine's own
      * E003s are raised from validation it performed itself, so there is nothing
@@ -202,10 +260,14 @@ export declare class ValidationError extends TurbineError {
      */
     constructor(message: string, options?: {
         cause?: unknown;
+        column?: string;
+        sqlstate?: string;
+        detail?: string;
     });
 }
 /** Thrown when a database connection fails */
 export declare class ConnectionError extends TurbineError {
+    static readonly CODE: "TURBINE_E004";
     /**
      * The driver code that produced this error: a Postgres SQLSTATE (`28P01`
      * wrong password, `3D000` no such database, `08006` connection failure, ...)
@@ -254,19 +316,23 @@ export declare class ConnectionError extends TurbineError {
 export declare function malformedConnectionStringMessage(engine: string, example: string): string;
 /** Thrown when a relation reference is invalid */
 export declare class RelationError extends TurbineError {
+    static readonly CODE: "TURBINE_E005";
     constructor(message: string);
 }
 /** Thrown when a migration operation fails */
 export declare class MigrationError extends TurbineError {
+    static readonly CODE: "TURBINE_E006";
     constructor(message: string);
 }
 /** Thrown when circular relation nesting is detected */
 export declare class CircularRelationError extends TurbineError {
+    static readonly CODE: "TURBINE_E007";
     readonly path: string[];
     constructor(path: string[]);
 }
 /** Thrown when a UNIQUE constraint is violated (pg code 23505) */
 export declare class UniqueConstraintError extends TurbineError {
+    static readonly CODE: "TURBINE_E008";
     readonly constraint?: string;
     readonly columns?: string[];
     readonly table?: string;
@@ -280,6 +346,7 @@ export declare class UniqueConstraintError extends TurbineError {
 }
 /** Thrown when a FOREIGN KEY constraint is violated (pg code 23503) */
 export declare class ForeignKeyError extends TurbineError {
+    static readonly CODE: "TURBINE_E009";
     readonly constraint?: string;
     readonly table?: string;
     constructor(opts?: {
@@ -291,6 +358,7 @@ export declare class ForeignKeyError extends TurbineError {
 }
 /** Thrown when a NOT NULL constraint is violated (pg code 23502) */
 export declare class NotNullViolationError extends TurbineError {
+    static readonly CODE: "TURBINE_E010";
     readonly column?: string;
     readonly table?: string;
     constructor(opts?: {
@@ -317,6 +385,7 @@ export declare class NotNullViolationError extends TurbineError {
  * ```
  */
 export declare class DeadlockError extends TurbineError {
+    static readonly CODE: "TURBINE_E012";
     /** Marks this error as safe to retry */
     readonly isRetryable: true;
     readonly constraint?: string;
@@ -344,6 +413,7 @@ export declare class DeadlockError extends TurbineError {
  * ```
  */
 export declare class SerializationFailureError extends TurbineError {
+    static readonly CODE: "TURBINE_E013";
     /** Marks this error as safe to retry */
     readonly isRetryable: true;
     constructor(opts?: {
@@ -353,6 +423,7 @@ export declare class SerializationFailureError extends TurbineError {
 }
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 export declare class CheckConstraintError extends TurbineError {
+    static readonly CODE: "TURBINE_E011";
     readonly constraint?: string;
     readonly table?: string;
     constructor(opts?: {
@@ -363,6 +434,7 @@ export declare class CheckConstraintError extends TurbineError {
     });
 }
 export declare class ExclusionConstraintError extends TurbineError {
+    static readonly CODE: "TURBINE_E016";
     readonly constraint?: string;
     readonly table?: string;
     constructor(opts?: {
@@ -401,6 +473,7 @@ export type PipelineResultSlot = {
  * ```
  */
 export declare class PipelineError extends TurbineError {
+    static readonly CODE: "TURBINE_E014";
     /** Per-query results: each slot is either `{status:'ok', value}` or `{status:'error', error}` */
     readonly results: PipelineResultSlot[];
     /** Zero-based index of the first query that failed */
@@ -416,9 +489,19 @@ export declare class PipelineError extends TurbineError {
     });
 }
 export declare class OptimisticLockError extends TurbineError {
+    static readonly CODE: "TURBINE_E015";
     readonly table: string;
     readonly versionField: string;
     readonly expectedVersion: unknown;
+    /**
+     * The comparison that failed, value included: `expected version = 3`.
+     * Populated in both modes, like `expectedVersion` itself; only the MESSAGE
+     * withholds the value under `errorMessages: 'safe'`. `optimisticLock` accepts
+     * any column as the version field (an `updated_at` timestamp, an etag
+     * string), so the value is a stored cell like any other, and the message
+     * treats it the way the constraint classes treat `detail`.
+     */
+    readonly detail: string;
     constructor(opts: {
         table: string;
         versionField: string;
@@ -432,6 +515,7 @@ export declare class OptimisticLockError extends TurbineError {
  * clear `unsupported on <engine>` message instead of generating broken SQL.
  */
 export declare class UnsupportedFeatureError extends TurbineError {
+    static readonly CODE: "TURBINE_E017";
     readonly feature: string;
     readonly dialect: string;
     constructor(feature: string, dialect: string, hint?: string);
@@ -451,6 +535,7 @@ export declare class UnsupportedFeatureError extends TurbineError {
  * identically; route it to a writable primary instead.
  */
 export declare class ReadOnlyError extends TurbineError {
+    static readonly CODE: "TURBINE_E018";
     /**
      * Why the write was refused. `'snapshot'`: the database itself is read-only
      * (snapshot serving, an embedded `readonly: true` open, or the client-level
@@ -473,7 +558,6 @@ export declare class ReadOnlyError extends TurbineError {
 }
 /**
  * Translate a pg driver error into a typed Turbine error.
- * If the error doesn't match a known constraint code, returns it unchanged.
  *
  * Maps:
  *   23505 (unique_violation)      -> UniqueConstraintError
@@ -487,6 +571,22 @@ export declare class ReadOnlyError extends TurbineError {
  *   28P01 / 28000 (auth refused)  -> ConnectionError, with a remediation hint
  *   3D000 (no such database)      -> 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
+ *                                    on `.detail`, redacted in 'safe' mode
+ *   42601 from to_tsquery         -> ValidationError with a `search` hint
+ *   any other server SQLSTATE     -> 'safe' mode: a clone keeping the SQLSTATE
+ *                                    on `.code` and repeating it on `.sqlstate`,
+ *                                    with the value-bearing fields redacted, the
+ *                                    driver message kept when the SQLSTATE
+ *                                    class's grammar cannot hold a row value and
+ *                                    withheld when it can, and the original on
+ *                                    `.cause` under the same rules (see
+ *                                    scrubUnclassifiedServerError);
+ *                                    'verbose' mode: returned unchanged
+ *
+ * Anything that is not a PostgreSQL server error (no SQLSTATE-shaped code, or
+ * no `severity`) is returned unchanged whatever the mode: see isPgServerError.
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */