@rdlabo/workers-hono-kit 0.10.6 → 0.11.1-beta.pr46.sha8ccc8da384f0

package/dist/db/columns.d.ts

@@ -1,4 +1,3 @@
-import type { DecimalNumberConfig } from './decimal.js';
 /**
  * SQL expression for `ON UPDATE CURRENT_TIMESTAMP` (the MySQL session clock).
  * customType columns have no `.onUpdateNow()`, so pair this with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`.
@@ -37,12 +36,3 @@ export declare const jstDate: (name: string) => import("drizzle-orm/mysql-core")
     driverParam: string | null;
     enumValues: undefined;
 }>;
-/** MySQL `decimal` — SELECT coerces string→number via `fromDriver`; writes bind the number as-is. */
-export declare const decimalNumber: (name: string, config: DecimalNumberConfig) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
-    name: string;
-    dataType: "custom";
-    columnType: "MySqlCustomColumn";
-    data: number | null;
-    driverParam: string | number | null;
-    enumValues: undefined;
-}>;

package/dist/db/columns.js

@@ -5,8 +5,7 @@
  * @remarks
  * `drizzle-orm` is a **peer** (the consumer resolves a single copy); the kit does not bundle it. The
  * return types are the `customType` inference as-is (`MySqlCustomColumnBuilder<…>`) with no `any`, so
- * the column's semantic type (`string | Date`, `number | null`, etc.) propagates to the consumer
- * table's `$inferSelect`.
+ * the column's semantic type (`string | Date`, etc.) propagates to the consumer table's `$inferSelect`.
  *
  * **Precondition (a single drizzle copy)**: Drizzle's `SQL` is a **nominal** type carrying a private
  * field `shouldInlineParams`, so if the kit and the consumer resolve different copies of drizzle,
@@ -23,7 +22,6 @@
  */
 import { sql } from 'drizzle-orm';
 import { customType } from 'drizzle-orm/mysql-core';
-import { decimalNumberParams } from './decimal.js';
 import { jstDateParams, jstDatetimeParams, jstTimestampParams } from './jst.js';
 /**
  * SQL expression for `ON UPDATE CURRENT_TIMESTAMP` (the MySQL session clock).
@@ -38,5 +36,3 @@ export const jstTimestamp = (name, opts) => customType(jstTimestampParams(opts?.
 export const jstDatetime = (name, opts) => customType(jstDatetimeParams(opts?.fsp))(name);
 /** MySQL `date` — on INSERT/UPDATE, normalizes ISO / empty strings to `YYYY-MM-DD` (via `toDriver`). */
 export const jstDate = (name) => customType(jstDateParams())(name);
-/** MySQL `decimal` — SELECT coerces string→number via `fromDriver`; writes bind the number as-is. */
-export const decimalNumber = (name, config) => customType(decimalNumberParams(config))(name);

package/dist/db/database.d.ts

@@ -6,8 +6,8 @@ import type { HyperdriveLike } from './connection.js';
  * @remarks
  * The two sides of the database are deliberately handled differently:
  *
- * - Reads go to the **replica** as raw SQL (`QueryRunner.query`) for transparency, returning plain
- *   rows.
+ * - Reads go to the **replica** as raw SQL (`QueryRunner.query`) by default, returning plain rows.
+ *   Hyperdrive-backed databases also expose `query()` for freshness-sensitive primary SELECTs.
  * - Writes and transactions go to the **primary** through the Drizzle ORM for type safety, but only
  *   via `write(fn)` / `transaction(fn)` — the raw query builder is never exposed. The builder is
  *   awaited inside those methods, which removes a foot-gun: a Drizzle builder is a lazy thenable, so
@@ -53,7 +53,8 @@ export type TxOf<TDrizzle> = TDrizzle extends {
  */
 export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
     /**
-     * Run a raw SQL read against the replica, with deadlock retry.
+     * Run a raw SQL read against the replica. Hyperdrive-backed databases retry deadlocks and repeat
+     * the SELECT once on a fresh connection after mysql2 reports a fatal connection error.
      *
      * @typeParam T - the row shape.
      * @param sql - the SQL text, with `?` placeholders for `params`.
@@ -98,6 +99,55 @@ export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Data
      */
     dispose(): Promise<void>;
 }
