@rdlabo/workers-hono-kit 0.4.0 → 0.4.3

package/dist/db/columns.js

@@ -1,36 +1,42 @@
 /**
- * Drizzle 列ヘルパー（フリート共通）。各 repo の `custom-types.ts` / `columns.ts` 薄いラッパーは不要。
+ * Shared Drizzle column helpers. Removes the need for a thin `custom-types.ts` / `columns.ts` wrapper
+ * in each repo.
  *
  * @remarks
- * `drizzle-orm` は **peer**（consumer が 1 本解決）。kit は `drizzle-orm` を bundled しない。
- * 戻り型は `customType` 推論そのまま（`MySqlCustomColumnBuilder<…>`）で `any` を使わない。
- * これにより consumer テーブルの `$inferSelect` に列の意味型（`string | Date` / `number | null` など）が伝播する。
+ * `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`.
  *
- * **前提（単一 drizzle コピー）**: drizzle の `SQL` は private フィールド `shouldInlineParams` を持つ
- * **名目型**なので、kit と consumer が drizzle の別コピーを解決すると
- * `jstTimestamp(…).default(sql\`…\`)` が `TS2345: separate declarations of a private property
- * 'shouldInlineParams'` で落ちる。フリートは kit を `file:` リンク参照するため kit 配下に drizzle が
- * ネストし二重コピーになりやすい。consumer 側 tsconfig の `paths` で `drizzle-orm` を **自身の 1 コピーへ
- * 固定**して単一化すること（README「Drizzle 列ヘルパー」参照）。published 版（単一コピー）ではそのまま単一。
+ * **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,
+ * `jstTimestamp(…).default(sql\`…\`)` fails with `TS2345: separate declarations of a private property
+ * 'shouldInlineParams'`. The fleet references the kit via a `file:` link, which tends to nest a second
+ * copy of drizzle under the kit. Pin `drizzle-orm` to the consumer's **own single copy** with tsconfig
+ * `paths` (see the "Drizzle column helpers" section of the README). The published package (a single
+ * copy) is already unified.
  *
- * **DEFAULT / ON UPDATE CURRENT_TIMESTAMP** … MySQL サーバ側の既定値（列を省略した INSERT / UPDATE）。
- * 接続 `timezone:'+09:00'`（{@link hyperdriveConnectionOptions}）が効くのは **アプリから Date を bind するとき**。
- * 両者を混同しないこと（`datetime-wire` / `drizzle-smoke` の JST テスト参照）。
+ * **DEFAULT / ON UPDATE CURRENT_TIMESTAMP** is a server-side default (an INSERT / UPDATE that omits the
+ * column). The connection's `timezone:'+09:00'` ({@link hyperdriveConnectionOptions}) only applies when
+ * the **app binds a `Date`**. Do not conflate the two (see the `datetime-wire` / `drizzle-smoke` JST
+ * tests).
  */
 import { sql } from 'drizzle-orm';
 import { customType } from 'drizzle-orm/mysql-core';
 import { decimalNumberParams } from './decimal.js';
 import { jstDateParams, jstDatetimeParams, jstTimestampParams } from './jst.js';
 /**
- * `ON UPDATE CURRENT_TIMESTAMP` 用式（MySQL セッション時刻）。
- * customType 列は `.onUpdateNow()` が無いため `.$onUpdateFn(() => jstOnUpdateNow(fsp))` と併用する。
+ * SQL expression for `ON UPDATE CURRENT_TIMESTAMP` (the MySQL session clock).
+ * customType columns have no `.onUpdateNow()`, so pair this with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `CURRENT_TIMESTAMP(fsp)`.
  */
 export const jstOnUpdateNow = (fsp) => fsp != null ? sql `(CURRENT_TIMESTAMP(${sql.raw(String(fsp))}))` : sql `(CURRENT_TIMESTAMP)`;
-/** MySQL `timestamp` — pass-through。Date は接続 `timezone:'+09:00'` で mysql2 が JST 整形。 */
+/** MySQL `timestamp` — pass-through. A `Date` is formatted as JST by mysql2 via the connection `timezone:'+09:00'`. */
 export const jstTimestamp = (name, opts) => customType(jstTimestampParams(opts?.fsp))(name);
-/** MySQL `datetime` — {@link jstTimestamp} と同じ pass-through 方針。 */
+/** MySQL `datetime` — same pass-through policy as {@link jstTimestamp}. */
 export const jstDatetime = (name, opts) => customType(jstDatetimeParams(opts?.fsp))(name);
