@rdlabo/workers-hono-kit 0.11.2 → 0.12.0-beta.pr48.sha371f5792ce8a

package/README.md

@@ -1,65 +1,100 @@
 # @rdlabo/workers-hono-kit
 
-`@rdlabo/workers-hono-kit` provides infrastructure-layer helpers for Hono on Cloudflare Workers. Domain logic, database schemas, and application-specific policy stay in the consuming application.
+Shared Hono building blocks for Cloudflare Workers APIs: weak ETags, NestJS-shaped validation and
+error bodies, Firebase auth middleware, AWS helpers, AI Gateway wiring, Stripe, KV, queues,
+realtime, and offline contracts. Domain logic and database schemas stay in the consuming
+application.
+
+## Choose an entry point
+
+| Import                                   | Responsibility                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `@rdlabo/workers-hono-kit`               | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives      |
+| `@rdlabo/workers-hono-kit/mysql`         | Hono container adapter for `@rdlabo/workers-mysql`                   |
+| `@rdlabo/workers-hono-kit/offline`       | Offline replica wire, cursor, journal, and compatibility contracts   |
+| `@rdlabo/workers-hono-kit/realtime`      | Durable Object WebSocket and retry helpers                           |
+| `@rdlabo/workers-hono-kit/testing`       | Auth helpers, fakes, Stripe fixtures, and compatibility test exports |
+| `@rdlabo/workers-hono-kit/db`            | Deprecated compatibility path for `@rdlabo/workers-mysql`            |
+| `@rdlabo/workers-hono-kit/business-time` | Deprecated compatibility path for `@rdlabo/workers-timezone`         |
+
+The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers
+install the standalone package, which owns `mysql2`; Hono-specific wiring stays in the `/mysql`
+adapter.
+
+## Install
 
 ```sh
 npm install @rdlabo/workers-hono-kit
 ```
 
-Install only the peer dependencies required by the features you use:
+The package is ESM with TypeScript declarations and requires Node.js 20 or later for tooling.
+Stripe is included directly. npm installs the required Hono, validation, authentication, AWS, and
+AI Gateway peers; package managers configured not to install peers automatically must add them
+explicitly:
 
 ```sh
-# Core HTTP, validation, Firebase, and AWS helpers
-npm install hono zod @hono/zod-validator jose aws4fetch
-
-# Data and testing entry points
-npm install drizzle-orm mysql2
-
-# AI Gateway
-npm install ai ai-gateway-provider
+npm install hono zod @hono/zod-validator jose aws4fetch ai-gateway-provider
 ```
 
-Stripe is a direct dependency of the kit. The package is compiled ESM with declarations, uses Web-standard APIs such as `fetch`, `crypto.subtle`, and `Response`, and requires Node.js 20 or later for tooling.
+Additional optional peers and packages stay separate:
 
