@rdlabo/workers-hono-kit 0.4.3 → 0.5.1

package/README.md

@@ -65,7 +65,9 @@ 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. |
+| `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). |
+| `createQueryFailedNestErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Compose a NestJS `QueryFailedExceptionFilter` analog **before** `createNestErrorHandler`: consumer supplies `classify(err)` (parity-critical messages stay in the app); classified DB errors log (`warn` for 400, `error` for 500) and trigger `onUnhandledError` on 500 only. |
+| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` / `reportClassifiedDbError(...)` | Low-level mysql2 driver-error detection (follows `err.cause`), structured logging, and classify-path reporting helpers. |
 | `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ 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. |
@@ -298,6 +300,24 @@ app.onError(
 );
 ```
 
+**Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Wire
+`onUnhandledError` → `Sentry.captureException` explicitly (mirrors Nest `SentryGlobalFilter`).
+
+Repos with a Nest `QueryFailedExceptionFilter` (e.g. odss-mobile) should use
+`createQueryFailedNestErrorHandler` so classified DB errors still log and report to Sentry:
+
+```ts
+import { createQueryFailedNestErrorHandler } from '@rdlabo/workers-hono-kit';
+
+app.onError(
+  createQueryFailedNestErrorHandler({
+    fieldOrder: 'message-first',
+    classify: classifyQueryFailed, // app-local parity (Japanese messages, errno rules)
+    onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') }),
+  }),
+);
+```
+
 ### Auth middleware
 
 Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →

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

@@ -0,0 +1,25 @@
+/**
+ * mysql2 driver error shape (= TypeORM QueryFailedError.driverError 相当).
+ * Drizzle / Error.cause で wrap される場合があるため cause も再帰探索する。
+ */
+export interface MysqlDriverErrorLike {
+    errno?: number;
+    sqlMessage?: string;
+    sqlState?: string;
+    message?: string;
+    sql?: string;
+    code?: string;
+    cause?: unknown;
+}
+/**
+ * err 本体 → `err.cause` を再帰的に辿り、mysql2 ドライバエラーを取り出す。
+ *
+ * @param err - handler / onError に渡された thrown value。
+ * @param seen - 循環参照防止（内部用）。
+ */
+export declare function findMysqlDriverError(err: unknown, seen?: Set<unknown>): MysqlDriverErrorLike | null;
+/**
+ * Nest QueryFailedExceptionFilter の logger.error / logger.warn 相当。
+ * レスポンス body には載せず、Workers Logs 用に errno / sqlMessage / sql を残す。
+ */
+export declare function logMysqlDriverError(err: unknown, statusCode: number): void;

package/dist/http/mysql-driver-error.js

@@ -0,0 +1,35 @@
+/**
+ * err 本体 → `err.cause` を再帰的に辿り、mysql2 ドライバエラーを取り出す。
+ *
+ * @param err - handler / onError に渡された thrown value。
+ * @param seen - 循環参照防止（内部用）。
+ */
+export function findMysqlDriverError(err, seen = new Set()) {
+    if (err === null || err === undefined || seen.has(err)) {
+        return null;
+    }
+    seen.add(err);
+    const e = err;
+    if (typeof e.errno === 'number' && (typeof e.sqlMessage === 'string' || typeof e.sqlState === 'string')) {
+        return e;
+    }
+    if (e.cause !== undefined) {
+        return findMysqlDriverError(e.cause, seen);
+    }
+    return null;
+}
+/**
+ * Nest QueryFailedExceptionFilter の logger.error / logger.warn 相当。
+ * レスポンス body には載せず、Workers Logs 用に errno / sqlMessage / sql を残す。
+ */
+export function logMysqlDriverError(err, statusCode) {
+    const driver = findMysqlDriverError(err);
+    const rawMessage = driver?.sqlMessage ?? driver?.message ?? (err instanceof Error ? err.message : String(err));
+    const detail = driver === null ? undefined : { errno: driver.errno, sql: driver.sql, code: driver.code };
+    const line = `QueryFailedError (${statusCode}): ${rawMessage}`;
+    if (statusCode >= 500) {
+        console.error(line, detail);
+        return;
+    }
+    console.warn(line, detail);
+}

package/dist/http/nest-error.js

@@ -1,3 +1,4 @@
+import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
 /**
  * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
  *
@@ -82,7 +83,12 @@ export function createNestErrorHandler(options = {}) {
         catch {
             // Reporting must never change the behavior of the error response.
         }
-        console.error(err);
+        if (findMysqlDriverError(err)) {
+            logMysqlDriverError(err, 500);
+        }
+        else {
+            console.error(err);
+        }
         return c.json(internalServerErrorBody, 500);
     };
 }

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

@@ -0,0 +1,29 @@
+import type { Context, Env } from 'hono';
+import type { ErrorReporter, NestErrorHandlerOptions } from './nest-error.js';
+/** Nest QueryFailedExceptionFilter が返す `{ statusCode, message }` 形（error フィールド無し）。 */
+export interface ClassifiedDbError {
+    statusCode: 400 | 500;
+    message: string;
+}
+/** mysql2 / Drizzle 由来の DB エラーを HTTP 応答用に分類する。非 DB エラーは null。 */
+export type QueryFailedClassifier = (err: unknown) => ClassifiedDbError | null;
+/**
+ * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
+ * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ */
+export declare function reportClassifiedDbError(err: unknown, classified: ClassifiedDbError, reportError?: ErrorReporter, requestId?: string): void;
+export interface QueryFailedNestErrorHandlerOptions<E extends Env = Env> extends NestErrorHandlerOptions<E> {
+    /** アプリ固有の分類（parity-critical な日本語メッセージ等は consumer 側で定義）。 */
+    classify: QueryFailedClassifier;
+}
+/**
+ * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ *
+ * @remarks
+ * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ *
+ * `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;

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

