@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

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) => {

package/src/testing/fakes.ts

@@ -4,17 +4,40 @@ 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 class FakeFirebaseVerifier implements FirebaseVerifier {
   private readonly tokens = new Map<string, DecodedIdToken>();
+  /** 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 {
     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: string): Promise<DecodedIdToken> {
     const record = this.tokens.get(idToken);
     if (!record) {
@@ -23,25 +46,57 @@ export class FakeFirebaseVerifier implements FirebaseVerifier {
     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: string): Promise<{ uid: string; email?: string } | null> {
     return { uid };
   }
 
+  /**
+   * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
+   *
+   * @param uid - UID being deleted.
+   */
   async deleteUser(uid: string): Promise<void> {
     this.deleted.push(uid);
   }
 }
 
+/**
+ * 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 function createPoolDatabase<TDrizzle>(
   options: CreatePoolDatabaseOptions<TDrizzle>,
@@ -57,9 +112,22 @@ export function createPoolDatabase<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 function createNoopDatabase<TDrizzle = unknown>(): DisposableDatabase<TDrizzle> {
   return {

package/src/testing/index.ts

@@ -1,5 +1,10 @@
-// @rdlabo/workers-hono-kit/testing — フリート共通のテスト基盤（mysql2/drizzle 依存）。
-// 実行時には読み込まれないテスト専用ヘルパ。各 repo の testing/db.ts・fakes.ts を集約。
+/**
+ * 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';
@@ -8,13 +13,13 @@ export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './
 export type { CreatePoolDatabaseOptions } from './fakes.js';
 export type { Database, DisposableDatabase, QueryRunner, TxOf } from '../db/database.js';
 
-// 認証テストヘルパ（route spec のヘッダ生成・ユーザ provision を集約）。
+// Authentication test helpers (route-spec header builders and user provisioning).
 export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
 
-// test double ヘルパ（未設定メソッドで明示 throw する部分実装 fake）。
+// Test double helper (partial-implementation fake that throws explicitly on unconfigured members).
 export { configurableFake } from './configurable-fake.js';
 
-// Stripe オブジェクトの test fixture factory。
+// Test fixture factories for Stripe objects.
 export {
   fakeApiList,
   fakePaymentIntent,

package/src/testing/stripe-fixtures.ts

@@ -1,11 +1,27 @@
 import type Stripe from 'stripe';
 
 /**
- * Stripe オブジェクトの test fixture factory。実 SDK 型は巨大なので、テストが参照する範囲だけを
- * 妥当な既定値で組み、`over` で上書きする（最後に 1 度だけ Stripe 型へキャスト）。fleet 各 repo の
- * 課金テストで同じダミー PaymentIntent/Event/... を手組みしていた重複を集約する。
+ * Test fixture factories for Stripe objects.
+ *
+ * The real SDK types are enormous, so each factory builds only the fields tests typically read,
+ * fills them with reasonable defaults, lets you override via `over`, and casts to the Stripe type
+ * once at the end. This consolidates the duplicated hand-built dummy `PaymentIntent`/`Event`/... that
+ * billing tests tend to reconstruct in every project.
  */
 
+/**
+ * Build a fake Stripe `ApiList` wrapping the given data.
+ *
+ * @remarks Defaults: `object: 'list'`, `has_more: false`, `url: '/v1/_test'`.
+ * @typeParam T - Element type of the list.
+ * @param data - Items to place in `data`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.ApiList<T>` fixture.
+ * @example
+ * ```ts
+ * const list = fakeApiList([fakePaymentIntent()]);
+ * ```
+ */
 export function fakeApiList<T>(data: T[], over: Partial<Stripe.ApiList<T>> = {}): Stripe.ApiList<T> {
   return {
     object: 'list',
@@ -16,6 +32,18 @@ export function fakeApiList<T>(data: T[], over: Partial<Stripe.ApiList<T>> = {})
   };
 }
 
+/**
+ * Build a fake Stripe `PaymentIntent`.
+ *
+ * @remarks Defaults: `id: 'pi_test_1'`, `object: 'payment_intent'`, `amount: 1000`, `currency: 'jpy'`,
+ * `status: 'succeeded'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.PaymentIntent` fixture.
+ * @example
+ * ```ts
+ * const pi = fakePaymentIntent({ status: 'requires_payment_method' });
+ * ```
+ */
 export function fakePaymentIntent(over: Partial<Stripe.PaymentIntent> = {}): Stripe.PaymentIntent {
   return {
     id: 'pi_test_1',
@@ -28,6 +56,20 @@ export function fakePaymentIntent(over: Partial<Stripe.PaymentIntent> = {}): Str
   } as Stripe.PaymentIntent;
 }
 
+/**
+ * Build a fake Stripe webhook `Event` wrapping the given payload.
+ *
+ * @remarks Defaults: `id: 'evt_test_1'`, `object: 'event'`, `api_version: '2024-06-20'`,
+ * `created: 1_700_000_000`, `livemode: false`. The payload is placed at `data.object`.
+ * @param type - Event type (e.g. `'payment_intent.succeeded'`), assigned to `type`.
+ * @param dataObject - The object placed at `data.object`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Event` fixture.
+ * @example
+ * ```ts
+ * const event = fakeStripeEvent('payment_intent.succeeded', fakePaymentIntent());
+ * ```
+ */
 export function fakeStripeEvent(type: string, dataObject: unknown, over: Partial<Stripe.Event> = {}): Stripe.Event {
   return {
     id: 'evt_test_1',
@@ -41,6 +83,18 @@ export function fakeStripeEvent(type: string, dataObject: unknown, over: Partial
   } as Stripe.Event;
 }
 
+/**
+ * Build a fake Stripe `Checkout.Session`.
+ *
+ * @remarks Defaults: `id: 'cs_test_1'`, `object: 'checkout.session'`,
+ * `url: 'https://checkout.stripe.test/cs_test_1'`, `mode: 'subscription'`, `status: 'open'`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Checkout.Session` fixture.
+ * @example
+ * ```ts
+ * const session = fakeCheckoutSession({ status: 'complete' });
+ * ```
+ */
 export function fakeCheckoutSession(over: Partial<Stripe.Checkout.Session> = {}): Stripe.Checkout.Session {
   return {
     id: 'cs_test_1',
@@ -52,6 +106,18 @@ export function fakeCheckoutSession(over: Partial<Stripe.Checkout.Session> = {})
   } as Stripe.Checkout.Session;
 }
 
+/**
+ * Build a fake Stripe `Customer`.
+ *
+ * @remarks Defaults: `id: 'cus_test_1'`, `object: 'customer'`, `created: 1_700_000_000`,
+ * `livemode: false`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Customer` fixture.
+ * @example
+ * ```ts
+ * const customer = fakeCustomer({ email: 'a@example.com' });
+ * ```
+ */
 export function fakeCustomer(over: Partial<Stripe.Customer> = {}): Stripe.Customer {
   return {
     id: 'cus_test_1',
@@ -62,6 +128,18 @@ export function fakeCustomer(over: Partial<Stripe.Customer> = {}): Stripe.Custom
   } as Stripe.Customer;
 }
 
+/**
+ * Build a fake Stripe `Price`.
+ *
+ * @remarks Defaults: `id: 'price_test_1'`, `object: 'price'`, `active: true`, `currency: 'jpy'`,
+ * `unit_amount: 1000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Price` fixture.
+ * @example
+ * ```ts
+ * const price = fakePrice({ unit_amount: 2000 });
+ * ```
+ */
 export function fakePrice(over: Partial<Stripe.Price> = {}): Stripe.Price {
   return {
     id: 'price_test_1',
@@ -73,6 +151,18 @@ export function fakePrice(over: Partial<Stripe.Price> = {}): Stripe.Price {
   } as Stripe.Price;
 }
 
+/**
+ * Build a fake Stripe `Subscription`.
+ *
+ * @remarks Defaults: `id: 'sub_test_1'`, `object: 'subscription'`, `status: 'active'`,
+ * `customer: 'cus_test_1'`, `created: 1_700_000_000`.
+ * @param over - Field overrides merged last.
+ * @returns A `Stripe.Subscription` fixture.
+ * @example
+ * ```ts
+ * const sub = fakeSubscription({ status: 'canceled' });
+ * ```
+ */
 export function fakeSubscription(over: Partial<Stripe.Subscription> = {}): Stripe.Subscription {
   return {
     id: 'sub_test_1',