@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

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

@@ -1,72 +1,133 @@
 import type { Context, Env } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 /**
- * NestJS の既定例外フィルタが付ける reason phrase（フリート共通 = receptray/winecode/foodlabel の
- * REASON_PHRASE / DEFAULT_MESSAGES と同一）。3 repo がそれぞれ手書きしていたものを一本化する。
+ * 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>;
-/** 想定外エラーの通報先に渡す文脈（request id 相関など）。フリート共通の最小形。 */
+/**
+ * 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;
 }
 /**
- * 想定外エラーの通報関数（Sentry 等）の型。各 repo の container.reportError がこの形。
- * `createNestErrorHandler({ onUnhandledError })` に `(err, c) => reporter(err, { requestId: c.get('requestId') })`
- * の形で差し込む。Sentry 呼び出し自体は各 repo（@sentry/cloudflare は workers-hono-kit に持ち込まない）。
+ * 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;
-/** http エラーとみなされた値から status / message / body を読むための最小形。 */
+/**
+ * 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;
-    /** repo 固有 body の脱出口（winecode の HttpError.body 相当）。あればそのまま render する。 */
+    /**
+     * 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> {
-    /** reason phrase map。既定 `NEST_REASON_PHRASES`。 */
+    /** Status-to-reason-phrase map for the `error` field. Defaults to {@link NEST_REASON_PHRASES}. */
     reasonPhrases?: Record<number, string>;
     /**
-     * `error` フィールドを省いて `{ statusCode, message }` のみ返す status。既定 `[401]`
-     * （NestJS の generic `HttpException(msg, 401)` は `error` を持たない）。
+     * 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[];
     /**
-     * 非 bare body のフィールド順序。既定 `'statusCode-first'`（= NestJS canonical / receptray・winecode）。
-     * **foodlabel は `'message-first'`** を指定して `{ message, error, statusCode }` の byte-parity を保つ。
+     * 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';
     /**
-     * reasonPhrases に無い（かつ bare でない）status の `error` フォールバック。既定 `undefined`
-     * （= reason 無しなら `error` を省く）。**winecode は `'Error'`** を指定し、全 status で `error` を必ず出す
-     * （NestJS 既定例外フィルタの「error は常に存在」を忠実再現）。
+     * 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;
     /**
-     * http エラー判定。既定は hono の `HTTPException`。
-     * **winecode は独自 `HttpError` を使う**ため `(e) => e instanceof HttpError` を渡す。
+     * 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;
     /**
-     * http エラーでない（= 想定外）エラーを 500 で返す前に呼ぶフック（Sentry 通報など）。
-     * **receptray は `container.reportError?.(err, { requestId })`** を差し込む。例外は握り潰す。
+     * 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;
-    /** 想定外エラー時の 500 body。既定 `{ statusCode: 500, message: 'Internal server error' }`。 */
+    /**
+     * Response body for unexpected errors returned as 500. Defaults to
+     * `{ statusCode: 500, message: 'Internal server error' }`.
+     */
     internalServerErrorBody?: unknown;
 }
 /**
- * NestJS の例外フィルタ相当の Hono `onError` ハンドラを作る（フリート共通）。
- * - http エラー（既定 `HTTPException`）→ Nest 形 body にマップ。`body` を持つ場合はそれを verbatim で返す。
- * - bareStatuses（既定 401）は `error` フィールド無し。
- * - それ以外（想定外エラー）→ `onUnhandledError` 通報 + `console.error` + 500。
+ * 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.
  *
- * `app.onError(createNestErrorHandler(...))` の形で使う。各 repo の parity 差異（body 順序・
- * エラー型・通報フック）は options で吸収し、本体の分岐ロジックは共有する。
+ * 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;
 /**
- * Express/Nest 既定の未マッチルート 404 body を返す `notFound` ハンドラ。
- * `app.notFound(nestNotFoundHandler)` で使う（receptray/winecode は未実装の parity ギャップ）。
+ * 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,6 +1,9 @@
 /**
- * NestJS の既定例外フィルタが付ける reason phrase（フリート共通 = receptray/winecode/foodlabel の
- * REASON_PHRASE / DEFAULT_MESSAGES と同一）。3 repo がそれぞれ手書きしていたものを一本化する。
+ * 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',
@@ -9,33 +12,60 @@ export const NEST_REASON_PHRASES = {
     404: 'Not Found',
 };
 /**
- * hono の `HTTPException` を **構造的に**判定する（`instanceof` ではない）。workers-hono-kit は consumer に
- * symlink 同梱されるため、workers-hono-kit が解決する `hono` と consumer の `hono` が別インスタンスになり得る
- * （別コピーの HTTPException は `instanceof` で一致しない）。`getResponse()` と数値 `status` を持つかで
- * 判定すればモジュール境界をまたいでも、prod バンドルでも安定する。
+ * 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';
 /**
- * NestJS の例外フィルタ相当の Hono `onError` ハンドラを作る（フリート共通）。
- * - http エラー（既定 `HTTPException`）→ Nest 形 body にマップ。`body` を持つ場合はそれを verbatim で返す。
- * - bareStatuses（既定 401）は `error` フィールド無し。
- * - それ以外（想定外エラー）→ `onUnhandledError` 通報 + `console.error` + 500。
+ * 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.
  *
- * `app.onError(createNestErrorHandler(...))` の形で使う。各 repo の parity 差異（body 順序・
- * エラー型・通報フック）は options で吸収し、本体の分岐ロジックは共有する。
+ * 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)) {
-            // repo 固有 body の脱出口（winecode）。
+            // Escape hatch for a custom error body: render it verbatim.
             if (err.body !== undefined) {
                 return c.json(err.body, err.status);
             }
-            // reasonPhrases[status] は型上 string だが noUncheckedIndexedAccess 無効のため実際は未定義になり得る。
-            // 未登録 status の fallbackReason フォールバックは意図的。
+            // 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) {
@@ -50,15 +80,26 @@ export function createNestErrorHandler(options = {}) {
             onUnhandledError?.(err, c);
         }
         catch {
-            // 通報はエラーレスポンスの挙動を変えてはならない。
+            // Reporting must never change the behavior of the error response.
         }
         console.error(err);
         return c.json(internalServerErrorBody, 500);
     };
 }
 /**
- * Express/Nest 既定の未マッチルート 404 body を返す `notFound` ハンドラ。
- * `app.notFound(nestNotFoundHandler)` で使う（receptray/winecode は未実装の parity ギャップ）。
+ * 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);

package/dist/http/user-protocol.d.ts

@@ -1,11 +1,31 @@
 import type { Context } from 'hono';
-/** クライアントの IP / UA（NestJS の @UserProtocol デコレータ相当）。 */
+/**
+ * The client's network identity: IP address and user agent.
+ *
+ * @remarks
+ * Equivalent to the data a NestJS `@UserProtocol` decorator would expose, so a Hono app can persist the
+ * same client metadata. Both fields are nullable to map directly onto nullable database columns.
+ */
 export interface IUserProtocol {
+    /** Client IP address, or `null` when no source header is present. */
     ipAddress: string | null;
+    /** Client user-agent string, or `null` when the `User-Agent` header is absent. */
     userAgent: string | null;
 }
 /**
- * Hono Context からクライアント IP / UA を取得する。Cloudflare は実 IP を `CF-Connecting-IP` に入れる
- * （`X-Forwarded-For` はフォールバック）。未取得は null（DB の nullable カラムにそのまま入る）。
+ * Read the client's IP address and user agent from the Hono request context.
+ *
+ * @remarks
+ * On Cloudflare the real client IP is provided in `CF-Connecting-IP`, with `X-Forwarded-For` used as a
+ * fallback. Missing values resolve to `null` so they map cleanly onto nullable storage.
+ *
+ * @param c - The Hono request context to read headers from.
+ * @returns The client's IP address and user agent for the current request.
+ *
+ * @example
+ * ```ts
+ * const { ipAddress, userAgent } = getUserProtocol(c);
+ * await auditLog.insert({ ipAddress, userAgent });
+ * ```
  */
 export declare const getUserProtocol: (c: Context) => IUserProtocol;

