@rdlabo/workers-hono-kit 0.3.7 → 0.4.2

package/src/http/nest-error.ts

@@ -1,207 +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 const NEST_REASON_PHRASES: Record<number, string> = {
-  400: 'Bad Request',
-  401: 'Unauthorized',
-  403: 'Forbidden',
-  404: 'Not Found',
-};
-
-/**
- * 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 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;
-}
-
-/**
- * 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: unknown): err is HttpErrorLike =>
-  err instanceof Error &&
-  typeof (err as { getResponse?: unknown }).getResponse === 'function' &&
-  typeof (err as { status?: unknown }).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<E extends Env = Env>(options: NestErrorHandlerOptions<E> = {}) {
-  const {
-    reasonPhrases = NEST_REASON_PHRASES,
-    bareStatuses = [401],
-    fieldOrder = 'statusCode-first',
-    isHttpError = isHTTPException,
-    onUnhandledError,
-    internalServerErrorBody = { statusCode: 500, message: 'Internal server error' },
-    fallbackReason,
-  } = options;
-
-  return (err: Error, c: Context<E>): Response => {
-    if (isHttpError(err)) {
-      // Escape hatch for a custom error body: render it verbatim.
-      if (err.body !== undefined) {
-        return c.json(err.body as object, 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.
-    }
-    console.error(err);
-    return c.json(internalServerErrorBody as object, 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: Context): Response {
-  return c.json(
-    { message: `Cannot ${c.req.method} ${new URL(c.req.url).pathname}`, error: 'Not Found', statusCode: 404 },
-    404,
-  );
-}

package/src/http/trailing-slash.ts

@@ -1,28 +0,0 @@
-/**
- * Trailing-slash normalization for NestJS(Express) → Hono parity.
- *
- * Express runs with strict routing off by default, so `/x` and `/x/` resolve to the same handler.
- * Hono distinguishes them, so a client that sends e.g. `GET /functions/timeline/` 404s against a
- * Hono worker that only registered `/functions/timeline`. Apply this at the Worker `fetch` entry to
- * strip a trailing slash before routing, preserving method / headers / body.
- *
- * We intentionally do NOT use `hono/trailing-slash`'s `trimTrailingSlash`, which responds with a 301
- * redirect and thus breaks non-GET methods (POST/PUT/DELETE) and clients that don't follow redirects.
- *
- * @example
- * export default {
- *   fetch: (request, env, ctx) => app.fetch(normalizeTrailingSlash(request), env, ctx),
- * };
- *
- * @param request - The incoming request.
- * @returns The same request when the path has no trailing slash (or is exactly `/`), otherwise a new
- *   Request with the trailing slash(es) removed.
- */
-export const normalizeTrailingSlash = (request: Request): Request => {
-  const url = new URL(request.url);
-  if (url.pathname.length > 1 && url.pathname.endsWith('/')) {
-    url.pathname = url.pathname.replace(/\/+$/, '');
-    return new Request(url, request);
-  }
-  return request;
-};

package/src/http/user-protocol.ts

