@rdlabo/workers-hono-kit 0.4.2 → 0.5.0

package/README.md

@@ -35,13 +35,13 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 > **Compiled ESM, with types.** The package is published as compiled ES modules (`./dist/*.js`) plus
 > declaration files (`./dist/*.d.ts`) via the `exports` field. It depends only on Web-standard APIs
 > (`fetch`, `crypto.subtle`, `Response`) available on Cloudflare Workers (`workerd`) and other edge
-> runtimes, and requires Node.js ≥ 20 for tooling. Three entry points are exposed:
+> runtimes, and requires Node.js ≥ 20 for tooling. Four entry points are exposed:
 >
 > | Subpath | Import | Use |
 > | --- | --- | --- |
 > | `.` | `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV). |
 > | `./db` | `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle). |
-> | `./business-time` | `@rdlabo/workers-hono-kit/business-time` | JST 業務時刻 API（`toBusinessDateTime` / `normalizeBusinessDate` 等）。 |
+> | `./business-time` | `@rdlabo/workers-hono-kit/business-time` | JST business-time API (`toBusinessDateTime` / `normalizeBusinessDate` / `formatBusinessDateTime`, etc.). |
 > | `./testing` | `@rdlabo/workers-hono-kit/testing` | Test helpers (mysql2 + Drizzle + fakes/fixtures). |
 
 ## API
@@ -65,16 +65,19 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `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` | HTTP status enum identical to NestJS `@nestjs/common`. |
-| `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. |
+| `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
+| `createQueryFailedNestErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Compose a NestJS `QueryFailedExceptionFilter` analog **before** `createNestErrorHandler`: consumer supplies `classify(err)` (parity-critical messages stay in the app); classified DB errors log (`warn` for 400, `error` for 500) and trigger `onUnhandledError` on 500 only. |
+| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` / `reportClassifiedDbError(...)` | Low-level mysql2 driver-error detection (follows `err.cause`), structured logging, and classify-path reporting helpers. |
 | `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ 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. |
 | `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason 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. |
+| `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`. |
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
 | `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` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
-| `sendInChunks(queue, messages, chunkSize?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. |
+| `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?)` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency (consumer-side counterpart to `sendInChunks`). |
 | `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape (for `withMysqlConnections` in worker entry modules without importing `./db`). |
 
@@ -88,45 +91,83 @@ Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via r
 | `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). |
+| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `ExecutionContextLike` is the same type as the root export, re-exported here so `withMysqlConnections` callers don't need the root import. |
 | `withMysqlConnections(...)` | Open primary/replica connections, run a function, close them in `finally` (via `ctx.waitUntil`). |
 | `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（高度な用途）。 |
-| `jstTimestamp` / `jstDatetime` / `jstDate` / `decimalNumber` | Drizzle 列ヘルパー（repo 側ラッパー不要）。 |
-| `jstOnUpdateNow` | `ON UPDATE CURRENT_TIMESTAMP` 用 SQL 式。`jstTimestamp` 等の customType は `.onUpdateNow()` 非対応のため `.$onUpdateFn(() => jstOnUpdateNow(fsp))` と併用。 |
-| `coerceDecimalNumber` / `decimalNumberParams` | DECIMAL 正規化 params（通常は `decimalNumber` 列ヘルパーで十分）。 |
+| `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` / `decimalNumber` | 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))`. |
+| `coerceDecimalNumber` / `decimalNumberParams` | DECIMAL normalization params (the `decimalNumber` column helper is usually enough). |
 | `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(options, secretId?)` / `ResolvedDbSecret` | Resolve RDS-managed or plain DB credentials from AWS Secrets Manager for CI migrate / local tooling. |
+| `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 列ヘルパー（`jstTimestamp` / `decimalNumber` 等）
+#### Drizzle column helpers (`jstTimestamp` / `decimalNumber`, etc.)
 
