@rdlabo/workers-hono-kit 0.10.6 → 0.11.0

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

@@ -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`.
@@ -161,7 +162,9 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  * 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.
+ * invocation, so callers do not need to close them manually. Replica SELECTs are 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.

package/dist/db/database.js

@@ -30,7 +30,9 @@ export function createMysqlDatabase(options) {
  * 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.
+ * invocation, so callers do not need to close them manually. Replica SELECTs are 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.
@@ -54,12 +56,24 @@ export function createHyperdriveDatabase(options) {
     const primary = () => (primaryConn ??= connect(primaryHyperdrive, connectionOptions));
     const replica = () => (replicaConn ??= connect(replicaHyperdrive, 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;
+    });
     return {
-        read(sql, params = []) {
-            return retryWhenDeadlock(async () => {
-                const [rows] = (await (await replica()).query(sql, params));
-                return rows;
-            });
+        async read(sql, params = []) {
+            const connection = replica();
+            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;
+            }
+            if (replicaConn === connection) {
+                replicaConn = undefined;
+            }
+            return readFrom(replica(), sql, params);
         },
         async write(fn) {
             const dz = await ormFor();
@@ -104,3 +118,16 @@ 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) {
+            return true;
+        }
+        current = value.cause;
+    }
+    return false;
+}

package/dist/db/index.d.ts

@@ -17,9 +17,7 @@ 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/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 run against a replica via raw SQL; 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)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. A replica SELECT is repeated at most once on a fresh connection after a fatal mysql2 connection error; writes and 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` / `QueryRunner` / `TxOf` | The `read` / `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) |

package/docs/cli.md

@@ -0,0 +1,33 @@
+# CLI
+
+The package ships `bin` commands that can be run with `npx` or wired into npm scripts in the consuming app. They are operational helpers: AWS credential sync, subrequest fan-out gating, and brownfield database baselining.
+
+| Command | Use |
+| --- | --- |
+| `workers-hono-kit-sync-dev-aws <wrangler-args…>` | Launch `wrangler` with AWS credentials injected as `--var`, resolved from the active AWS profile (honors `AWS_PROFILE`, supports short-lived SSO/temporary creds). Nothing is written to disk — replaces `.dev.vars`. Wire it as the `dev` script, e.g. `AWS_PROFILE=<p> workers-hono-kit-sync-dev-aws dev --var APP_ENV:development`. |
+| `workers-hono-kit-check-subrequest-fanout [dir…]` | CI gate that greps for per-item external-call fan-outs (`runWithConcurrency(` / `PromisePool` / `.withConcurrency(`) that would eventually exceed the Workers subrequest cap. Annotate a genuinely-safe site with `subrequest-ok`. Scans `src` by default; exits 1 on an un-annotated marker. |
+| `workers-hono-kit-db-baseline [--migrations ./drizzle]` | Brownfield first-deploy helper: record the baseline `0000` migration as *already applied* on an existing MySQL DB without running its DDL (the CLI wrapper around `baselineMigrations` / `readBaselineEntry`). Reads DB credentials from `DB_SECRET` (AWS RDS managed secret) or the individual `DB_*` env vars. |
+
+## `workers-hono-kit-sync-dev-aws`
+
+Use this in the `dev` npm script when you want AWS credentials from the active profile to be available inside `wrangler dev` without committing them to `.dev.vars`. It resolves short-lived SSO or temporary credentials and passes them as `--var` arguments. Nothing is written to disk.
+
+```bash
+AWS_PROFILE=my-sso-profile workers-hono-kit-sync-dev-aws dev --var APP_ENV:development
+```
+
+## `workers-hono-kit-check-subrequest-fanout`
+
+Run this in CI to catch per-item external call patterns (for example `runWithConcurrency`, `PromisePool`, or `.withConcurrency`) that could fan out beyond the Workers subrequest cap. If a call site is safe, annotate it with `subrequest-ok`. The command scans `src` by default and exits with `1` if it finds an un-annotated marker.
+
+```bash
+workers-hono-kit-check-subrequest-fanout src
+```
+
+## `workers-hono-kit-db-baseline`
+
+Use this for a brownfield first deploy against a MySQL database that already matches the schema in your first migration (`0000_*`). It records that migration as already applied without running its DDL, so later migrations can apply normally. Database credentials are read from `DB_SECRET` (an AWS RDS managed-secret JSON string) or from individual `DB_*` environment variables.
+
+```bash
+workers-hono-kit-db-baseline --migrations ./drizzle
+```

package/docs/data-layer.md

@@ -0,0 +1,44 @@
+Import database helpers from `@rdlabo/workers-hono-kit/db`. This entry point requires `drizzle-orm` and `mysql2`.
+
+## Hyperdrive database
+
+`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. Reads use the replica query runner; writes and transactions use the primary Drizzle instance. After a fatal mysql2 connection error, a replica read opens a fresh connection and repeats the SELECT at most once. Writes and transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
+
+```ts
+import { createHyperdriveDatabase } from '@rdlabo/workers-hono-kit/db';
+import { drizzle } from 'drizzle-orm/mysql2';
+
+const db = createHyperdriveDatabase({
+  primaryHyperdrive: env.DB_PRIMARY,
+  replicaHyperdrive: env.DB_REPLICA,
+  createOrm: (primary) => drizzle(primary, { schema }),
+});
+
+const rows = await db.read<Item>('SELECT * FROM items WHERE id = ?', [id]);
+await db.write((dz) => dz.insert(items).values(input));
+await db.transaction((tx) => tx.insert(items).values(input));
+```
+
+Use `hyperdriveConnectionOptions()` when constructing lower-level mysql2 connections. The default JavaScript date conversion timezone is `+09:00`; it does not change the MySQL session timezone.
+
+## Writes and retries
+
+- `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with exponential backoff.
+- `insertIdOf()`, `affectedRowsOf()`, and `insertedIdsOf()` normalize mysql2 write results.
+- `withMysqlConnections()` opens primary and replica connections in parallel for a scoped operation.
+
+## Drizzle and JST helpers
+
+Use `jstTimestamp`, `jstDatetime`, and `jstDate` for shared date behavior. Pair update timestamps with `jstOnUpdateNow()` because custom timestamp types do not expose Drizzle's `.onUpdateNow()`. For decimal columns, use Drizzle's `decimal(name, { precision, scale, mode: 'number' })` directly.
+
+The `/business-time` entry point converts instants and business dates in the JST business timezone:
+
+```ts
+import { addBusinessDays, toBusinessDateTime } from '@rdlabo/workers-hono-kit/business-time';
+
+toBusinessDateTime(new Date('2026-07-05T21:00:00Z'));
+// '2026-07-06 06:00:00'
+
+addBusinessDays('2026-07-06', 3);
+// '2026-07-09'
+```

package/docs/development.md

@@ -0,0 +1,32 @@
+# Development
+
+These commands are used when working on the package itself:
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm test            # vitest
+npm run build       # tsc -p tsconfig.build.json → dist/
+```
+
+## Local development / linking
+
+If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "zod": ["node_modules/zod"],
+      "zod/*": ["node_modules/zod/*"],
+      "@hono/zod-validator": ["node_modules/@hono/zod-validator"]
+    }
+  }
+}
+```
+
+When installed from npm normally, package managers dedupe `zod` to a single copy and this is not 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).

package/docs/http-auth.md

@@ -0,0 +1,36 @@
+## Validation
+
+`validate(target, schema, options?)` adapts a Zod schema to Hono and returns a NestJS `ValidationPipe`-shaped `400` response. Use `createValidate({ sentry })` to bind optional reporting once.
+
+```ts
+import { createValidate, zNumOptional } from '@rdlabo/workers-hono-kit';
+import { z } from 'zod';
+
+const validate = createValidate({ sentry });
+const querySchema = z.object({ page: zNumOptional() });
+
+app.get('/items', validate('query', querySchema), async (c) => {
+  const query = c.req.valid('query');
+  return c.json(await listItems(query.page));
+});
+```
+
+## Authentication
+
+`createAuthMiddleware()` reads a token header, verifies a Firebase ID token, optionally resolves the application user ID, and stores the result on the Hono context. Use `createRemoteFirebaseVerifier(projectId)` for cached remote JWKS verification or `createServiceAccountVerifier()` when Identity Toolkit `getUser` and `deleteUser` operations are required.
+
+Keep identity, reauthentication, and feature credential failures distinct with the stable auth-failure body helpers.
+
+## Error and routing contracts
+
+- `createAppErrorHandler()` composes query failure classification, generic mysql2 classification, and optional reporting.
+- `createHttpErrorHandler()` maps `HTTPException` to the shared JSON error body.
+- `notFoundHandler()` returns `Cannot METHOD path` with a 404 status.
+- `normalizeTrailingSlash()` removes trailing slashes without redirecting, preserving request bodies.
+- `finalizeResponse()` adds weak ETags and handles matching `If-None-Match` requests.
+
+Mount `createMaintenanceMiddleware()` after CORS and before container or database middleware so maintenance responses do not initialize expensive infrastructure.
+
+## Deferred work and observability
+
+`createWaitUntilDefer(ctx)` registers background work through `waitUntil` and logs rejected work. `perfLog()` emits per-request application latency, colo, cold/warm state, route, and status to Workers Logs and optionally Analytics Engine.

package/docs/realtime-offline.md

@@ -0,0 +1,27 @@
+## Durable Object realtime
+
+The root and `/realtime` entry points expose the same focused realtime primitives:
+
+- `configureHibernationAutoResponse()` configures runtime ping/pong without waking JavaScript.
+- `upgradeHibernationWebSocket()` attaches state before accepting the socket.
+- `broadcastHibernationWebSockets()` broadcasts through sockets restored by `getWebSockets()`.
+- `acknowledgeHibernationWebSocketClose()` and `closeHibernationWebSocket()` normalize close handling.
+- `retryDurableObjectOperation()` retries only errors marked `retryable` and not `overloaded`. Create a fresh stub inside the operation for every attempt.
+- `invokeDurableObjectFetch()` preserves the structured response/error contract for DO calls.
+
+WebSocket protocol parsers validate offered subprotocols before upgrade.
+
+## Offline replica contracts
+
+`@rdlabo/workers-hono-kit/offline` is table-agnostic. Product schemas, Zod objects, public-column allowlists, schema hashes, and domain policy stay in the application.
+
+`defineRestDbMethodConverter()` types a pure REST method ↔ table converter. Every represented table and column is required, including nullable/default columns. Omit an auto-increment `id` from the product-owned table scheme when a create method intentionally does not own it.
+
+Wire helpers canonicalize values:
+
+- `toReplicaIsoDatetime()` → UTC ISO-8601
+- `toReplicaDateOnly()` → `YYYY-MM-DD` or `null`
+- `toTinyIntFlag()` / `fromTinyIntFlag()` → boolean/tinyint conversion
+- `replicaNowIso(clock?)` → injectable current time
+
+Journal helpers enforce cursor coverage, retention, mutation transactions, and rebaseline behavior. Wire compatibility helpers let an application accept explicit previous fingerprints while maintaining a canonical current fingerprint.