+/**
+ * A Hyperdrive-backed database with an explicit primary query path.
+ *
+ * @remarks
+ * Use `query()` only for SELECTs that require read-after-write consistency or cannot use the
+ * configured replica. Fatal connection errors recreate the primary connection and repeat the
+ * SELECT at most once. Writes and transactions are never repeated for connection errors.
+ * Read-only transactions are serialized on a separately cached primary connection so their
+ * snapshot boundaries cannot mix with ordinary primary operations or with each other. Do not call
+ * `readTransaction()` recursively from its own callback.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
+export interface HyperdriveDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends DisposableDatabase<TDrizzle, TTx> {
+    /**
+     * Run a raw SQL SELECT against the primary database.
+     *
+     * @typeParam T - the complete rows result type (for example, `User[]`).
+     * @param sql - the SQL text, with `?` placeholders for `params`.
+     * @param params - optional positional parameters.
+     * @returns the rows returned by the query, typed as `T`.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /**
+     * Run a repeatable-read, consistent snapshot on the primary database.
+     *
+     * @remarks
+     * The callback is repeated at most once on a fresh connection after a fatal connection error.
+     * This is safe only because the transaction is declared read-only. Use {@link transaction} for
+     * writes; write transactions are never repeated after connection loss. Calls are serialized on
+     * one dedicated connection, so recursive `readTransaction()` calls are not supported.
+     */
+    readTransaction<T>(fn: (reader: ReadTransaction<TTx>) => Promise<T>): Promise<T>;
+}
+/** Primary read-only transaction handles that share one consistent snapshot. */
+export interface ReadTransaction<TTx> {
+    /**
+     * The consumer's Drizzle transaction handle.
+     *
+     * @remarks
+     * Drizzle's type does not distinguish read-only transactions. MySQL enforces read-only mode at
+     * runtime; applications may expose a narrower SELECT-only facade when they need compile-time
+     * enforcement.
+     */
+    orm: TTx;
+    /** Run raw SQL on the same primary connection and snapshot. */
+    query: <T = unknown>(sql: string, params?: unknown[]) => Promise<T>;
+}
 /**
  * Options for {@link createMysqlDatabase}.
  *
@@ -155,17 +205,19 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
     connectionOptions?: Record<string, unknown>;
 }
 /**
- * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
+ * Create a {@link HyperdriveDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
  * Construct one per request. Connections and the ORM are created on first use and reused for the
- * lifetime of the instance; the read/write/transaction surface is identical to
- * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
- * invocation, so callers do not need to close them manually.
+ * lifetime of the instance. `read()` uses the replica, while `query()` provides an explicit
+ * primary SELECT path. Workers automatically cleans up connections at the end of the invocation,
+ * so callers do not need to close them manually. Either SELECT path is repeated once on a fresh
+ * connection after a fatal mysql2 connection error. Writes and transactions are never repeated
+ * for connection errors because their commit state can be ambiguous.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ * @returns a {@link HyperdriveDatabase} whose compatibility `dispose()` method is a no-op; Workers
  *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
@@ -177,7 +229,7 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
-export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): DisposableDatabase<TDrizzle>;
+export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): HyperdriveDatabase<TDrizzle>;
 /**
  * Internal helper that assembles a {@link Database} from an ORM and a replica connection.
  *

package/dist/db/database.js

@@ -24,17 +24,19 @@ export function createMysqlDatabase(options) {
     return databaseFrom(options.orm, options.replica);
 }
 /**
- * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
+ * Create a {@link HyperdriveDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
  * Construct one per request. Connections and the ORM are created on first use and reused for the
- * lifetime of the instance; the read/write/transaction surface is identical to
- * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
- * invocation, so callers do not need to close them manually.
+ * lifetime of the instance. `read()` uses the replica, while `query()` provides an explicit
+ * primary SELECT path. Workers automatically cleans up connections at the end of the invocation,
+ * so callers do not need to close them manually. Either SELECT path is repeated once on a fresh
+ * connection after a fatal mysql2 connection error. Writes and transactions are never repeated
+ * for connection errors because their commit state can be ambiguous.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ * @returns a {@link HyperdriveDatabase} whose compatibility `dispose()` method is a no-op; Workers
  *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
@@ -50,15 +52,84 @@ export function createHyperdriveDatabase(options) {
     const { primaryHyperdrive, replicaHyperdrive, createOrm, connectionOptions } = options;
     let primaryConn;
     let replicaConn;
+    let readTransactionConn;
     let orm;
+    let readTransactionOrm;
+    let readTransactionTail;
     const primary = () => (primaryConn ??= connect(primaryHyperdrive, connectionOptions));
     const replica = () => (replicaConn ??= connect(replicaHyperdrive, connectionOptions));
+    const readTransactionConnection = () => (readTransactionConn ??= connect(primaryHyperdrive, connectionOptions));
     const ormFor = async () => (orm ??= createOrm(await primary()));
+    const readFrom = (connection, sql, params) => retryWhenDeadlock(async () => {
+        const [rows] = (await (await connection).query(sql, params));
+        return rows;
+    });
+    const readWithRecovery = async (connectionFor, reset, sql, params) => {
+        const connection = connectionFor();
+        const outcome = await readFrom(connection, sql, params).then((rows) => ({ ok: true, rows }), (error) => ({ ok: false, error }));
+        if (outcome.ok) {
+            return outcome.rows;
+        }
+        if (!isFatalConnectionError(outcome.error)) {
+            throw outcome.error;
+        }
+        reset(connection);
+        return readFrom(connectionFor(), sql, params);
+    };
+    const resetPrimary = (failedConnection) => {
+        if (primaryConn === failedConnection) {
+            primaryConn = undefined;
+            orm = undefined;
+        }
+    };
+    const resetReadTransaction = (failedConnection) => {
+        if (readTransactionConn === failedConnection) {
+            readTransactionConn = undefined;
+            readTransactionOrm = undefined;
+        }
+    };
+    const withReadTransactionLock = (fn) => {
+        const result = readTransactionTail ? readTransactionTail.then(fn, fn) : fn();
+        readTransactionTail = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const runReadTransaction = async (connection, fn) => {
+        const conn = await connection;
+        const dz = (readTransactionOrm ??= createOrm(conn));
+        return retryWhenDeadlock(async () => {
+            await conn.query('SET TRANSACTION READ ONLY');
+            return dz.transaction((tx) => fn({
+                orm: tx,
+                query: async (sql, params = []) => {
+                    const [rows] = (await conn.query(sql, params));
+                    return rows;
+                },
+            }), { isolationLevel: 'repeatable read', withConsistentSnapshot: true });
+        });
+    };
     return {
         read(sql, params = []) {
-            return retryWhenDeadlock(async () => {
-                const [rows] = (await (await replica()).query(sql, params));
-                return rows;
+            return readWithRecovery(replica, (failedConnection) => {
+                if (replicaConn === failedConnection) {
+                    replicaConn = undefined;
+                }
+            }, sql, params);
+        },
+        query(sql, params = []) {
+            return readWithRecovery(primary, resetPrimary, sql, params);
+        },
+        async readTransaction(fn) {
+            return withReadTransactionLock(async () => {
+                const connection = readTransactionConnection();
+                const outcome = await runReadTransaction(connection, fn).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+                if (outcome.ok) {
+                    return outcome.value;
+                }
+                if (!isFatalConnectionError(outcome.error)) {
+                    throw outcome.error;
+                }
+                resetReadTransaction(connection);
+                return runReadTransaction(readTransactionConnection(), fn);
             });
         },
         async write(fn) {
@@ -104,3 +175,22 @@ export function databaseFrom(orm, replica) {
 function connect(hyperdrive, extra) {
     return createConnection(hyperdriveConnectionOptions(hyperdrive, extra));
 }
+function isFatalConnectionError(error) {
+    let current = error;
+    const seen = new Set();
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const value = current;
+        if (value.fatal === true ||
+            value.code === 'PROTOCOL_CONNECTION_LOST' ||
+            value.code === 'ECONNRESET' ||
+            value.code === 'EPIPE' ||
+            (typeof value.message === 'string' &&
+                (value.message.includes('Connection lost:') ||
+                    value.message.includes("Can't add new command when connection is in closed state")))) {
+            return true;
+        }
+        current = value.cause;
+    }
+    return false;
+}

package/dist/db/index.d.ts

@@ -11,15 +11,13 @@
  */
 export { retryWhenDeadlock } from './retry.js';
 export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
