@vibeorm/runtime 1.0.1 → 1.1.0

package/src/errors.ts

@@ -1,12 +1,159 @@
 /**
- * VibeORM Validation Error
+ * VibeORM Error Hierarchy
  *
- * Thrown when Zod validation fails for query inputs or outputs.
- * Contains structured information about which model, operation, and
- * direction (input/output) the validation failure occurred in.
+ * All VibeORM errors extend the abstract VibeError base class, split into
+ * two concrete branches:
+ *
+ * - VibeRequestError — deterministic failures caused by invalid data or
+ *   violated constraints. Running the same operation again will produce
+ *   the same error. Includes: unique constraint, FK violation, not-null,
+ *   check constraint, not-found, and validation errors.
+ *
+ * - VibeTransientError — transient infrastructure failures where retrying
+ *   the same operation may succeed. Includes: connection errors, deadlocks,
+ *   serialization failures, statement timeouts, and pool exhaustion.
+ *
+ * VibeValidationError (Zod validation) is a subclass of VibeRequestError,
+ * so `instanceof VibeRequestError` catches both constraint violations AND
+ * validation errors. Use `instanceof VibeValidationError` to narrow.
+ *
+ * @example
+ * ```ts
+ * import { VibeRequestError, VibeTransientError, VibeError } from "@vibeorm/runtime";
+ *
+ * try {
+ *   await db.user.create({ data: { email: "taken@example.com" } });
+ * } catch (error) {
+ *   if (error instanceof VibeRequestError) {
+ *     if (error.code === "UNIQUE_CONSTRAINT") {
+ *       console.log(error.meta.constraint); // "User_email_key"
+ *       console.log(error.meta.detail);     // 'Key (email)=(taken@example.com) already exists.'
+ *       return { error: "Email already taken" };
+ *     }
+ *   }
+ *   if (error instanceof VibeTransientError) {
+ *     // error.retryable is always true
+ *     return retry(() => db.user.create({ ... }));
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+
+// ─── Error Codes ─────────────────────────────────────────────────
+
+/**
+ * Error codes for deterministic request failures.
+ * The operation itself is invalid — changing the data would fix it.
+ */
+export type VibeRequestErrorCode =
+  | "UNIQUE_CONSTRAINT"
+  | "FOREIGN_KEY_VIOLATION"
+  | "NOT_NULL_VIOLATION"
+  | "CHECK_CONSTRAINT"
+  | "NOT_FOUND"
+  | "VALIDATION_ERROR"
+  | "UNKNOWN_REQUEST_ERROR";
+
+/**
+ * Error codes for transient infrastructure failures.
+ * The operation is valid but the infrastructure failed — retrying may fix it.
+ */
+export type VibeTransientErrorCode =
+  | "CONNECTION_ERROR"
+  | "DEADLOCK"
+  | "SERIALIZATION_FAILURE"
+  | "STATEMENT_TIMEOUT"
+  | "TOO_MANY_CONNECTIONS"
+  | "UNKNOWN_TRANSIENT_ERROR";
+
+/** Union of all VibeORM error codes. */
+export type VibeErrorCode = VibeRequestErrorCode | VibeTransientErrorCode;
+
+// ─── Error Meta ──────────────────────────────────────────────────
+
+/**
+ * Structured metadata attached to every VibeORM error.
+ * Fields are populated when available from the PostgreSQL error protocol
+ * or from the application-level context (model name, operation, etc.).
+ */
+export type VibeErrorMeta = {
+  /** VibeORM model name (e.g. "User", "Post"). Set for app-level errors. */
+  model?: string;
+  /** The field that caused the error (extracted from PG detail when possible). */
+  field?: string;
+  /** PostgreSQL constraint name (e.g. "User_email_key"). */
+  constraint?: string;
+  /** PostgreSQL table name from the error (e.g. "User"). */
+  table?: string;
+  /** PostgreSQL column name from the error. */
+  column?: string;
+  /** PostgreSQL schema name from the error (e.g. "public"). */
+  schema?: string;
+  /** Human-readable detail from PostgreSQL (e.g. 'Key (email)=(x@y.com) already exists.'). */
+  detail?: string;
+  /** The VibeORM operation that triggered this error (e.g. "create", "update"). */
+  operation?: string;
+  /** Validation direction — only set on VibeValidationError. */
+  direction?: "input" | "output";
+  /** Raw Zod error object — only set on VibeValidationError. */
+  zodError?: unknown;
+};
+
+// ─── Base Class ──────────────────────────────────────────────────
+
+/**
+ * Abstract base class for all VibeORM errors.
+ * Use `instanceof VibeError` to catch any error originating from VibeORM.
+ */
+export abstract class VibeError extends Error {
+  abstract readonly code: VibeErrorCode;
+  readonly meta: VibeErrorMeta;
+
+  constructor(params: { message: string; meta?: VibeErrorMeta; cause?: Error }) {
+    super(params.message, { cause: params.cause });
+    this.name = "VibeError";
+    this.meta = params.meta ?? {};
+  }
+}
+
+// ─── Request Error (deterministic) ──────────────────────────────
+
+/**
+ * Deterministic request error — the operation itself is invalid.
+ * Same input will always produce the same failure.
+ *
+ * Covers: constraint violations, not-found, validation, and
+ * unrecognized database errors that aren't transient.
+ *
+ * Use `error.code` to narrow the specific failure type.
  */