-- `drizzle-orm` は **peer** のみ。kit は `drizzle-orm` を依存に含めない（publish 後も consumer の 1 本を使う）。
-- consumer は通常どおり `drizzle-orm` を `dependencies` に置くだけでよい。**`package.json` の `overrides` は不要**。
-- npm publish 物には `devDependencies` は含まれないため、インストール先で kit 専用の `drizzle-orm` は増えない（peer の 1 本のみ）。
-- 列ヘルパーは runtime で consumer の `drizzle-orm` を `import` し、型は `customType` 推論そのまま（`MySqlCustomColumnBuilder<…>`）。`any` は使わないので consumer テーブルの `$inferSelect` に列の意味型が伝播する。
-- **前提: drizzle を単一コピーに解決すること。** drizzle の `SQL` は private フィールド `shouldInlineParams` を持つ**名目型**で、kit と consumer が別コピーを解決すると `jstTimestamp(…).default(sql\`…\`)` が `TS2345 separate declarations of a private property 'shouldInlineParams'` で全 schema 落ちする。`file:` リンク開発では kit 配下に `drizzle-orm` がネストして二重コピーになるため、**consumer の `tsconfig.json` で `drizzle-orm` を自身の 1 コピーへ固定**する:
+- `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（既存 paths があればマージ）
+  // tsconfig.json compilerOptions (merge with existing paths if any)
   "paths": {
     "drizzle-orm": ["./node_modules/drizzle-orm"],
     "drizzle-orm/*": ["./node_modules/drizzle-orm/*"]
   }
   ```
 
-  `moduleResolution: "Bundler"` なら `baseUrl` 不要（`baseUrl` 設定済みなら先頭 `./` は外す）。published 版（単一コピー）ではこの `paths` は無害。**overrides は不要。**
-- `file:` で kit を直リンクする開発では、kit リポジトリ側で `npm install` して peer を満たす（consumer 側で overrides を足さない）。
+  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` と接続 `timezone:'+09:00'` の違い**
+**`CURRENT_TIMESTAMP` vs the connection `timezone:'+09:00'`**
 
-| 経路 | 誰が時刻を決めるか | JST との関係 |
+| Path | Who decides the time | Relationship to JST |
 | --- | --- | --- |
-| アプリが `Date` を bind（INSERT/UPDATE） | mysql2 + 接続 `timezone:'+09:00'` | ワイヤ上は JST として扱われる（`datetime-wire` テスト） |
-| `DEFAULT CURRENT_TIMESTAMP` / `ON UPDATE CURRENT_TIMESTAMP` | MySQL サーバ（セッション `time_zone`） | 接続オプションとは**別経路**。RDS の `time_zone` が `+09:00` なら JST、UTC なら UTC |
+| 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` は読書の pass-through と DATE 正規化のみ担当し、DB 既定値の時刻帯は変えない。`ON UPDATE` が必要な列は `.$onUpdateFn(() => jstOnUpdateNow(6))` で DDL 意図を維持する。
+`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))`.
+
+### Business time — `@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'
+```
 
 ### Testing — `@rdlabo/workers-hono-kit/testing`
 
@@ -259,6 +300,24 @@ app.onError(
 );
 ```
 
+**Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Wire
+`onUnhandledError` → `Sentry.captureException` explicitly (mirrors Nest `SentryGlobalFilter`).
+
+Repos with a Nest `QueryFailedExceptionFilter` (e.g. odss-mobile) should use
+`createQueryFailedNestErrorHandler` so classified DB errors still log and report to Sentry:
+
+```ts
+import { createQueryFailedNestErrorHandler } from '@rdlabo/workers-hono-kit';
+
+app.onError(
+  createQueryFailedNestErrorHandler({
+    fieldOrder: 'message-first',
+    classify: classifyQueryFailed, // app-local parity (Japanese messages, errno rules)
+    onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') }),
+  }),
+);
+```
+
 ### Auth middleware
 
 Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →
@@ -291,6 +350,47 @@ const tokenAuth = createAuthMiddleware<AppEnv, UserRecord>({
 });
 ```
 
+### Latency instrumentation (`perfLog`)
+
+Records one data point per request — `t_app` (time inside the app), `colo`, `cold`/`warm`, matched
+route, `status` — and ships it to **Workers Logs** and/or **Workers Analytics Engine**. This lets you
+measure a low-traffic Worker after the fact (retained + queryable) instead of watching a live
+`wrangler tail`. Register it first so it wraps everything.
+
+```ts
+import { perfLog } from '@rdlabo/workers-hono-kit';
+
+// A) app served with env (`app.fetch(req, env, ctx)`): bare — reads `PERF` (Analytics Engine
+//    dataset binding) and `PERF_LOG === '1'` (Workers Logs) off `c.env`.
+app.use('*', perfLog());
+
+// B) app built without Hono env (`createApp(container).fetch(req)`): pass bindings explicitly.
+app.use('*', perfLog({ console: env.PERF_LOG === '1', dataset: env.PERF }));
+```
+
+```toml
+# wrangler.toml — dataset is created on first write (no provisioning); needs [observability] for Logs.
+[[analytics_engine_datasets]]
+binding = "PERF"
+dataset = "myapp_perf"
+```
+
+Query percentiles by route/colo with the Analytics Engine SQL API:
+
+```sql
+SELECT blob1 AS path, blob2 AS colo,
+       quantileWeighted(0.5)(double1, _sample_interval) AS p50,
+       quantileWeighted(0.9)(double1, _sample_interval) AS p90
+FROM myapp_perf WHERE timestamp > now() - INTERVAL '7' DAY
+GROUP BY path, colo ORDER BY p90 DESC
+```
+
+> **Scope of `t_app`**: it covers everything *inside* the app; work done in `fetch` *before* the app
+> (e.g. secrets fetch / DB connect in `createApp(container)` vs. building the container in `fetch`) is
+> not comparable across differently-wired apps. Instrument the `fetch` seam if you need a secrets/connect
+> cold breakdown. On production Workers `Date.now()` only advances at I/O boundaries, so `t_app` ≈ I/O
+> wait, not CPU time.
+
 ### AI Gateway
 
 Route `@ai-sdk` models through the Cloudflare AI Gateway — either with a Workers `AI` binding
@@ -363,7 +463,7 @@ await testDb.resetSchema();
 const pool = testDb.createTestPool();
 
 const firebase = new FakeFirebaseVerifier();
-firebase.register('uid-1', { email: 'a@example.com' });
+firebase.register('token-1', { uid: 'uid-1', email: 'a@example.com' });
 
 const gateway = configurableFake<PaymentGateway>({ charge: async () => ({ ok: true }) }, 'PaymentGateway');
 ```
@@ -387,6 +487,16 @@ If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit":
 
 When installed from npm normally, package managers dedupe `zod` to a single copy and this is not needed.
 
