@rdlabo/workers-hono-kit 0.6.0 → 0.6.3

package/README.md

@@ -7,7 +7,7 @@ It provides the building blocks a NestJS-style API needs but that don't run on `
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
 - **AWS Secrets Manager** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) — no AWS SDK.
 - **Middleware**: `finalizeResponse` (Express-compatible weak ETag + JSON charset), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
-- **NestJS-shaped errors**: `createNestErrorHandler` / `nestNotFoundHandler` / `HttpStatus`.
+- **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`.
 - **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
 - **AI Gateway**: route `@ai-sdk` models through the Cloudflare AI Gateway.
 - **Stripe** Workers-native client + async webhook verification.
@@ -66,17 +66,17 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. |
 | `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). |
 | `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
-| `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
-| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedNestErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). |
-| `createQueryFailedNestErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. |
-| `classifyGenericMysqlDriverError(err)` | Default classifier for apps without Nest filter parity: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. |
-| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss parity). |
-| `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
+| `createHttpErrorHandler(options?)` / `HttpErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to `{ statusCode, message, error? }` (`401` omits `error`). Optional custom error predicate and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
+| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). |
+| `createQueryFailedErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. |
+| `classifyGenericMysqlDriverError(err)` | Default classifier: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. |
+| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss). |
+| `notFoundHandler(c)` | `app.notFound()` handler with `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
 | `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. |
-| `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason phrases. |
+| `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
 | `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
-| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
+| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. |
 | `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). |
 | `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: `defaultDefer` swallows rejections (tests); `createWaitUntilDefer` registers work via `ctx.waitUntil`. |
 | `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
@@ -283,12 +283,10 @@ const appInfo = getAppInfo(c);
 return c.json(body, HttpStatus.CREATED);
 ```
 
-### NestJS-shaped error / 404 handlers
+### HTTP error / 404 handlers
 
-`createNestErrorHandler()` renders a thrown `HTTPException` as the NestJS exception-filter
-body, and `nestNotFoundHandler` gives the Express/Nest default 404. The defaults match the
-NestJS canonical shape (`{ statusCode, message, error? }`, `401` omits `error`); the options
-let you reproduce any byte-for-byte variation an existing API expects.
+`createHttpErrorHandler()` renders a thrown `HTTPException` as standard API error JSON,
+and `notFoundHandler` gives the default unmatched-route 404 body.
 
 #### App entry (fleet standard)
 
@@ -314,7 +312,7 @@ app.onError(
 );
 
 // odss-mobile: add classify: classifyQueryFailed (repo parity)
-// winecode: sentry + isHttpError / reasonPhrases in errors.ts (no container middleware)
+// winecode: sentry + isHttpError in errors.ts (no container middleware)
 // foodlabel: sentry + reportError: container.reportError (per-request container closure)
 ```
 
@@ -341,19 +339,19 @@ const { middleware: containerMiddleware, withContainer } = createContainerRuntim
 Use `withContainer` from `scheduled` / `queue` handlers; use `containerMiddleware` in `createApp`.
 
 ```ts
-import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hono-kit';
+import { createHttpErrorHandler, notFoundHandler } from '@rdlabo/workers-hono-kit';
 
-app.notFound(nestNotFoundHandler);
+app.notFound(notFoundHandler);
 
 // Prefer createAppErrorHandler (see "App entry" above). Lower-level only when needed:
-app.onError(createNestErrorHandler());
+app.onError(createHttpErrorHandler());
 ```
 
 **Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Pass `sentry`
 to `createAppErrorHandler` (or wire `getReportError` / `reportError` for tests and scheduled paths).
 
-Repos with a Nest `QueryFailedExceptionFilter` parity layer (e.g. odss-mobile) pass `classify` to
-`createAppErrorHandler` — do not call `createQueryFailedNestErrorHandler` directly unless you need full control.
+Repos with a custom DB error classifier (e.g. odss-mobile) pass `classify` to
+`createAppErrorHandler` — do not call `createQueryFailedErrorHandler` directly unless you need full control.
 
 ### Auth middleware
 

package/dist/http/app-error-handler.d.ts

@@ -1,16 +1,15 @@
 import type { Context, Env } from 'hono';