-export type { Database, DisposableDatabase, QueryRunner, TxOf, CreateMysqlDatabaseOptions, CreateHyperdriveDatabaseOptions, Connection, Pool, } from './database.js';
+export type { Database, DisposableDatabase, HyperdriveDatabase, ReadTransaction, QueryRunner, TxOf, CreateMysqlDatabaseOptions, CreateHyperdriveDatabaseOptions, Connection, Pool, } from './database.js';
 export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
 export type { DzWriteResult } from './write-result.js';
 export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
 export type { HyperdriveLike, ExecutionContextLike } from './connection.js';
 export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
-export { coerceDecimalNumber, decimalNumberParams } from './decimal.js';
-export type { DecimalNumberConfig } from './decimal.js';
-export { jstTimestamp, jstDatetime, jstDate, decimalNumber, jstOnUpdateNow } from './columns.js';
+export { jstTimestamp, jstDatetime, jstDate, jstOnUpdateNow } from './columns.js';
 export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-config.js';
 export type { HonoDrizzleConfigOptions, ResolvedDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';

package/dist/db/index.js

@@ -14,8 +14,7 @@ export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './d
 export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
 export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
 export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
-export { coerceDecimalNumber, decimalNumberParams } from './decimal.js';
-export { jstTimestamp, jstDatetime, jstDate, decimalNumber, jstOnUpdateNow } from './columns.js';
+export { jstTimestamp, jstDatetime, jstDate, jstOnUpdateNow } from './columns.js';
 export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';
 export { reopenGuardedPaymentFailedSet } from './payment-failed.js';

package/dist/db/retry.js

@@ -32,8 +32,7 @@ export async function retryWhenDeadlock(fn, retries = 3, delay = 100) {
         if (outcome.ok) {
             return outcome.value;
         }
-        const code = outcome.error.code;
-        if (code === 'ER_LOCK_DEADLOCK' && attempt < retries - 1) {
+        if (isDeadlock(outcome.error) && attempt < retries - 1) {
             await new Promise((resolve) => setTimeout(resolve, delay * (attempt + 1)));
             continue;
         }
@@ -42,3 +41,16 @@ export async function retryWhenDeadlock(fn, retries = 3, delay = 100) {
     // Unreachable: the loop returns on success and throws on the final failed attempt.
     throw new Error('retryWhenDeadlock: exhausted retries');
 }
+function isDeadlock(error) {
+    let current = error;
+    const seen = new Set();
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const value = current;
+        if (value.code === 'ER_LOCK_DEADLOCK') {
+            return true;
+        }
+        current = value.cause;
+    }
+    return false;
+}

package/docs/api-business-time.md

@@ -0,0 +1,33 @@
+# 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. |
+
+```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'
+```

package/docs/api-db.md

@@ -0,0 +1,49 @@
+# API: `@rdlabo/workers-hono-kit/db`
+
+Requires the `drizzle-orm` and `mysql2` peers. Reads use raw SQL against the replica by default, with an explicit primary read path for freshness; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in.
+
+| Export | Description |
+| --- | --- |
+| `createHyperdriveDatabase(options)` | `HyperdriveDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. `read()` targets the replica, `query()` targets the primary, and `readTransaction()` pins raw and Drizzle reads to one primary consistent snapshot. Read transactions are serialized on a separately cached connection and must not be recursively nested. A SELECT or complete read-only transaction is repeated at most once on a fresh connection after a fatal mysql2 connection error. Writes and write transactions are not repeated. Workers cleans connections up at invocation end; the legacy `dispose()` is a no-op. |
+| `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
+| `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. |
+| `Database` / `DisposableDatabase` / `HyperdriveDatabase` / `ReadTransaction` / `QueryRunner` / `TxOf` | The `read` / `query` / `readTransaction` / `write` / `transaction` API and its supporting types. |
+| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. |
+| `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. |
+| `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |
+| `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
+| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). |
+| `MYSQL_TIMEZONE` | Default mysql2 connection `timezone` (`'+09:00'`) for the JST DB deployment. |
+| `jstTimestamp` / `jstDatetime` / `jstDate` | Drizzle column helpers (no repo-side wrapper needed). |
+| `jstOnUpdateNow` | SQL expression for `ON UPDATE CURRENT_TIMESTAMP`. The `jstTimestamp` customType (and friends) do not support `.onUpdateNow()`, so pair it with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`. |
+| `DRIZZLE_ORM_OPTIONS` / `honoDrizzleConfig(options)` / `HonoDrizzleConfigOptions` | Shared Drizzle casing (`snake_case`) for both the runtime `drizzle()` call and `drizzle.config.ts`, keeping config ↔ runtime in sync. |
+| `resolveDbSecret()` / `ResolvedDbSecret` | Resolve DB connection info from the `DB_SECRET` env var (an AWS RDS managed-secret JSON string) for CI migrate / local tooling. Returns `undefined` when `DB_SECRET` is unset; throws on invalid JSON or a missing required key. |
+| `baselineMigrations(options)` / `readBaselineEntry(migrationsFolder)` / `BaselineMigrationsOptions` / `BaselineResult` / `BaselineEntry` | Brownfield first-deploy helper: mark an existing `0000_*` migration as applied without re-running DDL. |
+
+## Drizzle column helpers (`jstTimestamp`, etc.)
+
+- `drizzle-orm` is a **peer** only. The kit does not include `drizzle-orm` as a dependency (even after publishing, it uses the consumer's single copy).
+- The consumer just keeps `drizzle-orm` in its `dependencies` as usual. **No `overrides` in `package.json` are needed.**
+- The npm-published artifact contains no `devDependencies`, so installing it does not add a kit-specific `drizzle-orm` (there is only the one peer copy).
+- The column helpers `import` the consumer's `drizzle-orm` at runtime, and the types are the `customType` inference as-is (`MySqlCustomColumnBuilder<…>`). No `any` is used, so the column's semantic type propagates to the consumer table's `$inferSelect`.
+- **Precondition: resolve drizzle to a single copy.** Drizzle's `SQL` is a **nominal** type carrying a private field `shouldInlineParams`, so if the kit and the consumer resolve different copies, `jstTimestamp(…).default(sql\`…\`)` fails the whole schema with `TS2345 separate declarations of a private property 'shouldInlineParams'`. Under `file:`-link development, `drizzle-orm` nests under the kit and becomes a second copy, so **pin `drizzle-orm` to the consumer's own single copy in `tsconfig.json`**:
+
+  ```jsonc
+  // tsconfig.json compilerOptions (merge with existing paths if any)
+  "paths": {
+    "drizzle-orm": ["./node_modules/drizzle-orm"],
+    "drizzle-orm/*": ["./node_modules/drizzle-orm/*"]
+  }
+  ```
+
+  With `moduleResolution: "Bundler"`, `baseUrl` is not required (if `baseUrl` is already set, drop the leading `./`). On the published package (a single copy) these `paths` are harmless. **No `overrides` needed.**
+- When developing against the kit via a direct `file:` link, run `npm install` in the kit repo itself to satisfy its peers (do not add `overrides` on the consumer side).
+
+## `CURRENT_TIMESTAMP` vs the connection `timezone:'+09:00'`
+
+| Path | Who decides the time | Relationship to JST |
+| --- | --- | --- |
+| The app binds a `Date` (INSERT/UPDATE) | mysql2 + connection `timezone:'+09:00'` | Treated as JST on the wire (`datetime-wire` test) |
+| `DEFAULT CURRENT_TIMESTAMP` / `ON UPDATE CURRENT_TIMESTAMP` | The MySQL server (session `time_zone`) | A **separate path** from the connection option. JST if the RDS `time_zone` is `+09:00`, UTC if UTC |
+
+`jstTimestamp` / `jstDatetime` only handle read/write pass-through and DATE normalization; they do not change the timezone of server-side defaults. For columns that need `ON UPDATE`, keep the DDL intent with `.$onUpdateFn(() => jstOnUpdateNow(6))`.

package/docs/api-offline.md

@@ -0,0 +1,67 @@
+# API: `@rdlabo/workers-hono-kit/offline`
+
+Table-agnostic building blocks for product-owned REST ↔ DB method converters and their offline replica wire values. This subpath does not define table projections, Zod object shapes, public-column allowlists, schema hashes, or domain rules; those remain in each Hono application.
+
+This is an additive subpath: existing root and subpath exports are unchanged. Consumers can migrate converter internals independently without changing REST payloads, schema hashes, or persisted SQLite rows. For an `AUTO_INCREMENT` table, omit `id` from a create method's table scheme; keep the client-generated UUID in `local_id` and keep `server_id` null until the server confirms its id.
+
+| Export | Description |
+| --- | --- |
+| `defineRestDbMethodConverter(converter)` | Type a product-owned, pure `MethodScheme ↔ TableScheme` converter without hiding HTTP or persistence side effects. |
+| `RestDbMethodConverter` | Product-owned converter contract. Select and insert bundles may differ; every represented table and column remains required. |
+| `CompleteRestDbTableScheme` | Compile-time lock requiring every represented table key and row column. |
+| `toReplicaIsoDatetime(value)` | `Date` / datetime string → canonical UTC ISO-8601 wire value. |
+| `toReplicaDateOnly(value)` | `Date` / date string / `null` → canonical `YYYY-MM-DD` / `null`. |
+| `replicaTimestampMs(value)` | Replica datetime → epoch milliseconds for legacy DTOs. |
+| `toTinyIntFlag(value)` / `fromTinyIntFlag(value)` | Boolean-like value ↔ numeric tinyint flag. |
+| `replicaNowIso(clock?)` | Injectable wall clock → canonical UTC ISO-8601 wire value. |
+
+```ts
+import {
+  defineRestDbMethodConverter,
+  replicaNowIso,
+  toReplicaIsoDatetime,
+} from '@rdlabo/workers-hono-kit/offline';
+
+type Tables = {
+  foods: FoodRow[];
+  allergens: AllergenRow[];
+};
+
+export const foodMethodConverter = defineRestDbMethodConverter<FoodMethodScheme, Tables>({
+  toMethodScheme: ({ foods, allergens }) => ({
+    ...foods[0],
+    allergens: allergens.map(({ value }) => value),
+  }),
+  toTableScheme: (method) => ({
+    foods: [{ id: method.id, memo: method.memo ?? null }],
+    allergens: method.allergens.map((value) => ({ threadId: method.id, value })),
+  }),
+});
+```
+
+`toTableScheme` requires every key represented by its DB row types. This includes nullable/default columns that Drizzle marks optional in `$inferInsert`; write `memo: method.memo ?? null` instead of omitting `memo`. If a REST method intentionally does not own an `AUTO_INCREMENT` column, remove it from that method's product-owned table scheme explicitly:
+
+```ts
+type CreateTables = {
+  foods: Omit<typeof foods.$inferInsert, 'id'>[];
+};
+```
+
+The converter then cannot demand or manufacture `id`; the server adds the generated id to the confirmed response before it is stored as `server_id`.
+
+When a write needs authenticated ownership or scope that is intentionally absent from the public REST body, use separate select/insert bundles and an explicit write context. The original two-generic form remains valid.
+
+```ts
+defineRestDbMethodConverter<Method, SelectTables, InsertTables, { userId: number }>({
+  toMethodScheme: ({ foods, allergens }) => composeFood(foods, allergens),
+  toTableScheme: (method, { userId }) => ({
+    foods: [{ userId, name: method.name, memo: method.memo ?? null }],
+    allergens: method.allergens.map((value) => ({ value })),
+  }),
+});
+```
+
+```ts
+replicaNowIso(() => new Date('2026-07-23T10:00:00Z')); // '2026-07-23T10:00:00.000Z'
+toReplicaIsoDatetime('2026-07-23T19:00:00+09:00'); // '2026-07-23T10:00:00.000Z'
+```

package/docs/api-root.md

@@ -0,0 +1,71 @@
+# API: `@rdlabo/workers-hono-kit`
+
+The root export is web-standard only: it runs on `workerd` and never depends on Node.js APIs or `mysql2`. The table below lists the helpers exported from the root entry point.
+
+| Export | Description |
+| --- | --- |
+| `finalizeResponse()` | Middleware that adds a weak `ETag` (delegates to `hono/etag`; also handles `If-None-Match` → `304`). |
+| `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). |
+| `createValidate({ sentry? })` | Bound `validate` factory. Pass `sentry` on Sentry apps; omit for console-only (review, cbs-ai). |
+| `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. |
+| `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
+| `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
+| `getTemporaryCredentials(options)` / `GetTemporaryCredentialsOptions` / `StsCredentials` | STS `AssumeRole` via SigV4 `fetch` (global `sts.amazonaws.com`); returns temporary credentials for browser S3 uploads. |
+| `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
+| `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). |
+| `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). |
+| `createServiceAccountVerifier(serviceAccountJson)` | Cached verifier built from a service-account JSON, **with `IdentityToolkit`** (getUser/deleteUser). One per isolate, re-created only when the SA JSON changes. |
+| `IdentityToolkit` / `ServiceAccount` / `SECURETOKEN_JWK_URL` | Identity Toolkit REST client + constants for `getUser` / `deleteUser`. |
+| `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. |
+| `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). |
+| `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. |
+| `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). |
+| `HttpStatus` | Standard HTTP status code enum (IANA registry). |
+| `createHttpErrorHandler(options?)` / `HttpErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to `{ statusCode, message, error? }` (`401` omits `error`). Optional custom error predicate and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
+| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). |
+| `createQueryFailedErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. |
+| `classifyGenericMysqlDriverError(err)` | Default classifier: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. |
+| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss). |
+| `notFoundHandler(c)` | `app.notFound()` handler with `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
+| `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. |
+| `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. |
+| `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
+| `createIdentityAuthFailureBody()` / `createLegacyIdentityAuthFailureBody()` / `createAuthFailureBody(scope, code, message)` / `AuthFailureScope` | Stable wire contract for distinguishing a lost global identity (`identity`) from recent-login (`reauthentication`) and feature credential (`credential`) failures. The legacy helper tags products whose installed clients still require auth failure as `403`. |
+| `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
+| `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. |
+| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. |
+| `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). |
+| `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: both variants log background rejections without propagating them; `createWaitUntilDefer` also registers work via `ctx.waitUntil`. |
+| `configureHibernationAutoResponse` / `upgradeHibernationWebSocket` / `broadcastHibernationWebSockets` | Hibernation WebSocket room primitives: runtime ping/pong without waking JavaScript, attachment-before-accept upgrade, and broadcast through sockets restored by `getWebSockets()`. |
+| `acknowledgeHibernationWebSocketClose` / `closeHibernationWebSocket` | Safe close helpers, including normalization of reserved received-only close codes. |
+| `retryDurableObjectOperation(operation, options?)` / `isRetryableDurableObjectError(error)` | Retry idempotent DO work only for `retryable && !overloaded`, with jittered exponential backoff. `operation` runs per attempt so callers create a fresh stub after an exception. |
+| `createIdempotencyInput(...)` / `runIdempotentMutation(...)` | Canonical payload hashing and a transaction-bound mutation state machine. Missing keys preserve legacy behavior; replay/conflict/in-flight semantics are shared while each app owns its schema and ORM adapter. |
+| `withIdempotencyHttpErrors(run)` | Maps only standard idempotency failures to 400/409/503 and rethrows unrelated failures. |
+| `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
+| `KVCache` / `KVNamespace` / `KVCacheOptions` / `KVCacheErrorContext` / `KVCacheOperation` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application; optional `onError(error, context)` observes fail-soft read/parse/serialize/write/delete failures. Context contains only the operation and logical table, not cache types, keys, ids, or values. |
+| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
+| `extractStripeFailureReason(source)` / `StripeFailureReason` | Duck-type a Stripe `PaymentIntent` / `Invoice` / `{ paymentIntent?, invoice? }` / thrown error into a normalized `{ code, declineCode, message, paymentIntentId, invoiceId, subscriptionId }` (SDK-free), or `null`. |
+| `stripeFailureMessageJa(reason)` | Render a `StripeFailureReason` (or `null`) as a single user-facing Japanese sentence (`decline_code` > `code`; fraud codes masked; unknown → generic). |
+| `PaymentDeclinedError` / `toPaymentDeclinedError(error, status?)` / `PaymentDeclinedBody` | `HTTPException` carrying a verbatim `{ statusCode, message, code?, declineCode? }` body for a synchronous card decline (defaults to `400`). `toPaymentDeclinedError` returns `null` for non-declines (re-throw → 500). |
+| `classifyStripeReconcile(subscription)` / `StripeReconcileAction` | Classify an expanded Stripe subscription into `trial` / `clear` / `canceled` / `failed` / `action_required` / `none` (termination evaluated before `succeeded`). Consumer does the DB write. |
+| `serializePaymentFailure(record)` / `parsePaymentFailure(receipt)` / `PaymentFailureRecord` / `PaymentFailureReason` / `PaymentFailureSource` | (De)serialize the `payment_failed.receipt` JSON. `parsePaymentFailure` restores both a full Stripe record and a bare IAP reason. |
+| `serializeIapFailureReason(reason)` / `IapFailureReason` | Serialize an IAP reason (`billing_retry` / `auto_renew_off` / `subscription_canceled` / `subscription_gone` + provider codes) directly, without the source/timestamp wrapper. |
+| `paymentFailureMessageJa(input)` / `PaymentFailureStatus` / `PaymentFailureType` / `UNRESOLVED_PAYMENT_STATUSES` | Provider-agnostic Japanese message for a `payment_failed` row (`canceled` re-subscribe prompt, IAP `failed` App Store/Google Play prompt, else Stripe wording). `UNRESOLVED_PAYMENT_STATUSES` = everything except `resolved` for read/resolve `WHERE`. |
+| `iapFailureKey(input)` | Provider-native `payment_failed.recursions_id`: iOS `${original_transaction_id}:${expires_date_ms}`, Android `${orderId}` (provider is in the `type` column). |
+| `verifyAppleReceipt(receipt, opts)` / `classifyAppleRenewal(verify, now)` / `AppleRenewalClassification` / `AppleRenewalState` / `AppleVerifyReceiptResponse` / `ApplePendingRenewalInfo` / `AppleLatestReceiptInfo` | Verify an App Store receipt (production → sandbox fallback; inject `password` / `fetchImpl`) and classify it into `billing_retry` / `lapsed` / `active` / `unknown` plus the raw fields used (`statusCode` / `billingRetryStatus` / `autoRenewStatus`, latest `original_transaction_id` / `expires_date_ms`). |
+| `googleAccessToken(creds, fetch?)` / `getGoogleSubscription(opts)` / `classifyGoogleSubscription(purchase, now)` / `GoogleSubscriptionClassification` / `GoogleSubscriptionState` / `GoogleSubscriptionPurchase` / `GoogleOAuthCredentials` | Exchange a refresh token for an Android Publisher access token (throws on `invalid_grant`), fetch a subscription purchase, and classify it into `canceled` / `gone` / `active` / `unknown` plus raw `statusCode` / `cancelReason`. |
+| `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). |
+| `processBatch(batch, handler, options?)` / `isNonRetryableQueueError(error)` / `NonRetryableQueueErrorLike` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency. Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acked as permanent failures; all other errors are retried. |
+| `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt, except permanent failures which are reported immediately). |
+| `assertStripeCustomerUpdated(options)` | Preserve the shared Stripe UPDATE→existence-check algorithm. `createNotFoundError(customerId)` can supply a domain-specific error without forking the algorithm. |
+| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape used by lifecycle-compatible APIs and deferred work helpers. |
+
+Permanent Queue failures must opt in with the Queue-specific marker; unrelated `retryable` fields are ignored:
+
+```ts
+import type { NonRetryableQueueErrorLike } from '@rdlabo/workers-hono-kit';
+
+class CustomerLinkMissingError extends Error implements NonRetryableQueueErrorLike {
+  readonly queueDisposition = 'discard' as const;
+}
+```