@@ -0,0 +1,43 @@
+import { logMysqlDriverError } from './mysql-driver-error.js';
+import { createNestErrorHandler } from './nest-error.js';
+/**
+ * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
+ * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ */
+export function reportClassifiedDbError(err, classified, reportError, requestId) {
+    logMysqlDriverError(err, classified.statusCode);
+    if (classified.statusCode === 500) {
+        reportError?.(err, { requestId });
+    }
+}
+/**
+ * QueryFailedExceptionFilter → Nest 既定 exception filter の合成 onError。
+ *
+ * @remarks
+ * classify が non-null のときは parity 用 body を返しつつログ（+ 500 は onUnhandledError）を残す。
+ * 非 DB エラーは {@link createNestErrorHandler} に委譲する。
+ *
+ * `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;
+    return (err, c) => {
+        const classified = classify(err);
+        if (classified) {
+            logMysqlDriverError(err, classified.statusCode);
+            if (classified.statusCode === 500) {
+                try {
+                    onUnhandledError?.(err, c);
+                }
+                catch {
+                    // Reporting must never change the error response.
+                }
+            }
+            return c.json({ statusCode: classified.statusCode, message: classified.message }, classified.statusCode);
+        }
+        return nestErrorHandler(err, c);
+    };
+}

package/dist/index.d.ts

@@ -26,6 +26,10 @@ 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 { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
+export type { MysqlDriverErrorLike } from './http/mysql-driver-error.js';
+export { createQueryFailedNestErrorHandler, reportClassifiedDbError } from './http/query-failed-error.js';
+export type { ClassifiedDbError, QueryFailedClassifier, QueryFailedNestErrorHandlerOptions, } from './http/query-failed-error.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export type { ExecutionContextLike } from './http/execution-context.js';
 export { KVCache } from './cache/kv-cache.js';

package/dist/index.js

@@ -21,6 +21,8 @@ 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 { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
+export { createQueryFailedNestErrorHandler, reportClassifiedDbError } from './http/query-failed-error.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';

package/package.json

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