honertia 0.1.16 → 0.1.17

package/README.md

@@ -1243,7 +1243,204 @@ return yield* forbidden('You cannot edit this project')
 
 ## Error Handling
 
-Honertia provides typed errors:
+Honertia provides typed errors that integrate with Effect's error channel. Each error type has specific handling behavior designed for Inertia-style applications.
+
+### Built-in Error Types
+
+| Error Type | HTTP Status | Handling Behavior |
+|------------|-------------|-------------------|
+| `ValidationError` | 422 / redirect | Re-renders form with field errors, or redirects back |
+| `UnauthorizedError` | 302/303 | Redirects to login page |
+| `NotFoundError` | 404 | Uses Hono's `notFound()` handler → renders via Honertia |
+| `ForbiddenError` | 403 | Returns JSON response (for API compatibility) |
+| `HttpError` | Custom | Returns JSON with custom status (developer-controlled) |
+| `RouteConfigurationError` | 500 | Throws to Hono's `onError` → renders error page |
+| Unexpected errors | 500 | Throws to Hono's `onError` → renders error page |
+
+### Error Type Details
+
+#### `ValidationError`
+
+Thrown when request validation fails. Automatically re-renders the form with field-level errors.
+
+```typescript
+import { ValidationError, validateRequest } from 'honertia/effect'
+
+// Automatic: validateRequest throws ValidationError on failure
+const input = yield* validateRequest(schema, {
+  errorComponent: 'Projects/Create', // Re-renders this component with errors
+})
+
+// Manual: throw ValidationError directly
+yield* Effect.fail(new ValidationError({
+  errors: { email: 'Invalid email format' },
+  component: 'Auth/Register', // Optional: component to re-render
+}))
+```
+
+**Behavior:**
+- If request prefers JSON (API calls): returns `{ errors: {...} }` with 422 status
+- If `component` is set: re-renders that component with errors in props
+- Otherwise: redirects back to referer with errors in session
+
+#### `UnauthorizedError`
+
+Thrown when authentication is required but the user is not logged in.
+
+```typescript
+import { UnauthorizedError, authorize } from 'honertia/effect'
+
+// Automatic: authorize() throws UnauthorizedError if no user
+const auth = yield* authorize()
+
+// Manual: throw with custom redirect
+yield* Effect.fail(new UnauthorizedError({
+  message: 'Please log in to continue',
+  redirectTo: '/login', // Defaults to '/login'
+}))
+```
+
+**Behavior:** Redirects to the specified URL (302 for regular requests, 303 for Inertia requests).
+
+#### `NotFoundError`
+
+Thrown when a requested resource doesn't exist.
+
+```typescript
+import { NotFoundError, notFound } from 'honertia/effect'
+
+// Helper function
+return yield* notFound('Project', projectId)
+
+// Manual
+yield* Effect.fail(new NotFoundError({
+  resource: 'Project',
+  id: projectId,
+}))
+```
+
+**Behavior:** Triggers Hono's `notFound()` handler. If you've set up `registerErrorHandlers()`, this renders your error component with status 404.
+
+#### `ForbiddenError`
+
+Thrown when the user is authenticated but not authorized to perform an action.
+
+```typescript
+import { ForbiddenError, forbidden, authorize } from 'honertia/effect'
+
+// Automatic: authorize() throws ForbiddenError if check fails
+const auth = yield* authorize((a) => a.user.role === 'admin')
+
+// Helper function
+return yield* forbidden('You cannot edit this project')
+
+// Manual
+yield* Effect.fail(new ForbiddenError({
+  message: 'Admin access required',
+}))
+```
+
+**Behavior:** Returns JSON `{ message: "..." }` with 403 status. This is intentionally JSON for API compatibility.
+
+#### `HttpError`
+
+A generic error for custom HTTP responses. Use when you need precise control over the response.
+
+```typescript
+import { HttpError, httpError } from 'honertia/effect'
+
+// Helper function
+return yield* httpError(429, 'Rate limited', { retryAfter: 60 })
+
+// Manual
+yield* Effect.fail(new HttpError({
+  status: 429,
+  message: 'Too many requests',
+  body: { retryAfter: 60 }, // Optional additional data
+}))
+```
+
+**Behavior:** Returns JSON `{ message: "...", ...body }` with the specified status code.
+
+#### `RouteConfigurationError`
+
+Thrown when there's a developer configuration error, such as using route model binding without providing a schema.
+
+```typescript
+import { RouteConfigurationError } from 'honertia/effect'
+
+// This error is thrown automatically when:
+// - You use bound('project') but didn't pass schema to effectRoutes()
+// - Other route configuration mistakes
+
+// You typically don't throw this manually
+```
+
+**Behavior:** Re-throws to Hono's `onError` handler, which renders your error component. The error message and hint are logged to the console for debugging.
+
+### Setting Up Error Pages
+
+To render errors via Honertia instead of returning plain text/JSON, use `registerErrorHandlers`:
+
+```typescript
+import { registerErrorHandlers } from 'honertia'
+
+// In your app setup
+registerErrorHandlers(app, {
+  component: 'Error',        // Your error page component
+  showDevErrors: true,       // Show detailed errors in development
+  envKey: 'ENVIRONMENT',     // Env var to check
+  devValue: 'development',   // Value that enables dev errors
+})
+```
+
+Your `Error` component receives:
+
+```tsx
+// src/pages/Error.tsx
+interface ErrorProps {
+  status: number    // 404, 500, etc.
+  message: string   // Error message (detailed in dev, generic in prod)
+}
+
+export default function Error({ status, message }: ErrorProps) {
+  return (
+    <div className="error-page">
+      <h1>{status}</h1>
+      <p>{message}</p>
+    </div>
+  )
+}
+```
+
+### Error Handling Flow
+
+```
+Effect Handler
+     │
+     ▼
+┌─────────────────────────────────────────────────────────┐
+│                    errorToResponse()                     │
+├─────────────────────────────────────────────────────────┤
+│ ValidationError  → Re-render form / redirect back       │
+│ UnauthorizedError → Redirect to login                   │
+│ NotFoundError    → c.notFound() → Hono notFound handler │
+│ ForbiddenError   → JSON 403                             │
+│ HttpError        → JSON with custom status              │
+│ Other errors     → throw → Hono onError handler         │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           ▼ (for thrown errors)
+┌─────────────────────────────────────────────────────────┐
+│              Hono onError handler                        │
+│         (from registerErrorHandlers)                     │
+├─────────────────────────────────────────────────────────┤
+│ Renders error component via Honertia                    │
+│ Shows detailed message in dev, generic in prod          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Usage Examples
 
 ```typescript
 import {
@@ -1252,7 +1449,7 @@ import {
   NotFoundError,
   ForbiddenError,
   HttpError,
-} from 'honertia'
+} from 'honertia/effect'
 
 // Validation errors automatically re-render with field errors
 const input = yield* validateRequest(schema, {

package/dist/effect/handler.d.ts

@@ -8,6 +8,11 @@ import type { Context as HonoContext, MiddlewareHandler, Env } from 'hono';
 import { Redirect, type AppError } from './errors.js';
 /**
  * Convert an Effect error to an HTTP response.
+ *
+ * Most errors are re-thrown so Hono's onError handler can render them
+ * via Honertia's error component. Only errors that need special handling
+ * (ValidationError for form re-rendering, UnauthorizedError for redirects)
+ * return responses directly.
  */
 export declare function errorToResponse<E extends Env>(error: AppError, c: HonoContext<E>): Promise<Response>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/effect/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAA+B,MAAM,QAAQ,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE1E,OAAO,EAOL,QAAQ,EACR,KAAK,QAAQ,EACd,MAAM,aAAa,CAAA;AAGpB;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,GAAG,EACjD,KAAK,EAAE,QAAQ,EACf,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,OAAO,CAAC,QAAQ,CAAC,CAyDnB;AAgBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,SAAS,QAAQ,EAClE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GACjD,iBAAiB,CAAC,CAAC,CAAC,CAoBtB;AAsCD;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,SAAS,QAAQ,EAC3D,EAAE,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GACnD,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,sBAAgB,CAAA"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/effect/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAA+B,MAAM,QAAQ,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE1E,OAAO,EAML,QAAQ,EACR,KAAK,QAAQ,EACd,MAAM,aAAa,CAAA;AAuBpB;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,GAAG,EACjD,KAAK,EAAE,QAAQ,EACf,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAChB,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAgBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,SAAS,QAAQ,EAClE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GACjD,iBAAiB,CAAC,CAAC,CAAC,CAoBtB;AAgDD;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,SAAS,QAAQ,EAC3D,EAAE,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GACnD,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,sBAAgB,CAAA"}

package/dist/effect/handler.js

@@ -5,11 +5,36 @@
  */
 import { Effect, Exit, Cause, ManagedRuntime } from 'effect';
 import { getEffectRuntime, buildContextLayer } from './bridge.js';
-import { ValidationError, UnauthorizedError, NotFoundError, ForbiddenError, HttpError, RouteConfigurationError, Redirect, } from './errors.js';
+import { ValidationError, UnauthorizedError, NotFoundError, HttpError, RouteConfigurationError, Redirect, } from './errors.js';
+/**
+ * Convert an AppError to a throwable Error for Hono's onError handler.
+ * Preserves error metadata like status codes and hints.
+ */
+function toThrowableError(error) {
+    const err = new Error(error.message);
+    err.name = error._tag;
+    // Preserve status for HttpError
+    if (error instanceof HttpError) {
+        ;
+        err.status = error.status;
+    }
+    // Preserve hint for RouteConfigurationError
+    if (error instanceof RouteConfigurationError && error.hint) {
+        ;
+        err.hint = error.hint;
+    }
+    return err;
+}
 /**
  * Convert an Effect error to an HTTP response.
+ *
+ * Most errors are re-thrown so Hono's onError handler can render them
+ * via Honertia's error component. Only errors that need special handling
+ * (ValidationError for form re-rendering, UnauthorizedError for redirects)
+ * return responses directly.
  */
 export async function errorToResponse(error, c) {
+    // ValidationError: re-render form with errors or redirect back
     if (error instanceof ValidationError) {
         const isInertia = c.req.header('X-Inertia') === 'true';
         const prefersJson = c.req.header('Accept')?.includes('application/json') ||
@@ -28,34 +53,26 @@ export async function errorToResponse(error, c) {
         c.var?.honertia?.setErrors(error.errors);
         return c.redirect(referer, 303);
     }
+    // UnauthorizedError: redirect to login
     if (error instanceof UnauthorizedError) {
         const isInertia = c.req.header('X-Inertia') === 'true';
         const redirectTo = error.redirectTo ?? '/login';
         return c.redirect(redirectTo, isInertia ? 303 : 302);
     }
-    if (error instanceof ForbiddenError) {
-        return c.json({ message: error.message }, 403);
-    }
+    // NotFoundError: use Hono's notFound handler (renders via Honertia if configured)
     if (error instanceof NotFoundError) {
         return c.notFound();
     }
+    // ForbiddenError: return 403 JSON (useful for API routes)
+    if ('_tag' in error && error._tag === 'ForbiddenError') {
+        return c.json({ message: error.message }, 403);
+    }
+    // HttpError: return custom status JSON (gives developers control over HTTP responses)
     if (error instanceof HttpError) {
         return c.json({ message: error.message, ...error.body }, error.status);
     }
-    if (error instanceof RouteConfigurationError) {
-        console.error(`[honertia] Route configuration error: ${error.message}`);
-        if (error.hint) {
-            console.error(`[honertia] Hint: ${error.hint}`);
-        }
-        return c.json({
-            message: error.message,
-            hint: error.hint,
-            type: 'RouteConfigurationError'
-        }, 500);
-    }
-    // Unknown error
-    console.error('Unhandled error:', error);
-    return c.json({ message: 'Internal server error' }, 500);
+    // All other errors (RouteConfigurationError, etc.): throw to Hono's onError handler
+    throw toThrowableError(error);
 }
 /**
  * Handle a Redirect value (which is not an error).
@@ -93,6 +110,9 @@ export function effectHandler(effect) {
 }
 /**
  * Handle an Effect exit value.
+ *
+ * Failures are converted to responses via errorToResponse.
+ * Defects (unexpected errors) are re-thrown for Hono's onError handler.
  */
 async function handleExit(exit, c) {
     if (Exit.isSuccess(exit)) {
@@ -102,7 +122,7 @@ async function handleExit(exit, c) {
         }
         return value;
     }
-    // Handle failure
+    // Handle typed failures
     const cause = exit.cause;
     if (Cause.isFailure(cause)) {
         const error = Cause.failureOption(cause);
@@ -110,14 +130,21 @@ async function handleExit(exit, c) {
             return await errorToResponse(error.value, c);
         }
     }
-    // Handle defects (unexpected errors)
+    // Handle defects (unexpected errors) - throw to Hono's onError handler
     if (Cause.isDie(cause)) {
         const defect = Cause.dieOption(cause);
         if (defect._tag === 'Some') {
-            console.error('Effect defect:', defect.value);
+            const err = defect.value;
+            // If it's already an Error, throw it directly
+            if (err instanceof Error) {
+                throw err;
+            }
+            // Otherwise wrap it
+            throw new Error(String(err));
         }
     }
-    return c.json({ message: 'Internal server error' }, 500);
+    // Fallback: throw generic error for Hono's onError handler
+    throw new Error('Unknown effect failure');
 }
 /**
  * Create a handler from a function that returns an Effect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honertia",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Inertia.js-style server-driven SPA adapter for Hono",
   "type": "module",
   "main": "./dist/index.js",