@rdlabo/workers-hono-kit 0.11.2 → 0.12.0-beta.pr48.sha371f5792ce8a

package/dist/testing/db.d.ts

@@ -1,106 +1,19 @@
-import type { Pool } from 'mysql2/promise';
-/**
- * Connection parameters for the test MySQL server.
- *
- * @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 {
-    /**
-     * 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;
-    /**
-     * Absolute path to the Drizzle migrations folder. Resolve it on the caller side, e.g.
-     * `join(here, '..', 'drizzle')`.
-     */
-    migrationsFolder: string;
-    /**
-     * 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 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>;
-    /**
-     * 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 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>;
-    /**
-     * 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>;
-    /**
-     * 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;
+import type { Database as DatabaseCanonical, DisposableDatabase as DisposableDatabaseCanonical, QueryRunner as QueryRunnerCanonical, TxOf as TxOfCanonical } from '@rdlabo/workers-mysql';
+import { createTestDb as createTestDbCanonical } from '@rdlabo/workers-mysql/testing';
+import type { CreateTestDbOptions as CreateTestDbOptionsCanonical, TestDb as TestDbCanonical, TestDbConnection as TestDbConnectionCanonical } from '@rdlabo/workers-mysql/testing';
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export declare const createTestDb: typeof createTestDbCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export type TestDb = TestDbCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export type CreateTestDbOptions = CreateTestDbOptionsCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export type TestDbConnection = TestDbConnectionCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql` or `@rdlabo/workers-mysql/testing` instead. */
+export type TxOf<TDrizzle> = TxOfCanonical<TDrizzle>;
+/** @deprecated Import from `@rdlabo/workers-mysql` or `@rdlabo/workers-mysql/testing` instead. */
+export type Database<TDrizzle, TTx = TxOfCanonical<TDrizzle>> = DatabaseCanonical<TDrizzle, TTx>;
+/** @deprecated Import from `@rdlabo/workers-mysql` or `@rdlabo/workers-mysql/testing` instead. */
+export type DisposableDatabase<TDrizzle, TTx = TxOfCanonical<TDrizzle>> = DisposableDatabaseCanonical<TDrizzle, TTx>;
+/** @deprecated Import from `@rdlabo/workers-mysql` or `@rdlabo/workers-mysql/testing` instead. */
+export type QueryRunner = QueryRunnerCanonical;

package/dist/testing/db.js

