@rdlabo/workers-hono-kit 0.1.0 → 0.2.1

package/src/middleware/validation.ts

@@ -2,31 +2,45 @@ import { zValidator } from '@hono/zod-validator';
 import type { Context } from 'hono';
 import type { ZodType } from 'zod';
 
-/** zod v3(ZodError) / v4(core $ZodError) どちらの error でも受けられる最小形 */
+/**
+ * Minimal structural shape that accepts either a zod v3 `ZodError` or a zod v4 core `$ZodError`.
+ *
+ * @remarks
+ * Declaring only the `issues` array (with `path` and `message`) keeps the kit independent of a
+ * specific zod major version while still exposing enough to format human-readable messages.
+ */
 export interface ZodErrorLike {
+  /** The validation issues reported by zod, each with a property path and a message. */
   issues: readonly { path: PropertyKey[]; message: string }[];
 }
 
+/** Request part that a validator inspects, mirroring the targets supported by `@hono/zod-validator`. */
 export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'cookie' | 'form';
 
+/** Options controlling the optional side effects of {@link validate}. */
 export interface ValidateOptions {
   /**
-   * 検証失敗時のフック（Sentry 通報など）。**検証の挙動は変えない** — レスポンスは常に
-   * NestJS ValidationPipe 同形の 400 を返す。例外を投げても握り潰す。
-   * 既定は no-op（receptray 互換 = 4xx を通報しない）。foodlabel は Sentry 実通報を差し込む。
+   * Hook invoked when validation fails (e.g. to report to Sentry).
+   *
+   * @remarks
+   * This never changes validation behavior — the response is always a NestJS `ValidationPipe`-shaped
+   * 400. Exceptions thrown by the hook are swallowed. The default is a no-op (4xx errors are not
+   * reported); pass a hook to forward failures to an error tracker.
+   *
+   * @param error - The zod error describing the failed validation.
+   * @param c - The Hono context for the failing request.
    */
   onValidationError?: (error: ZodErrorLike, c: Context) => void;
 }
 
 /**
- * Zod 検証ミドルウェア（フリート共通 = receptray/winecode hono と同一仕様）。
- * 失敗時は NestJS の ValidationPipe と同形の body を返す:
- *   { statusCode: 400, message: string[], error: 'Bad Request' }
+ * Convert a {@link ZodErrorLike} into NestJS `ValidationPipe`-style message strings.
  *
- * NOTE(parity): message の文字列内容は class-validator と Zod で異なる。各 repo の固定 app の
- * 正常系では DTO 検証 400 は発生しない前提（ビジネス 400 は各エンドポイントで HttpError 忠実再現）。
+ * Each issue becomes `"<dotted.path>: <message>"`, or just `"<message>"` when the path is empty.
+ *
+ * @param error - The zod error to flatten.
+ * @returns One message string per issue.
  */
