honertia 0.1.21 → 0.1.22

package/README.md

@@ -1402,25 +1402,132 @@ registerErrorHandlers(app, {
 })
 ```
 
-Your `Error` component receives:
+Your `Error` component receives structured error props that vary by environment:
+
+**In Development** (`ENVIRONMENT=development`):
+
+```json
+{
+  "status": 500,
+  "code": "HON_CFG_100_DATABASE_NOT_CONFIGURED",
+  "title": "Database Not Configured",
+  "message": "DatabaseService is not configured. Add it to setupHonertia.",
+  "hint": "Add database to setupHonertia config",
+  "fixes": [{ "description": "Add database config", "confidence": "high" }],
+  "source": { "file": "src/routes/projects.ts", "line": 42 },
+  "docsUrl": "https://..."
+}
+```
+
+**In Production** (`ENVIRONMENT=production` or unset):
+
+```json
+{
+  "status": 500,
+  "code": "HON_CFG_100_DATABASE_NOT_CONFIGURED",
+  "title": "Database Not Configured",
+  "message": "An error occurred. Please try again later."
+}
+```
+
+In production, sensitive details (stack traces, source locations, hints, fixes) are automatically hidden while the error code and title remain visible for debugging reference.
+
+**Example React Error Component:**
 
 ```tsx
 // src/pages/Error.tsx
 interface ErrorProps {
-  status: number    // 404, 500, etc.
-  message: string   // Error message (detailed in dev, generic in prod)
+  status: number
+  code: string
+  title: string
+  message: string
+  hint?: string
+  fixes?: Array<{ description: string; confidence: string }>
+  source?: { file: string; line: number }
+  docsUrl?: string
 }
 
-export default function Error({ status, message }: ErrorProps) {
+export default function Error(props: ErrorProps) {
+  const { status, title, message, hint, fixes, source, docsUrl } = props
+
   return (
     <div className="error-page">
       <h1>{status}</h1>
+      <h2>{title}</h2>
       <p>{message}</p>
+
+      {/* Only shown in dev (these props won't exist in prod) */}
+      {hint && <p className="hint">{hint}</p>}
+
+      {source && (
+        <code>{source.file}:{source.line}</code>
+      )}
+
+      {fixes?.map((fix, i) => (
+        <div key={i} className={`fix fix-${fix.confidence}`}>
+          {fix.description}
+        </div>
+      ))}
+
+      {docsUrl && <a href={docsUrl}>View Documentation</a>}
     </div>
   )
 }
 ```
 
+### Environment Detection
+
+Honertia automatically detects development mode by checking environment variables:
+
+```typescript
+// Checks these in order:
+// 1. env.ENVIRONMENT === 'development'
+// 2. env.NODE_ENV === 'development'
+// 3. env.CF_PAGES_BRANCH !== undefined (Cloudflare Pages preview deployments)
+```
+
+To enable development mode, set the environment variable in your Hono app:
+
+```toml
+# wrangler.toml
+[vars]
+ENVIRONMENT = "development"
+```
+
+Or for Bun/Node:
+
+```typescript
+// Pass env via Bun.serve or test setup
+const app = new Hono<{ Bindings: { ENVIRONMENT: string } }>()
+```
+
+### Safe Message Filtering
+
+For sensitive error categories, production automatically shows generic messages instead of implementation details:
+
+| Category | Production Message |
+|----------|-------------------|
+| `configuration` | "An error occurred. Please try again later." |
+| `internal` | "An error occurred. Please try again later." |
+| `database` | "An error occurred. Please try again later." |
+| `validation` | Original message (safe to show) |
+| `auth` | Original message (safe to show) |
+
+This ensures that configuration mistakes, database errors, and internal implementation details are never leaked to end users in production.
+
+### Error Handler Options
+
+The `registerErrorHandlers` function accepts these options:
+
+```typescript
+registerErrorHandlers(app, {
+  component: 'Error',        // React component name (required)
+  showDevErrors: true,       // Set false to always hide details (default: true)
+  envKey: 'ENVIRONMENT',     // Which env var to check (default: 'ENVIRONMENT')
+  devValue: 'development',   // What value means "dev mode" (default: 'development')
+})
+```
+
 ### Error Handling Flow
 
 ```

package/dist/effect/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/effect/binding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;;;;AAWrD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAC;IACA,IAAI,OAAO,WAEV;CACF;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAa3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,gBAG9B;CAAG;AAEN;;;GAGG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,IAC7B,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,GAC/D,CAAC,SAAS,GAAG,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,KAAK,GACzC,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC,IAAI,GAC/E,GAAG,CAAC,GAAG,CAAA;AAET;;GAEG;AACH,UAAU,uBAAuB,CAAC,CAAC,SAAS,MAAM;IAChD,QAAQ,CAAC,OAAO,EAAE,gCAAgC,CAAC,oDAAoD,CAAA;IACvG,QAAQ,CAAC,MAAM,EAAE,wHAAwH,CAAA;CAC1I;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAErC,UAAU,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC,uBAAuB,CAAC,CAAC,CAAC,GAC1B,SAAS,CAAC,CAAC,CAAC,SAAS,MAAM,UAAU,GACnC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,GACpC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,GACxC,OAAO,GACT,CAAC,SAAS,MAAM,UAAU,GACxB,UAAU,CAAC,CAAC,CAAC,SAAS,KAAK,GACzB,UAAU,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,GAC7B,OAAO,GACT,OAAO,CAAA;AAEjB;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,EACpC,KAAK,CAAC,KACL,MAAM,CAAC,MAAM,CACd,UAAU,CAAC,CAAC,CAAC,EACb,kBAAkB,GAAG,uBAAuB,EAC5C,WAAW,CAkBT,CAAA;AAEJ;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS9C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAA;IAClB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACtB,YAAY,GAAG,IAAI,CA2CrB;AAkCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CA+DnE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EAAE,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAwBrB"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/effect/binding.ts"],"names":[],"mappings":"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"}