@@ -1,95 +1,3 @@
-import { drizzle } from 'drizzle-orm/mysql2';
-import { migrate } from 'drizzle-orm/mysql2/migrator';
-import { createConnection, createPool } from 'mysql2/promise';
-function resolveConnection(override) {
-    const env = globalThis.process?.env ?? {};
-    return {
-        host: override?.host ?? env.DB_HOST ?? '127.0.0.1',
-        port: override?.port ?? Number(env.DB_PORT ?? '3306'),
-        user: override?.user ?? env.DB_USER ?? 'root',
-        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);
-    return {
-        dbName,
-        connection,
-        async resetSchema() {
-            const admin = await createConnection({ ...connection, multipleStatements: true });
-            await admin.query(`DROP DATABASE IF EXISTS \`${dbName}\`; CREATE DATABASE \`${dbName}\` DEFAULT CHARACTER SET utf8mb4;`);
-            await admin.changeUser({ database: dbName });
-            await migrate(drizzle(admin), { migrationsFolder });
-            await admin.end();
-        },
-        createTestPool() {
-            // decimalNumbers / timezone mirror the runtime hyperdriveConnectionOptions so specs read
-            // DECIMAL columns as numbers and handle datetime in +09:00 (JST), matching production.
-            const pool = createPool({
-                ...connection,
-                database: dbName,
-                connectionLimit: 5,
-                decimalNumbers: true,
-                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 (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) => {
-                void conn.query("SET SESSION sql_mode = CONCAT(@@SESSION.sql_mode, ',ONLY_FULL_GROUP_BY')");
-            });
-            return pool;
-        },
-        async truncateAll(pool) {
-            const [rows] = await pool.query("SELECT table_name AS t FROM information_schema.tables WHERE table_schema = ? AND table_type='BASE TABLE' AND table_name <> '__drizzle_migrations'", [dbName]);
-            const tables = rows.map((r) => r.t);
-            await pool.query('SET FOREIGN_KEY_CHECKS=0');
-            for (const t of tables) {
-                await pool.query(`TRUNCATE TABLE \`${t}\``);
-            }
-            await pool.query('SET FOREIGN_KEY_CHECKS=1');
-        },
-        async seed(pool, table, row) {
-            const cols = Object.keys(row);
-            if (cols.length === 0) {
-                return;
-            }
-            const placeholders = cols.map(() => '?').join(', ');
-            const columnList = cols.map((c) => `\`${c}\``).join(', ');
-            await pool.query(`INSERT INTO \`${table}\` (${columnList}) VALUES (${placeholders})`, Object.values(row));
-        },
-        async mysqlReachable() {
-            const connect = async () => createConnection({ ...connection });
-            const c = await connect().catch(() => undefined);
-            if (!c) {
-                return false;
-            }
-            const close = async () => c.end();
-            return close().then(() => true, () => false);
-        },
-    };
-}
+import { createTestDb as createTestDbCanonical } from '@rdlabo/workers-mysql/testing';
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export const createTestDb = createTestDbCanonical;

package/dist/testing/fakes.d.ts

@@ -1,113 +1,31 @@
-import type { Pool } from 'mysql2/promise';
-import type { DisposableDatabase } from '../db/database.js';
+import { createNoopDatabase as createNoopDatabaseCanonical, createPoolDatabase as createPoolDatabaseCanonical } from '@rdlabo/workers-mysql/testing';
+import type { CreatePoolDatabaseOptions as CreatePoolDatabaseOptionsCanonical } from '@rdlabo/workers-mysql/testing';
 import type { DecodedIdToken, FirebaseVerifier } from '../firebase/firebase-verifier.js';
-/**
- * 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' }
- * ```
- */
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export declare const createPoolDatabase: typeof createPoolDatabaseCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export declare const createNoopDatabase: typeof createNoopDatabaseCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export type CreatePoolDatabaseOptions<TDrizzle> = CreatePoolDatabaseOptionsCanonical<TDrizzle>;
+/** In-memory Firebase verifier for route tests. */
 export declare class FakeFirebaseVerifier implements FirebaseVerifier {
     private readonly tokens;
-    /** UIDs passed to {@link FakeFirebaseVerifier.deleteUser}, in call order, for assertions. */
+    /** UIDs passed to {@link deleteUser}, in call order. */
     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 a decoded token for later verification. */
     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.
-     */
+    /** Resolve a registered token. */
     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).
-     */
+    /** Return a minimal fake user. */
     getUser(uid: string): Promise<{
         uid: string;
         email?: string;
     } | null>;
-    /**
-     * Return minimal user records echoing each requested UID.
-     *
-     * @param uids - UIDs to look up.
-     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
-     */
+    /** Return one minimal fake user per UID. */
     getUsers(uids: string[]): Promise<{
         uid: string;
         email?: string;
     }[]>;
-    /**
-     * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
-     *
-     * @param uid - UID being deleted.
-     */
+    /** Record a fake user deletion. */
     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> {
-    /** Test pool used as both primary and replica. */
-    pool: Pool;
-    /** Drizzle instance built by the consumer with its own `drizzle-orm`, e.g. `drizzle(pool, { schema, ... })`. */
-    orm: TDrizzle;
-}
-/**
- * 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>;
-/**
- * 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,37 +1,18 @@
-import { databaseFrom } from '../db/database.js';
-/**
- * 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' }
- * ```
- */
+import { createNoopDatabase as createNoopDatabaseCanonical, createPoolDatabase as createPoolDatabaseCanonical, } from '@rdlabo/workers-mysql/testing';
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export const createPoolDatabase = createPoolDatabaseCanonical;
+/** @deprecated Import from `@rdlabo/workers-mysql/testing` instead. */
+export const createNoopDatabase = createNoopDatabaseCanonical;
+/** In-memory Firebase verifier for route tests. */
 export class FakeFirebaseVerifier {
     tokens = new Map();
-    /** UIDs passed to {@link FakeFirebaseVerifier.deleteUser}, in call order, for assertions. */
+    /** UIDs passed to {@link deleteUser}, in call order. */
     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 a decoded token for later verification. */
     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.
-     */
+    /** Resolve a registered token. */
     async verifyIdToken(idToken) {
         const record = this.tokens.get(idToken);
         if (!record) {
@@ -39,89 +20,16 @@ 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).
-     */
+    /** Return a minimal fake user. */
     async getUser(uid) {
         return { uid };
     }
-    /**
-     * Return minimal user records echoing each requested UID.
-     *
-     * @param uids - UIDs to look up.
-     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
-     */
+    /** Return one minimal fake user per UID. */
     async getUsers(uids) {
         return uids.map((uid) => ({ uid }));
     }
-    /**
-     * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
-     *
-     * @param uid - UID being deleted.
-     */
+    /** Record a fake user deletion. */
     async deleteUser(uid) {
         this.deleted.push(uid);
     }
 }
-/**
- * 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;
-    const base = databaseFrom(orm, pool);
-    return {
-        ...base,
-        async dispose() {
-            await pool.end();
-        },
-    };
-}
-/**
- * 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 {
-        read: async () => [],
-        write: () => {
-            throw new Error('noopDatabase.write accessed unexpectedly');
-        },
-        transaction: () => {
-            throw new Error('noopDatabase.transaction accessed unexpectedly');
-        },
-        dispose: async () => { },
-    };
-}

package/dist/testing/index.d.ts

@@ -1,5 +1,9 @@
 /**
- * Shared test infrastructure for Hono on Cloudflare Workers projects (depends on `mysql2`/`drizzle-orm`).
+ * Shared test infrastructure for Hono on Cloudflare Workers projects.
+ * Every import requires `@rdlabo/workers-mysql` and `drizzle-orm` because DB compatibility exports
+ * are loaded statically, including when only non-DB helpers are used. Prefer
+ * `@rdlabo/workers-mysql/testing` for database helpers; kit-owned Firebase/auth/KV/Stripe fakes remain
+ * the supported testing surface here.
  *
  * 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
@@ -7,9 +11,10 @@
  */
 export { createTestDb } from './db.js';
 export type { TestDb, CreateTestDbOptions, TestDbConnection } from './db.js';
-export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes.js';
+export type { Database, DisposableDatabase, QueryRunner, TxOf } from './db.js';
+export { FakeFirebaseVerifier } from './fakes.js';
+export { createPoolDatabase, createNoopDatabase } from './fakes.js';
 export type { CreatePoolDatabaseOptions } from './fakes.js';
-export type { Database, DisposableDatabase, QueryRunner, TxOf } from '../db/database.js';
 export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
 export { configurableFake } from './configurable-fake.js';
 export { fakeApiList, fakePaymentIntent, fakeStripeEvent, fakeCheckoutSession, fakeCustomer, fakePrice, fakeSubscription, } from './stripe-fixtures.js';

package/dist/testing/index.js

@@ -1,12 +1,18 @@
 /**
- * Shared test infrastructure for Hono on Cloudflare Workers projects (depends on `mysql2`/`drizzle-orm`).
+ * Shared test infrastructure for Hono on Cloudflare Workers projects.
+ * Every import requires `@rdlabo/workers-mysql` and `drizzle-orm` because DB compatibility exports
+ * are loaded statically, including when only non-DB helpers are used. Prefer
+ * `@rdlabo/workers-mysql/testing` for database helpers; kit-owned Firebase/auth/KV/Stripe fakes remain
+ * the supported testing surface here.
  *
  * 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.
  */
+/* eslint-disable @typescript-eslint/no-deprecated -- compatibility barrel re-exports DB helpers */
 export { createTestDb } from './db.js';
-export { FakeFirebaseVerifier, createPoolDatabase, createNoopDatabase } from './fakes.js';
+export { FakeFirebaseVerifier } from './fakes.js';
+export { createPoolDatabase, createNoopDatabase } from './fakes.js';
 // Authentication test helpers (route-spec header builders and user provisioning).
 export { authHeaders, registerFirebaseToken, provisionUser } from './auth.js';
 // Test double helper (partial-implementation fake that throws explicitly on unconfigured members).

package/docs/api-business-time.md

@@ -1,33 +1,50 @@
-# API: `@rdlabo/workers-hono-kit/business-time`
-
-String-level JST business-time conversions (Workers UTC instant ↔ business calendar date / date-time), with **no `mysql2` / `drizzle-orm` dependency**. This is a different layer from the `./db` column helpers (which handle the MySQL wire format): the DB stays on JST, and the app handles JST explicitly through this module instead of relying implicitly on the connection `timezone`.
-
-| Export | Description |
-| --- | --- |
-| `today(ref?)` | The JST business calendar date (`YYYY-MM-DD`) of `ref` (defaults to now). |
-| `toBusinessDate(instant)` | UTC instant → JST business calendar date (`YYYY-MM-DD`). |
-| `normalizeBusinessDate(value)` | Normalize a `string` / `Date` / nullish to `YYYY-MM-DD`; a `YYYY-MM-DD` string passes through unchanged, nullish/empty/invalid → `null`. |
-| `toBusinessDateTime(instant)` | UTC instant → JST business date-time (`YYYY-MM-DD HH:mm:ss`). |
-| `parseBusinessDateTime(value)` | JST business date-time string → UTC instant (accepts a space or `T` separator). |
-| `formatBusinessDateTime(instant, pattern?)` | Format an instant in the business TZ (Nest `helper.formatDate`-compatible tokens). |
-| `startOfBusinessDay(date)` / `endOfBusinessDay(date)` | UTC instant of `00:00:00` / `23:59:59` on a JST business date. |
-| `businessDateTimeInstant(date, time)` | JST business date + wall-clock time → UTC instant. |
-| `addBusinessDays(date, days)` | Add calendar days to a JST business date. |
-| `ageOnBusinessDate(birthDate, asOfDate?)` | Full years of age on a business date (`asOfDate` defaults to `today()`). |
-| `DEFAULT_BUSINESS_DATETIME_PATTERN` | Default `formatBusinessDateTime` pattern (`YYYY-MM-DDThh:mm:ss`). |
-| `BUSINESS_TIMEZONE` / `BusinessDate` / `BusinessDateTime` | JST timezone constant and the business-date / date-time string types. |
+# API: `@rdlabo/workers-timezone`
+
+Install with `npm install @rdlabo/workers-timezone`. The kit's `/business-time` entry point is a
+deprecated compatibility re-export from `0.12.0`.
+
+Timezone-aware calendar and wall-clock conversion for Cloudflare Workers, with no database or Node
+runtime dependency. The uninitialized default remains `Asia/Tokyo` for compatibility.
+
+```ts
+import { TIME_ZONES, initializeTimezone, toLocalDateTime } from '@rdlabo/workers-timezone';
+
+initializeTimezone({ timeZone: TIME_ZONES.NEW_YORK });
+toLocalDateTime(new Date('2026-07-01T13:00:00Z')); // '2026-07-01 09:00:00'
+```
+
+Initialize once during module evaluation using deployment-wide static configuration. Do not mutate
+the default per request, user, or tenant. Every conversion function accepts an explicit IANA
+timezone override without changing the module-instance default.
+
+| Export                                          | Description                                                                      |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| `initializeTimezone(config)`                    | Set the module-instance default once; repeated identical initialization is safe. |
+| `getTimezoneConfig()`                           | Return the active configuration.                                                 |
+| `toLocalDate(instant, timeZone?)`               | Instant to local `YYYY-MM-DD`.                                                   |
+| `toLocalDateTime(instant, timeZone?)`           | Instant to local `YYYY-MM-DD HH:mm:ss`.                                          |
+| `localDateTimeToInstant(date, time, timeZone?)` | Local calendar date and wall clock to an instant.                                |
+| `startOfDay` / `endOfDay`                       | First or final representable whole second of a local calendar day.               |
+| `addDays(date, days)`                           | Add calendar days without assuming a 24-hour day.                                |
+| `TIME_ZONES` / `TimeZone`                       | Common typed constants and the open IANA timezone type.                          |
+
+IANA rules determine daylight-saving and historical offsets. A skipped local clock throws
+`RangeError`; when a clock occurs twice during a DST overlap, the earlier instant is selected.
+
+## Legacy compatibility
+
+`@rdlabo/workers-hono-kit/business-time` is deprecated and re-exports the same module instance from
+`@rdlabo/workers-timezone`. Existing names such as `today`, `normalizeBusinessDate`,
+`toBusinessDateTime`, `businessDateTimeInstant`, `formatBusinessDateTime`, and
+`ageOnBusinessDate` remain available during migration.
+
+This is source compatibility for API names, not full output compatibility. Results now follow IANA
+historical offsets instead of the legacy fixed `+09:00`, so historical dates can change when
+Tokyo's offset was not `+09:00`. Impossible `YYYY-MM-DD` values now normalize to `null`; invalid
+date-time construction and parsing throw `RangeError` instead of using JavaScript `Date` rollover.
+Treat both behavior changes as breaking when planning the migration.
 
 ```ts
-import {
-  toBusinessDate,
-  toBusinessDateTime,
-  formatBusinessDateTime,
-  addBusinessDays,
-} from '@rdlabo/workers-hono-kit/business-time';
-
-const now = new Date('2026-07-05T21:00:00Z');
-toBusinessDate(now); // '2026-07-06' (JST)
-toBusinessDateTime(now); // '2026-07-06 06:00:00'
-formatBusinessDateTime(now); // '2026-07-06T06:00:00'
-addBusinessDays('2026-07-06', 3); // '2026-07-09'
+// Deprecated; migrate the import path when practical.
+import { toBusinessDateTime } from '@rdlabo/workers-hono-kit/business-time';
 ```