-
 function zodToMessages(error: ZodErrorLike): string[] {
   return error.issues.map((issue) => {
     const path = issue.path.map(String).join('.');
@@ -34,6 +48,35 @@ function zodToMessages(error: ZodErrorLike): string[] {
   });
 }
 
+/**
+ * Create a zod validation middleware that returns a NestJS `ValidationPipe`-shaped 400 on failure.
+ *
+ * On success the parsed value is made available through `@hono/zod-validator` as usual. On failure
+ * the response body is `{ statusCode: 400, message: string[], error: 'Bad Request' }`, the failing
+ * field paths are logged via `console.warn` (so 400s are visible in `wrangler dev`/Workers logs),
+ * and {@link ValidateOptions.onValidationError} is invoked if provided.
+ *
+ * @remarks
+ * The exact message strings differ from class-validator because they are produced by zod, but the
+ * envelope shape matches NestJS so clients can parse failures identically.
+ *
+ * @typeParam T - The type produced by the zod schema.
+ * @param target - The request part to validate.
+ * @param schema - The zod schema to validate the target against.
+ * @param options - Optional hooks; see {@link ValidateOptions}.
+ * @returns A Hono middleware that validates `target` and short-circuits with a 400 on failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { validate } from '@rdlabo/workers-hono-kit';
+ *
+ * app.post('/users', validate('json', z.object({ name: z.string() })), (c) => {
+ *   const { name } = c.req.valid('json');
+ *   return c.json({ name });
+ * });
+ * ```
+ */
 export function validate<T>(target: ValidationTarget, schema: ZodType<T>, options?: ValidateOptions) {
   return zValidator(target, schema, (result, c) => {
     if (!result.success) {
@@ -55,21 +98,52 @@ export function validate<T>(target: ValidationTarget, schema: ZodType<T>, option
   });
 }
 
-/** Sentry の最小形（`@sentry/cloudflare` 等への直接依存を避けるための構造型）。 */
+/**
+ * Minimal structural shape of a Sentry scope, covering only the methods this kit calls.
+ *
+ * @remarks
+ * Declaring the shape structurally avoids a direct dependency on `@sentry/cloudflare`; any object
+ * exposing these methods (such as the real Sentry scope) is accepted.
+ */
 export interface SentryScopeLike {
+  /** Attach a string tag to the current scope. */
   setTag(key: string, value: string): void;
+  /** Attach (or clear, with `null`) a structured context entry on the current scope. */
   setContext(key: string, context: Record<string, unknown> | null): void;
 }
+
+/**
+ * Minimal structural shape of the Sentry client, covering only the methods this kit calls.
+ *
+ * @remarks
+ * Like {@link SentryScopeLike}, this avoids a hard dependency on `@sentry/cloudflare`.
+ */
 export interface SentryLike {
+  /** Run a callback with an isolated scope, restoring the previous scope afterward. */
   withScope(callback: (scope: SentryScopeLike) => void): void;
+  /** Report an exception to Sentry. */
   captureException(error: unknown): void;
 }
 
 /**
- * DTO 検証 400 を Sentry に通報する `validate` を返すファクトリ（foodlabel/tipsys/winecode で重複していた
- * reportValidationToSentry を集約）。kit は `@sentry/cloudflare` に依存せず、Sentry モジュールを注入する。
- * 通報は `tag error.type=dto_validation` ＋ `context validation={errorCount, errors}`（各 /api の
- * sentry-validation.pipe.ts 準拠）。検証の挙動・レスポンスは `validate` と同一（通報は副作用のみ）。
+ * Create a {@link validate}-like factory that additionally reports DTO validation 400s to Sentry.
+ *
+ * The returned function has the same signature and behavior as {@link validate}; reporting is a pure
+ * side effect that does not alter validation behavior or the response. Each report is tagged with
+ * `error.type=dto_validation` and carries a `validation` context of `{ errorCount, errors }`.
+ *
+ * @param sentry - A Sentry-like client used to capture validation failures; see {@link SentryLike}.
+ * @returns A function `(target, schema) => MiddlewareHandler` mirroring {@link validate}.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from '@sentry/cloudflare';
+ * import { z } from 'zod';
+ * import { createSentryValidate } from '@rdlabo/workers-hono-kit';
+ *
+ * const validate = createSentryValidate(Sentry);
+ * app.post('/users', validate('json', z.object({ name: z.string() })), handler);
+ * ```
  */
 export function createSentryValidate(sentry: SentryLike) {
   const onValidationError = (error: ZodErrorLike): void => {

package/src/middleware/zod-coerce.ts

@@ -1,17 +1,22 @@
 import { z } from 'zod';
 
 /**
- * `/api` の class-transformer @Transform（number-transform.util.ts）を Zod preprocess で忠実再現する。
- * path/query は常に文字列で来るため数値強制が必要。空白のみ文字列は NaN にして後段の数値スキーマで弾く
- * （class-validator の @IsInt/@IsNumber が NaN を拒否する挙動と一致。zod v4 は z.number() が NaN を既定拒否）。
+ * Zod preprocessors that coerce string path/query parameters into numbers.
+ *
+ * @remarks
+ * These mirror a class-transformer `@Transform(() => Number)` coercion: path and query parameters
+ * always arrive as strings, so they must be forced to numbers before number validation. Whitespace-only
+ * strings are mapped to `NaN` so the downstream number schema rejects them (matching class-validator's
+ * `@IsInt`/`@IsNumber`, which reject `NaN`; zod v4's `z.number()` also rejects `NaN` by default).
  */
 
+/** Return `true` when `value` is a string that is empty or contains only whitespace. */
 const isBlankString = (value: unknown): value is string => typeof value === 'string' && value.trim() === '';
 
-// toNumber: 空白文字列 → NaN、それ以外 → Number(value)
+// toNumber: blank string → NaN, otherwise → Number(value).
 const rawToNumber = (value: unknown): unknown => (isBlankString(value) ? Number(undefined) : Number(value));
 
-// toNumberWithDefault: undefined/'' → default、空白 → NaN、else Number
+// toNumberWithDefault: undefined/'' → default, blank → NaN, else Number.
 const rawToNumberWithDefault =
   (defaultValue: number) =>
   (value: unknown): unknown => {
@@ -24,7 +29,7 @@ const rawToNumberWithDefault =
     return Number(value);
   };
 
-// toOptionalNumber: undefined/null/'' → undefined、空白 → NaN、else Number
+// toOptionalNumber: undefined/null/'' → undefined, blank → NaN, else Number.
 const rawToOptionalNumber = (value: unknown): unknown => {
   if (value === undefined || value === null || value === '') {
     return undefined;
@@ -35,7 +40,7 @@ const rawToOptionalNumber = (value: unknown): unknown => {
   return Number(value);
 };
 
-// toNullableNumber: null/undefined → passthrough、'' → undefined、空白 → NaN、else Number
+// toNullableNumber: null/undefined → passthrough, '' → undefined, blank → NaN, else Number.
 const rawToNullableNumber = (value: unknown): unknown => {
   if (value === null || value === undefined) {
     return value;
@@ -50,16 +55,70 @@ const rawToNullableNumber = (value: unknown): unknown => {
 };
 
 /**
- * 数値強制スキーマ。`inner` に `z.number().int()` 等を渡して制約を足せる（既定は z.number()）。
- * 例: zNum(z.number().int()) で整数必須。
+ * Build a required number schema that coerces string input to a number.
+ *
+ * @param inner - The inner number schema to apply after coercion; pass e.g. `z.number().int()` to add
+ * constraints. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Require an integer path param:
+ * const schema = z.object({ id: zNum(z.number().int()) });
+ * // '42' → 42, '' / '  ' → NaN (rejected)
+ * ```
  */
 export const zNum = (inner: z.ZodNumber = z.number()): z.ZodType<number> => z.preprocess(rawToNumber, inner);
 
+/**
+ * Build a number schema that coerces string input and substitutes a default for missing values.
+ *
+ * `undefined` or an empty string yields `defaultValue`; a whitespace-only string yields `NaN`
+ * (rejected by the inner schema); anything else is passed through `Number`.
+ *
+ * @param defaultValue - The value used when the input is `undefined` or an empty string.
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Default page to 1 when the query param is absent:
+ * const schema = z.object({ page: zNumWithDefault(1) });
+ * ```
+ */
 export const zNumWithDefault = (defaultValue: number, inner: z.ZodNumber = z.number()): z.ZodType<number> =>
   z.preprocess(rawToNumberWithDefault(defaultValue), inner);
 
+/**
+ * Build an optional number schema that coerces string input.
+ *
+ * `undefined`, `null`, or an empty string yields `undefined`; a whitespace-only string yields `NaN`
+ * (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ limit: zNumOptional(z.number().int()) });
+ * ```
+ */
 export const zNumOptional = (inner: z.ZodNumber = z.number()): z.ZodType<number | undefined> =>
   z.preprocess(rawToOptionalNumber, inner.optional());
 
+/**
+ * Build a nullable, optional number schema that coerces string input.
+ *
+ * `null`/`undefined` pass through unchanged; an empty string yields `undefined`; a whitespace-only
+ * string yields `NaN` (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | null | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ parentId: zNumNullable(z.number().int()) });
+ * ```
+ */
 export const zNumNullable = (inner: z.ZodNumber = z.number()): z.ZodType<number | null | undefined> =>
   z.preprocess(rawToNullableNumber, inner.nullish());

package/src/stripe/client.ts

@@ -1,17 +1,33 @@
 import Stripe from 'stripe';
 
 /**
- * Stripe クライアント生成（フリート共通 = receptray/tipsys hono）。Cloudflare Workers には Node の
- * http スタックが無いため、Stripe SDK の fetch ベース HttpClient を使う。
- *
- * `apiVersion` は **任意**: 各 repo の `/api`（NestJS）と挙動を一致させるため、固定したい repo は
- * 渡し（例 tipsys は `'2024-04-10'`）、SDK 既定で良い repo は省く（例 receptray）。
+ * Options for {@link createStripeClient}.
  */
 export interface CreateStripeClientOptions {
-  /** 固定する Stripe API バージョン。省略すると SDK 既定。 */
+  /**
+   * Stripe API version to pin the client to. When omitted, the SDK's built-in default is used.
+   * Pin it when you need stable, reproducible API behavior independent of SDK upgrades.
+   */
   apiVersion?: string;
 }
 
+/**
+ * Create a Stripe client configured to run on Cloudflare Workers.
+ *
+ * @remarks
+ * Workers has no Node.js `http` stack, so the client is built with `Stripe.createFetchHttpClient()`
+ * (a `fetch`-based HTTP client) instead of the SDK's default Node transport.
+ *
+ * @param secret - Stripe secret API key.
+ * @param options - Optional client configuration; see {@link CreateStripeClientOptions}.
+ * @returns A configured {@link Stripe} instance.
+ * @throws Error when `secret` is empty.
+ * @example
+ * ```ts
+ * const stripe = createStripeClient(env.STRIPE_SECRET, { apiVersion: '2024-04-10' });
+ * const customer = await stripe.customers.retrieve(customerId);
+ * ```
+ */
 export function createStripeClient(secret: string, options: CreateStripeClientOptions = {}): Stripe {
   if (!secret) {
     throw new Error('Stripe secret is not set');
@@ -24,9 +40,30 @@ export function createStripeClient(secret: string, options: CreateStripeClientOp
 }
 
 /**
- * Webhook 署名の検証。Workers では同期版 `constructEvent` が使えない（SubtleCrypto が非同期）ため
- * `constructEventAsync` + `SubtleCryptoProvider` を使う。`secret` は署名検証には無関係だが、検証用の
- * クライアント生成に必要（API コールはしない）。
+ * Verify a Stripe webhook signature and return the parsed event.
+ *
+ * @remarks
+ * Uses `constructEventAsync` together with `Stripe.createSubtleCryptoProvider()` because the Workers
+ * crypto API (SubtleCrypto) is asynchronous and the synchronous `constructEvent` is unavailable.
+ * The `secret` is not used by signature verification itself, but a client must be constructed to
+ * perform the check; no Stripe API call is made.
+ *
+ * @param secret - Stripe secret API key, used only to construct the verifying client.
+ * @param webhookSecret - Endpoint signing secret used to validate the signature.
+ * @param payload - Raw request body exactly as received (string or `ArrayBuffer`).
+ * @param signature - Value of the `Stripe-Signature` request header.
+ * @returns The verified {@link Stripe.Event}.
+ * @throws Error when `webhookSecret` is empty, or when `secret` is empty (the verifying client cannot be constructed).
+ * @throws Stripe.errors.StripeSignatureVerificationError when the signature does not match.
+ * @example
+ * ```ts
+ * const event = await verifyStripeWebhook(
+ *   env.STRIPE_SECRET,
+ *   env.STRIPE_WEBHOOK_SECRET,
+ *   await request.text(),
+ *   request.headers.get('stripe-signature')!,
+ * );
+ * ```
  */
 export function verifyStripeWebhook(
   secret: string,

package/src/testing/auth.ts

@@ -1,13 +1,29 @@
 import type { Pool } from 'mysql2/promise';
-import type { DecodedIdToken } from '../firebase/firebase-verifier';
-import type { FakeFirebaseVerifier } from './fakes';
+import type { DecodedIdToken } from '../firebase/firebase-verifier.js';
+import type { FakeFirebaseVerifier } from './fakes.js';
 
 /**
- * app interceptor 互換の認証ヘッダ（`x-amz-security-token` + `x-amz-meta-*`）を組む。
- * fleet 全 hono repo の route spec で同形に重複していたものを集約。
+ * Build authentication headers compatible with the client interceptor convention
+ * (`x-amz-security-token` + `x-amz-meta-*`).
  *
- * - `version` は `app_version`(varchar(10)) に入るため 10 文字以内。
- * - `contentType: null` を渡すと content-type を付けない（GET 等）。
+ * Consolidates the identically-shaped header boilerplate that route specs tend to duplicate.
+ *
+ * @remarks
+ * `version` is persisted into an `app_version` column (`varchar(10)`), so keep it to 10 characters
+ * or fewer. Passing `contentType: null` omits the `content-type` header entirely (e.g. for GET requests).
+ *
+ * @param token - Security token placed in the `x-amz-security-token` header.
+ * @param opts - Optional overrides.
+ * @param opts.version - App version for `x-amz-meta-version` (defaults to `'1.0.0'`).
+ * @param opts.uuid - Device/client UUID for `x-amz-meta-uuid` (defaults to `'test-uuid'`).
+ * @param opts.contentType - Content type; defaults to `'application/json'`. Pass `null` to omit the header.
+ * @returns A plain header record suitable for `fetch`/`app.request` calls.
+ * @example
+ * ```ts
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * // GET without a content-type header:
+ * await app.request('/items', { headers: authHeaders(token, { contentType: null }) });
+ * ```
  */
 export function authHeaders(
   token: string,
@@ -25,8 +41,22 @@ export function authHeaders(
 }
 
 /**
- * fake firebase にトークンを登録するだけの薄いヘルパ（DB を触らない）。戻り値はトークン。
- * `users` テーブル形が repo 固有（例: airlec は email 主）で provisionUser が合わない場合に使う。
+ * Register a token on a fake Firebase verifier without touching the database.
+ *
+ * Use this when {@link provisionUser} does not fit because the project's `users` table has a
+ * non-conventional shape (for example, keyed by email rather than `firebase_uid`); pair it with a
+ * project-specific provisioning step.
+ *
+ * @param firebase - In-memory verifier to register the token on.
+ * @param uid - Firebase UID associated with the token.
+ * @param record - Additional decoded-token fields to merge in (e.g. `email`).
+ * @param token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @returns The registered token string.
+ * @example
+ * ```ts
+ * const token = registerFirebaseToken(firebase, 'uid-1', { email: 'a@example.com' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export function registerFirebaseToken(
   firebase: FakeFirebaseVerifier,
@@ -39,10 +69,28 @@ export function registerFirebaseToken(
 }
 
 /**
- * fake firebase にトークンを登録し、`users(firebase_uid)` 行を用意して userId を返す。
- * `users(id, firebase_uid, agree)` の fleet 共通形を前提（foodlabel/receptray など）。同 uid の
- * 既存行があれば再利用する（冪等）。users テーブル形が異なる repo は registerFirebaseToken + 独自
- * provision を使う。
+ * Register a token on a fake Firebase verifier and ensure a matching `users` row exists, returning
+ * its id.
+ *
+ * @remarks
+ * Assumes a conventional `users(id, firebase_uid, agree)` table. The operation is idempotent: if a
+ * row with the same `firebase_uid` already exists it is reused rather than re-inserted. For projects
+ * whose `users` table has a different shape, use {@link registerFirebaseToken} plus project-specific
+ * provisioning instead.
+ *
+ * @param pool - mysql2 pool connected to the test database.
+ * @param firebase - In-memory verifier to register the token on.
+ * @param opts - Provisioning options.
+ * @param opts.uid - Firebase UID for the user.
+ * @param opts.token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @param opts.agree - Value for the `agree` column on insert (defaults to `1`).
+ * @param opts.email - Optional email merged into the decoded token record.
+ * @returns The resolved `userId`, along with the `uid` and registered `token`.
+ * @example
+ * ```ts
+ * const { userId, token } = await provisionUser(pool, firebase, { uid: 'uid-1' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export async function provisionUser(
   pool: Pool,

package/src/testing/configurable-fake.ts

@@ -1,15 +1,26 @@
 /**
- * 部分実装から test double を作る。設定済みメソッドはそのまま、未設定メソッドを呼ぶと
- * `${name}.${method} not configured` で明示的に失敗する。
+ * Build a test double from a partial implementation: configured members are returned as-is, while
+ * calling any unconfigured member fails explicitly with `` `${name}.${method} not configured` ``.
  *
- * 各 repo の Fake*Gateway に散っていた「`Partial<impl>` を受け取り、未設定なら throw する手書き
- * クラス」の定型を一本化する。interface がドメインごとに異なる gateway（Stripe 等）でも、これで
- * 1 行で必要メソッドだけ差した fake を作れる:
+ * @remarks
+ * Replaces the hand-written "accept a `Partial<impl>` and throw on anything unset" fake classes that
+ * tend to proliferate per gateway. Because gateway interfaces differ by domain (Stripe, etc.), this
+ * lets you stub only the members a given test exercises in a single line.
  *
- *   const stripe = configurableFake<StripeGateway>(
- *     { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
- *     'FakeStripeGateway',
- *   );
+ * @typeParam T - The interface being faked.
+ * @param impl - Partial implementation; only the members the test needs.
+ * @param name - Label used in the "not configured" error message (defaults to `'fake'`).
+ * @returns A proxy typed as `T` that delegates to `impl` and throws on unconfigured members.
+ * @throws Error `` `${name}.${method} not configured` `` when an unconfigured string-keyed member is called.
+ * @example
+ * ```ts
+ * const stripe = configurableFake<StripeGateway>(
+ *   { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
+ *   'FakeStripeGateway',
+ * );
+ * await stripe.listPaymentIntents(); // ok
+ * await stripe.cancelPaymentIntent('pi_1'); // throws: FakeStripeGateway.cancelPaymentIntent not configured
+ * ```
  */
 export function configurableFake<T extends object>(impl: Partial<T>, name = 'fake'): T {
   return new Proxy(impl, {
@@ -17,8 +28,9 @@ export function configurableFake<T extends object>(impl: Partial<T>, name = 'fak
       if (prop in target) {
         return (target as Record<string | symbol, unknown>)[prop];
       }
-      // Promise インターロップ用プロパティには「未設定メソッド」関数を返さない。返すと fake 自身が
-      // thenable 扱いされ、誤って await / Promise.resolve した瞬間に then() が呼ばれて throw する罠になる。
+      // Never return the "unconfigured member" function for Promise-interop properties. Doing so would
+      // make the fake itself look thenable, so accidentally awaiting it (or passing it to
+      // Promise.resolve) would invoke then() and throw — a subtle footgun.
       if (prop === 'then' || prop === 'catch' || prop === 'finally') {
         return undefined;
       }

package/src/testing/db.ts

@@ -4,40 +4,87 @@ import { createConnection, createPool } from 'mysql2/promise';
 import type { Pool } from 'mysql2/promise';
 
 /**
- * フリート共通のテスト DB ヘルパ（各 repo の testing/db.ts を集約）。
- * テストスキーマは「コミット済み Drizzle マイグレーション」を単一ソースとして構築する
- * （手書き schema.sql ではなく `db:generate` 由来の ./drizzle）。
+ * Connection parameters for the test MySQL server.
  *
- * Node 専用（vitest 下で実行）。実行時 parity には無関係なテスト基盤。
+ * @see {@link CreateTestDbOptions.connection} for how defaults are resolved.
  */
 export interface TestDbConnection {
+  /** Server host. */
   host: string;
+  /** Server port. */
   port: number;
+  /** User name. */
   user: string;
+  /** Password. */
   password: string;
 }
 
+/**
+ * Options for {@link createTestDb}.
+ */
 export interface CreateTestDbOptions {
-  /** テスト DB 名（例 'tipsys_test'）。並列実行で feature 毎に分けたい場合は呼び出し側で TEST_DB を解決して渡す。 */
+  /**
+   * Test database name (e.g. `'app_test'`). To isolate parallel runs per feature, resolve a per-run
+   * name on the caller side and pass it here.
+   */
   dbName: string;
-  /** Drizzle マイグレーションフォルダの絶対パス（呼び出し側で `join(here, '..', 'drizzle')` を解決して渡す）。 */
+  /**
+   * Absolute path to the Drizzle migrations folder. Resolve it on the caller side, e.g.
+   * `join(here, '..', 'drizzle')`.
+   */
   migrationsFolder: string;
-  /** 接続情報。未指定は env（DB_HOST/DB_PORT/DB_USER/DB_PASSWORD）→ 127.0.0.1/3306/root/root。 */
+  /**
+   * Connection overrides. Unspecified fields fall back to environment variables
+   * (`DB_HOST`/`DB_PORT`/`DB_USER`/`DB_PASSWORD`), then to `127.0.0.1`/`3306`/`root`/`root`.
+   */
   connection?: Partial<TestDbConnection>;
 }
 
+/**
+ * Test database handle returned by {@link createTestDb}, bundling schema setup, pooling, and
+ * fixture helpers for a single test database.
+ */
 export interface TestDb {
+  /** The resolved test database name. */
   readonly dbName: string;
+  /** The resolved connection parameters. */
   readonly connection: TestDbConnection;
-  /** DROP/CREATE して Drizzle マイグレーションを適用しスキーマを構築。 */
+  /**
+   * Drop and recreate the database, then apply the committed Drizzle migrations to build the schema.
+   *
+   * @returns A promise that resolves once migrations have been applied.
+   */
   resetSchema(): Promise<void>;
-  /** テスト DB に繋いだ mysql2 プールを返す（afterAll で pool.end()）。 */
+  /**
+   * Create a mysql2 pool connected to the test database.
+   *
+   * @remarks Call `pool.end()` (e.g. in `afterAll`) to release connections.
+   * @returns A connection pool for the test database.
+   */
   createTestPool(): Pool;
-  /** 全テーブルを TRUNCATE（information_schema から動的取得。__drizzle_migrations は除外）。 */
+  /**
+   * Truncate every base table in the database.
+   *
+   * @remarks Table names are discovered dynamically from `information_schema`; the
+   * `__drizzle_migrations` bookkeeping table is excluded. Foreign-key checks are disabled for the
+   * duration so truncation order does not matter.
+   * @param pool - Pool connected to the test database.
+   */
   truncateAll(pool: Pool): Promise<void>;
-  /** 1 行 insert する汎用 seed（列名→値）。route spec の fixture 用。 */
+  /**
+   * Insert a single row, mapping column names to values — a generic fixture helper for specs.
+   *
+   * @param pool - Pool connected to the test database.
+   * @param table - Target table name.
+   * @param row - Column-name to value map. A no-op if empty.
+   */
   seed(pool: Pool, table: string, row: Record<string, unknown>): Promise<void>;
-  /** ローカル MySQL が到達可能か（`describe.skipIf(!(await mysqlReachable()))` のガード用）。 */
+  /**
+   * Report whether the local MySQL server is reachable.
+   *
+   * @remarks Useful as a guard, e.g. `describe.skipIf(!(await mysqlReachable()))`.
+   * @returns `true` if a connection could be opened, otherwise `false`.
+   */
   mysqlReachable(): Promise<boolean>;
 }
 
@@ -51,6 +98,28 @@ function resolveConnection(override?: Partial<TestDbConnection>): TestDbConnecti
   };
 }
 
+/**
+ * Create a {@link TestDb} handle for a single test database.
+ *
+ * @remarks
+ * The test schema is built from the committed Drizzle migrations as the single source of truth
+ * (the `db:generate` output under `./drizzle`), rather than a hand-written `schema.sql`. This helper
+ * is Node-only test infrastructure (run under Vitest) and is unrelated to runtime behavior.
+ *
+ * @param options - Database name, migrations folder, and optional connection overrides. See
+ *   {@link CreateTestDbOptions}.
+ * @returns A handle exposing schema setup, pooling, truncation, seeding, and a reachability probe.
+ * @example
+ * ```ts
+ * const testDb = createTestDb({ dbName: 'app_test', migrationsFolder: join(here, '..', 'drizzle') });
+ * beforeAll(async () => {
+ *   await testDb.resetSchema();
+ * });
+ * const pool = testDb.createTestPool();
+ * beforeEach(() => testDb.truncateAll(pool));
+ * afterAll(() => pool.end());
+ * ```
+ */
 export function createTestDb(options: CreateTestDbOptions): TestDb {
   const { dbName, migrationsFolder } = options;
   const connection = resolveConnection(options.connection);
@@ -80,7 +149,7 @@ export function createTestDb(options: CreateTestDbOptions): TestDb {
         timezone: '+09:00',
       });
       // Pin ONLY_FULL_GROUP_BY on every pooled connection so GROUP BY violations surface in specs
-      // regardless of the server's my.cnf (fleet policy centralized here, not per-repo). CONCAT keeps
+      // regardless of the server's my.cnf (the policy is centralized here, not left to each server). CONCAT keeps
       // the server's other sql_mode flags and is harmless if ONLY_FULL_GROUP_BY is already present.
       // mysql2 queues this SET ahead of the consumer's first query on each new physical connection.
       pool.on('connection', (conn) => {