package/dist/effect/binding.js

@@ -63,10 +63,7 @@ export const bound = (key) => Effect.gen(function* () {
     const models = yield* BoundModels;
     // Check if schema was not configured (sentinel value set by routing.ts)
     if (models.has('__schema_not_configured__')) {
-        return yield* new RouteConfigurationError({
-            message: `Route model binding requires schema configuration. Cannot resolve bound('${key}') without schema.`,
-            hint: `Pass your schema to setupHonertia: setupHonertia({ honertia: { schema } })`
-        });
+        return yield* RouteConfigurationError.schemaNotConfigured(key);
     }
     const model = models.get(key);
     if (!model) {

package/dist/effect/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/effect/bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE9C,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAC1E,OAAO,EACL,eAAe,EACf,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,eAAe,EAQhB,MAAM,eAAe,CAAA;AAEtB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK;IACvE;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;IAC3E;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,QAAA,MAAM,cAAc,eAA0B,CAAA;AAE9C;;GAEG;AACH,QAAA,MAAM,aAAa,eAAyB,CAAA;AA8B5C;;GAEG;AACH,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAkB;QAC1B,CAAC,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,cAAc,CAC5C,eAAe,GACf,WAAW,GACX,eAAe,GACf,eAAe,GACf,cAAc,GACd,sBAAsB,EACxB,KAAK,CACN,CAAA;QACD,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAC1C;CACF;AAsDD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK,EACrE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,cAAc,CAAC,GAC7C,KAAK,CAAC,KAAK,CACV,cAAc,GACd,sBAAsB,GACtB,eAAe,GACf,eAAe,GACf,WAAW,GACX,eAAe,GACf,eAAe,GACf,cAAc,EAChB,KAAK,EACL,KAAK,CACN,CAkEA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,cAAc,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,CAEvD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK,EAChE,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,cAAc,CAAC,GAC7C,iBAAiB,CAAC,CAAC,CAAC,CAoBtB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,GAAG,EAC3C,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAErC"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/effect/bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAG9C,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAC1E,OAAO,EACL,eAAe,EACf,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,eAAe,EAQhB,MAAM,eAAe,CAAA;AAEtB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK;IACvE;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;IAC3E;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,QAAA,MAAM,cAAc,eAA0B,CAAA;AAE9C;;GAEG;AACH,QAAA,MAAM,aAAa,eAAyB,CAAA;AAsC5C;;GAEG;AACH,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAkB;QAC1B,CAAC,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,cAAc,CAC5C,eAAe,GACf,WAAW,GACX,eAAe,GACf,eAAe,GACf,cAAc,GACd,sBAAsB,EACxB,KAAK,CACN,CAAA;QACD,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAC1C;CACF;AAsDD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK,EACrE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,cAAc,CAAC,GAC7C,KAAK,CAAC,KAAK,CACV,cAAc,GACd,sBAAsB,GACtB,eAAe,GACf,eAAe,GACf,WAAW,GACX,eAAe,GACf,eAAe,GACf,cAAc,EAChB,KAAK,EACL,KAAK,CACN,CAoEA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,cAAc,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,CAEvD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,cAAc,GAAG,KAAK,EAChE,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,cAAc,CAAC,GAC7C,iBAAiB,CAAC,CAAC,CAAC,CAoBtB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,GAAG,EAC3C,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAErC"}

package/dist/effect/bridge.js

@@ -5,6 +5,7 @@
  */
 import { Layer, ManagedRuntime } from 'effect';
 import { HonertiaConfigurationError } from './errors.js';
+import { ErrorCodes } from './error-catalog.js';
 import { DatabaseService, AuthService, AuthUserService, HonertiaService, RequestService, ResponseFactoryService, BindingsService, } from './services.js';
 /**
  * Symbol for storing Effect runtime in Hono context.
@@ -17,8 +18,13 @@ const EFFECT_SCHEMA = Symbol('effectSchema');
 /**
  * Creates a proxy that throws a helpful error when any property is accessed.
  * Used when a service (database, auth) is not configured but the user tries to use it.
+ *
+ * @param serviceName - The name of the unconfigured service.
+ * @param configPath - The configuration path hint (e.g., 'database: (c) => ...').
+ * @param example - An example of how to configure the service.
+ * @param errorCode - The specific error code to use.
  */
-function createUnconfiguredServiceProxy(serviceName, configPath, example) {
+function createUnconfiguredServiceProxy(serviceName, configPath, example, errorCode) {
     const message = `${serviceName} is not configured. Add it to setupHonertia: setupHonertia({ honertia: { ${configPath} } })`;
     return new Proxy({}, {
         get(_, prop) {
@@ -29,6 +35,8 @@ function createUnconfiguredServiceProxy(serviceName, configPath, example) {
             throw new HonertiaConfigurationError({
                 message,
                 hint: `Example: ${example}`,
+                code: errorCode,
+                service: serviceName,
             });
         },
     });
@@ -94,11 +102,11 @@ export function buildContextLayer(c, config) {
     // Database layer - provide helpful error proxy if not configured
     const db = c.var?.db;
     const databaseLayer = Layer.succeed(DatabaseService, (db ??
-        createUnconfiguredServiceProxy('DatabaseService', 'database: (c) => createDb(...)', 'database: (c) => drizzle(c.env.DB)')));
+        createUnconfiguredServiceProxy('DatabaseService', 'database: (c) => createDb(...)', 'database: (c) => drizzle(c.env.DB)', ErrorCodes.CFG_300_DATABASE_NOT_CONFIGURED)));
     // Auth layer - provide helpful error proxy if not configured
     const auth = c.var?.auth;
     const authLayer = Layer.succeed(AuthService, (auth ??
-        createUnconfiguredServiceProxy('AuthService', 'auth: (c) => createAuth(...)', 'auth: (c) => betterAuth({ database: c.var.db, ... })')));
+        createUnconfiguredServiceProxy('AuthService', 'auth: (c) => createAuth(...)', 'auth: (c) => betterAuth({ database: c.var.db, ... })', ErrorCodes.CFG_301_AUTH_NOT_CONFIGURED)));
     let baseLayer = Layer.mergeAll(requestLayer, responseLayer, honertiaLayer, bindingsLayer, databaseLayer, authLayer);
     if (c.var?.authUser) {
         baseLayer = Layer.merge(baseLayer, Layer.succeed(AuthUserService, c.var.authUser));

package/dist/effect/error-catalog.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Error Catalog for Honertia
+ *
+ * Central registry of all error codes with fix generators.
+ * This is the single source of truth for error definitions.
+ */
+import type { ErrorCategory, ErrorContext, ErrorDefinition, HonertiaStructuredError } from './error-types.js';
+/**
+ * All Honertia error codes organized by category.
+ *
+ * Naming convention: HON_<CATEGORY>_<NUMBER>_<NAME>
+ *
+ * Categories:
+ * - VAL (001-099): Validation errors
+ * - AUTH (100-199): Authentication/authorization
+ * - RES (200-299): Resource errors
+ * - CFG (300-399): Configuration errors
+ * - HTTP (400-499): HTTP errors
+ * - DB (500-599): Database errors
+ * - RTE (600-699): Routing errors
+ * - SVC (700-799): Service errors
+ * - INT (800-899): Internal errors
+ */
+export declare const ErrorCodes: {
+    readonly VAL_001_FIELD_REQUIRED: "HON_VAL_001_FIELD_REQUIRED";
+    readonly VAL_002_FIELD_INVALID: "HON_VAL_002_FIELD_INVALID";
+    readonly VAL_003_BODY_PARSE_FAILED: "HON_VAL_003_BODY_PARSE_FAILED";
+    readonly VAL_004_SCHEMA_MISMATCH: "HON_VAL_004_SCHEMA_MISMATCH";
+    readonly VAL_005_TYPE_COERCION_FAILED: "HON_VAL_005_TYPE_COERCION_FAILED";
+    readonly AUTH_100_UNAUTHENTICATED: "HON_AUTH_100_UNAUTHENTICATED";
+    readonly AUTH_101_SESSION_EXPIRED: "HON_AUTH_101_SESSION_EXPIRED";
+    readonly AUTH_102_FORBIDDEN: "HON_AUTH_102_FORBIDDEN";
+    readonly AUTH_103_INVALID_CREDENTIALS: "HON_AUTH_103_INVALID_CREDENTIALS";
+    readonly RES_200_NOT_FOUND: "HON_RES_200_NOT_FOUND";
+    readonly RES_201_ALREADY_EXISTS: "HON_RES_201_ALREADY_EXISTS";
+    readonly RES_202_GONE: "HON_RES_202_GONE";
+    readonly CFG_300_DATABASE_NOT_CONFIGURED: "HON_CFG_300_DATABASE_NOT_CONFIGURED";
+    readonly CFG_301_AUTH_NOT_CONFIGURED: "HON_CFG_301_AUTH_NOT_CONFIGURED";
+    readonly CFG_302_SCHEMA_NOT_CONFIGURED: "HON_CFG_302_SCHEMA_NOT_CONFIGURED";
+    readonly CFG_303_HONERTIA_NOT_CONFIGURED: "HON_CFG_303_HONERTIA_NOT_CONFIGURED";
+    readonly CFG_304_BINDINGS_NOT_CONFIGURED: "HON_CFG_304_BINDINGS_NOT_CONFIGURED";
+    readonly CFG_305_INVALID_CONFIG: "HON_CFG_305_INVALID_CONFIG";
+    readonly HTTP_400_BAD_REQUEST: "HON_HTTP_400_BAD_REQUEST";
+    readonly HTTP_429_RATE_LIMITED: "HON_HTTP_429_RATE_LIMITED";
+    readonly HTTP_500_INTERNAL_ERROR: "HON_HTTP_500_INTERNAL_ERROR";
+    readonly HTTP_502_BAD_GATEWAY: "HON_HTTP_502_BAD_GATEWAY";
+    readonly HTTP_503_SERVICE_UNAVAILABLE: "HON_HTTP_503_SERVICE_UNAVAILABLE";
+    readonly DB_500_CONNECTION_FAILED: "HON_DB_500_CONNECTION_FAILED";
+    readonly DB_501_QUERY_FAILED: "HON_DB_501_QUERY_FAILED";
+    readonly DB_502_CONSTRAINT_VIOLATION: "HON_DB_502_CONSTRAINT_VIOLATION";
+    readonly DB_503_TRANSACTION_FAILED: "HON_DB_503_TRANSACTION_FAILED";
+    readonly RTE_600_BINDING_NOT_FOUND: "HON_RTE_600_BINDING_NOT_FOUND";
+    readonly RTE_601_TABLE_NOT_FOUND: "HON_RTE_601_TABLE_NOT_FOUND";
+    readonly RTE_602_PARAM_VALIDATION: "HON_RTE_602_PARAM_VALIDATION";
+    readonly RTE_603_RELATION_NOT_FOUND: "HON_RTE_603_RELATION_NOT_FOUND";
+    readonly SVC_700_SERVICE_UNAVAILABLE: "HON_SVC_700_SERVICE_UNAVAILABLE";
+    readonly SVC_701_SERVICE_ERROR: "HON_SVC_701_SERVICE_ERROR";
+    readonly INT_800_UNEXPECTED: "HON_INT_800_UNEXPECTED";
+    readonly INT_801_EFFECT_DEFECT: "HON_INT_801_EFFECT_DEFECT";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * The error catalog with all error definitions.
+ */
+export declare const ErrorCatalog: Record<ErrorCode, ErrorDefinition>;
+/**
+ * Create a structured error from an error code and parameters.
+ *
+ * @param code - The error code (from ErrorCodes) or any string. Unknown codes fallback to INT_800_UNEXPECTED.
+ * @param params - Parameters to interpolate into the message template.
+ * @param context - The error context (route, request, handler info).
+ * @returns A fully structured error with fix suggestions.
+ *
+ * @example
+ * ```ts
+ * const error = createStructuredError(
+ *   ErrorCodes.VAL_001_FIELD_REQUIRED,
+ *   { field: 'email' },
+ *   captureErrorContext(c)
+ * )
+ * ```
+ */
+export declare function createStructuredError(code: ErrorCode | string, params: Record<string, unknown>, context: ErrorContext): HonertiaStructuredError;
+/**
+ * Get an error definition by code.
+ */
+export declare function getErrorDefinition(code: ErrorCode): ErrorDefinition | undefined;
+/**
+ * Get all error codes for a category.
+ */
+export declare function getErrorsByCategory(category: ErrorCategory): ErrorCode[];
+/**
+ * Determine the appropriate configuration error code from a service name or message.
+ *
+ * @param serviceName - The service name (e.g., 'DatabaseService').
+ * @param message - Optional message to check if service name doesn't match.
+ * @returns The appropriate error code, defaulting to CFG_305_INVALID_CONFIG.
+ */
+export declare function getConfigErrorCode(serviceName?: string, message?: string): ErrorCode;
+//# sourceMappingURL=error-catalog.d.ts.map

package/dist/effect/error-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-catalog.d.ts","sourceRoot":"","sources":["../../src/effect/error-catalog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EAGf,uBAAuB,EACxB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDb,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAA;AA8JpE;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,eAAe,CAmb3D,CAAA;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,YAAY,GACpB,uBAAuB,CAwCzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,CAE/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE,CAIxE;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAUX"}