package/dist/http/user-protocol.js

@@ -1,6 +1,18 @@
 /**
- * Hono Context からクライアント IP / UA を取得する。Cloudflare は実 IP を `CF-Connecting-IP` に入れる
- * （`X-Forwarded-For` はフォールバック）。未取得は null（DB の nullable カラムにそのまま入る）。
+ * Read the client's IP address and user agent from the Hono request context.
+ *
+ * @remarks
+ * On Cloudflare the real client IP is provided in `CF-Connecting-IP`, with `X-Forwarded-For` used as a
+ * fallback. Missing values resolve to `null` so they map cleanly onto nullable storage.
+ *
+ * @param c - The Hono request context to read headers from.
+ * @returns The client's IP address and user agent for the current request.
+ *
+ * @example
+ * ```ts
+ * const { ipAddress, userAgent } = getUserProtocol(c);
+ * await auditLog.insert({ ipAddress, userAgent });
+ * ```
  */
 export const getUserProtocol = (c) => ({
     ipAddress: c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? null,

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * `@rdlabo/workers-hono-kit` — infrastructure-layer helpers for Hono on Cloudflare Workers.
+ *
+ * This package collects reusable, configuration-injected building blocks (HTTP middleware,
+ * caching, Stripe, Drizzle helpers, AI Gateway, AWS/Firebase integrations) that can be shared
+ * across services. Domain logic, database schemas, and application-specific behavior are
+ * intentionally left to the consuming application; only generic infrastructure that can be made
+ * reusable through dependency/configuration injection lives here.
+ *
+ * @packageDocumentation
+ */
 export { finalizeResponse } from './middleware/finalize-response.js';
 export { validate, createSentryValidate } from './middleware/validation.js';
 export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, SentryScopeLike, } from './middleware/validation.js';

package/dist/index.js

@@ -1,6 +1,14 @@
-// @rdlabo/workers-hono-kit — フリート共通のインフラ層ヘルパ（receptray / winecode / foodlabel）。
-// ドメイン・DB・各 repo 固有の parity 差異（auth エラー status/body、secretId、Secret スキーマ）は
-// 各 repo 側に残し、ここには「設定注入で汎用化できるインフラ」だけを置く。
+/**
+ * `@rdlabo/workers-hono-kit` — infrastructure-layer helpers for Hono on Cloudflare Workers.
+ *
+ * This package collects reusable, configuration-injected building blocks (HTTP middleware,
+ * caching, Stripe, Drizzle helpers, AI Gateway, AWS/Firebase integrations) that can be shared
+ * across services. Domain logic, database schemas, and application-specific behavior are
+ * intentionally left to the consuming application; only generic infrastructure that can be made
+ * reusable through dependency/configuration injection lives here.
+ *
+ * @packageDocumentation
+ */
 // middleware
 export { finalizeResponse } from './middleware/finalize-response.js';
 export { validate, createSentryValidate } from './middleware/validation.js';

package/dist/middleware/auth.d.ts

@@ -1,36 +1,97 @@
 import type { Context, Env, MiddlewareHandler } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import type { AppInfo } from '../http/app-info.js';
+/**
+ * Configuration for {@link createAuthMiddleware}.
+ *
+ * @typeParam E - The Hono `Env` (bindings/variables) of the application.
+ * @typeParam Verified - The value produced by {@link AuthMiddlewareOptions.verify} (e.g. a decoded token or user record).
+ * @typeParam Id - The resolved user identifier type.
+ */
 export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
-    /** ID トークンを載せるヘッダ。既定 `'x-amz-security-token'`（フリート共通）。 */
+    /** Header carrying the ID token. Defaults to `'x-amz-security-token'`. */
     tokenHeader?: string;
-    /** 生トークンを検証して record/decoded を返す。無効なら throw / reject すること。 */
+    /**
+     * Verify the raw token and return the decoded value or user record.
+     *
+     * @param token - The raw token read from {@link AuthMiddlewareOptions.tokenHeader} (empty string if absent).
+     * @param c - The current Hono context.
+     * @returns The verified value passed to {@link AuthMiddlewareOptions.resolveUserId}/{@link AuthMiddlewareOptions.setContext}.
+     * @throws If the token is invalid; rejecting/throwing triggers the failure path.
+     */
     verify: (token: string, c: Context<E>) => Promise<Verified>;
     /**
-     * DB userId を解決（必要なら新規作成）する。**省略すると token-only**（検証のみ・login 用）になる。
-     * create-on-miss（`getUserIdFromFirebase(...).catch(() => createUser(...))`）は repo 側でここに合成する。
+     * Resolve the database user id (creating the user if necessary).
+     *
+     * @remarks
+     * Omit this to run in **token-only** mode (verification only, e.g. for login). Create-on-miss
+     * behavior (such as `getUserId(...).catch(() => createUser(...))`) should be composed here by the
+     * caller.
+     *
+     * @param verified - The value returned by {@link AuthMiddlewareOptions.verify}.
+     * @param c - The current Hono context.
+     * @param appInfo - The resolved application info for the request.
+     * @returns The resolved user id.
      */
     resolveUserId?: (verified: Verified, c: Context<E>, appInfo: AppInfo) => Promise<Id>;
-    /** 検証結果を c.var に載せる。repo 固有の var 名（`decodedToken` / `userRecord` / `userProtocol` 等）を注入する。 */
+    /**
+     * Store the verification result on the context variables.
+     *
+     * @remarks
+     * Inject the application-specific variable names here (e.g. `decodedToken`, `userRecord`, `userProtocol`).
+     *
+     * @param c - The current Hono context.
+     * @param data - The verified value, resolved app info, and (when available) the user id.
+     */
     setContext: (c: Context<E>, data: {
         verified: Verified;
         appInfo: AppInfo;
         userId?: Id;
     }) => void;
     /**
-     * 失敗時の挙動。既定は `throw new HTTPException(failureStatus, { message: failureMessage })`
-     * （foodlabel/receptray と同形）。**winecode は `c.json(BODY, n)` を返す**ため上書きする。
+     * Override the failure behavior.
+     *
+     * @remarks
+     * Defaults to `throw new HTTPException(failureStatus, { message: failureMessage })`. Provide this to
+     * return a custom `Response` instead (e.g. `c.json(body, status)`).
+     *
+     * @param err - The error thrown during verification/resolution.
+     * @param c - The current Hono context.
+     * @returns The failure response to send.
      */
     onFailure?: (err: unknown, c: Context<E>) => Response;
-    /** 既定 onFailure の status。既定 `403`（token-only の 401 等は repo が上書き）。 */
+    /** Status used by the default `onFailure`. Defaults to `403`. */
     failureStatus?: ContentfulStatusCode;
-    /** 既定 onFailure の message。既定 `'Forbidden resource'`。 */
+    /** Message used by the default `onFailure`. Defaults to `'Forbidden resource'`. */
     failureMessage?: string;
 }
 /**
- * NestJS の AuthGuard / TokenGuard 相当の認証 middleware を作る（フリート共通）。
- * スケルトン（ヘッダ読取 → verify → getAppInfo → resolveUserId → setContext、失敗で console.error +
- * onFailure）を共有し、repo 固有部分（verify / userId 解決 / var 名 / 失敗レスポンス）だけ注入させる。
- * `resolveUserId` を省けば token-only middleware になる。
+ * Create an authentication middleware equivalent to a NestJS `AuthGuard` / `TokenGuard`.
+ *
+ * The middleware runs a fixed skeleton — read the token header, `verify`, `getAppInfo`,
+ * `resolveUserId`, `setContext`, and on error `console.error` then `onFailure` — while the
+ * application injects the variable parts (token verification, user-id resolution, context variable
+ * names, and the failure response). Omitting {@link AuthMiddlewareOptions.resolveUserId} yields a
+ * token-only middleware.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @typeParam Verified - The value produced by `verify`.
+ * @typeParam Id - The resolved user identifier type.
+ * @param options - The verification, resolution, and failure hooks; see {@link AuthMiddlewareOptions}.
+ * @returns A {@link MiddlewareHandler} that authenticates the request and populates the context.
+ * @throws HTTPException From the default failure handler when `onFailure` is not supplied.
+ *
+ * @example
+ * ```ts
+ * const auth = createAuthMiddleware({
+ *   verify: (token, c) => verifier.verifyIdToken(token),
+ *   resolveUserId: (decoded) => findUserId(decoded.uid),
+ *   setContext: (c, { verified, userId }) => {
+ *     c.set('decodedToken', verified);
+ *     c.set('userId', userId);
+ *   },
+ * });
+ * app.use('/api/*', auth);
+ * ```
  */
 export declare function createAuthMiddleware<E extends Env = Env, Verified = unknown, Id = unknown>(options: AuthMiddlewareOptions<E, Verified, Id>): MiddlewareHandler<E>;

