@prisma-next/sql-errors 0.0.1

package/README.md

@@ -0,0 +1,83 @@
+# @prisma-next/sql-errors
+
+SQL-normalized driver error types for Prisma Next.
+
+## Package Classification
+
+- **Domain**: sql
+- **Layer**: core
+- **Plane**: shared
+
+## Overview
+
+This package provides normalized error classes for SQL driver errors. These errors are shared across both migration-plane and runtime-plane code, allowing consistent error handling regardless of which driver is being used.
+
+## Purpose
+
+Normalize driver-specific errors (e.g., Postgres `pg` errors) into well-typed, SQL-family error classes that can be handled deterministically by migration runners, CLI commands, and other downstream systems.
+
+## Responsibilities
+
+- **Error Types**: Define `SqlQueryError` and `SqlConnectionError` classes
+- **Type Predicates**: Provide `.is()` methods for safe error checking without `instanceof`
+- **Stack Trace Preservation**: Preserve original error stack traces via ES2022 `Error.cause`
+
+## Error Classes
+
+### SqlQueryError
+
+Represents query-related failures:
+- Syntax errors
+- Constraint violations
+- Permission errors
+- Other SQL execution errors
+
+**Fields**:
+- `kind`: `'sql_query'` (discriminator)
+- `sqlState`: Postgres SQLSTATE code (e.g., `'23505'`)
+- `constraint`: Constraint name if applicable
+- `table`: Table name if applicable
+- `column`: Column name if applicable
+- `detail`: Additional detail from database
+
+### SqlConnectionError
+
+Represents connection-related failures:
+- Connection timeouts
+- Connection resets
+- Connection refused
+- Other connectivity issues
+
+**Fields**:
+- `kind`: `'sql_connection'` (discriminator)
+- `transient`: Whether retry might succeed
+
+## Usage
+
+```typescript
+import { SqlQueryError, SqlConnectionError } from '@prisma-next/sql-errors';
+
+// Check error type using type predicate (recommended)
+if (SqlQueryError.is(error)) {
+  console.log('SQLSTATE:', error.sqlState);
+  console.log('Constraint:', error.constraint);
+  console.log('Original stack:', error.cause?.stack);
+}
+
+// Create normalized error with original error preserved
+const normalized = new SqlQueryError('Query failed', {
+  cause: originalError,
+  sqlState: '23505',
+  constraint: 'user_email_unique',
+});
+```
+
+## Architecture
+
+This package is in the **shared plane**, meaning it can be imported by both migration-plane and runtime-plane packages. This allows drivers (runtime plane) and migration runners (migration plane) to use the same error types.
+
+## Related Documentation
+
+- `docs/architecture docs/subsystems/5. Adapters & Targets.md`: Driver architecture
+- `docs/Error Handling.md`: Error handling patterns
+

package/dist/exports/index.d.ts

@@ -0,0 +1,45 @@
+interface SqlDriverError<Kind extends string> {
+    readonly kind: Kind;
+}
+/**
+ * SQL query error for query-related failures (syntax errors, constraint violations, permissions).
+ */
+declare class SqlQueryError extends Error implements SqlDriverError<'sql_query'> {
+    static readonly ERROR_NAME: "SqlQueryError";
+    readonly kind: "sql_query";
+    readonly sqlState: string | undefined;
+    readonly constraint: string | undefined;
+    readonly table: string | undefined;
+    readonly column: string | undefined;
+    readonly detail: string | undefined;
+    constructor(message: string, options?: {
+        readonly cause?: Error;
+        readonly sqlState?: string;
+        readonly constraint?: string;
+        readonly table?: string;
+        readonly column?: string;
+        readonly detail?: string;
+    });
+    /**
+     * Type predicate to check if an error is a SqlQueryError.
+     */
+    static is(error: unknown): error is SqlQueryError;
+}
+/**
+ * SQL connection error (timeouts, connection resets, etc.).
+ */
+declare class SqlConnectionError extends Error implements SqlDriverError<'sql_connection'> {
+    static readonly ERROR_NAME: "SqlConnectionError";
+    readonly kind: "sql_connection";
+    readonly transient: boolean | undefined;
+    constructor(message: string, options?: {
+        readonly cause?: Error;
+        readonly transient?: boolean;
+    });
+    /**
+     * Type predicate to check if an error is a SqlConnectionError.
+     */
+    static is(error: unknown): error is SqlConnectionError;
+}
+
+export { SqlConnectionError, SqlQueryError };

package/dist/exports/index.js