@@ -1,36 +0,0 @@
-import type { Context } from 'hono';
-
-/**
- * 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;
-}
-
-/**
- * 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: Context): IUserProtocol => ({
-  ipAddress: c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? null,
-  userAgent: c.req.header('user-agent') ?? null,
-});

package/src/index.ts

@@ -1,77 +0,0 @@
-/**
- * `@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';
-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';
-export type { AuthMiddlewareOptions } from './middleware/auth.js';
-
-// http
-export { getUserProtocol } from './http/user-protocol.js';
-export type { IUserProtocol } from './http/user-protocol.js';
-export { getAppInfo } from './http/app-info.js';
-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 { normalizeTrailingSlash } from './http/trailing-slash.js';
-export type { ExecutionContextLike } from './http/execution-context.js';
-
-// cache
-export { KVCache } from './cache/kv-cache.js';
-export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
-
-// stripe
-export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
-export type { CreateStripeClientOptions } from './stripe/client.js';
-
-// db
-export { retryWhenDeadlock } from './db/retry.js';
-
-// queue
-export { sendInChunks } from './queue/send.js';
-export type { QueueLike, QueueSendMessage } from './queue/send.js';
-export { processBatch } from './queue/consumer.js';
-export type { QueueMessageLike, MessageBatchLike, ProcessBatchOptions, ProcessBatchResult } from './queue/consumer.js';
-
-// ai
-export { createAiGatewayProvider } from './ai/gateway.js';
-export type {
-  AiGatewayConfig,
-  AiGatewayProvider,
-  AiGatewayBinding,
-  AiGateway,
-  AiGatewayOptions,
-} from './ai/gateway.js';
-
-// aws
-export { getAuthenticationSecret } from './aws/secrets-manager.js';
-export type { AwsSecretsOptions } from './aws/secrets-manager.js';
-export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
-
-// firebase
-export type { DecodedIdToken, FirebaseVerifier } from './firebase/firebase-verifier.js';
-export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
-export { IdentityToolkit } from './firebase/identity-toolkit.js';
-export type { ServiceAccount } from './firebase/identity-toolkit.js';
-export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';

package/src/middleware/auth.ts

@@ -1,129 +0,0 @@
-import type { Context, Env, MiddlewareHandler } from 'hono';
-import { HTTPException } from 'hono/http-exception';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
-import { getAppInfo } from '../http/app-info.js';
-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> {
-  /** Header carrying the ID token. Defaults to `'x-amz-security-token'`. */
-  tokenHeader?: string;
-  /**
-   * 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>;
-  /**
-   * 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>;
-  /**
-   * 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;
-  /**
-   * 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;
-  /** Status used by the default `onFailure`. Defaults to `403`. */
-  failureStatus?: ContentfulStatusCode;
-  /** Message used by the default `onFailure`. Defaults to `'Forbidden resource'`. */
-  failureMessage?: string;
-}
-
-/**
- * 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<E extends Env = Env, Verified = unknown, Id = unknown>(
-  options: AuthMiddlewareOptions<E, Verified, Id>,
-): MiddlewareHandler<E> {
-  const {
-    tokenHeader = 'x-amz-security-token',
-    verify,
-    resolveUserId,
-    setContext,
-    onFailure,
-    failureStatus = 403,
-    failureMessage = 'Forbidden resource',
-  } = options;
-
-  return async (c, next) => {
-    try {
-      const token = c.req.header(tokenHeader) ?? '';
-      const verified = await verify(token, c);
-      const appInfo = getAppInfo(c);
-      const userId = resolveUserId ? await resolveUserId(verified, c, appInfo) : undefined;
-      setContext(c, { verified, appInfo, userId });
-    } catch (e) {
-      // 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);
-      }
-      throw new HTTPException(failureStatus, { message: failureMessage });
-    }
-    await next();
-  };
-}

package/src/middleware/finalize-response.ts

@@ -1,90 +0,0 @@
-import type { MiddlewareHandler } from 'hono';
-
-/**
- * Compute an Express `etag`-package compatible weak ETag for a response body.
- *
- * The format is `W/"<byteLength-in-hex>-<first 27 chars of base64(sha1(body))>"`, byte-for-byte
- * identical to the weak ETag produced by the Express `etag` package. This deliberately differs
- * from `hono/etag`'s own format so responses match an Express/Nest backend exactly.
- *
- * @param body - The raw response body bytes to hash.
- * @returns The weak ETag header value (e.g. `W/"1a-Qwerty..."`).
- * @internal
- */
-async function weakEtag(body: ArrayBuffer): Promise<string> {
-  const digest = await crypto.subtle.digest('SHA-1', body);
-  const bytes = new Uint8Array(digest);
-  let bin = '';
-  for (const b of bytes) {
-    bin += String.fromCharCode(b);
-  }
-  const b64 = btoa(bin).substring(0, 27);
-  return `W/"${body.byteLength.toString(16)}-${b64}"`;
-}
-
-/**
- * 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 function finalizeResponse(): MiddlewareHandler {
-  return async (c, next) => {
-    await next();
-
-    const status = c.res.status;
-    const contentType = c.res.headers.get('content-type') ?? '';
-
-    // Leave SSE / streaming responses untouched.
-    if (contentType.includes('text/event-stream')) {
-      return;
-    }
-
-    // Charset target: add the charset when a JSON response leaves it unspecified.
-    const needsCharset = contentType === 'application/json';
-    // ETag target: Express omits it on 204/304 and respects an existing ETag.
-    const needsEtag = status !== 204 && status !== 304 && !c.res.headers.has('etag') && !!c.res.body;
-
-    if (!needsCharset && !needsEtag) {
-      return;
-    }
-
-    const headers = new Headers(c.res.headers);
-    if (needsCharset) {
-      headers.set('content-type', 'application/json; charset=utf-8');
-    }
-
-    if (needsEtag) {
-      const buf = await c.res.clone().arrayBuffer();
-      headers.set('ETag', await weakEtag(buf));
-      c.res = new Response(buf, { status, statusText: c.res.statusText, headers });
-    } else {
-      // Swap only the headers without reading the body.
-      c.res = new Response(c.res.body, { status, statusText: c.res.statusText, headers });
-    }
-  };
-}