-## Entry points
+| Capability              | Install                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| AI SDK model wrappers   | `ai`                                                                                                               |
+| MySQL and Hyperdrive    | [`@rdlabo/workers-mysql`](https://docs.rdlabo.dev/projects/workers-mysql/docs/readme) and optionally `drizzle-orm` |
+| IANA timezone utilities | [`@rdlabo/workers-timezone`](https://docs.rdlabo.dev/projects/workers-timezone/docs/readme)                        |
 
-| Import                                   | Responsibility                                                                 |
-| ---------------------------------------- | ------------------------------------------------------------------------------ |
-| `@rdlabo/workers-hono-kit`               | HTTP, auth, errors, Firebase, AWS, AI, Stripe, KV, queues, realtime primitives |
-| `@rdlabo/workers-hono-kit/db`            | Hyperdrive, MySQL, Drizzle, migrations, JST columns                            |
-| `@rdlabo/workers-hono-kit/business-time` | JST business dates and date-times                                              |
-| `@rdlabo/workers-hono-kit/offline`       | Offline replica wire, cursor, journal, and compatibility contracts             |
-| `@rdlabo/workers-hono-kit/realtime`      | Durable Object WebSocket and retry helpers                                     |
-| `@rdlabo/workers-hono-kit/testing`       | Test databases, auth helpers, fakes, and Stripe fixtures                       |
+From `0.12.0`, `/testing` retains static DB compatibility exports. Every `/testing` consumer,
+including applications using only Firebase or KV fakes, must install `@rdlabo/workers-mysql` and
+`drizzle-orm`.
 
-Subpath imports keep optional database and testing dependencies out of the root runtime surface.
+Version `0.12.0` moves the root MySQL exports to the standalone package and `/mysql` adapter.
+Existing users should follow the [MySQL migration guide](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/data-layer)
+before upgrading.
 
-## Documentation
+## Quick start
 
-- [HTTP and Authentication](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/http-auth)
-- [Data Layer](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/data-layer)
-- [Realtime and Offline](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/realtime-offline)
-- [Testing and Operations](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/testing-operations)
-- [API Reference](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/api)
+A minimal Hono app with weak ETags, the shared error body, and 404 JSON
+`{ message: 'Cannot METHOD path', error: 'Not Found', statusCode: 404 }`:
 
-<!-- rdlabo-docs-omit -->
-**Full documentation:** [https://docs.rdlabo.dev/projects/workers-hono-kit](https://docs.rdlabo.dev/projects/workers-hono-kit)
+```ts
+import { Hono } from 'hono';
+import { createAppErrorHandler, finalizeResponse, notFoundHandler } from '@rdlabo/workers-hono-kit';
 
-## Prerelease channels
+const app = new Hono();
 
-An open, non-draft pull request can be published to the npm `beta` dist-tag after its `Validation` and `Package Candidate` workflows pass. A repository owner or maintainer must add a comment whose entire body is:
+app.use('*', finalizeResponse());
+app.onError(createAppErrorHandler());
+app.notFound(notFoundHandler);
 
-```text
-/beta
+app.get('/health', (c) => c.json({ ok: true }));
+
+export default app;
 ```
 
-The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer `/beta` comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on `main`.
+### Compatibility import deprecations
 
-Beta versions use `<base>-beta.pr<PR number>.sha<12-character SHA>`. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.
+Kit `/db`, `/business-time`, and the DB-related `/testing` exports (`createTestDb`, pool/noop
+database fakes, and shared `Database` types) carry symbol-level `@deprecated` tags that point at
+`@rdlabo/workers-mysql` / `@rdlabo/workers-timezone`. Prefer those packages for new code. The
+compatibility aliases keep the same runtime identity and signatures; there is no planned removal.
+Kit-owned helpers such as `reopenGuardedPaymentFailedSet`, `/mysql` `createContainerRuntime`, and
+Firebase/auth/KV/Stripe test helpers are not deprecated by this migration.
 
-When a pull request is merged into `main`, it is automatically published to `beta` only after the required CI and `Package Candidate` succeed for that exact merge commit. Direct pushes to `main` do not publish a candidate.
+## Documentation
 
-Only `npm run release` creates a release tag. Stable `vX.Y.Z` tags publish to npm `latest`; revision/prerelease tags publish to `next`. Neither `beta` nor `next` publishing changes the npm `latest` dist-tag.
+- [HTTP and Authentication](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/http-auth)
+- [Data Layer and MySQL migration](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/data-layer)
+- [Realtime and Offline](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/realtime-offline)
+- [Testing and Operations](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/testing-operations)
+- [Packages and API Reference](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/api)
+
+<!-- rdlabo-docs-omit -->
+
+**Full documentation:** [https://docs.rdlabo.dev/projects/workers-hono-kit](https://docs.rdlabo.dev/projects/workers-hono-kit)
+
+Candidate artifacts and publication controls are documented in
+[Development](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/development).
 
 ## Maintainers
 
@@ -68,4 +103,5 @@ Only `npm run release` creates a release tag. Stable `vX.Y.Z` tags publish to np
 ## License
 
 [MIT](./LICENSE) © rdlabo-dev
+
 <!-- /rdlabo-docs-omit -->

package/dist/aws/sts.d.ts

@@ -48,8 +48,8 @@ export interface StsCredentials {
 /**
  * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
  *
- * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
- * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ * Issues temporary credentials for browser uploads via STS `AssumeRole` — no AWS SDK. The consuming
+ * app supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
  *
  * @param options - Caller AWS keys plus assume-role parameters.
  * @returns Temporary credentials for browser or edge PutObject / GetObject.

package/dist/aws/sts.js

@@ -1,16 +1,16 @@
 import { AwsClient } from 'aws4fetch';
 /** STS SigV4 signing region for the global endpoint (`sts.amazonaws.com`). */
 const DEFAULT_STS_REGION = 'us-east-1';
-/** winecode / airlec default — 15 minutes. */
+/** Default AssumeRole session duration — 15 minutes. */
 const DEFAULT_DURATION_SECONDS = 900;
 const STS_API_VERSION = '2011-06-15';
-/** Global STS endpoint (unchanged from winecode AwsService). */
+/** Global STS endpoint (`sts.amazonaws.com`). */
 const DEFAULT_STS_ENDPOINT = 'https://sts.amazonaws.com/';
 /**
  * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
  *
- * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
- * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ * Issues temporary credentials for browser uploads via STS `AssumeRole` — no AWS SDK. The consuming
+ * app supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
  *
  * @param options - Caller AWS keys plus assume-role parameters.
  * @returns Temporary credentials for browser or edge PutObject / GetObject.

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

@@ -1,126 +1,72 @@
 /**
- * Explicit JST business-time API (Workers UTC instant ↔ business calendar date / date-time).
- *
- * @remarks
- * - 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.
+ * Compatibility re-export of `@rdlabo/workers-timezone`. Prefer importing the standalone package
+ * directly. Symbol-level `@deprecated` tags mark each promoted export. Historical offsets and
+ * invalid calendar or wall-clock inputs follow the migration behavior documented in
+ * `docs/api-business-time.md`.
  *
  * @packageDocumentation
  */
-import { BUSINESS_TIMEZONE } from './types.js';
-import type { BusinessDate, BusinessDateTime } from './types.js';
-export { BUSINESS_TIMEZONE, type BusinessDate, type BusinessDateTime };
-/**
- * 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;
-/**
- * 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;
-/**
- * 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`.
- *
- * @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;
-/**
- * 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;
-/** Default pattern for the Nest / foodlabel / winecode `helper.formatDate`. */
-export declare const DEFAULT_BUSINESS_DATETIME_PATTERN: "YYYY-MM-DDThh:mm:ss";
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
+import { BUSINESS_TIMEZONE as businessTimezoneCanonical, BUSINESS_TIME_ZONES as businessTimeZonesCanonical, DEFAULT_BUSINESS_DATETIME_PATTERN as defaultBusinessDatetimePatternCanonical, TIME_ZONES as timeZonesCanonical, addBusinessDays as addBusinessDaysCanonical, addDays as addDaysCanonical, ageOnBusinessDate as ageOnBusinessDateCanonical, businessDateTimeInstant as businessDateTimeInstantCanonical, endOfBusinessDay as endOfBusinessDayCanonical, endOfDay as endOfDayCanonical, formatBusinessDateTime as formatBusinessDateTimeCanonical, getBusinessTimeConfig as getBusinessTimeConfigCanonical, getTimezoneConfig as getTimezoneConfigCanonical, initializeBusinessTime as initializeBusinessTimeCanonical, initializeTimezone as initializeTimezoneCanonical, localDateTimeToInstant as localDateTimeToInstantCanonical, normalizeBusinessDate as normalizeBusinessDateCanonical, parseBusinessDateTime as parseBusinessDateTimeCanonical, startOfBusinessDay as startOfBusinessDayCanonical, startOfDay as startOfDayCanonical, toBusinessDate as toBusinessDateCanonical, toBusinessDateTime as toBusinessDateTimeCanonical, toLocalDate as toLocalDateCanonical, toLocalDateTime as toLocalDateTimeCanonical, today as todayCanonical } from '@rdlabo/workers-timezone';
+import type { BusinessDate as BusinessDateCanonical, BusinessDateTime as BusinessDateTimeCanonical, BusinessTimeConfig as BusinessTimeConfigCanonical, BusinessTimeZone as BusinessTimeZoneCanonical, TimeZone as TimeZoneCanonical, TimezoneConfig as TimezoneConfigCanonical } from '@rdlabo/workers-timezone';
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const TIME_ZONES: typeof timeZonesCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const BUSINESS_TIMEZONE: typeof businessTimezoneCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const BUSINESS_TIME_ZONES: typeof businessTimeZonesCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const DEFAULT_BUSINESS_DATETIME_PATTERN: typeof defaultBusinessDatetimePatternCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const initializeTimezone: typeof initializeTimezoneCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const getTimezoneConfig: typeof getTimezoneConfigCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const toLocalDate: typeof toLocalDateCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const toLocalDateTime: typeof toLocalDateTimeCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const localDateTimeToInstant: typeof localDateTimeToInstantCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const startOfDay: typeof startOfDayCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const endOfDay: typeof endOfDayCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const addDays: typeof addDaysCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const toBusinessDate: typeof toBusinessDateCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const toBusinessDateTime: typeof toBusinessDateTimeCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const businessDateTimeInstant: typeof businessDateTimeInstantCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const startOfBusinessDay: typeof startOfBusinessDayCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const endOfBusinessDay: typeof endOfBusinessDayCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const addBusinessDays: typeof addBusinessDaysCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const today: typeof todayCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const normalizeBusinessDate: typeof normalizeBusinessDateCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const formatBusinessDateTime: typeof formatBusinessDateTimeCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const parseBusinessDateTime: typeof parseBusinessDateTimeCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const ageOnBusinessDate: typeof ageOnBusinessDateCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const initializeBusinessTime: typeof initializeBusinessTimeCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export declare const getBusinessTimeConfig: typeof getBusinessTimeConfigCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type TimeZone = TimeZoneCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type TimezoneConfig = TimezoneConfigCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type BusinessTimeZone = BusinessTimeZoneCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type BusinessTimeConfig = BusinessTimeConfigCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type BusinessDate = BusinessDateCanonical;
+/** @deprecated Import from `@rdlabo/workers-timezone` instead. */
+export type BusinessDateTime = BusinessDateTimeCanonical;