+## CLI
+
+The package ships three `bin` commands (run via `npx` or an npm script in the consuming app):
+
+| 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. |
+
 ## Development
 
 ```bash

package/dist/business-time/index.d.ts

@@ -1,49 +1,126 @@
 /**
- * JST 業務時刻の明示 API（Workers UTC instant ↔ 業務暦日/日時）。
+ * Explicit JST business-time API (Workers UTC instant ↔ business calendar date / date-time).
  *
  * @remarks
- * - DB は JST 運用のまま。アプリは mysql2 `timezone` に暗黙依存せず、ここ経由で JST を扱う。
- * - MySQL ワイヤ形式への変換は {@link ../db/jst.js | db/jst} の責務。
- * - `Date` の local getter（`getHours` 等）は業務判定に使わない。
+ * - The DB stays on JST. The app does not implicitly rely on the mysql2 `timezone` option; it goes
+ *   through this module to handle JST.
+ * - Converting to the MySQL wire format is the responsibility of {@link ../db/jst.js | db/jst}.
+ * - Do not use a `Date`'s local getters (`getHours`, etc.) for business-time decisions.
  *
  * @packageDocumentation
  */
 import { BUSINESS_TIMEZONE } from './types.js';
 import type { BusinessDate, BusinessDateTime } from './types.js';
 export { BUSINESS_TIMEZONE, type BusinessDate, type BusinessDateTime };
-/** 参照 instant の JST 業務暦日。 */
+/**
+ * The JST business calendar date of a reference instant.
+ *
+ * @param ref - the instant to read; defaults to now.
+ * @returns the business date as `YYYY-MM-DD`.
+ * @example
+ * today(new Date('2026-07-05T20:00:00Z')); // → '2026-07-06' (JST)
+ */
 export declare function today(ref?: Date): BusinessDate;
-/** UTC instant → JST 業務暦日。 */
+/**
+ * Convert a UTC instant to a JST business calendar date.
+ *
+ * @param instant - the UTC instant to convert.
+ * @returns the business date as `YYYY-MM-DD`.
+ */
 export declare function toBusinessDate(instant: Date): BusinessDate;
 /**
- * クライアント / DB 入力を JST 業務暦日 `YYYY-MM-DD` へ正規化する。
+ * Normalize a client / DB input to a JST business calendar date `YYYY-MM-DD`.
+ *
+ * - A string already in `YYYY-MM-DD` form is returned as-is, **without** constructing a `Date`
+ *   (a birthday is a calendar day, not an instant).
+ * - ISO 8601 and similar values are converted to a JST calendar date via their instant.
+ * - Nullish / empty / invalid inputs yield `null`.
  *
- * - 既に `YYYY-MM-DD` の文字列は **Date 化せず**そのまま返す（誕生日は instant ではない）。
- * - ISO 8601 等は instant 経由で JST 暦日へ変換。
- * - nullish / 空 / 不正は `null`。
+ * @param value - the string, `Date`, or nullish value to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
+ * @example
+ * normalizeBusinessDate('1990-01-15');            // → '1990-01-15' (unchanged)
+ * normalizeBusinessDate('2026-07-05T20:00:00Z');  // → '2026-07-06' (JST)
+ * normalizeBusinessDate('');                       // → null
  */
 export declare function normalizeBusinessDate(value: string | Date | null | undefined): BusinessDate | null;
-/** UTC instant → JST 業務日時（`YYYY-MM-DD HH:mm:ss`）。 */
+/**
+ * Convert a UTC instant to a JST business date-time (`YYYY-MM-DD HH:mm:ss`).
+ *
+ * @param instant - the UTC instant to convert.
+ * @returns the business date-time string.
+ * @example
+ * toBusinessDateTime(new Date('2026-07-05T21:00:00Z')); // → '2026-07-06 06:00:00' (JST)
+ */
 export declare function toBusinessDateTime(instant: Date): BusinessDateTime;
-/** Nest / foodlabel / winecode `helper.formatDate` 既定パターン。 */
+/** Default pattern for the Nest / foodlabel / winecode `helper.formatDate`. */
 export declare const DEFAULT_BUSINESS_DATETIME_PATTERN: "YYYY-MM-DDThh:mm:ss";
 /**
- * Nest `helper.formatDate` 互換のパターン整形（業務 TZ）。
- * `S` トークンは元 instant のミリ秒（Nest 正本）。
+ * Format an instant in the business TZ, compatible with the Nest `helper.formatDate`.
+ *
+ * Supported tokens: `YYYY` / `MM` / `DD` / `hh` / `mm` / `ss`, plus `S` for the source instant's
+ * milliseconds (matching the Nest reference implementation).
+ *
+ * @param instant - the UTC instant to format.
+ * @param pattern - the format pattern; defaults to {@link DEFAULT_BUSINESS_DATETIME_PATTERN}.
+ * @returns the formatted string.
+ * @example
+ * formatBusinessDateTime(new Date('2026-07-05T21:00:00Z')); // → '2026-07-06T06:00:00' (JST)
  */
 export declare function formatBusinessDateTime(instant: Date, pattern?: string): string;
-/** JST 業務日時文字列 → UTC instant。`YYYY-MM-DD HH:mm:ss` / `T` 区切りを受け付ける。 */
+/**
+ * Parse a JST business date-time string into a UTC instant. Accepts a space or `T` separator
+ * (`YYYY-MM-DD HH:mm:ss` or `YYYY-MM-DDTHH:mm:ss`).
+ *
+ * @param value - the business date-time string to parse.
+ * @returns the corresponding UTC instant.
+ * @throws RangeError when `value` is not a valid business date-time.
+ * @example
+ * parseBusinessDateTime('2026-07-06 06:00:00'); // → 2026-07-05T21:00:00Z
+ */
 export declare function parseBusinessDateTime(value: BusinessDateTime): Date;
-/** JST 業務暦日の 00:00:00 を表す UTC instant。 */
+/**
+ * The UTC instant of `00:00:00` on a JST business calendar date.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @returns the UTC instant at the start of that business day.
+ */
 export declare function startOfBusinessDay(date: BusinessDate): Date;
-/** JST 業務暦日の 23:59:59 を表す UTC instant。 */
+/**
+ * The UTC instant of `23:59:59` on a JST business calendar date.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @returns the UTC instant at the end of that business day.
+ */
 export declare function endOfBusinessDay(date: BusinessDate): Date;
 /**
- * JST 業務暦日 + 壁時計時刻 → UTC instant。
- * @example businessDateTimeInstant('2026-07-05', '06:00:00')
+ * Convert a JST business calendar date + wall-clock time to a UTC instant.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @param time - the wall-clock time as `HH:mm:ss` (or `HH:mm`).
+ * @returns the corresponding UTC instant.
+ * @throws RangeError when `date` or `time` is malformed.
+ * @example
+ * businessDateTimeInstant('2026-07-06', '06:00:00'); // → 2026-07-05T21:00:00Z
  */
 export declare function businessDateTimeInstant(date: BusinessDate, time: string): Date;
-/** JST 業務暦日に日数を加算（暦日単位）。 */
+/**
+ * Add a number of calendar days to a JST business calendar date.
+ *
+ * @param date - the starting business date as `YYYY-MM-DD`.
+ * @param days - the number of calendar days to add (may be negative).
+ * @returns the resulting business date as `YYYY-MM-DD`.
+ * @example
+ * addBusinessDays('2026-07-06', 3); // → '2026-07-09'
+ */
 export declare function addBusinessDays(date: BusinessDate, days: number): BusinessDate;
-/** 業務暦日基準の満年齢（誕生日は instant ではなく BusinessDate）。 */
+/**
+ * The full years of age on a business calendar date (a birthday is a `BusinessDate`, not an instant).
+ *
+ * @param birthDate - the birth date as `YYYY-MM-DD`.
+ * @param asOfDate - the reference business date; defaults to {@link today}.
+ * @returns the age in completed years.
+ * @example
+ * ageOnBusinessDate('1990-07-10', '2026-07-06'); // → 35
+ */
 export declare function ageOnBusinessDate(birthDate: BusinessDate, asOfDate?: BusinessDate): number;

package/dist/business-time/index.js

@@ -1,17 +1,18 @@
 /**
- * JST 業務時刻の明示 API（Workers UTC instant ↔ 業務暦日/日時）。
+ * Explicit JST business-time API (Workers UTC instant ↔ business calendar date / date-time).
  *
  * @remarks
- * - DB は JST 運用のまま。アプリは mysql2 `timezone` に暗黙依存せず、ここ経由で JST を扱う。
- * - MySQL ワイヤ形式への変換は {@link ../db/jst.js | db/jst} の責務。
- * - `Date` の local getter（`getHours` 等）は業務判定に使わない。
+ * - The DB stays on JST. The app does not implicitly rely on the mysql2 `timezone` option; it goes
+ *   through this module to handle JST.
+ * - Converting to the MySQL wire format is the responsibility of {@link ../db/jst.js | db/jst}.
+ * - Do not use a `Date`'s local getters (`getHours`, etc.) for business-time decisions.
  *
  * @packageDocumentation
  */
 import { BUSINESS_TIMEZONE } from './types.js';
 export { BUSINESS_TIMEZONE };
 const pad2 = (n) => String(n).padStart(2, '0');
-/** instant を業務 TZ 壁時計として読むためのシフト（`getUTC*` で成分を得る）。 */
+/** Shift an instant so it can be read as a business-TZ wall clock (extract fields with `getUTC*`). */
 function toWallClock(instant) {
     return new Date(instant.getTime() + BUSINESS_TIMEZONE.offsetMinutes * 60_000);
 }
@@ -29,21 +30,41 @@ function parseHms(time) {
     }
     return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
 }
-/** 参照 instant の JST 業務暦日。 */
+/**
+ * The JST business calendar date of a reference instant.
+ *
+ * @param ref - the instant to read; defaults to now.
+ * @returns the business date as `YYYY-MM-DD`.
+ * @example
+ * today(new Date('2026-07-05T20:00:00Z')); // → '2026-07-06' (JST)
+ */
 export function today(ref = new Date()) {
     return toBusinessDate(ref);
 }
-/** UTC instant → JST 業務暦日。 */
+/**
+ * Convert a UTC instant to a JST business calendar date.
+ *
+ * @param instant - the UTC instant to convert.
+ * @returns the business date as `YYYY-MM-DD`.
+ */
 export function toBusinessDate(instant) {
     const wall = toWallClock(instant);
     return `${wall.getUTCFullYear()}-${pad2(wall.getUTCMonth() + 1)}-${pad2(wall.getUTCDate())}`;
 }
 /**
- * クライアント / DB 入力を JST 業務暦日 `YYYY-MM-DD` へ正規化する。
+ * Normalize a client / DB input to a JST business calendar date `YYYY-MM-DD`.
+ *
+ * - A string already in `YYYY-MM-DD` form is returned as-is, **without** constructing a `Date`
+ *   (a birthday is a calendar day, not an instant).
+ * - ISO 8601 and similar values are converted to a JST calendar date via their instant.
+ * - Nullish / empty / invalid inputs yield `null`.
  *
- * - 既に `YYYY-MM-DD` の文字列は **Date 化せず**そのまま返す（誕生日は instant ではない）。
- * - ISO 8601 等は instant 経由で JST 暦日へ変換。
- * - nullish / 空 / 不正は `null`。
+ * @param value - the string, `Date`, or nullish value to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
+ * @example
+ * normalizeBusinessDate('1990-01-15');            // → '1990-01-15' (unchanged)
+ * normalizeBusinessDate('2026-07-05T20:00:00Z');  // → '2026-07-06' (JST)
+ * normalizeBusinessDate('');                       // → null
  */
 export function normalizeBusinessDate(value) {
     if (value == null) {
@@ -72,16 +93,31 @@ export function normalizeBusinessDate(value) {
     }
     return toBusinessDate(new Date(ms));
 }
-/** UTC instant → JST 業務日時（`YYYY-MM-DD HH:mm:ss`）。 */
+/**
+ * Convert a UTC instant to a JST business date-time (`YYYY-MM-DD HH:mm:ss`).
+ *
+ * @param instant - the UTC instant to convert.
+ * @returns the business date-time string.
+ * @example
+ * toBusinessDateTime(new Date('2026-07-05T21:00:00Z')); // → '2026-07-06 06:00:00' (JST)
+ */
 export function toBusinessDateTime(instant) {
     const wall = toWallClock(instant);
     return `${wall.getUTCFullYear()}-${pad2(wall.getUTCMonth() + 1)}-${pad2(wall.getUTCDate())} ${pad2(wall.getUTCHours())}:${pad2(wall.getUTCMinutes())}:${pad2(wall.getUTCSeconds())}`;
 }
-/** Nest / foodlabel / winecode `helper.formatDate` 既定パターン。 */
+/** Default pattern for the Nest / foodlabel / winecode `helper.formatDate`. */
 export const DEFAULT_BUSINESS_DATETIME_PATTERN = 'YYYY-MM-DDThh:mm:ss';
 /**
- * Nest `helper.formatDate` 互換のパターン整形（業務 TZ）。
- * `S` トークンは元 instant のミリ秒（Nest 正本）。
+ * Format an instant in the business TZ, compatible with the Nest `helper.formatDate`.
+ *
+ * Supported tokens: `YYYY` / `MM` / `DD` / `hh` / `mm` / `ss`, plus `S` for the source instant's
+ * milliseconds (matching the Nest reference implementation).
+ *
+ * @param instant - the UTC instant to format.
+ * @param pattern - the format pattern; defaults to {@link DEFAULT_BUSINESS_DATETIME_PATTERN}.
+ * @returns the formatted string.
+ * @example
+ * formatBusinessDateTime(new Date('2026-07-05T21:00:00Z')); // → '2026-07-06T06:00:00' (JST)
  */
 export function formatBusinessDateTime(instant, pattern = DEFAULT_BUSINESS_DATETIME_PATTERN) {
     const wall = toWallClock(instant);
@@ -102,7 +138,16 @@ export function formatBusinessDateTime(instant, pattern = DEFAULT_BUSINESS_DATET
     }
     return out;
 }
-/** JST 業務日時文字列 → UTC instant。`YYYY-MM-DD HH:mm:ss` / `T` 区切りを受け付ける。 */
+/**
+ * Parse a JST business date-time string into a UTC instant. Accepts a space or `T` separator
+ * (`YYYY-MM-DD HH:mm:ss` or `YYYY-MM-DDTHH:mm:ss`).
+ *
+ * @param value - the business date-time string to parse.
+ * @returns the corresponding UTC instant.
+ * @throws RangeError when `value` is not a valid business date-time.
+ * @example
+ * parseBusinessDateTime('2026-07-06 06:00:00'); // → 2026-07-05T21:00:00Z
+ */
 export function parseBusinessDateTime(value) {
     const normalized = value.includes('T') ? value.replace('T', ' ') : value;
     const m = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/.exec(normalized);
@@ -113,17 +158,33 @@ export function parseBusinessDateTime(value) {
     const offsetHours = BUSINESS_TIMEZONE.offsetMinutes / 60;
     return new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h) - offsetHours, Number(mi), Number(s), 0));
 }
-/** JST 業務暦日の 00:00:00 を表す UTC instant。 */
+/**
+ * The UTC instant of `00:00:00` on a JST business calendar date.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @returns the UTC instant at the start of that business day.
+ */
 export function startOfBusinessDay(date) {
     return businessDateTimeInstant(date, '00:00:00');
 }
-/** JST 業務暦日の 23:59:59 を表す UTC instant。 */
+/**
+ * The UTC instant of `23:59:59` on a JST business calendar date.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @returns the UTC instant at the end of that business day.
+ */
 export function endOfBusinessDay(date) {
     return businessDateTimeInstant(date, '23:59:59');
 }
 /**
- * JST 業務暦日 + 壁時計時刻 → UTC instant。
- * @example businessDateTimeInstant('2026-07-05', '06:00:00')
+ * Convert a JST business calendar date + wall-clock time to a UTC instant.
+ *
+ * @param date - the business date as `YYYY-MM-DD`.
+ * @param time - the wall-clock time as `HH:mm:ss` (or `HH:mm`).
+ * @returns the corresponding UTC instant.
+ * @throws RangeError when `date` or `time` is malformed.
+ * @example
+ * businessDateTimeInstant('2026-07-06', '06:00:00'); // → 2026-07-05T21:00:00Z
  */
 export function businessDateTimeInstant(date, time) {
     const [y, mo, d] = parseYmd(date);
@@ -131,12 +192,28 @@ export function businessDateTimeInstant(date, time) {
     const offsetHours = BUSINESS_TIMEZONE.offsetMinutes / 60;
     return new Date(Date.UTC(y, mo - 1, d, h - offsetHours, mi, s, 0));
 }
-/** JST 業務暦日に日数を加算（暦日単位）。 */
+/**
+ * Add a number of calendar days to a JST business calendar date.
+ *
+ * @param date - the starting business date as `YYYY-MM-DD`.
+ * @param days - the number of calendar days to add (may be negative).
+ * @returns the resulting business date as `YYYY-MM-DD`.
+ * @example
+ * addBusinessDays('2026-07-06', 3); // → '2026-07-09'
+ */
 export function addBusinessDays(date, days) {
     const anchor = businessDateTimeInstant(date, '12:00:00');
     return toBusinessDate(new Date(anchor.getTime() + days * 24 * 60 * 60 * 1000));
 }
-/** 業務暦日基準の満年齢（誕生日は instant ではなく BusinessDate）。 */
+/**
+ * The full years of age on a business calendar date (a birthday is a `BusinessDate`, not an instant).
+ *
+ * @param birthDate - the birth date as `YYYY-MM-DD`.
+ * @param asOfDate - the reference business date; defaults to {@link today}.
+ * @returns the age in completed years.
+ * @example
+ * ageOnBusinessDate('1990-07-10', '2026-07-06'); // → 35
+ */
 export function ageOnBusinessDate(birthDate, asOfDate) {
     const asOf = asOfDate ?? today();
     const [by, bm, bd] = parseYmd(birthDate);

package/dist/business-time/types.d.ts

@@ -1,8 +1,8 @@
-/** JST 業務暦日 `YYYY-MM-DD`（instant ではない）。 */
+/** A JST business calendar date `YYYY-MM-DD` (a calendar day, not an instant). */
 export type BusinessDate = string;
-/** JST 業務日時 `YYYY-MM-DD HH:mm:ss`（MySQL DATETIME 互換の壁時計表現）。 */
+/** A JST business date-time `YYYY-MM-DD HH:mm:ss` (a wall-clock value, MySQL `DATETIME`-compatible). */
 export type BusinessDateTime = string;
-/** JST 業務タイムゾーン定数（Workers は UTC instant、業務はここで明示）。 */
+/** JST business timezone constant. Workers run in UTC instants; business time is made explicit here. */
 export declare const BUSINESS_TIMEZONE: {
     readonly iana: "Asia/Tokyo";
     readonly offsetMinutes: 540;

package/dist/business-time/types.js

@@ -1,4 +1,4 @@
-/** JST 業務タイムゾーン定数（Workers は UTC instant、業務はここで明示）。 */
+/** JST business timezone constant. Workers run in UTC instants; business time is made explicit here. */
 export const BUSINESS_TIMEZONE = {
     iana: 'Asia/Tokyo',
     offsetMinutes: 540,