@@ -0,0 +1,46 @@
+// src/errors.ts
+var SqlQueryError = class _SqlQueryError extends Error {
+  static ERROR_NAME = "SqlQueryError";
+  kind = "sql_query";
+  sqlState;
+  constraint;
+  table;
+  column;
+  detail;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = _SqlQueryError.ERROR_NAME;
+    this.sqlState = options?.sqlState;
+    this.constraint = options?.constraint;
+    this.table = options?.table;
+    this.column = options?.column;
+    this.detail = options?.detail;
+  }
+  /**
+   * Type predicate to check if an error is a SqlQueryError.
+   */
+  static is(error) {
+    return typeof error === "object" && error !== null && Object.hasOwn(error, "kind") && error.kind === "sql_query";
+  }
+};
+var SqlConnectionError = class _SqlConnectionError extends Error {
+  static ERROR_NAME = "SqlConnectionError";
+  kind = "sql_connection";
+  transient;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = _SqlConnectionError.ERROR_NAME;
+    this.transient = options?.transient;
+  }
+  /**
+   * Type predicate to check if an error is a SqlConnectionError.
+   */
+  static is(error) {
+    return typeof error === "object" && error !== null && Object.hasOwn(error, "kind") && error.kind === "sql_connection";
+  }
+};
+export {
+  SqlConnectionError,
+  SqlQueryError
+};
+//# sourceMappingURL=index.js.map

package/dist/exports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts"],"sourcesContent":["export interface SqlDriverError<Kind extends string> {\n  readonly kind: Kind;\n}\n/**\n * SQL query error for query-related failures (syntax errors, constraint violations, permissions).\n */\nexport class SqlQueryError extends Error implements SqlDriverError<'sql_query'> {\n  static readonly ERROR_NAME = 'SqlQueryError' as const;\n  readonly kind = 'sql_query' as const;\n  readonly sqlState: string | undefined;\n  readonly constraint: string | undefined;\n  readonly table: string | undefined;\n  readonly column: string | undefined;\n  readonly detail: string | undefined;\n\n  constructor(\n    message: string,\n    options?: {\n      readonly cause?: Error;\n      readonly sqlState?: string;\n      readonly constraint?: string;\n      readonly table?: string;\n      readonly column?: string;\n      readonly detail?: string;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = SqlQueryError.ERROR_NAME;\n    this.sqlState = options?.sqlState;\n    this.constraint = options?.constraint;\n    this.table = options?.table;\n    this.column = options?.column;\n    this.detail = options?.detail;\n  }\n\n  /**\n   * Type predicate to check if an error is a SqlQueryError.\n   */\n  static is(error: unknown): error is SqlQueryError {\n    return (\n      typeof error === 'object' &&\n      error !== null &&\n      Object.hasOwn(error, 'kind') &&\n      (error as { kind: unknown }).kind === 'sql_query'\n    );\n  }\n}\n\n/**\n * SQL connection error (timeouts, connection resets, etc.).\n */\nexport class SqlConnectionError extends Error implements SqlDriverError<'sql_connection'> {\n  static readonly ERROR_NAME = 'SqlConnectionError' as const;\n  readonly kind = 'sql_connection' as const;\n  readonly transient: boolean | undefined;\n\n  constructor(\n    message: string,\n    options?: {\n      readonly cause?: Error;\n      readonly transient?: boolean;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = SqlConnectionError.ERROR_NAME;\n    this.transient = options?.transient;\n  }\n\n  /**\n   * Type predicate to check if an error is a SqlConnectionError.\n   */\n  static is(error: unknown): error is SqlConnectionError {\n    return (\n      typeof error === 'object' &&\n      error !== null &&\n      Object.hasOwn(error, 'kind') &&\n      (error as { kind: unknown }).kind === 'sql_connection'\n    );\n  }\n}\n"],"mappings":";AAMO,IAAM,gBAAN,MAAM,uBAAsB,MAA6C;AAAA,EAC9E,OAAgB,aAAa;AAAA,EACpB,OAAO;AAAA,EACP;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAQA;AACA,UAAM,SAAS,EAAE,OAAO,SAAS,MAAM,CAAC;AACxC,SAAK,OAAO,eAAc;AAC1B,SAAK,WAAW,SAAS;AACzB,SAAK,aAAa,SAAS;AAC3B,SAAK,QAAQ,SAAS;AACtB,SAAK,SAAS,SAAS;AACvB,SAAK,SAAS,SAAS;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,GAAG,OAAwC;AAChD,WACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAO,OAAO,OAAO,MAAM,KAC1B,MAA4B,SAAS;AAAA,EAE1C;AACF;AAKO,IAAM,qBAAN,MAAM,4BAA2B,MAAkD;AAAA,EACxF,OAAgB,aAAa;AAAA,EACpB,OAAO;AAAA,EACP;AAAA,EAET,YACE,SACA,SAIA;AACA,UAAM,SAAS,EAAE,OAAO,SAAS,MAAM,CAAC;AACxC,SAAK,OAAO,oBAAmB;AAC/B,SAAK,YAAY,SAAS;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,GAAG,OAA6C;AACrD,WACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAO,OAAO,OAAO,MAAM,KAC1B,MAA4B,SAAS;AAAA,EAE1C;AACF;","names":[]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@prisma-next/sql-errors",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Normalized SQL driver error types for Prisma Next",
+  "dependencies": {},
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "@prisma-next/test-utils": "0.0.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/exports/index.d.ts",
+      "import": "./dist/exports/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --config-path ../../../../biome.json --error-on-warnings",
+    "lint:fix": "biome check --write . --config-path ../../../../biome.json",
+    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../../biome.json",
+    "clean": "node ../../../../scripts/clean.mjs"
+  }
+}