package/docs/api-testing.md

@@ -0,0 +1,16 @@
+# API: `@rdlabo/workers-hono-kit/testing`
+
+Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boilerplate.
+
+| Export | Description |
+| --- | --- |
+| `createTestDb(options)` / `TestDb` / `CreateTestDbOptions` / `TestDbConnection` | Test database built from committed Drizzle migrations as the single source of truth: `resetSchema` / `createTestPool` / `truncateAll` / `seed` / `mysqlReachable`. |
+| `FakeFirebaseVerifier` | In-memory `FirebaseVerifier` for offline route tests (`register` / `verifyIdToken` / `getUser` / `deleteUser`). |
+| `createPoolDatabase(options)` / `CreatePoolDatabaseOptions` | A `Database` backed by a single pool used as both primary and replica. |
+| `createNoopDatabase()` | A `Database` stub that throws on `write` / `transaction` to catch accidental DB use in DB-less routes. |
+| `authHeaders(token, opts?)` | Build interceptor-compatible auth headers for requests. |
+| `registerFirebaseToken(firebase, uid, record?, token?)` | Register a token in a `FakeFirebaseVerifier` (no DB). |
+| `provisionUser(pool, firebase, opts)` | Register a token and provision a conventional `users(id, firebase_uid, agree)` row; returns the user id (idempotent). |
+| `configurableFake(impl, name?)` | Build a test double from a partial implementation; un-stubbed members throw `"${name}.${method} not configured"`. |
+| `fakeApiList` / `fakePaymentIntent` / `fakeStripeEvent` / `fakeCheckoutSession` / `fakeCustomer` / `fakePrice` / `fakeSubscription` | Stripe object fixtures with sensible defaults, overridable per test. |
+| `fakeKv()` / `fakeQueue()` / `FakeQueue` | In-memory Workers KV / Queues producer doubles (`sent` + `batchCount` on queues for subrequest-bound assertions). |

package/docs/api.md

@@ -0,0 +1,12 @@
+# API
+
+`@rdlabo/workers-hono-kit` exposes these entry points. This page maps each entry point to its dedicated reference page. For feature-level examples, see [HTTP and Authentication](./http-auth.md), [Data Layer](./data-layer.md), [Realtime and Offline](./realtime-offline.md), and [Testing and Operations](./testing-operations.md).
+
+| Entry point | Description | Reference |
+| --- | --- | --- |
+| `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV, queues, idempotency). | [Root](./api-root.md) |
+| `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle), JST column helpers, baseline migrations. | [DB](./api-db.md) |
+| `@rdlabo/workers-hono-kit/business-time` | JST business calendar and date-time conversions. | [Business time](./api-business-time.md) |
+| `@rdlabo/workers-hono-kit/offline` | Table-agnostic REST/DB method converters and replica wire helpers. | [Offline](./api-offline.md) |
+| `@rdlabo/workers-hono-kit/realtime` | Durable Object WebSocket and retry helpers. | [Realtime and Offline](./realtime-offline.md) |
+| `@rdlabo/workers-hono-kit/testing` | Drizzle-backed test DB, fakes, fixtures, and binding doubles. | [Testing](./api-testing.md) |