package/dist/middleware/auth.js

@@ -1,10 +1,33 @@
 import { HTTPException } from 'hono/http-exception';
 import { getAppInfo } from '../http/app-info.js';
 /**
- * NestJS の AuthGuard / TokenGuard 相当の認証 middleware を作る（フリート共通）。
- * スケルトン（ヘッダ読取 → verify → getAppInfo → resolveUserId → setContext、失敗で console.error +
- * onFailure）を共有し、repo 固有部分（verify / userId 解決 / var 名 / 失敗レスポンス）だけ注入させる。
- * `resolveUserId` を省けば token-only middleware になる。
+ * Create an authentication middleware equivalent to a NestJS `AuthGuard` / `TokenGuard`.
+ *
+ * The middleware runs a fixed skeleton — read the token header, `verify`, `getAppInfo`,
+ * `resolveUserId`, `setContext`, and on error `console.error` then `onFailure` — while the
+ * application injects the variable parts (token verification, user-id resolution, context variable
+ * names, and the failure response). Omitting {@link AuthMiddlewareOptions.resolveUserId} yields a
+ * token-only middleware.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @typeParam Verified - The value produced by `verify`.
+ * @typeParam Id - The resolved user identifier type.
+ * @param options - The verification, resolution, and failure hooks; see {@link AuthMiddlewareOptions}.
+ * @returns A {@link MiddlewareHandler} that authenticates the request and populates the context.
+ * @throws HTTPException From the default failure handler when `onFailure` is not supplied.
+ *
+ * @example
+ * ```ts
+ * const auth = createAuthMiddleware({
+ *   verify: (token, c) => verifier.verifyIdToken(token),
+ *   resolveUserId: (decoded) => findUserId(decoded.uid),
+ *   setContext: (c, { verified, userId }) => {
+ *     c.set('decodedToken', verified);
+ *     c.set('userId', userId);
+ *   },
+ * });
+ * app.use('/api/*', auth);
+ * ```
  */
 export function createAuthMiddleware(options) {
     const { tokenHeader = 'x-amz-security-token', verify, resolveUserId, setContext, onFailure, failureStatus = 403, failureMessage = 'Forbidden resource', } = options;
@@ -17,8 +40,9 @@ export function createAuthMiddleware(options) {
             setContext(c, { verified, appInfo, userId });
         }
         catch (e) {
-            // Nest guard が false → ForbiddenException('Forbidden resource')。原因をログし、既定では throw して
-            // app.onError に Nest 形 body を描かせる（repo は onFailure で return 形に上書き可能）。
+            // Equivalent to a guard returning false → ForbiddenException('Forbidden resource'). Log the
+            // cause and, by default, throw so the app's onError renders the error body (callers can
+            // override with onFailure to return a custom response instead).
             console.error(e);
             if (onFailure) {
                 return onFailure(e, c);

package/dist/middleware/finalize-response.d.ts

@@ -1,2 +1,32 @@
 import type { MiddlewareHandler } from 'hono';
+/**
+ * Create a Hono middleware that finalizes responses for byte-parity with an Express/Nest backend.
+ *
+ * After the downstream handler runs, it performs two adjustments:
+ *
+ * 1. **JSON charset**: Express's `res.json` emits `application/json; charset=utf-8`, whereas Hono's
+ *    `c.json` emits a bare `application/json`. A bare `application/json` content type is rewritten
+ *    to include `; charset=utf-8`.
+ * 2. **Weak ETag**: An Express `etag`-package compatible weak ETag is added, matching the format an
+ *    Express/Nest backend applies to responses by default. See {@link weakEtag} for the exact format.
+ *
+ * Server-Sent Events (`text/event-stream`) are skipped entirely because the stream cannot be
+ * buffered. ETag generation is also skipped for `204`/`304` responses, responses that already carry
+ * an `etag` header, and responses without a body.
+ *
+ * @returns A {@link MiddlewareHandler} that rewrites the response headers (and body, when an ETag
+ * must be computed) in place.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { finalizeResponse } from '@rdlabo/workers-hono-kit';
+ *
+ * const app = new Hono();
+ * app.use('*', finalizeResponse());
+ * app.get('/users', (c) => c.json({ ok: true }));
+ * // → Content-Type: application/json; charset=utf-8
+ * // → ETag: W/"b-..." (b = 0xb = 11 bytes, the length of `{"ok":true}`)
+ * ```
+ */
 export declare function finalizeResponse(): MiddlewareHandler;