+export class VibeRequestError extends VibeError {
+  readonly code: VibeRequestErrorCode;
+
+  constructor(params: {
+    code: VibeRequestErrorCode;
+    message: string;
+    meta?: VibeErrorMeta;
+    cause?: Error;
+  }) {
+    super({ message: params.message, meta: params.meta, cause: params.cause });
+    this.name = "VibeRequestError";
+    this.code = params.code;
+  }
+}
+
+// ─── Validation Error (subclass of Request) ─────────────────────
 
-export class VibeValidationError extends Error {
+/**
+ * Zod validation error — thrown when input or output data fails schema validation.
+ *
+ * Subclass of VibeRequestError, so `instanceof VibeRequestError` catches it.
+ * Use `instanceof VibeValidationError` to narrow specifically to validation failures.
+ *
+ * Preserves backward-compatible fields: model, operation, direction, zodError.
+ */
+export class VibeValidationError extends VibeRequestError {
   readonly model: string;
   readonly operation: string;
   readonly direction: "input" | "output";
@@ -20,7 +167,11 @@ export class VibeValidationError extends Error {
   }) {
     const { model, operation, direction, zodError } = params;
     const msg = `Validation failed for ${model}.${operation} (${direction}): ${formatZodError({ error: zodError })}`;
-    super(msg);
+    super({
+      code: "VALIDATION_ERROR",
+      message: msg,
+      meta: { model, operation, direction, zodError },
+    });
     this.name = "VibeValidationError";
     this.model = model;
     this.operation = operation;
@@ -29,6 +180,276 @@ export class VibeValidationError extends Error {
   }
 }
 
+// ─── Transient Error (retryable) ────────────────────────────────
+
+/**
+ * Transient infrastructure error — the operation is valid but the
+ * infrastructure failed. Retrying the same operation may succeed.
+ *
+ * Covers: connection errors, deadlocks, serialization failures,
+ * statement timeouts, and pool exhaustion.
+ *
+ * `retryable` is always `true` on this class.
+ */
+export class VibeTransientError extends VibeError {
+  readonly code: VibeTransientErrorCode;
+  readonly retryable = true as const;
+
+  constructor(params: {
+    code: VibeTransientErrorCode;
+    message: string;
+    meta?: VibeErrorMeta;
+    cause?: Error;
+  }) {
+    super({ message: params.message, meta: params.meta, cause: params.cause });
+    this.name = "VibeTransientError";
+    this.code = params.code;
+  }
+}
+
+// ─── SQLSTATE → VibeError Mapping ───────────────────────────────
+
+/**
+ * SQLSTATE code ranges for transient (retryable) errors.
+ * Class 08 = connection, Class 40 = transaction rollback,
+ * 57014 = query_canceled (statement_timeout), 53300 = too_many_connections.
+ */
+const TRANSIENT_CODE_MAP: Record<string, VibeTransientErrorCode> = {
+  "08000": "CONNECTION_ERROR",
+  "08001": "CONNECTION_ERROR",
+  "08003": "CONNECTION_ERROR",
+  "08004": "CONNECTION_ERROR",
+  "08006": "CONNECTION_ERROR",
+  "08007": "CONNECTION_ERROR",
+  "08P01": "CONNECTION_ERROR",
+  "40P01": "DEADLOCK",
+  "40001": "SERIALIZATION_FAILURE",
+  "57014": "STATEMENT_TIMEOUT",
+  "53300": "TOO_MANY_CONNECTIONS",
+};
+
+/**
+ * SQLSTATE codes for constraint violation errors (Class 23).
+ */
+const CONSTRAINT_CODE_MAP: Record<string, VibeRequestErrorCode> = {
+  "23505": "UNIQUE_CONSTRAINT",
+  "23503": "FOREIGN_KEY_VIOLATION",
+  "23502": "NOT_NULL_VIOLATION",
+  "23514": "CHECK_CONSTRAINT",
+};
+
+/**
+ * Extract a field name from a PostgreSQL detail string.
+ *
+ * Examples:
+ * - 'Key (email)=(x@y.com) already exists.' → "email"
+ * - 'Failing row contains (1, null, ...).' → undefined
+ * - 'Key (author_id)=(999) is not present in table "User".' → "author_id"
+ */
+function extractFieldFromDetail(params: { detail: string }): string | undefined {
+  const match = params.detail.match(/Key \(([^)]+)\)/);
+  return match ? match[1] : undefined;
+}
+
+/**
+ * Shape of a PostgreSQL protocol error as exposed by both bun:sql and node-postgres.
+ *
+ * Note: bun:sql puts the SQLSTATE code in `errno` (e.g. "23505") while `code`
+ * contains a Node.js-style string (e.g. "ERR_POSTGRES_SERVER_ERROR").
+ * node-postgres puts the SQLSTATE code in `code` directly.
+ */
+type PgProtocolError = {
+  code: string;
+  errno?: string;
+  message: string;
+  detail?: string;
+  hint?: string;
+  constraint?: string;
+  table?: string;
+  column?: string | number;
+  schema?: string;
+  severity?: string;
+};
+
+/**
+ * Check whether a raw error object looks like a PostgreSQL protocol error.
+ * Both bun:sql (PostgresError) and node-postgres (DatabaseError) expose
+ * error fields from the PostgreSQL wire protocol. The SQLSTATE code is in
+ * `errno` (bun:sql) or `code` (node-postgres).
+ */
+function isPgError(error: unknown): error is PgProtocolError {
+  if (error === null || typeof error !== "object" || !("message" in error)) return false;
+  const e = error as Record<string, unknown>;
+  // node-postgres: has `code` as a 5-char SQLSTATE string
+  // bun:sql: has `errno` as a SQLSTATE string + `severity`
+  return (
+    (typeof e.code === "string" && /^[0-9A-Z]{5}$/.test(e.code)) ||
+    (typeof e.errno === "string" && typeof e.severity === "string")
+  );
+}
+
+/**
+ * Extract the SQLSTATE code from a PgProtocolError.
+ * bun:sql stores it in `errno`, node-postgres stores it in `code`.
+ */
+function getSqlStateCode(error: PgProtocolError): string {
+  // bun:sql: errno contains the actual SQLSTATE code (e.g. "23505")
+  if (error.errno && /^[0-9A-Z]{5}$/.test(error.errno)) {
+    return error.errno;
+  }
+  // node-postgres: code contains the SQLSTATE code
+  if (/^[0-9A-Z]{5}$/.test(error.code)) {
+    return error.code;
+  }
+  return error.code;
+}
+
+/**
+ * Check whether a raw error looks like a client-side connection error
+ * (e.g. ECONNREFUSED, ENOTFOUND, ETIMEDOUT) that doesn't have a SQLSTATE code.
+ */
+function isConnectionError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const anyErr = err as Record<string, unknown>;
+
+  // Node.js system errors from net/dns
+  if (typeof anyErr.code === "string") {
+    const code = anyErr.code;
+    if (
+      code === "ECONNREFUSED" ||
+      code === "ECONNRESET" ||
+      code === "ENOTFOUND" ||
+      code === "ETIMEDOUT" ||
+      code === "EPIPE"
+    ) {
+      return true;
+    }
+  }
+
+  // bun:sql connection-level errors often have specific message patterns
+  const msg = typeof anyErr.message === "string" ? anyErr.message : "";
+  if (
+    msg.includes("connection refused") ||
+    msg.includes("Connection terminated") ||
+    msg.includes("Connection lost") ||
+    msg.includes("connect ECONNREFUSED") ||
+    msg.includes("the database system is starting up")
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Normalize a raw database error into a structured VibeORM error.
+ *
+ * Both bun:sql and node-postgres expose the PostgreSQL ErrorResponse fields
+ * (code, detail, constraint, table, column, schema, severity), so this
+ * function is adapter-agnostic.
+ *
+ * If the error is already a VibeError, it is returned as-is.
+ *
+ * @param error - The raw error from the database driver.
+ * @param model - Optional VibeORM model name for context.
+ * @param operation - Optional operation name for context.
+ */
+export function normalizeError(params: {
+  error: unknown;
+  model?: string;
+  operation?: string;
+}): VibeRequestError | VibeTransientError {
+  const { error, model, operation } = params;
+
+  // Already a VibeError — return as-is (don't double-wrap)
+  if (error instanceof VibeError) {
+    return error as VibeRequestError | VibeTransientError;
+  }
+
+  const cause = error instanceof Error ? error : new Error(String(error));
+
+  // ─── PostgreSQL protocol error (has SQLSTATE code) ───────────
+  if (isPgError(error)) {
+    const pgErr = error;
+    const pgCode = getSqlStateCode(pgErr);
+    const meta: VibeErrorMeta = {
+      model,
+      operation,
+      constraint: pgErr.constraint,
+      table: pgErr.table,
+      column: typeof pgErr.column === "string" ? pgErr.column : undefined,
+      schema: pgErr.schema,
+      detail: pgErr.detail,
+    };
+
+    // Extract field name from detail when available
+    if (pgErr.detail) {
+      const field = extractFieldFromDetail({ detail: pgErr.detail });
+      if (field) meta.field = field;
+    }
+
+    // Check transient errors first (Class 08, 40, 57014, 53300)
+    const transientCode = TRANSIENT_CODE_MAP[pgCode];
+    if (transientCode) {
+      return new VibeTransientError({
+        code: transientCode,
+        message: pgErr.message,
+        meta,
+        cause,
+      });
+    }
+
+    // Check constraint violations (Class 23)
+    const constraintCode = CONSTRAINT_CODE_MAP[pgCode];
+    if (constraintCode) {
+      return new VibeRequestError({
+        code: constraintCode,
+        message: pgErr.message,
+        meta,
+        cause,
+      });
+    }
+
+    // Check transient by SQLSTATE class prefix
+    if (pgCode.startsWith("08") || pgCode.startsWith("40")) {
+      return new VibeTransientError({
+        code: pgCode.startsWith("08") ? "CONNECTION_ERROR" : "UNKNOWN_TRANSIENT_ERROR",
+        message: pgErr.message,
+        meta,
+        cause,
+      });
+    }
+
+    // Unrecognized SQLSTATE — treat as request error
+    return new VibeRequestError({
+      code: "UNKNOWN_REQUEST_ERROR",
+      message: pgErr.message,
+      meta,
+      cause,
+    });
+  }
+
+  // ─── Client-side connection error (no SQLSTATE) ──────────────
+  if (isConnectionError(error)) {
+    return new VibeTransientError({
+      code: "CONNECTION_ERROR",
+      message: cause.message,
+      meta: { model, operation },
+      cause,
+    });
+  }
+
+  // ─── Unknown error — treat as request error ──────────────────
+  return new VibeRequestError({
+    code: "UNKNOWN_REQUEST_ERROR",
+    message: cause.message,
+    meta: { model, operation },
+    cause,
+  });
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
 function formatZodError(params: { error: unknown }): string {
   const { error } = params;
   if (error && typeof error === "object" && "issues" in error) {

package/src/index.ts

@@ -8,7 +8,13 @@
  */
 
 export { createClient } from "./client.ts";
-export { VibeValidationError } from "./errors.ts";
+export {
+  VibeError,
+  VibeRequestError,
+  VibeTransientError,
+  VibeValidationError,
+  normalizeError,
+} from "./errors.ts";
 export {
   loadRelationsWithLateralJoin,
   executeLateralJoinQuery,
@@ -19,8 +25,16 @@ export type {
   DatabaseAdapter,
   QueryResult,
   SqlExecutor,
+  TransactionOptions,
 } from "./adapter.ts";
 
+export type {
+  VibeErrorCode,
+  VibeRequestErrorCode,
+  VibeTransientErrorCode,
+  VibeErrorMeta,
+} from "./errors.ts";
+
 export type {
   VibeClientOptions,
   ModelMeta,