-/** MySQL `date` — INSERT/UPDATE 時に ISO / 空文字を `YYYY-MM-DD` へ正規化（`toDriver`）。 */
+/** 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 は `fromDriver` で string→number、書込は number をそのまま bind。 */
+/** 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/decimal.d.ts

@@ -1,24 +1,32 @@
 /**
- * MySQL `DECIMAL` 列向け Drizzle `customType` params。
+ * Drizzle `customType` params for a MySQL `DECIMAL` column.
  *
  * @remarks
- * - **読込（SELECT）**: `fromDriver` で driver 値（`number` / `string` / `null`）を JS `number | null` に統一。
- *   接続 `decimalNumbers: true`（{@link hyperdriveConnectionOptions} 既定）と併用し、Drizzle builder 経路でも
- *   文字列 `"0"` / `"100.00"` が混ざったときに 0 を潰さず number へ揃える。
- * - **書込（INSERT/UPDATE）**: `toDriver` で number をそのまま mysql2 に bind（`String()` 変換不要）。
- * - 生 SQL `db.read` は接続 `decimalNumbers: true` が効く。列型の `fromDriver` は Drizzle `select` 経路向け。
+ * - **Reads (SELECT)**: `fromDriver` unifies the driver value (`number` / `string` / `null`) to a JS
+ *   `number | null`. Combined with the connection's `decimalNumbers: true`
+ *   ({@link hyperdriveConnectionOptions} default), it aligns values to numbers even on the Drizzle
+ *   builder path when strings like `"0"` / `"100.00"` slip in, without dropping `0`.
+ * - **Writes (INSERT/UPDATE)**: `toDriver` binds the number to mysql2 as-is (no `String()` conversion).
+ * - Raw-SQL `db.read` relies on the connection's `decimalNumbers: true`; the column's `fromDriver` is
+ *   for the Drizzle `select` path.
  */
 export interface DecimalNumberConfig {
     precision: number;
     scale: number;
 }
 /**
- * mysql2 / Drizzle から届いた DECIMAL 値を JS `number | null` へ正規化する。
- * `0` は falsy 落ちしないようそのまま保持する。
+ * Normalize a DECIMAL value coming from mysql2 / Drizzle to a JS `number | null`.
+ * `0` is preserved as-is so it is not dropped as falsy.
+ *
+ * @param value - the raw driver value (`number` / `string` / `bigint` / nullish).
+ * @returns the coerced finite number, or `null` when it cannot be resolved.
  */
 export declare function coerceDecimalNumber(value: unknown): number | null;
 /**
- * `customType` 用 params。高度な用途向け。通常は {@link decimalNumber} 列ヘルパーを使う。
+ * Params for a `customType`. For advanced use; the {@link decimalNumber} column helper is usually enough.
+ *
+ * @param config - the DECIMAL `precision` / `scale`.
+ * @returns the `customType` params (`dataType` / `fromDriver` / `toDriver`).
  */
 export declare const decimalNumberParams: (config: DecimalNumberConfig) => {
     dataType: () => string;

package/dist/db/decimal.js

@@ -1,16 +1,21 @@
 /**
- * MySQL `DECIMAL` 列向け Drizzle `customType` params。
+ * Drizzle `customType` params for a MySQL `DECIMAL` column.
  *
  * @remarks
- * - **読込（SELECT）**: `fromDriver` で driver 値（`number` / `string` / `null`）を JS `number | null` に統一。
- *   接続 `decimalNumbers: true`（{@link hyperdriveConnectionOptions} 既定）と併用し、Drizzle builder 経路でも
- *   文字列 `"0"` / `"100.00"` が混ざったときに 0 を潰さず number へ揃える。
- * - **書込（INSERT/UPDATE）**: `toDriver` で number をそのまま mysql2 に bind（`String()` 変換不要）。
- * - 生 SQL `db.read` は接続 `decimalNumbers: true` が効く。列型の `fromDriver` は Drizzle `select` 経路向け。
+ * - **Reads (SELECT)**: `fromDriver` unifies the driver value (`number` / `string` / `null`) to a JS
+ *   `number | null`. Combined with the connection's `decimalNumbers: true`
+ *   ({@link hyperdriveConnectionOptions} default), it aligns values to numbers even on the Drizzle
+ *   builder path when strings like `"0"` / `"100.00"` slip in, without dropping `0`.
+ * - **Writes (INSERT/UPDATE)**: `toDriver` binds the number to mysql2 as-is (no `String()` conversion).
+ * - Raw-SQL `db.read` relies on the connection's `decimalNumbers: true`; the column's `fromDriver` is
+ *   for the Drizzle `select` path.
  */
 /**
- * mysql2 / Drizzle から届いた DECIMAL 値を JS `number | null` へ正規化する。
- * `0` は falsy 落ちしないようそのまま保持する。
+ * Normalize a DECIMAL value coming from mysql2 / Drizzle to a JS `number | null`.
+ * `0` is preserved as-is so it is not dropped as falsy.
+ *
+ * @param value - the raw driver value (`number` / `string` / `bigint` / nullish).
+ * @returns the coerced finite number, or `null` when it cannot be resolved.
  */
 export function coerceDecimalNumber(value) {
     if (value === null || value === undefined) {
@@ -33,7 +38,10 @@ export function coerceDecimalNumber(value) {
     return null;
 }
 /**
- * `customType` 用 params。高度な用途向け。通常は {@link decimalNumber} 列ヘルパーを使う。
+ * Params for a `customType`. For advanced use; the {@link decimalNumber} column helper is usually enough.
+ *
+ * @param config - the DECIMAL `precision` / `scale`.
+ * @returns the `customType` params (`dataType` / `fromDriver` / `toDriver`).
  */
 export const decimalNumberParams = (config) => ({
     dataType: () => `decimal(${config.precision},${config.scale})`,

package/dist/db/jst.d.ts

@@ -1,16 +1,21 @@
 /**
- * MySQL / Drizzle 向け JST ワイヤ変換と DATE 列正規化。
+ * JST wire conversion and DATE-column normalization for MySQL / Drizzle.
  *
  * @remarks
- * 業務時刻の意味論は {@link ../business-time/index.js | business-time} に集約する。
- * このモジュールは「MySQL 接続既定」「DATE 列の toDriver」、列 `customType` params のみを担う。
+ * Business-time semantics are consolidated in {@link ../business-time/index.js | business-time}. This
+ * module only owns the MySQL connection default, the DATE column's `toDriver`, and the column
+ * `customType` params.
  */
 import type { BusinessDate } from '../business-time/index.js';
-/** mysql2 接続 `timezone` 既定（既存 JST DB 運用）。 */
+/** Default mysql2 connection `timezone` (for the existing JST DB deployment). */
 export declare const MYSQL_TIMEZONE = "+09:00";
 /**
- * クライアント入力を MySQL `DATE` 列向け `YYYY-MM-DD`（JST 業務暦日）へ正規化。
- * ISO 8601 / `YYYY-MM-DD` / 空文字を受け付ける。`YYYY-MM-DD` は Date 化せずそのまま渡す。
+ * Normalize a client input to `YYYY-MM-DD` (a JST business calendar date) for a MySQL `DATE` column.
+ * Accepts ISO 8601 / `YYYY-MM-DD` / empty strings. A `YYYY-MM-DD` value is passed through without
+ * constructing a `Date`.
+ *
+ * @param value - the string or nullish input to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
  */
 export declare function toJstDate(value: string | null | undefined): BusinessDate | null;
 /**

package/dist/db/jst.js

@@ -1,16 +1,21 @@
 /**
- * MySQL / Drizzle 向け JST ワイヤ変換と DATE 列正規化。
+ * JST wire conversion and DATE-column normalization for MySQL / Drizzle.
  *
  * @remarks
- * 業務時刻の意味論は {@link ../business-time/index.js | business-time} に集約する。
- * このモジュールは「MySQL 接続既定」「DATE 列の toDriver」、列 `customType` params のみを担う。
+ * Business-time semantics are consolidated in {@link ../business-time/index.js | business-time}. This
+ * module only owns the MySQL connection default, the DATE column's `toDriver`, and the column
+ * `customType` params.
  */
 import { normalizeBusinessDate } from '../business-time/index.js';
-/** mysql2 接続 `timezone` 既定（既存 JST DB 運用）。 */
+/** Default mysql2 connection `timezone` (for the existing JST DB deployment). */
 export const MYSQL_TIMEZONE = '+09:00';
 /**
- * クライアント入力を MySQL `DATE` 列向け `YYYY-MM-DD`（JST 業務暦日）へ正規化。
- * ISO 8601 / `YYYY-MM-DD` / 空文字を受け付ける。`YYYY-MM-DD` は Date 化せずそのまま渡す。
+ * Normalize a client input to `YYYY-MM-DD` (a JST business calendar date) for a MySQL `DATE` column.
+ * Accepts ISO 8601 / `YYYY-MM-DD` / empty strings. A `YYYY-MM-DD` value is passed through without
+ * constructing a `Date`.
+ *
+ * @param value - the string or nullish input to normalize.
+ * @returns the business date as `YYYY-MM-DD`, or `null` when the input cannot be resolved.
  */
 export function toJstDate(value) {
     return normalizeBusinessDate(value ?? null);

package/dist/db/migrate.d.ts

@@ -1,29 +1,29 @@
 import type { QueryRunner } from './database.js';
-/** baseline（=最初の）マイグレーションの識別情報。 */
+/** Identifying info for the baseline (i.e. first) migration. */
 export interface BaselineEntry {
-    /** マイグレーション tag（例 `0000_melted_weapon_omega`）。 */
+    /** The migration tag (e.g. `0000_melted_weapon_omega`). */
     tag: string;
-    /** `_journal.json` の `when`（= drizzle の `created_at`／`folderMillis`）。 */
+    /** The `when` from `_journal.json` (= drizzle's `created_at` / `folderMillis`). */
     when: number;
-    /** `<tag>.sql` の生内容の sha256（drizzle と同一アルゴリズム）。 */
+    /** The sha256 of the raw `<tag>.sql` contents (the same algorithm as drizzle). */
     hash: string;
 }
 /**
- * `migrationsFolder`（drizzle の `out`、例 `./drizzle`）から baseline（最初の）エントリを読む。
+ * Read the baseline (first) entry from `migrationsFolder` (drizzle's `out`, e.g. `./drizzle`).
  *
- * @param migrationsFolder - `meta/_journal.json` と `<tag>.sql` を含むフォルダ。
- * @returns baseline エントリ（tag/when/hash）。
- * @throws journal が無い / エントリが空 / `<tag>.sql` が無い場合。
+ * @param migrationsFolder - the folder containing `meta/_journal.json` and `<tag>.sql`.
+ * @returns the baseline entry (tag/when/hash).
+ * @throws Error when the journal is missing, the entries are empty, or `<tag>.sql` is missing.
  */
 export declare function readBaselineEntry(migrationsFolder: string): BaselineEntry;
-/** {@link baselineMigrations} のオプション。 */
+/** Options for {@link baselineMigrations}. */
 export interface BaselineMigrationsOptions {
-    /** 生 SQL を実行する QueryRunner（mysql2 `Connection`/`Pool` が代入可能）。対象 DB に接続済みのこと。 */
+    /** A QueryRunner for raw SQL (a mysql2 `Connection`/`Pool` is assignable). Must already be connected to the target DB. */
     db: QueryRunner;
-    /** drizzle の `out` フォルダ（既定 `./drizzle`）。 */
+    /** Drizzle's `out` folder (defaults to `./drizzle`). */
     migrationsFolder?: string;
 }
-/** {@link baselineMigrations} の結果。 */
+/** The result of {@link baselineMigrations}. */
 export type BaselineResult = {
     status: 'inserted';
     tag: string;
@@ -35,17 +35,17 @@ export type BaselineResult = {
     when: number;
 };
 /**
- * 既存 DB へ baseline（0000）を「適用済み」として記録する。冪等・安全ガード付き。
+ * Record the baseline (0000) as "applied" on an existing DB. Idempotent, with safety guards.
  *
  * @remarks
- * ガード:
- * - 既に baseline marker（`created_at = when`）が在れば **no-op**（`already-baselined`）。
- * - marker は無いが `__drizzle_migrations` に別の行が在る → **中断**（想定外の状態）。
- * - 対象 DB に base table が 1 つも無い（空 DB）→ **中断**（空 DB は 0000 を skip すると
- *   テーブルが作られない。新規 DB には `db:migrate` を使う）。
+ * Guards:
+ * - If a baseline marker (`created_at = when`) already exists → **no-op** (`already-baselined`).
+ * - If there is no marker but `__drizzle_migrations` has other rows → **abort** (unexpected state).
+ * - If the target DB has no base tables (an empty DB) → **abort** (skipping 0000 on an empty DB would
+ *   never create the tables; use `db:migrate` for a fresh DB).
  *
- * @param options - 接続と migrations フォルダ。{@link BaselineMigrationsOptions} 参照。
- * @returns 挿入したか既に baseline 済みか。
- * @throws 上記ガードに該当する場合。
+ * @param options - the connection and migrations folder; see {@link BaselineMigrationsOptions}.
+ * @returns whether a marker was inserted or the DB was already baselined.
+ * @throws Error when one of the guards above trips.
  */
 export declare function baselineMigrations(options: BaselineMigrationsOptions): Promise<BaselineResult>;

package/dist/db/migrate.js

@@ -1,32 +1,35 @@
 /**
  * Brownfield baseline for Drizzle MySQL migrations.
  *
- * 既存（現行サービス）の DB は先にスキーマが存在するため、コミット済みの baseline マイグレーション
- * （`drizzle/0000_*.sql` = 現行スキーマを introspect した CREATE TABLE 群）を `db:migrate` で流すと
- * 全テーブルが衝突して失敗する。そこで 0000 を **実行せず「適用済み」として記録**する。
+ * An existing (in-production) DB already has its schema, so running the committed baseline migration
+ * (`drizzle/0000_*.sql` = the CREATE TABLE statements introspected from the current schema) via
+ * `db:migrate` fails as every table collides. Instead, 0000 is **recorded as "applied" without being
+ * executed**.
  *
- * 適用判定の根拠（drizzle-orm/mysql-core dialect.migrate）: `__drizzle_migrations(id, hash,
- * created_at)` の **`created_at` 最大値のみ**で未適用判定し、`max(created_at) < entry.when` の
- * migration だけ実行する。hash は保存されるが判定には使われない。よって 0000 の marker として
- * `(hash, created_at=当該 when)` を 1 行入れれば、以後 `db:migrate` は when がより大きい 0001+ だけを
- * 適用し、0000 は skip する。新規/テスト DB は marker が無いのでフルチェーンが走る（挙動不変）。
+ * How "applied" is decided (drizzle-orm/mysql-core dialect.migrate): it determines the pending set from
+ * **only the maximum `created_at`** in `__drizzle_migrations(id, hash, created_at)`, running just the
+ * migrations where `max(created_at) < entry.when`. The hash is stored but not used for the decision. So
+ * inserting one row as the 0000 marker — `(hash, created_at = that entry's when)` — makes subsequent
+ * `db:migrate` runs apply only the later 0001+ (larger `when`) and skip 0000. A fresh / test DB has no
+ * marker, so the full chain runs (behavior unchanged).
  *
- * この関数は `drizzle-orm` に依存しない（journal/SQL を自前で読み、hash は drizzle と同じ sha256）。
- * QueryRunner（mysql2 の `Connection`/`Pool` が構造的に代入可能）に対して生 SQL を実行する。
+ * This function does not depend on `drizzle-orm` (it reads the journal/SQL itself and hashes with the
+ * same sha256 as drizzle). It runs raw SQL against a QueryRunner (a mysql2 `Connection`/`Pool` is
+ * structurally assignable).
  *
  * @packageDocumentation
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** drizzle が使う既定のマイグレーション管理テーブル名。 */
+/** The default migration-tracking table name used by drizzle. */
 const MIGRATIONS_TABLE = '__drizzle_migrations';
 /**
- * `migrationsFolder`（drizzle の `out`、例 `./drizzle`）から baseline（最初の）エントリを読む。
+ * Read the baseline (first) entry from `migrationsFolder` (drizzle's `out`, e.g. `./drizzle`).
  *
- * @param migrationsFolder - `meta/_journal.json` と `<tag>.sql` を含むフォルダ。
- * @returns baseline エントリ（tag/when/hash）。
- * @throws journal が無い / エントリが空 / `<tag>.sql` が無い場合。
+ * @param migrationsFolder - the folder containing `meta/_journal.json` and `<tag>.sql`.
+ * @returns the baseline entry (tag/when/hash).
+ * @throws Error when the journal is missing, the entries are empty, or `<tag>.sql` is missing.
  */
 export function readBaselineEntry(migrationsFolder) {
     const journalPath = join(migrationsFolder, 'meta', '_journal.json');
@@ -38,7 +41,8 @@ export function readBaselineEntry(migrationsFolder) {
     if (entries.length === 0) {
         throw new Error(`No migration entries in ${journalPath}.`);
     }
-    // 起点は必ず最初のエントリ（0000）。以降 0001+ は「新しい変更」なので既存 DB でも実行されるべき。
+    // The origin is always the first entry (0000). Later 0001+ are "new changes" that should run even on
+    // an existing DB.
     const first = entries[0];
     const sqlPath = join(migrationsFolder, `${first.tag}.sql`);
     if (!existsSync(sqlPath)) {
@@ -52,43 +56,44 @@ async function rowsOf(db, sql, params) {
     return result[0] ?? [];
 }
 /**
- * 既存 DB へ baseline（0000）を「適用済み」として記録する。冪等・安全ガード付き。
+ * Record the baseline (0000) as "applied" on an existing DB. Idempotent, with safety guards.
  *
  * @remarks
- * ガード:
- * - 既に baseline marker（`created_at = when`）が在れば **no-op**（`already-baselined`）。
- * - marker は無いが `__drizzle_migrations` に別の行が在る → **中断**（想定外の状態）。
- * - 対象 DB に base table が 1 つも無い（空 DB）→ **中断**（空 DB は 0000 を skip すると
- *   テーブルが作られない。新規 DB には `db:migrate` を使う）。
+ * Guards:
+ * - If a baseline marker (`created_at = when`) already exists → **no-op** (`already-baselined`).
+ * - If there is no marker but `__drizzle_migrations` has other rows → **abort** (unexpected state).
+ * - If the target DB has no base tables (an empty DB) → **abort** (skipping 0000 on an empty DB would
+ *   never create the tables; use `db:migrate` for a fresh DB).
  *
- * @param options - 接続と migrations フォルダ。{@link BaselineMigrationsOptions} 参照。
- * @returns 挿入したか既に baseline 済みか。
- * @throws 上記ガードに該当する場合。
+ * @param options - the connection and migrations folder; see {@link BaselineMigrationsOptions}.
+ * @returns whether a marker was inserted or the DB was already baselined.
+ * @throws Error when one of the guards above trips.
  */
 export async function baselineMigrations(options) {
     const { db, migrationsFolder = './drizzle' } = options;
     const baseline = readBaselineEntry(migrationsFolder);
-    // migrator と同一 DDL（存在すれば no-op）。
+    // Same DDL as the migrator (a no-op if it already exists).
     await db.query(`create table if not exists \`${MIGRATIONS_TABLE}\` (
       id serial primary key,
       hash text not null,
       created_at bigint
     )`);
-    // 既に baseline marker があれば冪等 no-op。
+    // If a baseline marker already exists, this is an idempotent no-op.
     const existing = await rowsOf(db, `select id from \`${MIGRATIONS_TABLE}\` where created_at = ? limit 1`, [
         baseline.when,
     ]);
     if (existing.length > 0) {
         return { status: 'already-baselined', tag: baseline.tag, when: baseline.when };
     }
-    // marker は無いが行が在る＝既に別の状態。誤爆防止で中断。
+    // No marker but rows exist = already in some other state. Abort to avoid misfiring.
     const countRows = await rowsOf(db, `select count(*) as n from \`${MIGRATIONS_TABLE}\``);
     const rowCount = Number(countRows[0]?.n ?? 0);
     if (rowCount > 0) {
         throw new Error(`${MIGRATIONS_TABLE} already has ${rowCount} row(s) but no baseline marker (created_at=${baseline.when}). ` +
             `Migration state is unexpected — refusing to insert. Inspect \`${MIGRATIONS_TABLE}\` manually.`);
     }
-    // 空 DB への baseline は危険（0000 を skip 扱いにするとテーブルが作られない）。brownfield 確認。
+    // Baselining an empty DB is dangerous (treating 0000 as skipped would never create the tables).
+    // Confirm this is a brownfield DB.
     const tableRows = await rowsOf(db, `select count(*) as n from information_schema.tables
       where table_schema = DATABASE() and table_type = 'BASE TABLE' and table_name <> ?`, [MIGRATIONS_TABLE]);
     const baseTableCount = Number(tableRows[0]?.n ?? 0);

package/dist/db/orm-config.d.ts

@@ -102,7 +102,7 @@ export declare function honoDrizzleConfig(options: HonoDrizzleConfigOptions): {
     out: string;
     casing: "snake_case";
 };
-/** {@link resolveDbSecret} の戻り値（正規化済みの接続情報）。 */
+/** The return value of {@link resolveDbSecret} (normalized connection info). */
 export interface ResolvedDbSecret {
     host: string;
     port: number;
@@ -111,13 +111,17 @@ export interface ResolvedDbSecret {
     password: string;
 }
 /**
- * AWS RDS マネージド secret（`DB_SECRET` に入れた JSON 文字列）を解決する。
+ * Resolve an AWS RDS managed secret (a JSON string placed in `DB_SECRET`).
  *
  * @remarks
- * - `DB_SECRET` 未設定 → `undefined`（ローカル/`db:generate` の正常フォールバック）。
- * - 設定されている場合は「完全な接続情報」であることを要求し、**不正 JSON / 必須キー欠損は throw**
- *   （静かに localhost へフォールバックして事故らせない）。`port` のみ欠損時は 3306 を補う。
+ * - `DB_SECRET` unset → `undefined` (the normal local / `db:generate` fallback).
+ * - When set, it must be complete connection info: **invalid JSON / a missing required key throws**
+ *   (rather than silently falling back to localhost and causing an incident). A missing `port` alone
+ *   defaults to 3306.
  *
- * `honoDrizzleConfig`（db:migrate）と `workers-hono-kit-db-baseline` bin の双方が同じ解釈を使う。
+ * Both `honoDrizzleConfig` (db:migrate) and the `workers-hono-kit-db-baseline` bin use this same logic.
+ *
+ * @returns the resolved connection info, or `undefined` when `DB_SECRET` is unset.
+ * @throws Error when `DB_SECRET` is set but is not valid JSON or is missing a required key.
  */
 export declare function resolveDbSecret(): ResolvedDbSecret | undefined;

package/dist/db/orm-config.js

@@ -53,12 +53,12 @@ export const DRIZZLE_ORM_OPTIONS = { mode: 'default', casing: 'snake_case' };
  */
 export function honoDrizzleConfig(options) {
     const { database, host, port, user, password, schema = './src/db/schemes', out = './drizzle', tablesFilter, introspect, } = options;
-    // CI/本番の migrate は AWS Secrets Manager の RDS マネージド secret（キー
-    // host/port/dbname/username/password）を `DB_SECRET` にまるごと渡す運用を吸収する。JSON.parse で
-    // 解釈するので secret のキー名（host≠DB_HOST）差を map でき、password の特殊文字もシェル安全。
-    // 未設定（ローカル/db:generate）は従来どおり個別 env → デフォルトにフォールバック。
-    // DB_SECRET が在れば「完全な secret」として全接続情報をそれで確定する（欠損/不正は throw）。
-    // 未設定時のみ従来の個別 env → デフォルトにフォールバックする。
+    // CI/production migrate absorbs the pattern of passing a whole AWS Secrets Manager RDS managed secret
+    // (keys host/port/dbname/username/password) via `DB_SECRET`. It is parsed with JSON.parse, so key-name
+    // differences (host ≠ DB_HOST) can be mapped and special characters in the password stay shell-safe.
+    // When `DB_SECRET` is set, it is treated as a complete secret and fully determines the connection
+    // (missing/invalid → throw). Only when it is unset do we fall back to the individual DB_* env vars
+    // and then the defaults (the local / db:generate path).
     const secret = resolveDbSecret();
     const dbCredentials = secret
         ? {
@@ -86,14 +86,18 @@ export function honoDrizzleConfig(options) {
     };
 }
 /**
- * AWS RDS マネージド secret（`DB_SECRET` に入れた JSON 文字列）を解決する。
+ * Resolve an AWS RDS managed secret (a JSON string placed in `DB_SECRET`).
  *
  * @remarks
- * - `DB_SECRET` 未設定 → `undefined`（ローカル/`db:generate` の正常フォールバック）。
- * - 設定されている場合は「完全な接続情報」であることを要求し、**不正 JSON / 必須キー欠損は throw**
- *   （静かに localhost へフォールバックして事故らせない）。`port` のみ欠損時は 3306 を補う。
+ * - `DB_SECRET` unset → `undefined` (the normal local / `db:generate` fallback).
+ * - When set, it must be complete connection info: **invalid JSON / a missing required key throws**
+ *   (rather than silently falling back to localhost and causing an incident). A missing `port` alone
+ *   defaults to 3306.
  *
- * `honoDrizzleConfig`（db:migrate）と `workers-hono-kit-db-baseline` bin の双方が同じ解釈を使う。
+ * Both `honoDrizzleConfig` (db:migrate) and the `workers-hono-kit-db-baseline` bin use this same logic.
+ *
+ * @returns the resolved connection info, or `undefined` when `DB_SECRET` is unset.
+ * @throws Error when `DB_SECRET` is set but is not valid JSON or is missing a required key.
  */
 export function resolveDbSecret() {
     const raw = process.env.DB_SECRET;

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, Sentr
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 export type { AuthMiddlewareOptions } from './middleware/auth.js';
+export { perfLog } from './middleware/perf-log.js';
+export type { PerfLogOptions, AnalyticsEngineDatasetLike } from './middleware/perf-log.js';
 export { getUserProtocol } from './http/user-protocol.js';
 export type { IUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { finalizeResponse } from './middleware/finalize-response.js';
 export { validate, createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
+export { perfLog } from './middleware/perf-log.js';
 // http
 export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';

package/dist/middleware/perf-log.d.ts

@@ -0,0 +1,77 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Minimal shape of a Workers Analytics Engine dataset binding.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`. Only the
+ * single write operation the emitter needs is modeled. A real `AnalyticsEngineDataset` binding is
+ * assignable. Writes are non-blocking and add no latency to the request.
+ *
+ * @see https://developers.cloudflare.com/analytics/analytics-engine/
+ */
+export interface AnalyticsEngineDatasetLike {
+    writeDataPoint(event: {
+        doubles?: number[];
+        blobs?: (string | null)[];
+        indexes?: string[];
+    }): void;
+}
+/** Options for {@link perfLog}. Both sinks are optional; enable either or both. */
+export interface PerfLogOptions {
+    /**
+     * When `true`, emit one `console.log(JSON.stringify({ perf }))` per request. With
+     * `[observability] enabled = true` these lines are captured by **Workers Logs** (retained up to
+     * 7 days, queryable via the dashboard Query Builder or the Observability REST API) — no live
+     * `wrangler tail` needed, which is what makes this practical for low-traffic Workers.
+     *
+     * Explicit wins over the `PERF_LOG` env fallback in both directions: `true` forces on, `false` forces
+     * off (even when `PERF_LOG === '1'`), `undefined` (default) defers to `PERF_LOG`.
+     */
+    console?: boolean;
+    /**
+     * When provided, write one data point per request to a **Workers Analytics Engine** dataset. Query
+     * percentiles by route/colo with the SQL API (≈90-day retention). Non-blocking. Layout:
+     * `doubles = [t_app_ms, cold(0|1), status]`, `blobs = [path, colo, method]`, `indexes = [path]`.
+     */
+    dataset?: AnalyticsEngineDatasetLike;
+    /**
+     * In-code sampling in `[0, 1]` (default `1` = every request; values are clamped to the range).
+     * Thins **Analytics Engine writes only** — Workers Logs volume is controlled separately by the
+     * observability `head_sampling_rate`. Low-traffic Workers should leave it at `1`.
+     */
+    sampleRate?: number;
+}
+/**
+ * Create a Hono middleware that records a per-request latency data point and emits it to Workers
+ * Logs (`console`) and/or Workers Analytics Engine (`dataset`).
+ *
+ * Register it first (`app.use('*', perfLog(...))`) so `t_app` covers the whole in-app path. Route
+ * grouping uses the matched route pattern (e.g. `/user/:id`) rather than the raw path so ids do not
+ * explode cardinality; unmatched requests collapse to `(unmatched)`. Colo comes from `request.cf.colo`;
+ * cold/warm from an isolate-scoped flag. See {@link PerfLogOptions} for the two sinks and the note
+ * above for exactly what `t_app` includes (it depends on where secrets/DB-connect are wired).
+ *
+ * Two wiring styles, both A/B-capable (Workers Logs and/or Analytics Engine):
+ *
+ * @example Bare, when the app is served with `app.fetch(req, env, ctx)` — reads `PERF` (Analytics
+ * Engine binding) and `PERF_LOG === '1'` (Workers Logs) straight off `c.env`:
+ * ```ts
+ * app.use('*', perfLog());
+ * ```
+ *
+ * @example Explicit, when the app is built without Hono `env` (e.g. `createApp(container).fetch(req)`)
+ * — thread the bindings in:
+ * ```ts
+ * app.use('*', perfLog({ console: env.PERF_LOG === '1', dataset: env.PERF }));
+ * ```
+ *
+ * @example Query Analytics Engine (SQL API), handler p50/p90 by route and colo:
+ * ```sql
+ * SELECT blob1 AS path, blob2 AS colo,
+ *        quantileWeighted(0.5)(double1, _sample_interval) AS p50,
+ *        quantileWeighted(0.9)(double1, _sample_interval) AS p90,
+ *        sum(_sample_interval) AS n
+ * FROM your_dataset WHERE timestamp > now() - INTERVAL '7' DAY
+ * GROUP BY path, colo ORDER BY n DESC
+ * ```
+ */
+export declare function perfLog(options?: PerfLogOptions): MiddlewareHandler;