-import { type QueryFailedClassifier } from './query-failed-error.js';
-import type { ErrorReporter, NestErrorHandlerOptions, SentryExceptionReporterLike } from './nest-error.js';
+import type { ErrorReporter, HttpErrorHandlerOptions, SentryExceptionReporterLike } from './http-error.js';
+import type { QueryFailedClassifier } from './query-failed-error.js';
 /**
  * Options for {@link createAppErrorHandler}.
  *
  * @remarks
- * Wires `createQueryFailedNestErrorHandler` with fleet defaults (`fieldOrder: 'message-first'`,
- * {@link classifyGenericMysqlDriverError}) and optional error reporting.
+ * Wires `createQueryFailedErrorHandler` with fleet defaults ({@link classifyGenericMysqlDriverError}) and optional error reporting.
  * Pass `sentry` for Sentry-backed apps; omit it (or pass `undefined`) when not used.
  * `getReportError` / `reportError` override `sentry` (tests, container injection, scheduled paths).
  */
-export interface CreateAppErrorHandlerOptions<E extends Env = Env> extends Omit<NestErrorHandlerOptions<E>, 'onUnhandledError'> {
+export interface CreateAppErrorHandlerOptions<E extends Env = Env> extends Omit<HttpErrorHandlerOptions<E>, 'onUnhandledError'> {
     /** mysql2 driver error classifier. Defaults to {@link classifyGenericMysqlDriverError}. */
     classify?: QueryFailedClassifier;
     /** Optional Sentry client (`@sentry/cloudflare`). Omitted on repos without Sentry. */
@@ -23,6 +22,6 @@ export interface CreateAppErrorHandlerOptions<E extends Env = Env> extends Omit<
     onUnhandledError?: (err: unknown, c: Context<E>) => void;
 }
 /**
- * Standard `app.onError` factory: QueryFailed filter → Nest default filter, with optional error reporting.
+ * Standard `app.onError` factory: QueryFailed filter → HTTP error handler, with optional error reporting.
  */
 export declare function createAppErrorHandler<E extends Env = Env>(options?: CreateAppErrorHandlerOptions<E>): (err: Error, c: Context<E, any, {}>) => Response;

package/dist/http/app-error-handler.js

@@ -1,10 +1,10 @@
-import { classifyGenericMysqlDriverError, createQueryFailedNestErrorHandler, } from './query-failed-error.js';
-import { createSentryErrorReporter } from './nest-error.js';
+import { createSentryErrorReporter } from './http-error.js';
+import { classifyGenericMysqlDriverError, createQueryFailedErrorHandler } from './query-failed-error.js';
 /**
- * Standard `app.onError` factory: QueryFailed filter → Nest default filter, with optional error reporting.
+ * Standard `app.onError` factory: QueryFailed filter → HTTP error handler, with optional error reporting.
  */
 export function createAppErrorHandler(options = {}) {
-    const { classify = classifyGenericMysqlDriverError, sentry, reportError, getReportError, onUnhandledError, fieldOrder = 'message-first', ...nestOptions } = options;
+    const { classify = classifyGenericMysqlDriverError, sentry, reportError, getReportError, onUnhandledError, ...httpOptions } = options;
     const sentryReporter = sentry ? createSentryErrorReporter(sentry) : undefined;
     const resolvedOnUnhandled = onUnhandledError ??
         ((err, c) => {
@@ -12,9 +12,8 @@ export function createAppErrorHandler(options = {}) {
             const requestId = c.get('requestId');
             reporter?.(err, { requestId });
         });
-    return createQueryFailedNestErrorHandler({
-        fieldOrder,
-        ...nestOptions,
+    return createQueryFailedErrorHandler({
+        ...httpOptions,
         classify,
         onUnhandledError: resolvedOnUnhandled,
     });

package/dist/http/http-error.d.ts

@@ -0,0 +1,113 @@
+import type { Context, Env } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+/**
+ * Standard `error` field phrases for common HTTP status codes.
+ *
+ * @remarks
+ * Used by {@link createHttpErrorHandler} for the `error` field on client-error statuses.
+ */
+export declare const HTTP_ERROR_PHRASES: Record<number, string>;
+/**
+ * Contextual metadata passed to an {@link ErrorReporter} when reporting an unexpected error.
+ */
+export interface ErrorReportContext {
+    /** Correlation id for the failing request, if one is tracked. */
+    requestId?: string;
+}
+/**
+ * Signature of a function that reports an unexpected (non-HTTP) error to an external sink such as Sentry.
+ *
+ * @remarks
+ * Wire it into {@link createHttpErrorHandler} via `onUnhandledError`, e.g.
+ * `(err, c) => reporter(err, { requestId: c.get('requestId') })`. The reporting client itself is
+ * intentionally kept out of this kit; the consumer supplies the implementation.
+ *
+ * @param error - The thrown value being reported.
+ * @param context - Optional correlation context for the failing request.
+ */
+export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
+/**
+ * Minimal Sentry-like client for {@link createSentryErrorReporter} and {@link createQueueErrorHandler}.
+ *
+ * @remarks
+ * Declared structurally to avoid a hard dependency on `@sentry/cloudflare`.
+ */
+export interface SentryExceptionReporterLike {
+    captureException(exception: unknown, captureContext?: {
+        tags?: Record<string, string>;
+        extra?: Record<string, unknown>;
+    }): void;
+}
+/**
+ * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
+ */
+export declare function createSentryErrorReporter(sentry: SentryExceptionReporterLike): ErrorReporter;
+/**
+ * Minimal shape read from a value treated as an HTTP error: its status, message, and optional body.
+ *
+ * @internal
+ */
+interface HttpErrorLike {
+    /** HTTP status code to respond with. */
+    status: ContentfulStatusCode;
+    /** Human-readable error message placed in the response body. */
+    message: string;
+    /**
+     * Escape hatch for a fully custom response body. When present, it is rendered verbatim instead of
+     * the standard error JSON shape.
+     */
+    body?: unknown;
+}
+/**
+ * Options controlling how {@link createHttpErrorHandler} shapes error responses.
+ *
+ * @typeParam E - The Hono environment type, so `onUnhandledError` receives a correctly typed context.
+ */
+export interface HttpErrorHandlerOptions<E extends Env = Env> {
+    /**
+     * Predicate identifying which thrown values are HTTP errors. Defaults to detecting Hono's `HTTPException`.
+     * Override it (e.g. `(e) => e instanceof MyHttpError`) when the app throws a custom HTTP error type.
+     */
+    isHttpError?: (err: unknown) => err is HttpErrorLike;
+    /**
+     * Hook invoked before an unexpected (non-HTTP) error is returned as a 500, typically used to report the
+     * error (e.g. to Sentry). Any exception thrown by this hook is swallowed so reporting cannot alter the
+     * error response.
+     */
+    onUnhandledError?: (err: unknown, c: Context<E>) => void;
+}
+/**
+ * Create a Hono `onError` handler that maps thrown errors to standard API error JSON.
+ *
+ * @remarks
+ * - HTTP errors (by default `HTTPException`) map to `{ statusCode, message, error? }`; `401` omits `error`.
+ * - Errors with a custom `body` are returned verbatim.
+ * - Unexpected errors trigger `onUnhandledError`, are logged, and return generic 500.
+ *
+ * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
+ * @param options - Optional custom HTTP error detection and reporting hook.
+ * @returns A handler suitable for `app.onError(...)`.
+ *
+ * @example
+ * ```ts
+ * app.onError(
+ *   createHttpErrorHandler({
+ *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
+ *   }),
+ * );
+ * ```
+ */
+export declare function createHttpErrorHandler<E extends Env = Env>(options?: HttpErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;
+/**
+ * Hono `notFound` handler for unmatched routes.
+ *
+ * @param c - The Hono request context for the unmatched route.
+ * @returns A 404 JSON response: `{ message: 'Cannot METHOD path', error, statusCode }`.
+ *
+ * @example
+ * ```ts
+ * app.notFound(notFoundHandler);
+ * ```
+ */
+export declare function notFoundHandler(c: Context): Response;
+export {};

package/dist/http/http-error.js

@@ -0,0 +1,106 @@
+import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
+/** Statuses that return only `{ statusCode, message }` (no `error` field). */
+const BARE_STATUSES = [401];
+const INTERNAL_SERVER_ERROR_BODY = { statusCode: 500, message: 'Internal server error' };
+/**
+ * Standard `error` field phrases for common HTTP status codes.
+ *
+ * @remarks
+ * Used by {@link createHttpErrorHandler} for the `error` field on client-error statuses.
+ */
+export const HTTP_ERROR_PHRASES = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+};
+/**
+ * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
+ */
+export function createSentryErrorReporter(sentry) {
+    return (error, context) => {
+        sentry.captureException(error, context?.requestId ? { tags: { request_id: context.requestId } } : undefined);
+    };
+}
+/**
+ * Structurally detect Hono's `HTTPException` without relying on `instanceof`.
+ *
+ * @remarks
+ * When this kit is symlinked into a consumer, the `hono` instance it resolves can differ from the
+ * consumer's `hono`, so an `HTTPException` from one copy fails an `instanceof` check against the other.
+ * Detecting the presence of a `getResponse()` method and a numeric `status` is stable across module
+ * boundaries and production bundles.
+ *
+ * @param err - The thrown value to test.
+ * @returns `true` when `err` looks like a Hono `HTTPException`.
+ *
+ * @internal
+ */
+const isHTTPException = (err) => err instanceof Error &&
+    typeof err.getResponse === 'function' &&
+    typeof err.status === 'number';
+/**
+ * Create a Hono `onError` handler that maps thrown errors to standard API error JSON.
+ *
+ * @remarks
+ * - HTTP errors (by default `HTTPException`) map to `{ statusCode, message, error? }`; `401` omits `error`.
+ * - Errors with a custom `body` are returned verbatim.
+ * - Unexpected errors trigger `onUnhandledError`, are logged, and return generic 500.
+ *
+ * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
+ * @param options - Optional custom HTTP error detection and reporting hook.
+ * @returns A handler suitable for `app.onError(...)`.
+ *
+ * @example
+ * ```ts
+ * app.onError(
+ *   createHttpErrorHandler({
+ *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
+ *   }),
+ * );
+ * ```
+ */
+export function createHttpErrorHandler(options = {}) {
+    const { isHttpError = isHTTPException, onUnhandledError } = options;
+    return (err, c) => {
+        if (isHttpError(err)) {
+            if (err.body !== undefined) {
+                return c.json(err.body, err.status);
+            }
+            const reason = BARE_STATUSES.includes(err.status)
+                ? undefined
+                : HTTP_ERROR_PHRASES[err.status];
+            if (reason === undefined) {
+                return c.json({ statusCode: err.status, message: err.message }, err.status);
+            }
+            return c.json({ statusCode: err.status, message: err.message, error: reason }, err.status);
+        }
+        try {
+            onUnhandledError?.(err, c);
+        }
+        catch {
+            // Reporting must never change the behavior of the error response.
+        }
+        if (findMysqlDriverError(err)) {
+            logMysqlDriverError(err, 500);
+        }
+        else {
+            console.error(err);
+        }
+        return c.json(INTERNAL_SERVER_ERROR_BODY, 500);
+    };
+}
+/**
+ * Hono `notFound` handler for unmatched routes.
+ *
+ * @param c - The Hono request context for the unmatched route.
+ * @returns A 404 JSON response: `{ message: 'Cannot METHOD path', error, statusCode }`.
+ *
+ * @example
+ * ```ts
+ * app.notFound(notFoundHandler);
+ * ```
+ */
+export function notFoundHandler(c) {
+    return c.json({ message: `Cannot ${c.req.method} ${new URL(c.req.url).pathname}`, error: 'Not Found', statusCode: 404 }, 404);
+}

package/dist/http/query-failed-error.d.ts

@@ -1,6 +1,6 @@
 import type { Context, Env } from 'hono';
-import type { NestErrorHandlerOptions } from './nest-error.js';
-/** Nest QueryFailedExceptionFilter が返す `{ statusCode, message }` 形（error フィールド無し）。 */
+import type { HttpErrorHandlerOptions } from './http-error.js';
+/** DB エラー分類結果: `{ statusCode, message }` 形（error フィールド無し）。 */
 export interface ClassifiedDbError {
     statusCode: 400 | 500;
     message: string;
@@ -8,22 +8,21 @@ export interface ClassifiedDbError {
 /** mysql2 / Drizzle 由来の DB エラーを HTTP 応答用に分類する。非 DB エラーは null。 */
 export type QueryFailedClassifier = (err: unknown) => ClassifiedDbError | null;
 /**
- * Default classifier for apps without a NestJS `QueryFailedExceptionFilter` parity layer.
- * Maps any mysql2 driver error to generic 500 `{ statusCode, message: 'Internal server error' }`.
+ * Default classifier: any mysql2 driver error → generic 500 `{ statusCode, message: 'Internal server error' }`.
  */
 export declare function classifyGenericMysqlDriverError(err: unknown): ClassifiedDbError | null;
-export interface QueryFailedNestErrorHandlerOptions<E extends Env = Env> extends NestErrorHandlerOptions<E> {
-    /** アプリ固有の分類（parity-critical な日本語メッセージ等は consumer 側で定義）。 */
+export interface QueryFailedErrorHandlerOptions<E extends Env = Env> extends HttpErrorHandlerOptions<E> {
+    /** アプリ固有の分類（日本語メッセージ等は consumer 側で定義）。 */
     classify: QueryFailedClassifier;
 }
 /**
- * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ * DB エラー分類 → 標準 HTTP エラーハンドラの合成 onError。
  *
  * @remarks
- * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
- * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ * classify が non-null のときは分類結果の body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createHttpErrorHandler} に委譲する。
  *
  * `Sentry.withSentry` だけでは onError 握りエラーは capture されないため、
  * `onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') })` を必ず配線する。
  */
-export declare function createQueryFailedNestErrorHandler<E extends Env = Env>(options: QueryFailedNestErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;
+export declare function createQueryFailedErrorHandler<E extends Env = Env>(options: QueryFailedErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;

package/dist/http/query-failed-error.js

@@ -1,8 +1,7 @@
+import { createHttpErrorHandler } from './http-error.js';
 import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
-import { createNestErrorHandler } from './nest-error.js';
 /**
- * Default classifier for apps without a NestJS `QueryFailedExceptionFilter` parity layer.
- * Maps any mysql2 driver error to generic 500 `{ statusCode, message: 'Internal server error' }`.
+ * Default classifier: any mysql2 driver error → generic 500 `{ statusCode, message: 'Internal server error' }`.
  */
 export function classifyGenericMysqlDriverError(err) {
     if (!findMysqlDriverError(err)) {
@@ -11,7 +10,7 @@ export function classifyGenericMysqlDriverError(err) {
     return { statusCode: 500, message: 'Internal server error' };
 }
 /**
- * @internal Used by {@link createQueryFailedNestErrorHandler} only.
+ * @internal Used by {@link createQueryFailedErrorHandler} only.
  */
 function reportClassifiedDbError(err, classified, reportError, requestId) {
     logMysqlDriverError(err, classified.statusCode);
@@ -20,19 +19,19 @@ function reportClassifiedDbError(err, classified, reportError, requestId) {
     }
 }
 /**
- * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ * DB エラー分類 → 標準 HTTP エラーハンドラの合成 onError。
  *
  * @remarks
- * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
- * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ * classify が non-null のときは分類結果の body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createHttpErrorHandler} に委譲する。
  *
  * `Sentry.withSentry` だけでは onError 握りエラーは capture されないため、
  * `onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') })` を必ず配線する。
  */
-export function createQueryFailedNestErrorHandler(options) {
-    const { classify, ...nestOptions } = options;
-    const nestErrorHandler = createNestErrorHandler(nestOptions);
-    const { onUnhandledError } = nestOptions;
+export function createQueryFailedErrorHandler(options) {
+    const { classify, ...httpOptions } = options;
+    const httpErrorHandler = createHttpErrorHandler(httpOptions);
+    const { onUnhandledError } = httpOptions;
     return (err, c) => {
         const classified = classify(err);
         if (classified) {
@@ -47,6 +46,6 @@ export function createQueryFailedNestErrorHandler(options) {
             }
             return c.json({ statusCode: classified.statusCode, message: classified.message }, classified.statusCode);
         }
-        return nestErrorHandler(err, c);
+        return httpErrorHandler(err, c);
     };
 }

package/dist/index.d.ts

@@ -10,7 +10,8 @@
  * @packageDocumentation
  */
 export { finalizeResponse } from './middleware/finalize-response.js';
-export { validate, createValidate, createSentryValidate } from './middleware/validation.js';
+export { validate, createValidate } from './middleware/validation.js';
+export { createSentryValidate } from './middleware/validation.js';
 export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, SentryScopeLike, } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
@@ -28,20 +29,20 @@ export type { AppInfo } from './http/app-info.js';
 export { resolveAppEnv, isProductionEnv } from './http/app-env.js';
 export type { AppEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
-export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
-export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error.js';
+export { createHttpErrorHandler, notFoundHandler, HTTP_ERROR_PHRASES } from './http/http-error.js';
+export type { HttpErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/http-error.js';
 export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
 export type { MysqlDriverErrorLike } from './http/mysql-driver-error.js';
-export { createQueryFailedNestErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
-export type { ClassifiedDbError, QueryFailedClassifier, QueryFailedNestErrorHandlerOptions, } from './http/query-failed-error.js';
+export { createQueryFailedErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
+export type { ClassifiedDbError, QueryFailedClassifier, QueryFailedErrorHandlerOptions, } from './http/query-failed-error.js';
 export { createAppErrorHandler } from './http/app-error-handler.js';
 export type { CreateAppErrorHandlerOptions } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export type { ExecutionContextLike } from './http/execution-context.js';
 export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export type { DeferExecutor } from './http/defer.js';
-export { createSentryErrorReporter } from './http/nest-error.js';
-export type { SentryExceptionReporterLike } from './http/nest-error.js';
+export { createSentryErrorReporter } from './http/http-error.js';
+export type { SentryExceptionReporterLike } from './http/http-error.js';
 export { KVCache } from './cache/kv-cache.js';
 export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';

package/dist/index.js

@@ -11,7 +11,10 @@
  */
 // middleware
 export { finalizeResponse } from './middleware/finalize-response.js';
-export { validate, createValidate, createSentryValidate } from './middleware/validation.js';
+export { validate, createValidate } from './middleware/validation.js';
+// Backward-compat alias; prefer createValidate({ sentry }).
+// eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional public re-export
+export { createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
@@ -22,13 +25,13 @@ export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
 export { resolveAppEnv, isProductionEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
-export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
+export { createHttpErrorHandler, notFoundHandler, HTTP_ERROR_PHRASES } from './http/http-error.js';
 export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
-export { createQueryFailedNestErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
+export { createQueryFailedErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
 export { createAppErrorHandler } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
-export { createSentryErrorReporter } from './http/nest-error.js';
+export { createSentryErrorReporter } from './http/http-error.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';
 // stripe

package/dist/queue/error-handler.d.ts

@@ -1,5 +1,5 @@
+import type { SentryExceptionReporterLike } from '../http/http-error.js';
 import type { QueueMessageLike } from './consumer.js';
-import type { SentryExceptionReporterLike } from '../http/nest-error.js';
 /**
  * Options for {@link createQueueErrorHandler}.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "private": false,
   "publishConfig": {
     "access": "public"

package/dist/http/nest-error.d.ts

@@ -1,149 +0,0 @@
-import type { Context, Env } from 'hono';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
-/**
- * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
- *
- * @remarks
- * Mirrors the `error` field values NestJS produces for common client-error statuses, so a Hono app can
- * return byte-identical error bodies. Used as the default `reasonPhrases` map by {@link createNestErrorHandler}.
- */
-export declare const NEST_REASON_PHRASES: Record<number, string>;
-/**
- * Contextual metadata passed to an {@link ErrorReporter} when reporting an unexpected error.
- */
-export interface ErrorReportContext {
-    /** Correlation id for the failing request, if one is tracked. */
-    requestId?: string;
-}
-/**
- * Signature of a function that reports an unexpected (non-HTTP) error to an external sink such as Sentry.
- *
- * @remarks
- * Wire it into {@link createNestErrorHandler} via `onUnhandledError`, e.g.
- * `(err, c) => reporter(err, { requestId: c.get('requestId') })`. The reporting client itself is
- * intentionally kept out of this kit; the consumer supplies the implementation.
- *
- * @param error - The thrown value being reported.
- * @param context - Optional correlation context for the failing request.
- */
-export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
-/**
- * Minimal Sentry-like client for {@link createSentryErrorReporter} and {@link createQueueErrorHandler}.
- *
- * @remarks
- * Declared structurally to avoid a hard dependency on `@sentry/cloudflare`.
- */
-export interface SentryExceptionReporterLike {
-    captureException(exception: unknown, captureContext?: {
-        tags?: Record<string, string>;
-        extra?: Record<string, unknown>;
-    }): void;
-}
-/**
- * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
- */
-export declare function createSentryErrorReporter(sentry: SentryExceptionReporterLike): ErrorReporter;
-/**
- * Minimal shape read from a value treated as an HTTP error: its status, message, and optional body.
- *
- * @internal
- */
-interface HttpErrorLike {
-    /** HTTP status code to respond with. */
-    status: ContentfulStatusCode;
-    /** Human-readable error message placed in the response body. */
-    message: string;
-    /**
-     * Escape hatch for a fully custom response body. When present, it is rendered verbatim instead of
-     * the NestJS-shaped body.
-     */
-    body?: unknown;
-}
-/**
- * Options controlling how {@link createNestErrorHandler} shapes error responses.
- *
- * @typeParam E - The Hono environment type, so `onUnhandledError` receives a correctly typed context.
- */
-export interface NestErrorHandlerOptions<E extends Env = Env> {
-    /** Status-to-reason-phrase map for the `error` field. Defaults to {@link NEST_REASON_PHRASES}. */
-    reasonPhrases?: Record<number, string>;
-    /**
-     * Statuses that return only `{ statusCode, message }`, omitting the `error` field. Defaults to `[401]`,
-     * matching NestJS where a generic `HttpException(msg, 401)` carries no `error`.
-     */
-    bareStatuses?: readonly number[];
-    /**
-     * Field order of the non-bare error body. Defaults to `'statusCode-first'` (the NestJS canonical order).
-     * Use `'message-first'` to emit `{ message, error, statusCode }` when byte parity requires it.
-     */
-    fieldOrder?: 'statusCode-first' | 'message-first';
-    /**
-     * Fallback `error` value for statuses that are neither bare nor present in `reasonPhrases`. Defaults to
-     * `undefined`, meaning the `error` field is omitted when no reason phrase is known. Set to a string such
-     * as `'Error'` to always include an `error` field, faithfully reproducing the NestJS default exception
-     * filter behavior where `error` is always present.
-     */
-    fallbackReason?: string;
-    /**
-     * Predicate identifying which thrown values are HTTP errors. Defaults to detecting Hono's `HTTPException`.
-     * Override it (e.g. `(e) => e instanceof MyHttpError`) when the app throws a custom HTTP error type.
-     */
-    isHttpError?: (err: unknown) => err is HttpErrorLike;
-    /**
-     * Hook invoked before an unexpected (non-HTTP) error is returned as a 500, typically used to report the
-     * error (e.g. to Sentry). Any exception thrown by this hook is swallowed so reporting cannot alter the
-     * error response.
-     */
-    onUnhandledError?: (err: unknown, c: Context<E>) => void;
-    /**
-     * Response body for unexpected errors returned as 500. Defaults to
-     * `{ statusCode: 500, message: 'Internal server error' }`.
-     */
-    internalServerErrorBody?: unknown;
-}
-/**
- * Create a Hono `onError` handler that maps thrown errors to NestJS-shaped error JSON.
- *
- * @remarks
- * Reproduces the NestJS default exception filter so a Hono app returns byte-identical error bodies:
- * - HTTP errors (by default `HTTPException`) are mapped to a NestJS-shaped body; if the error carries a
- *   custom `body`, that body is returned verbatim.
- * - Statuses listed in `bareStatuses` (default `[401]`) omit the `error` field.
- * - Any other (unexpected) error triggers `onUnhandledError`, is logged via `console.error`, and returns 500.
- *
- * Per-app differences in body field order, HTTP error type, and reporting hook are absorbed through
- * {@link NestErrorHandlerOptions}, while the branching logic stays shared.
- *
- * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
- * @param options - Overrides for reason phrases, bare statuses, field order, error detection, and reporting.
- * @returns A handler suitable for `app.onError(...)`.
- *
- * @example
- * ```ts
- * app.onError(
- *   createNestErrorHandler({
- *     fieldOrder: 'message-first',
- *     fallbackReason: 'Error',
- *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
- *   }),
- * );
- * ```
- */
-export declare function createNestErrorHandler<E extends Env = Env>(options?: NestErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;
-/**
- * Hono `notFound` handler that returns the canonical Express/NestJS unmatched-route 404 body.
- *
- * @remarks
- * Produces `{ message: "Cannot <METHOD> <path>", error: 'Not Found', statusCode: 404 }`, matching the
- * NestJS default 404 response so unmatched routes stay byte-identical.
- *
- * @param c - The Hono request context for the unmatched route.
- * @returns A 404 JSON response.
- *
- * @example
- * ```ts
- * app.notFound(nestNotFoundHandler);
- * ```
- */
-export declare function nestNotFoundHandler(c: Context): Response;
-export {};

package/dist/http/nest-error.js

@@ -1,120 +0,0 @@
-import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
-/**
- * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
- *
- * @remarks
- * Mirrors the `error` field values NestJS produces for common client-error statuses, so a Hono app can
- * return byte-identical error bodies. Used as the default `reasonPhrases` map by {@link createNestErrorHandler}.
- */
-export const NEST_REASON_PHRASES = {
-    400: 'Bad Request',
-    401: 'Unauthorized',
-    403: 'Forbidden',
-    404: 'Not Found',
-};
-/**
- * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
- */
-export function createSentryErrorReporter(sentry) {
-    return (error, context) => {
-        sentry.captureException(error, context?.requestId ? { tags: { request_id: context.requestId } } : undefined);
-    };
-}
-/**
- * Structurally detect Hono's `HTTPException` without relying on `instanceof`.
- *
- * @remarks
- * When this kit is symlinked into a consumer, the `hono` instance it resolves can differ from the
- * consumer's `hono`, so an `HTTPException` from one copy fails an `instanceof` check against the other.
- * Detecting the presence of a `getResponse()` method and a numeric `status` is stable across module
- * boundaries and production bundles.
- *
- * @param err - The thrown value to test.
- * @returns `true` when `err` looks like a Hono `HTTPException`.
- *
- * @internal
- */
-const isHTTPException = (err) => err instanceof Error &&
-    typeof err.getResponse === 'function' &&
-    typeof err.status === 'number';
-/**
- * Create a Hono `onError` handler that maps thrown errors to NestJS-shaped error JSON.
- *
- * @remarks
- * Reproduces the NestJS default exception filter so a Hono app returns byte-identical error bodies:
- * - HTTP errors (by default `HTTPException`) are mapped to a NestJS-shaped body; if the error carries a
- *   custom `body`, that body is returned verbatim.
- * - Statuses listed in `bareStatuses` (default `[401]`) omit the `error` field.
- * - Any other (unexpected) error triggers `onUnhandledError`, is logged via `console.error`, and returns 500.
- *
- * Per-app differences in body field order, HTTP error type, and reporting hook are absorbed through
- * {@link NestErrorHandlerOptions}, while the branching logic stays shared.
- *
- * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
- * @param options - Overrides for reason phrases, bare statuses, field order, error detection, and reporting.
- * @returns A handler suitable for `app.onError(...)`.
- *
- * @example
- * ```ts
- * app.onError(
- *   createNestErrorHandler({
- *     fieldOrder: 'message-first',
- *     fallbackReason: 'Error',
- *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
- *   }),
- * );
- * ```
- */
-export function createNestErrorHandler(options = {}) {
-    const { reasonPhrases = NEST_REASON_PHRASES, bareStatuses = [401], fieldOrder = 'statusCode-first', isHttpError = isHTTPException, onUnhandledError, internalServerErrorBody = { statusCode: 500, message: 'Internal server error' }, fallbackReason, } = options;
-    return (err, c) => {
-        if (isHttpError(err)) {
-            // Escape hatch for a custom error body: render it verbatim.
-            if (err.body !== undefined) {
-                return c.json(err.body, err.status);
-            }
-            // reasonPhrases[status] is typed as string, but with noUncheckedIndexedAccess disabled it can be
-            // undefined at runtime. The fallbackReason fallback for unregistered statuses is intentional.
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            const reason = bareStatuses.includes(err.status) ? undefined : (reasonPhrases[err.status] ?? fallbackReason);
-            if (reason === undefined) {
-                return c.json({ statusCode: err.status, message: err.message }, err.status);
-            }
-            const body = fieldOrder === 'message-first'
-                ? { message: err.message, error: reason, statusCode: err.status }
-                : { statusCode: err.status, message: err.message, error: reason };
-            return c.json(body, err.status);
-        }
-        try {
-            onUnhandledError?.(err, c);
-        }
-        catch {
-            // Reporting must never change the behavior of the error response.
-        }
-        if (findMysqlDriverError(err)) {
-            logMysqlDriverError(err, 500);
-        }
-        else {
-            console.error(err);
-        }
-        return c.json(internalServerErrorBody, 500);
-    };
-}
-/**
- * Hono `notFound` handler that returns the canonical Express/NestJS unmatched-route 404 body.
- *
- * @remarks
- * Produces `{ message: "Cannot <METHOD> <path>", error: 'Not Found', statusCode: 404 }`, matching the
- * NestJS default 404 response so unmatched routes stay byte-identical.
- *
- * @param c - The Hono request context for the unmatched route.
- * @returns A 404 JSON response.
- *
- * @example
- * ```ts
- * app.notFound(nestNotFoundHandler);
- * ```
- */
-export function nestNotFoundHandler(c) {
-    return c.json({ message: `Cannot ${c.req.method} ${new URL(c.req.url).pathname}`, error: 'Not Found', statusCode: 404 }, 404);
-}