@rdlabo/workers-hono-kit 0.4.2 → 0.5.0

package/dist/db/columns.d.ts

@@ -1,10 +1,12 @@
 import type { DecimalNumberConfig } from './decimal.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 declare const jstOnUpdateNow: (fsp?: number) => import("drizzle-orm").SQL<unknown>;
-/** 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 declare const jstTimestamp: (name: string, opts?: {
     fsp?: number;
 }) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
@@ -15,7 +17,7 @@ export declare const jstTimestamp: (name: string, opts?: {
     driverParam: string | Date;
     enumValues: undefined;
 }>;
-/** MySQL `datetime` — {@link jstTimestamp} と同じ pass-through 方針。 */
+/** MySQL `datetime` — same pass-through policy as {@link jstTimestamp}. */
 export declare const jstDatetime: (name: string, opts?: {
     fsp?: number;
 }) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
@@ -26,7 +28,7 @@ export declare const jstDatetime: (name: string, opts?: {
     driverParam: string | Date;
     enumValues: undefined;
 }>;
-/** 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 declare const jstDate: (name: string) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
     name: string;
     dataType: "custom";
@@ -35,7 +37,7 @@ export declare const jstDate: (name: string) => import("drizzle-orm/mysql-core")
     driverParam: string | null;
     enumValues: undefined;
 }>;
-/** MySQL `decimal` — SELECT は `fromDriver` で string→number、書込は number をそのまま bind。 */
+/** 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";

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/http/mysql-driver-error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * mysql2 driver error shape (= TypeORM QueryFailedError.driverError 相当).
+ * Drizzle / Error.cause で wrap される場合があるため cause も再帰探索する。
+ */
+export interface MysqlDriverErrorLike {
+    errno?: number;
+    sqlMessage?: string;
+    sqlState?: string;
+    message?: string;
+    sql?: string;
+    code?: string;
+    cause?: unknown;
+}
+/**
+ * err 本体 → `err.cause` を再帰的に辿り、mysql2 ドライバエラーを取り出す。
+ *
+ * @param err - handler / onError に渡された thrown value。
+ * @param seen - 循環参照防止（内部用）。
+ */
+export declare function findMysqlDriverError(err: unknown, seen?: Set<unknown>): MysqlDriverErrorLike | null;
+/**
+ * Nest QueryFailedExceptionFilter の logger.error / logger.warn 相当。
+ * レスポンス body には載せず、Workers Logs 用に errno / sqlMessage / sql を残す。
+ */
+export declare function logMysqlDriverError(err: unknown, statusCode: number): void;

package/dist/http/mysql-driver-error.js

@@ -0,0 +1,35 @@
+/**
+ * err 本体 → `err.cause` を再帰的に辿り、mysql2 ドライバエラーを取り出す。
+ *
+ * @param err - handler / onError に渡された thrown value。
+ * @param seen - 循環参照防止（内部用）。
+ */
+export function findMysqlDriverError(err, seen = new Set()) {
+    if (err === null || err === undefined || seen.has(err)) {
+        return null;
+    }
+    seen.add(err);
+    const e = err;
+    if (typeof e.errno === 'number' && (typeof e.sqlMessage === 'string' || typeof e.sqlState === 'string')) {
+        return e;
+    }
+    if (e.cause !== undefined) {
+        return findMysqlDriverError(e.cause, seen);
+    }
+    return null;
+}
+/**
+ * Nest QueryFailedExceptionFilter の logger.error / logger.warn 相当。
+ * レスポンス body には載せず、Workers Logs 用に errno / sqlMessage / sql を残す。
+ */
+export function logMysqlDriverError(err, statusCode) {
+    const driver = findMysqlDriverError(err);
+    const rawMessage = driver?.sqlMessage ?? driver?.message ?? (err instanceof Error ? err.message : String(err));
+    const detail = driver === null ? undefined : { errno: driver.errno, sql: driver.sql, code: driver.code };
+    const line = `QueryFailedError (${statusCode}): ${rawMessage}`;
+    if (statusCode >= 500) {
+        console.error(line, detail);
+        return;
+    }
+    console.warn(line, detail);
+}

package/dist/http/nest-error.js

@@ -1,3 +1,4 @@
+import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
 /**
  * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
  *
@@ -82,7 +83,12 @@ export function createNestErrorHandler(options = {}) {
         catch {
             // Reporting must never change the behavior of the error response.
         }
-        console.error(err);
+        if (findMysqlDriverError(err)) {
+            logMysqlDriverError(err, 500);
+        }
+        else {
+            console.error(err);
+        }
         return c.json(internalServerErrorBody, 500);
     };
 }