@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

package/dist/testing/auth.d.ts

@@ -2,11 +2,27 @@ import type { Pool } from 'mysql2/promise';
 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 declare function authHeaders(token: string, opts?: {
     version?: string;
@@ -14,15 +30,47 @@ export declare function authHeaders(token: string, opts?: {
     contentType?: string | null;
 }): Record<string, string>;
 /**
- * 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 declare function registerFirebaseToken(firebase: FakeFirebaseVerifier, uid: string, record?: Partial<DecodedIdToken>, token?: string): string;
 /**
- * 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 declare function provisionUser(pool: Pool, firebase: FakeFirebaseVerifier, opts: {
     uid: string;

package/dist/testing/auth.js

@@ -1,9 +1,25 @@
 /**
- * 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, opts = {}) {
     const headers = {
@@ -17,18 +33,50 @@ export function authHeaders(token, opts = {}) {
     return headers;
 }
 /**
- * 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, uid, record = {}, token = `tok-${uid}`) {
     firebase.register(token, { uid, ...record });
     return token;
 }
 /**
- * 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, firebase, opts) {
     const token = registerFirebaseToken(firebase, opts.uid, opts.email ? { email: opts.email } : {}, opts.token);

package/dist/testing/configurable-fake.d.ts

@@ -1,14 +1,25 @@
 /**
- * 部分実装から 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 declare function configurableFake<T extends object>(impl: Partial<T>, name?: string): T;

package/dist/testing/configurable-fake.js

@@ -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(impl, name = 'fake') {
     return new Proxy(impl, {
@@ -17,8 +28,9 @@ export function configurableFake(impl, name = 'fake') {
             if (prop in target) {
                 return target[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/dist/testing/db.d.ts

@@ -1,37 +1,106 @@
 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>;
 }
+/**
+ * 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 declare function createTestDb(options: CreateTestDbOptions): TestDb;

package/dist/testing/db.js

@@ -10,6 +10,28 @@ function resolveConnection(override) {
         password: override?.password ?? env.DB_PASSWORD ?? 'root',
     };
 }
+/**
+ * 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) {
     const { dbName, migrationsFolder } = options;
     const connection = resolveConnection(options.connection);
@@ -34,7 +56,7 @@ export function createTestDb(options) {
                 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) => {

package/dist/testing/fakes.d.ts

@@ -2,34 +2,102 @@ import type { Pool } from 'mysql2/promise';
 import type { DisposableDatabase } from '../db/database.js';
 import type { DecodedIdToken, FirebaseVerifier } from '../firebase/firebase-verifier.js';
 /**
- * オフライン route テスト用の in-memory FirebaseVerifier（4 repo 同一実装を集約）。
- * `register(token, { uid })` で偽 ID を仕込む。
+ * In-memory {@link FirebaseVerifier} implementation for offline route tests.
+ *
+ * Seed fake identities with {@link FakeFirebaseVerifier.register | register(token, { uid })}, then
+ * verification resolves the registered decoded token instead of calling a real Firebase backend.
+ *
+ * @example
+ * ```ts
+ * const firebase = new FakeFirebaseVerifier();
+ * firebase.register('tok-1', { uid: 'uid-1' });
+ * const decoded = await firebase.verifyIdToken('tok-1'); // { uid: 'uid-1' }
+ * ```
  */
 export declare class FakeFirebaseVerifier implements FirebaseVerifier {
     private readonly tokens;
+    /** UIDs passed to {@link FakeFirebaseVerifier.deleteUser}, in call order, for assertions. */
     readonly deleted: string[];
+    /**
+     * Register a fake decoded token so that {@link FakeFirebaseVerifier.verifyIdToken} resolves it.
+     *
+     * @param token - Token string clients will present.
+     * @param record - Decoded token returned on verification (must include `uid`).
+     */
     register(token: string, record: DecodedIdToken): void;
+    /**
+     * Resolve the decoded token previously registered for `idToken`.
+     *
+     * @param idToken - Token string to verify.
+     * @returns The registered decoded token.
+     * @throws Error if the token was never registered.
+     */
     verifyIdToken(idToken: string): Promise<DecodedIdToken>;
+    /**
+     * Return a minimal user record echoing the requested UID.
+     *
+     * @param uid - UID to look up.
+     * @returns An object containing the `uid` (never `null` in this fake).
+     */
     getUser(uid: string): Promise<{
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
+     *
+     * @param uid - UID being deleted.
+     */
     deleteUser(uid: string): Promise<void>;
 }
+/**
+ * Options for {@link createPoolDatabase}.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type, supplied by the consumer so that type identity is
+ *   not coupled to this package's copy of `drizzle-orm`.
+ */
 export interface CreatePoolDatabaseOptions<TDrizzle> {
-    /** テスト用プール（primary/replica 兼用）。 */
+    /** Test pool used as both primary and replica. */
     pool: Pool;
-    /** 消費側の drizzle-orm で `drizzle(pool, { schema, ... })` を作って渡す。 */
+    /** Drizzle instance built by the consumer with its own `drizzle-orm`, e.g. `drizzle(pool, { schema, ... })`. */
     orm: TDrizzle;
 }
 /**
- * テスト用にプール 1 本を primary/replica 兼用にした Database（foodlabel の PoolDatabase 相当）。
- * `dispose()` はプールを閉じる。orm は消費側が自分の drizzle-orm で作って渡す（型同一性の分離）。
+ * Create a `Database` backed by a single pool used as both primary and replica, suitable for tests.
+ *
+ * @remarks
+ * `dispose()` ends the pool. The `orm` is provided by the caller (rather than constructed here) so
+ * the returned database uses the consumer's own `drizzle-orm` types, avoiding type-identity clashes
+ * across duplicated `drizzle-orm` installs.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type provided by the consumer.
+ * @param options - Pool and Drizzle instance. See {@link CreatePoolDatabaseOptions}.
+ * @returns A {@link DisposableDatabase} whose `dispose()` closes the pool.
+ * @example
+ * ```ts
+ * const pool = testDb.createTestPool();
+ * const db = createPoolDatabase({ pool, orm: drizzle(pool, { schema }) });
+ * // ... run tests ...
+ * await db.dispose();
+ * ```
  */
 export declare function createPoolDatabase<TDrizzle>(options: CreatePoolDatabaseOptions<TDrizzle>): DisposableDatabase<TDrizzle>;
 /**
- * DB に触れない route（GET / 等）用の Database スタブ。write/transaction は誤用検知のため throw。
- * dispose は no-op（Hyperdrive/Pool 背面の DisposableDatabase を期待する repo でもそのまま使える）。
- * orm 型は呼び出し側が指定（既定 unknown）。
+ * Create a no-op `Database` stub for routes that never touch the database (e.g. plain GET handlers).
+ *
+ * @remarks
+ * `read` resolves to an empty array, while `write` and `transaction` throw so that any unexpected
+ * database access is caught as a misuse. `dispose` is a no-op, so this can stand in for a
+ * {@link DisposableDatabase} backing (e.g. a Hyperdrive- or pool-based one) without changes.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type the consumer expects (defaults to `unknown`).
+ * @returns A {@link DisposableDatabase} that reads empty and throws on writes/transactions.
+ * @throws Error from `write`/`transaction` if they are accessed.
+ * @example
+ * ```ts
+ * const db = createNoopDatabase();
+ * await db.read('SELECT 1'); // []
+ * await db.write(async (dz) => dz); // throws: noopDatabase.write accessed unexpectedly
+ * ```
  */
 export declare function createNoopDatabase<TDrizzle = unknown>(): DisposableDatabase<TDrizzle>;

package/dist/testing/fakes.js

@@ -1,14 +1,37 @@
 import { databaseFrom } from '../db/database.js';
 /**
- * オフライン route テスト用の in-memory FirebaseVerifier（4 repo 同一実装を集約）。
- * `register(token, { uid })` で偽 ID を仕込む。
+ * In-memory {@link FirebaseVerifier} implementation for offline route tests.
+ *
+ * Seed fake identities with {@link FakeFirebaseVerifier.register | register(token, { uid })}, then
+ * verification resolves the registered decoded token instead of calling a real Firebase backend.
+ *
+ * @example
+ * ```ts
+ * const firebase = new FakeFirebaseVerifier();
+ * firebase.register('tok-1', { uid: 'uid-1' });
+ * const decoded = await firebase.verifyIdToken('tok-1'); // { uid: 'uid-1' }
+ * ```
  */
 export class FakeFirebaseVerifier {
     tokens = new Map();
+    /** UIDs passed to {@link FakeFirebaseVerifier.deleteUser}, in call order, for assertions. */
     deleted = [];
+    /**
+     * Register a fake decoded token so that {@link FakeFirebaseVerifier.verifyIdToken} resolves it.
+     *
+     * @param token - Token string clients will present.
+     * @param record - Decoded token returned on verification (must include `uid`).
+     */
     register(token, record) {
         this.tokens.set(token, record);
     }
+    /**
+     * Resolve the decoded token previously registered for `idToken`.
+     *
+     * @param idToken - Token string to verify.
+     * @returns The registered decoded token.
+     * @throws Error if the token was never registered.
+     */
     async verifyIdToken(idToken) {
         const record = this.tokens.get(idToken);
         if (!record) {
@@ -16,16 +39,42 @@ export class FakeFirebaseVerifier {
         }
         return record;
     }
+    /**
+     * Return a minimal user record echoing the requested UID.
+     *
+     * @param uid - UID to look up.
+     * @returns An object containing the `uid` (never `null` in this fake).
+     */
     async getUser(uid) {
         return { uid };
     }
+    /**
+     * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
+     *
+     * @param uid - UID being deleted.
+     */
     async deleteUser(uid) {
         this.deleted.push(uid);
     }
 }
 /**
- * テスト用にプール 1 本を primary/replica 兼用にした Database（foodlabel の PoolDatabase 相当）。
- * `dispose()` はプールを閉じる。orm は消費側が自分の drizzle-orm で作って渡す（型同一性の分離）。
+ * Create a `Database` backed by a single pool used as both primary and replica, suitable for tests.
+ *
+ * @remarks
+ * `dispose()` ends the pool. The `orm` is provided by the caller (rather than constructed here) so
+ * the returned database uses the consumer's own `drizzle-orm` types, avoiding type-identity clashes
+ * across duplicated `drizzle-orm` installs.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type provided by the consumer.
+ * @param options - Pool and Drizzle instance. See {@link CreatePoolDatabaseOptions}.
+ * @returns A {@link DisposableDatabase} whose `dispose()` closes the pool.
+ * @example
+ * ```ts
+ * const pool = testDb.createTestPool();
+ * const db = createPoolDatabase({ pool, orm: drizzle(pool, { schema }) });
+ * // ... run tests ...
+ * await db.dispose();
+ * ```
  */
 export function createPoolDatabase(options) {
     const { pool, orm } = options;
@@ -38,9 +87,22 @@ export function createPoolDatabase(options) {
     };
 }
 /**
- * DB に触れない route（GET / 等）用の Database スタブ。write/transaction は誤用検知のため throw。
- * dispose は no-op（Hyperdrive/Pool 背面の DisposableDatabase を期待する repo でもそのまま使える）。
- * orm 型は呼び出し側が指定（既定 unknown）。
+ * Create a no-op `Database` stub for routes that never touch the database (e.g. plain GET handlers).
+ *
+ * @remarks
+ * `read` resolves to an empty array, while `write` and `transaction` throw so that any unexpected
+ * database access is caught as a misuse. `dispose` is a no-op, so this can stand in for a
+ * {@link DisposableDatabase} backing (e.g. a Hyperdrive- or pool-based one) without changes.
+ *
+ * @typeParam TDrizzle - The Drizzle instance type the consumer expects (defaults to `unknown`).
+ * @returns A {@link DisposableDatabase} that reads empty and throws on writes/transactions.
+ * @throws Error from `write`/`transaction` if they are accessed.
+ * @example
+ * ```ts
+ * const db = createNoopDatabase();
+ * await db.read('SELECT 1'); // []
+ * await db.write(async (dz) => dz); // throws: noopDatabase.write accessed unexpectedly
+ * ```
  */
 export function createNoopDatabase() {
     return {

package/dist/testing/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Shared test infrastructure for Hono on Cloudflare Workers projects (depends on `mysql2`/`drizzle-orm`).
+ *
+ * Test-only helpers that are never loaded at runtime. This subpath consolidates the duplicated
+ * test boilerplate (test DB setup, in-memory fakes, auth header builders, Stripe fixtures) that
+ * tends to be copy-pasted across projects into a single, importable surface.
+ */
 export { createTestDb } from './db.js';
 export type { TestDb, CreateTestDbOptions, TestDbConnection } from './db.js';
 export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes.js';