From d898b82dbecfeaddb648f03ea76850e475a2c27c Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 19 Aug 2026 13:18:46 +0900 Subject: [PATCH 1/2] docs: split README into package guides with omit markers Align docs/ with the portal page list and keep CLI, role-policy, and development notes on GitHub only. --- README.md | 805 ++----------------------------------- docs/api-business-time.md | 37 ++ docs/api-db.md | 53 +++ docs/api-offline.md | 71 ++++ docs/api-root.md | 75 ++++ docs/api-testing.md | 20 + docs/api.md | 15 + docs/cli.md | 37 ++ docs/data-layer.md | 44 ++ docs/development.md | 36 ++ docs/http-auth.md | 36 ++ docs/realtime-offline.md | 27 ++ docs/role-policies.md | 52 +++ docs/testing-operations.md | 25 ++ package.json | 1 + 15 files changed, 562 insertions(+), 772 deletions(-) create mode 100644 docs/api-business-time.md create mode 100644 docs/api-db.md create mode 100644 docs/api-offline.md create mode 100644 docs/api-root.md create mode 100644 docs/api-testing.md create mode 100644 docs/api.md create mode 100644 docs/cli.md create mode 100644 docs/data-layer.md create mode 100644 docs/development.md create mode 100644 docs/http-auth.md create mode 100644 docs/realtime-offline.md create mode 100644 docs/role-policies.md create mode 100644 docs/testing-operations.md diff --git a/README.md b/README.md index 7c449b0..b1fc051 100644 --- a/README.md +++ b/README.md @@ -1,796 +1,57 @@ # @rdlabo/workers-hono-kit -Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudflare Workers](https://workers.cloudflare.com). +`@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. -**Documentation:** [Read the full documentation](https://docs.rdlabo.dev/projects/workers-hono-kit) - -It provides Workers-oriented building blocks for a NestJS-style API, plus middleware for common HTTP response concerns: - -- **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`. -- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via focused SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto, avoiding a broad SDK dependency when only a few AWS APIs are needed. -- **Middleware**: `finalizeResponse` (weak ETag via `hono/etag`), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers. -- **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`. -- **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle. -- **AI Gateway**: route `@ai-sdk` models through the Cloudflare AI Gateway. -- **Stripe** Workers-native client + async webhook verification. -- **Payment failure & subscription reconcile**: provider-agnostic `payment_failed` helpers — Stripe decline reasons → Japanese messages, Apple / Google subscription-renewal classification, `iapFailureKey` / receipt (de)serialization, and Stripe reconcile branch decisions. -- **Testing helpers** (`@rdlabo/workers-hono-kit/testing`): a Drizzle-migration-backed test database, in-memory Firebase fake, configurable test doubles, and Stripe fixtures. -- **Realtime helpers**: Hibernation WebSocket upgrade/broadcast/close, legacy SSE bridging, and Durable Object retry policy. - -## Install - -```bash +```sh npm install @rdlabo/workers-hono-kit ``` -Peer dependencies — install the ones you use: +Install only the peer dependencies required by the features you use: -```bash -# Core (root export) +```sh +# Core HTTP, validation, Firebase, and AWS helpers npm install hono zod @hono/zod-validator jose aws4fetch -# Optional, only if you use the corresponding feature: -npm install drizzle-orm mysql2 # ./db and ./testing -npm install ai ai-gateway-provider # createAiGatewayProvider -``` - -`stripe` is bundled as a direct dependency, so the Stripe helpers work without an extra install. - -> **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. 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 business-time API (`toBusinessDateTime` / `normalizeBusinessDate` / `formatBusinessDateTime`, etc.). | -> | `./offline` | `@rdlabo/workers-hono-kit/offline` | Table-agnostic REST/DB method converters plus replica wire and clock helpers. | -> | `./testing` | `@rdlabo/workers-hono-kit/testing` | Test helpers (mysql2 + Drizzle + fakes/fixtures). | - -## API - -### Root — `@rdlabo/workers-hono-kit` - -| Export | Description | -| --- | --- | -| `finalizeResponse()` | Middleware that adds a weak `ETag` (delegates to `hono/etag`; also handles `If-None-Match` → `304`). | -| `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). | -| `createValidate({ sentry? })` | Bound `validate` factory. Pass `sentry` on Sentry apps; omit for console-only (review, cbs-ai). | -| `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. | -| `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). | -| `getAuthenticationSecret(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). | -| `getTemporaryCredentials(options)` / `GetTemporaryCredentialsOptions` / `StsCredentials` | STS `AssumeRole` via SigV4 `fetch` (global `sts.amazonaws.com`); returns temporary credentials for browser S3 uploads. | -| `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. | -| `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). | -| `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). | -| `createServiceAccountVerifier(serviceAccountJson)` | Cached verifier built from a service-account JSON, **with `IdentityToolkit`** (getUser/deleteUser). One per isolate, re-created only when the SA JSON changes. | -| `IdentityToolkit` / `ServiceAccount` / `SECURETOKEN_JWK_URL` | Identity Toolkit REST client + constants for `getUser` / `deleteUser`. | -| `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. | -| `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). | -| `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. | -| `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). | -| `HttpStatus` | Standard HTTP status code enum (IANA registry). | -| `createHttpErrorHandler(options?)` / `HttpErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to `{ statusCode, message, error? }` (`401` omits `error`). Optional custom error predicate and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). | -| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). | -| `createQueryFailedErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. | -| `classifyGenericMysqlDriverError(err)` | Default classifier: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. | -| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss). | -| `notFoundHandler(c)` | `app.notFound()` handler with `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. | -| `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. | -| `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. | -| `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. | -| `createIdentityAuthFailureBody()` / `createLegacyIdentityAuthFailureBody()` / `createAuthFailureBody(scope, code, message)` / `AuthFailureScope` | Stable wire contract for distinguishing a lost global identity (`identity`) from recent-login (`reauthentication`) and feature credential (`credential`) failures. The legacy helper tags products whose installed clients still require auth failure as `403`. | -| `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. | -| `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. | -| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. | -| `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). | -| `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: both variants log background rejections without propagating them; `createWaitUntilDefer` also registers work via `ctx.waitUntil`. | -| `configureHibernationAutoResponse` / `upgradeHibernationWebSocket` / `broadcastHibernationWebSockets` | Hibernation WebSocket room primitives: runtime ping/pong without waking JavaScript, attachment-before-accept upgrade, and broadcast through sockets restored by `getWebSockets()`. | -| `acknowledgeHibernationWebSocketClose` / `closeHibernationWebSocket` | Safe close helpers, including normalization of reserved received-only close codes. | -| `retryDurableObjectOperation(operation, options?)` / `isRetryableDurableObjectError(error)` | Retry idempotent DO work only for `retryable && !overloaded`, with jittered exponential backoff. `operation` runs per attempt so callers create a fresh stub after an exception. | -| `createIdempotencyInput(...)` / `runIdempotentMutation(...)` | Canonical payload hashing and a transaction-bound mutation state machine. Missing keys preserve legacy behavior; replay/conflict/in-flight semantics are shared while each app owns its schema and ORM adapter. | -| `withIdempotencyHttpErrors(run)` | Maps only standard idempotency failures to 400/409/503 and rethrows unrelated failures. | -| `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). | -| `KVCache` / `KVNamespace` / `KVCacheOptions` / `KVCacheErrorContext` / `KVCacheOperation` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application; optional `onError(error, context)` observes fail-soft read/parse/serialize/write/delete failures. Context contains only the operation and logical table, not cache types, keys, ids, or values. | -| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). | -| `extractStripeFailureReason(source)` / `StripeFailureReason` | Duck-type a Stripe `PaymentIntent` / `Invoice` / `{ paymentIntent?, invoice? }` / thrown error into a normalized `{ code, declineCode, message, paymentIntentId, invoiceId, subscriptionId }` (SDK-free), or `null`. | -| `stripeFailureMessageJa(reason)` | Render a `StripeFailureReason` (or `null`) as a single user-facing Japanese sentence (`decline_code` > `code`; fraud codes masked; unknown → generic). | -| `PaymentDeclinedError` / `toPaymentDeclinedError(error, status?)` / `PaymentDeclinedBody` | `HTTPException` carrying a verbatim `{ statusCode, message, code?, declineCode? }` body for a synchronous card decline (defaults to `400`). `toPaymentDeclinedError` returns `null` for non-declines (re-throw → 500). | -| `classifyStripeReconcile(subscription)` / `StripeReconcileAction` | Classify an expanded Stripe subscription into `trial` / `clear` / `canceled` / `failed` / `action_required` / `none` (termination evaluated before `succeeded`). Consumer does the DB write. | -| `serializePaymentFailure(record)` / `parsePaymentFailure(receipt)` / `PaymentFailureRecord` / `PaymentFailureReason` / `PaymentFailureSource` | (De)serialize the `payment_failed.receipt` JSON. `parsePaymentFailure` restores both a full Stripe record and a bare IAP reason. | -| `serializeIapFailureReason(reason)` / `IapFailureReason` | Serialize an IAP reason (`billing_retry` / `auto_renew_off` / `subscription_canceled` / `subscription_gone` + provider codes) directly, without the source/timestamp wrapper. | -| `paymentFailureMessageJa(input)` / `PaymentFailureStatus` / `PaymentFailureType` / `UNRESOLVED_PAYMENT_STATUSES` | Provider-agnostic Japanese message for a `payment_failed` row (`canceled` re-subscribe prompt, IAP `failed` App Store/Google Play prompt, else Stripe wording). `UNRESOLVED_PAYMENT_STATUSES` = everything except `resolved` for read/resolve `WHERE`. | -| `iapFailureKey(input)` | Provider-native `payment_failed.recursions_id`: iOS `${original_transaction_id}:${expires_date_ms}`, Android `${orderId}` (provider is in the `type` column). | -| `verifyAppleReceipt(receipt, opts)` / `classifyAppleRenewal(verify, now)` / `AppleRenewalClassification` / `AppleRenewalState` / `AppleVerifyReceiptResponse` / `ApplePendingRenewalInfo` / `AppleLatestReceiptInfo` | Verify an App Store receipt (production → sandbox fallback; inject `password` / `fetchImpl`) and classify it into `billing_retry` / `lapsed` / `active` / `unknown` plus the raw fields used (`statusCode` / `billingRetryStatus` / `autoRenewStatus`, latest `original_transaction_id` / `expires_date_ms`). | -| `googleAccessToken(creds, fetch?)` / `getGoogleSubscription(opts)` / `classifyGoogleSubscription(purchase, now)` / `GoogleSubscriptionClassification` / `GoogleSubscriptionState` / `GoogleSubscriptionPurchase` / `GoogleOAuthCredentials` | Exchange a refresh token for an Android Publisher access token (throws on `invalid_grant`), fetch a subscription purchase, and classify it into `canceled` / `gone` / `active` / `unknown` plus raw `statusCode` / `cancelReason`. | -| `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). | -| `processBatch(batch, handler, options?)` / `isNonRetryableQueueError(error)` / `NonRetryableQueueErrorLike` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency. Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acked as permanent failures; all other errors are retried. | -| `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt, except permanent failures which are reported immediately). | -| `assertStripeCustomerUpdated(options)` | Preserve the shared Stripe UPDATE→existence-check algorithm. `createNotFoundError(customerId)` can supply a domain-specific error without forking the algorithm. | -| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape used by lifecycle-compatible APIs and deferred work helpers. | - -Permanent Queue failures must opt in with the Queue-specific marker; unrelated `retryable` fields are ignored: - -```ts -import type { NonRetryableQueueErrorLike } from '@rdlabo/workers-hono-kit'; - -class CustomerLinkMissingError extends Error implements NonRetryableQueueErrorLike { - readonly queueDisposition = 'discard' as const; -} -``` - -### Data layer — `@rdlabo/workers-hono-kit/db` - -Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in. - -| Export | Description | -| --- | --- | -| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. Workers cleans them up at invocation end; the legacy `dispose()` is a no-op. | -| `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. | -| `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. | -| `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. | -| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. | -| `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. | -| `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. | -| `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. | -| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). | -| `MYSQL_TIMEZONE` | Default mysql2 connection `timezone` (`'+09:00'`) for the JST DB deployment. | -| `jstTimestamp` / `jstDatetime` / `jstDate` | Drizzle column helpers (no repo-side wrapper needed). | -| `jstOnUpdateNow` | SQL expression for `ON UPDATE CURRENT_TIMESTAMP`. The `jstTimestamp` customType (and friends) do not support `.onUpdateNow()`, so pair it with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`. | -| `DRIZZLE_ORM_OPTIONS` / `honoDrizzleConfig(options)` / `HonoDrizzleConfigOptions` | Shared Drizzle casing (`snake_case`) for both the runtime `drizzle()` call and `drizzle.config.ts`, keeping config ↔ runtime in sync. | -| `resolveDbSecret()` / `ResolvedDbSecret` | Resolve DB connection info from the `DB_SECRET` env var (an AWS RDS managed-secret JSON string) for CI migrate / local tooling. Returns `undefined` when `DB_SECRET` is unset; throws on invalid JSON or a missing required key. | -| `baselineMigrations(options)` / `readBaselineEntry(migrationsFolder)` / `BaselineMigrationsOptions` / `BaselineResult` / `BaselineEntry` | Brownfield first-deploy helper: mark an existing `0000_*` migration as applied without re-running DDL. | - -#### Drizzle column helpers (`jstTimestamp` / `jstDatetime` / `jstDate`, etc.) - -- `drizzle-orm` is a **peer** only. The kit does not include `drizzle-orm` as a dependency (even after publishing, it uses the consumer's single copy). -- The consumer just keeps `drizzle-orm` in its `dependencies` as usual. **No `overrides` in `package.json` are needed.** -- The npm-published artifact contains no `devDependencies`, so installing it does not add a kit-specific `drizzle-orm` (there is only the one peer copy). -- The column helpers `import` the consumer's `drizzle-orm` at runtime, and the types are the `customType` inference as-is (`MySqlCustomColumnBuilder<…>`). No `any` is used, so the column's semantic type propagates to the consumer table's `$inferSelect`. -- **Precondition: resolve drizzle to a single copy.** Drizzle's `SQL` is a **nominal** type carrying a private field `shouldInlineParams`, so if the kit and the consumer resolve different copies, `jstTimestamp(…).default(sql\`…\`)` fails the whole schema with `TS2345 separate declarations of a private property 'shouldInlineParams'`. Under `file:`-link development, `drizzle-orm` nests under the kit and becomes a second copy, so **pin `drizzle-orm` to the consumer's own single copy in `tsconfig.json`**: - - ```jsonc - // tsconfig.json compilerOptions (merge with existing paths if any) - "paths": { - "drizzle-orm": ["./node_modules/drizzle-orm"], - "drizzle-orm/*": ["./node_modules/drizzle-orm/*"] - } - ``` - - With `moduleResolution: "Bundler"`, `baseUrl` is not required (if `baseUrl` is already set, drop the leading `./`). On the published package (a single copy) these `paths` are harmless. **No `overrides` needed.** -- When developing against the kit via a direct `file:` link, run `npm install` in the kit repo itself to satisfy its peers (do not add `overrides` on the consumer side). - -**`CURRENT_TIMESTAMP` vs the connection `timezone:'+09:00'`** - -| Path | Who decides the time | Relationship to JST | -| --- | --- | --- | -| The app binds a `Date` (INSERT/UPDATE) | mysql2 + connection `timezone:'+09:00'` | Treated as JST on the wire (`datetime-wire` test) | -| `DEFAULT CURRENT_TIMESTAMP` / `ON UPDATE CURRENT_TIMESTAMP` | The MySQL server (session `time_zone`) | A **separate path** from the connection option. JST if the RDS `time_zone` is `+09:00`, UTC if UTC | - -`jstTimestamp` / `jstDatetime` only handle read/write pass-through and DATE normalization; they do not change the timezone of server-side defaults. For columns that need `ON UPDATE`, keep the DDL intent with `.$onUpdateFn(() => jstOnUpdateNow(6))`. - -### 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' -``` - -### Offline replicas — `@rdlabo/workers-hono-kit/offline` - -Table-agnostic building blocks for product-owned REST ↔ DB method converters and their offline -replica wire values. This subpath does not define table projections, Zod object shapes, -public-column allowlists, schema hashes, or domain rules; those remain in each Hono application. - -This is an additive subpath: existing root and subpath exports are unchanged. Consumers can migrate -converter internals independently without changing REST payloads, schema hashes, or persisted SQLite -rows. For an `AUTO_INCREMENT` table, omit `id` from a create method's table scheme; keep the -client-generated UUID in `local_id` and keep `server_id` null until the server confirms its id. - -| Export | Description | -| --- | --- | -| `defineRestDbMethodConverter(converter)` | Type a product-owned, pure `MethodScheme ↔ TableScheme` converter without hiding HTTP or persistence side effects. | -| `RestDbMethodConverter` | Product-owned converter contract. Select and insert bundles may differ; every represented table and column remains required. | -| `CompleteRestDbTableScheme` | Compile-time lock requiring every represented table key and row column. | -| `toReplicaIsoDatetime(value)` | `Date` / datetime string → canonical UTC ISO-8601 wire value. | -| `toReplicaDateOnly(value)` | `Date` / date string / `null` → canonical `YYYY-MM-DD` / `null`. | -| `replicaTimestampMs(value)` | Replica datetime → epoch milliseconds for legacy DTOs. | -| `toTinyIntFlag(value)` / `fromTinyIntFlag(value)` | Boolean-like value ↔ numeric tinyint flag. | -| `replicaNowIso(clock?)` | Injectable wall clock → canonical UTC ISO-8601 wire value. | - -```ts -import { - defineRestDbMethodConverter, - replicaNowIso, - toReplicaIsoDatetime, -} from '@rdlabo/workers-hono-kit/offline'; - -type Tables = { - foods: FoodRow[]; - allergens: AllergenRow[]; -}; - -export const foodMethodConverter = defineRestDbMethodConverter({ - toMethodScheme: ({ foods, allergens }) => ({ - ...foods[0], - allergens: allergens.map(({ value }) => value), - }), - toTableScheme: (method) => ({ - foods: [{ id: method.id, memo: method.memo ?? null }], - allergens: method.allergens.map((value) => ({ threadId: method.id, value })), - }), -}); -``` - -`toTableScheme` requires every key represented by its DB row types. This includes nullable/default -columns that Drizzle marks optional in `$inferInsert`; write `memo: method.memo ?? null` instead of -omitting `memo`. If a REST method intentionally does not own an `AUTO_INCREMENT` column, remove it -from that method's product-owned table scheme explicitly: - -```ts -type CreateTables = { - foods: Omit[]; -}; -``` - -The converter then cannot demand or manufacture `id`; the server adds the generated id to the -confirmed response before it is stored as `server_id`. - -When a write needs authenticated ownership or scope that is intentionally absent from the public -REST body, use separate select/insert bundles and an explicit write context. The original -two-generic form remains valid. - -```ts -defineRestDbMethodConverter({ - toMethodScheme: ({ foods, allergens }) => composeFood(foods, allergens), - toTableScheme: (method, { userId }) => ({ - foods: [{ userId, name: method.name, memo: method.memo ?? null }], - allergens: method.allergens.map((value) => ({ value })), - }), -}); -``` - -```ts -replicaNowIso(() => new Date('2026-07-23T10:00:00Z')); // '2026-07-23T10:00:00.000Z' -toReplicaIsoDatetime('2026-07-23T19:00:00+09:00'); // '2026-07-23T10:00:00.000Z' -``` - -### Testing — `@rdlabo/workers-hono-kit/testing` - -Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boilerplate. - -| Export | Description | -| --- | --- | -| `createTestDb(options)` / `TestDb` / `CreateTestDbOptions` / `TestDbConnection` | Test database built from committed Drizzle migrations as the single source of truth: `resetSchema` / `createTestPool` / `truncateAll` / `seed` / `mysqlReachable`. | -| `FakeFirebaseVerifier` | In-memory `FirebaseVerifier` for offline route tests (`register` / `verifyIdToken` / `getUser` / `deleteUser`). | -| `createPoolDatabase(options)` / `CreatePoolDatabaseOptions` | A `Database` backed by a single pool used as both primary and replica. | -| `createNoopDatabase()` | A `Database` stub that throws on `write` / `transaction` to catch accidental DB use in DB-less routes. | -| `authHeaders(token, opts?)` | Build interceptor-compatible auth headers for requests. | -| `registerFirebaseToken(firebase, uid, record?, token?)` | Register a token in a `FakeFirebaseVerifier` (no DB). | -| `provisionUser(pool, firebase, opts)` | Register a token and provision a conventional `users(id, firebase_uid, agree)` row; returns the user id (idempotent). | -| `configurableFake(impl, name?)` | Build a test double from a partial implementation; un-stubbed members throw `"${name}.${method} not configured"`. | -| `fakeApiList` / `fakePaymentIntent` / `fakeStripeEvent` / `fakeCheckoutSession` / `fakeCustomer` / `fakePrice` / `fakeSubscription` | Stripe object fixtures with sensible defaults, overridable per test. | -| `fakeKv()` / `fakeQueue()` / `FakeQueue` | In-memory Workers KV / Queues producer doubles (`sent` + `batchCount` on queues for subrequest-bound assertions). | - -## Usage - -### Response finalization (ETag) - -```ts -import { Hono } from 'hono'; -import { finalizeResponse } from '@rdlabo/workers-hono-kit'; - -const app = new Hono(); -app.use('*', finalizeResponse()); -``` - -### Request validation - -```ts -import { validate } from '@rdlabo/workers-hono-kit'; -import { z } from 'zod'; - -app.post('/users', validate('json', z.object({ name: z.string() })), (c) => { - const body = c.req.valid('json'); // typed & validated - return c.json(body, 201); -}); - -// Report validation failures (response is unchanged): -validate('json', schema, { - onValidationError: (err, c) => Sentry.captureException(err), -}); -``` - -`param` / `query` values arrive as strings — coerce numbers with the zod helpers: - -```ts -import { zNum, zNumOptional } from '@rdlabo/workers-hono-kit'; - -const Params = z.object({ id: zNum(z.number().int()), page: zNumOptional() }); -``` - -### Firebase ID-token verification - -```ts -import { createRemoteFirebaseVerifier } from '@rdlabo/workers-hono-kit'; - -const verifier = createRemoteFirebaseVerifier(projectId); -const decoded = await verifier.verifyIdToken(idToken); // { uid, email, ... } -``` - -With `getUser` / `deleteUser` (needs a service account): - -```ts -import { createRemoteJWKSet } from 'jose'; -import { JoseFirebaseVerifier, IdentityToolkit, SECURETOKEN_JWK_URL } from '@rdlabo/workers-hono-kit'; - -const verifier = new JoseFirebaseVerifier({ - projectId, - keyResolver: createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL)), - identity: new IdentityToolkit(serviceAccount), -}); -``` - -### AWS Secrets Manager - -```ts -import { getAuthenticationSecret } from '@rdlabo/workers-hono-kit'; - -interface MySecret { - firebaseProduction: string; - stripeSecret: string; -} - -const secret = await getAuthenticationSecret( - { - accessKeyId: env.AWS_ACCESS_KEY_ID, - secretAccessKey: env.AWS_SECRET_ACCESS_KEY, - region: 'ap-northeast-1', - }, - 'myapp/secret', -); -``` - -### STS AssumeRole (browser S3 uploads) - -```ts -import { getTemporaryCredentials } from '@rdlabo/workers-hono-kit'; - -const credentials = await getTemporaryCredentials({ - accessKeyId: env.AWS_ACCESS_KEY_ID, - secretAccessKey: env.AWS_SECRET_ACCESS_KEY, - roleArn: 'arn:aws:iam::123456789012:role/s3-put-app-only-role', - roleSessionName: `session-${userId}-${Date.now()}`, -}); -// Return credentials to the browser; PutObject uses @aws-sdk/client-s3 with AccessKeyId / … -``` - -### Deadlock retry & HTTP helpers - -```ts -import { retryWhenDeadlock, getUserProtocol, getAppInfo, HttpStatus } from '@rdlabo/workers-hono-kit'; - -await retryWhenDeadlock(() => db.transaction(/* ... */)); - -const { ipAddress, userAgent } = getUserProtocol(c); -const appInfo = getAppInfo(c); -return c.json(body, HttpStatus.CREATED); -``` - -### HTTP error / 404 handlers +# Data and testing entry points +npm install drizzle-orm mysql2 -`createHttpErrorHandler()` renders a thrown `HTTPException` as standard API error JSON, -and `notFoundHandler` gives the default unmatched-route 404 body. - -#### App entry (fleet standard) - -Use a **singleton** Hono app and inject the request-scoped container in middleware — do **not** -call `createApp(container).fetch(...)` on every request (rebuilds the route graph each time). - -```ts -// worker.ts — once per isolate -const app = createApp(); -export default Sentry.withSentry(/* … */, { - fetch: (req, env, ctx) => app.fetch(req, env, ctx), -}); - -// app.ts — fleet-standard onError (Sentry optional) -import * as Sentry from '@sentry/cloudflare'; -import { createAppErrorHandler } from '@rdlabo/workers-hono-kit'; - -app.onError( - createAppErrorHandler({ - sentry: Sentry, // omit on repos without Sentry (airlec, review, cbs-ai) - getReportError: (c) => c.get('container')?.reportError, // tests + scheduled paths - }), -); - -// odss-mobile: add classify: classifyQueryFailed (repo parity) -// winecode: sentry + isHttpError in errors.ts (no container middleware) -// foodlabel: sentry + reportError: container.reportError (per-request container closure) -``` - -Reference: `winecode/hono` (singleton + container middleware). Legacy repos still using -per-request `createApp(container)` should migrate to this shape where possible. - -**Isolate-scoped memo + container runtime** (shared across the fleet): - -```ts -import { createContainerRuntime, createIsolateMemo } from '@rdlabo/workers-hono-kit'; - -// Secrets / env: cache successes per isolate; rejections are NOT cached (retry on next request). -const resolveSecrets = createIsolateMemo(async (env: Env) => { /* SM or env vars */ }); - -const { middleware: containerMiddleware, withContainer } = createContainerRuntime({ - hyperdrives: (env) => ({ primary: env.HYPERDRIVE_PRIMARY, replica: env.HYPERDRIVE_REPLICA }), - createContainer: async ({ env, executionCtx, primary, replica }) => { - const secret = await resolveSecrets(env); - return buildContainer({ /* db from primary/replica, secret, … */ }); - }, -}); -``` - -Use `withContainer` from `scheduled` / `queue` handlers; use `containerMiddleware` in `createApp`. - -```ts -import { createHttpErrorHandler, notFoundHandler } from '@rdlabo/workers-hono-kit'; - -app.notFound(notFoundHandler); - -// Prefer createAppErrorHandler (see "App entry" above). Lower-level only when needed: -app.onError(createHttpErrorHandler()); -``` - -**Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Pass `sentry` -to `createAppErrorHandler` (or wire `getReportError` / `reportError` for tests and scheduled paths). - -Repos with a custom DB error classifier (e.g. odss-mobile) pass `classify` to -`createAppErrorHandler` — do not call `createQueryFailedErrorHandler` directly unless you need full control. - -### Auth middleware - -Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id → -set context, with configurable reporting and response hooks). Inject your own verify/resolver, -context-variable names, and failure mode. By default a missing header remains backward compatible -and calls `verify('')`; set `rejectMissingToken: true` to reject missing/blank input first with -`AuthTokenMissingError`. - -`createAuthMiddleware` is generic over your Hono `Env`, so `c.set(...)` in -`setContext` is type-checked against your `Variables`. - -```ts -import { createAuthMiddleware, createIdentityAuthFailureBody } from '@rdlabo/workers-hono-kit'; - -// AuthGuard: verify + resolve (and provision) the DB user id. -const userAuth = createAuthMiddleware({ - rejectMissingToken: true, - verify: (token) => container.firebase.verifyIdToken(token), - resolveUserId: (record, _c, appInfo) => - container.auth.getUserIdFromFirebase(record, appInfo).catch(() => container.auth.createUser(record)), - setContext: (c, { verified, appInfo, userId }) => { - c.set('userRecord', verified); - c.set('userId', userId); - c.set('appInfo', appInfo); - }, - reportFailure: (error, context, { stage, tokenPresent }) => { - // Suppress expected credential rejection; report dependency/internal failures without tokens. - }, - onFailure: (_error, context, { stage }) => - context.json(createIdentityAuthFailureBody(), 401), -}); - -// TokenGuard (login): verify only — omit resolveUserId. Override the failure if needed. -const tokenAuth = createAuthMiddleware({ - rejectMissingToken: true, - verify: (token) => container.firebase.verifyIdToken(token), - setContext: (c, { verified }) => c.set('userRecord', verified), - onFailure: (_e, c) => c.json(createIdentityAuthFailureBody(), 401), -}); -``` - -`reportFailure(error, context, details)` receives only the stage (`token`, `verify`, `appInfo`, -`resolveUserId`, or `setContext`) and a `tokenPresent` boolean; raw token data is never included in -`details`. If the hook is omitted, the historical `console.error(error)` behavior remains. A reporting -hook failure is logged but cannot change the authentication response. `onFailure` receives the same -details as its third argument and may be asynchronous. - -Authentication failures use three explicit scopes. Only `identity` permits a client to purge its -global authenticated session, offline replica boundary, and outbox. `reauthentication` means the -identity remains valid but a recent sign-in is required; `credential` belongs to a domain feature -such as a public booking token. New APIs use `401`; products with installed clients that historically -interpret auth failure as `403` use `createLegacyIdentityAuthFailureBody()` until that compatibility -contract can be retired. An untagged `403` is an authenticated permission/business denial and must -not be used as a global-session invalidation signal. Domain-specific `code` values remain product-owned. -`createAuthMiddleware` retains its historical untagged `403` default for source/runtime compatibility; -the tagged identity contract is an explicit `onFailure` opt-in as shown above. - -### 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) bindings not on Hono env (legacy per-request createApp): pass explicitly — prefer fleet -// standard singleton app + container middleware so env is always on `c.env`. -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" +# AI Gateway +npm install ai ai-gateway-provider ``` -Query percentiles by route/colo with the Analytics Engine SQL API: +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. -```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 container middleware vs. building the container in `worker.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. +## Entry points -### AI Gateway +| 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 | -Route `@ai-sdk` models through the Cloudflare AI Gateway — either with a Workers `AI` binding -(production / `wrangler dev`) or with REST credentials (non-Workers contexts). +Subpath imports keep optional database and testing dependencies out of the root runtime surface. -```ts -import { createAiGatewayProvider } from '@rdlabo/workers-hono-kit'; -import { openai } from '@ai-sdk/openai'; +## Documentation -// Binding form (Workers): -const provider = createAiGatewayProvider({ binding: env.AI.gateway('my-gateway') }); +- [HTTP and Authentication](./docs/http-auth.md) +- [Data Layer](./docs/data-layer.md) +- [Realtime and Offline](./docs/realtime-offline.md) +- [Testing and Operations](./docs/testing-operations.md) -// REST form (anywhere): -const rest = createAiGatewayProvider({ - accountId: env.CF_ACCOUNT_ID, - gateway: 'my-gateway', - token: env.CF_AIG_TOKEN, -}); + +**Full documentation:** [https://docs.rdlabo.dev/projects/workers-hono-kit](https://docs.rdlabo.dev/projects/workers-hono-kit) -const model = provider.aigateway(openai('gpt-4o-mini')); -``` - -### MySQL data layer (Hyperdrive + Drizzle) - -```ts -import { createHyperdriveDatabase, hyperdriveConnectionOptions } from '@rdlabo/workers-hono-kit/db'; -import { drizzle } from 'drizzle-orm/mysql2'; -import { DRIZZLE_ORM_OPTIONS } from '@rdlabo/workers-hono-kit/db'; - -const db = createHyperdriveDatabase({ - primaryHyperdrive: env.HYPERDRIVE, - replicaHyperdrive: env.HYPERDRIVE_REPLICA, - createOrm: (conn) => drizzle(conn, { ...DRIZZLE_ORM_OPTIONS, schema }), -}); - -const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL -await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried -``` +## Additional GitHub docs -### KV cache - -```ts -import { KVCache } from '@rdlabo/workers-hono-kit'; - -const cache = new KVCache(env.CACHE, { appName: 'myapp' }); // version prefix defaults to 'v8_' -await cache.set('users', 'byId', userId, user, 600); -const hit = await cache.get('users', 'byId', userId); -``` - -Cache failures remain fail-soft. To report them without changing caller behavior, configure the -optional observer (for example, to forward the raw error to Sentry). Kit-generated context is -limited to `operation` and `table`; it never adds the cache type, generated key, id, or value. - -```ts -const cache = new KVCache(env.CACHE, { - appName: 'myapp', - onError: (error, context) => reportError(error, context), -}); -``` - -### Stripe (Workers-native) - -```ts -import { createStripeClient, verifyStripeWebhook } from '@rdlabo/workers-hono-kit'; - -const stripe = createStripeClient(secret); // or { apiVersion: '2024-04-10' } to pin -const event = await verifyStripeWebhook(secret, webhookSecret, rawBody, c.req.header('stripe-signature') ?? ''); -``` - -### Payment failure & subscription reconcile - -Store only the raw reason; render the user-facing message on read (so wording changes never need a migration). - -```ts -import { - extractStripeFailureReason, - serializePaymentFailure, - paymentFailureMessageJa, -} from '@rdlabo/workers-hono-kit'; - -// On a Stripe failure webhook: persist the normalized reason. -const reason = extractStripeFailureReason(event.data.object); -if (reason) { - await db.write.insert(paymentFailed).values({ - type: 'stripe', - status: 'failed', - receipt: serializePaymentFailure({ reason, source: 'webhook.invoice.payment_failed', occurredAt }), - }); -} - -// On read: provider-agnostic Japanese message. -const message = paymentFailureMessageJa({ status: row.status, type: row.type, reason: parsed?.reason }); -``` - -In-app purchase: verify → classify → key the row by billing cycle. - -```ts -import { - verifyAppleReceipt, - classifyAppleRenewal, - iapFailureKey, - serializeIapFailureReason, -} from '@rdlabo/workers-hono-kit'; - -const verify = await verifyAppleReceipt(receipt, { password: appleSharedSecret }); -const cls = classifyAppleRenewal(verify, Date.now()); -if (cls.state === 'billing_retry' || cls.state === 'lapsed') { - await db.write.insert(paymentFailed).values({ - type: 'ios', - status: cls.state === 'billing_retry' ? 'failed' : 'canceled', - recursions_id: iapFailureKey({ - platform: 'ios', - originalTransactionId: cls.originalTransactionId!, - expiresDateMs: cls.expiresDateMs!, - }), - receipt: serializeIapFailureReason({ - code: cls.state === 'billing_retry' ? 'billing_retry' : 'subscription_canceled', - statusCode: cls.statusCode, - billingRetryStatus: cls.billingRetryStatus, - autoRenewStatus: cls.autoRenewStatus, - }), - }); -} -``` - -### Testing - -```ts -import { createTestDb, FakeFirebaseVerifier, configurableFake } from '@rdlabo/workers-hono-kit/testing'; - -const testDb = createTestDb({ dbName: 'myapp_test', migrationsFolder: './drizzle' }); -await testDb.resetSchema(); -const pool = testDb.createTestPool(); - -const firebase = new FakeFirebaseVerifier(); -firebase.register('token-1', { uid: 'uid-1', email: 'a@example.com' }); - -const gateway = configurableFake({ charge: async () => ({ ok: true }) }, 'PaymentGateway'); -``` - -## Local development / linking - -If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`: - -```jsonc -{ - "compilerOptions": { - "baseUrl": ".", - "paths": { - "zod": ["node_modules/zod"], - "zod/*": ["node_modules/zod/*"], - "@hono/zod-validator": ["node_modules/@hono/zod-validator"] - } - } -} -``` - -When installed from npm normally, package managers dedupe `zod` to a single copy and this is not needed. - -## 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 ` | 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=

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. | - -## Storage-agnostic role policies - -`createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The -application can resolve roles from a membership table, a `users.role` column, token claims, or any -other source. - -```ts -import { createRolePolicy } from '@rdlabo/workers-hono-kit'; - -type Role = 'owner' | 'admin' | 'member' | 'read'; -type Permission = 'organization.manage' | 'resource.write' | 'resource.read'; - -const policy = createRolePolicy({ - permissions: { - owner: ['organization.manage', 'resource.write', 'resource.read'], - admin: ['resource.write', 'resource.read'], - member: ['resource.write', 'resource.read'], - read: ['resource.read'], - }, - assignableRoles: { - owner: ['admin', 'member', 'read'], - admin: ['member', 'read'], - member: [], - read: [], - }, - manageableRoles: { - owner: ['admin', 'member', 'read'], - admin: ['member', 'read'], - member: [], - read: [], - }, -}); -``` - -## Development - -```bash -npm install -npm run typecheck # tsc --noEmit -npm run lint # eslint -npm test # vitest -npm run build # tsc -p tsconfig.build.json → dist/ -``` +- [CLI](./docs/cli.md) +- [Role Policies](./docs/role-policies.md) +- [Development](./docs/development.md) +- [API Reference](./docs/api.md) ## License [MIT](./LICENSE) © rdlabo-dev + diff --git a/docs/api-business-time.md b/docs/api-business-time.md new file mode 100644 index 0000000..083504f --- /dev/null +++ b/docs/api-business-time.md @@ -0,0 +1,37 @@ +--- +title: 'API: Business Time' +--- + +# API: `@rdlabo/workers-hono-kit/business-time` + +String-level JST business-time conversions (Workers UTC instant ↔ business calendar date / date-time), with **no `mysql2` / `drizzle-orm` dependency**. This is a different layer from the `./db` column helpers (which handle the MySQL wire format): the DB stays on JST, and the app handles JST explicitly through this module instead of relying implicitly on the connection `timezone`. + +| Export | Description | +| --- | --- | +| `today(ref?)` | The JST business calendar date (`YYYY-MM-DD`) of `ref` (defaults to now). | +| `toBusinessDate(instant)` | UTC instant → JST business calendar date (`YYYY-MM-DD`). | +| `normalizeBusinessDate(value)` | Normalize a `string` / `Date` / nullish to `YYYY-MM-DD`; a `YYYY-MM-DD` string passes through unchanged, nullish/empty/invalid → `null`. | +| `toBusinessDateTime(instant)` | UTC instant → JST business date-time (`YYYY-MM-DD HH:mm:ss`). | +| `parseBusinessDateTime(value)` | JST business date-time string → UTC instant (accepts a space or `T` separator). | +| `formatBusinessDateTime(instant, pattern?)` | Format an instant in the business TZ (Nest `helper.formatDate`-compatible tokens). | +| `startOfBusinessDay(date)` / `endOfBusinessDay(date)` | UTC instant of `00:00:00` / `23:59:59` on a JST business date. | +| `businessDateTimeInstant(date, time)` | JST business date + wall-clock time → UTC instant. | +| `addBusinessDays(date, days)` | Add calendar days to a JST business date. | +| `ageOnBusinessDate(birthDate, asOfDate?)` | Full years of age on a business date (`asOfDate` defaults to `today()`). | +| `DEFAULT_BUSINESS_DATETIME_PATTERN` | Default `formatBusinessDateTime` pattern (`YYYY-MM-DDThh:mm:ss`). | +| `BUSINESS_TIMEZONE` / `BusinessDate` / `BusinessDateTime` | JST timezone constant and the business-date / date-time string types. | + +```ts +import { + toBusinessDate, + toBusinessDateTime, + formatBusinessDateTime, + addBusinessDays, +} from '@rdlabo/workers-hono-kit/business-time'; + +const now = new Date('2026-07-05T21:00:00Z'); +toBusinessDate(now); // '2026-07-06' (JST) +toBusinessDateTime(now); // '2026-07-06 06:00:00' +formatBusinessDateTime(now); // '2026-07-06T06:00:00' +addBusinessDays('2026-07-06', 3); // '2026-07-09' +``` diff --git a/docs/api-db.md b/docs/api-db.md new file mode 100644 index 0000000..81ce2bf --- /dev/null +++ b/docs/api-db.md @@ -0,0 +1,53 @@ +--- +title: 'API: DB' +--- + +# API: `@rdlabo/workers-hono-kit/db` + +Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in. + +| Export | Description | +| --- | --- | +| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. Workers cleans them up at invocation end; the legacy `dispose()` is a no-op. | +| `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. | +| `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. | +| `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. | +| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. | +| `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. | +| `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. | +| `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. | +| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). | +| `MYSQL_TIMEZONE` | Default mysql2 connection `timezone` (`'+09:00'`) for the JST DB deployment. | +| `jstTimestamp` / `jstDatetime` / `jstDate` | Drizzle column helpers (no repo-side wrapper needed). | +| `jstOnUpdateNow` | SQL expression for `ON UPDATE CURRENT_TIMESTAMP`. The `jstTimestamp` customType (and friends) do not support `.onUpdateNow()`, so pair it with `.$onUpdateFn(() => jstOnUpdateNow(fsp))`. | +| `DRIZZLE_ORM_OPTIONS` / `honoDrizzleConfig(options)` / `HonoDrizzleConfigOptions` | Shared Drizzle casing (`snake_case`) for both the runtime `drizzle()` call and `drizzle.config.ts`, keeping config ↔ runtime in sync. | +| `resolveDbSecret()` / `ResolvedDbSecret` | Resolve DB connection info from the `DB_SECRET` env var (an AWS RDS managed-secret JSON string) for CI migrate / local tooling. Returns `undefined` when `DB_SECRET` is unset; throws on invalid JSON or a missing required key. | +| `baselineMigrations(options)` / `readBaselineEntry(migrationsFolder)` / `BaselineMigrationsOptions` / `BaselineResult` / `BaselineEntry` | Brownfield first-deploy helper: mark an existing `0000_*` migration as applied without re-running DDL. | + +## Drizzle column helpers (`jstTimestamp`, etc.) + +- `drizzle-orm` is a **peer** only. The kit does not include `drizzle-orm` as a dependency (even after publishing, it uses the consumer's single copy). +- The consumer just keeps `drizzle-orm` in its `dependencies` as usual. **No `overrides` in `package.json` are needed.** +- The npm-published artifact contains no `devDependencies`, so installing it does not add a kit-specific `drizzle-orm` (there is only the one peer copy). +- The column helpers `import` the consumer's `drizzle-orm` at runtime, and the types are the `customType` inference as-is (`MySqlCustomColumnBuilder<…>`). No `any` is used, so the column's semantic type propagates to the consumer table's `$inferSelect`. +- **Precondition: resolve drizzle to a single copy.** Drizzle's `SQL` is a **nominal** type carrying a private field `shouldInlineParams`, so if the kit and the consumer resolve different copies, `jstTimestamp(…).default(sql\`…\`)` fails the whole schema with `TS2345 separate declarations of a private property 'shouldInlineParams'`. Under `file:`-link development, `drizzle-orm` nests under the kit and becomes a second copy, so **pin `drizzle-orm` to the consumer's own single copy in `tsconfig.json`**: + + ```jsonc + // tsconfig.json compilerOptions (merge with existing paths if any) + "paths": { + "drizzle-orm": ["./node_modules/drizzle-orm"], + "drizzle-orm/*": ["./node_modules/drizzle-orm/*"] + } + ``` + + With `moduleResolution: "Bundler"`, `baseUrl` is not required (if `baseUrl` is already set, drop the leading `./`). On the published package (a single copy) these `paths` are harmless. **No `overrides` needed.** +- When developing against the kit via a direct `file:` link, run `npm install` in the kit repo itself to satisfy its peers (do not add `overrides` on the consumer side). + +## `CURRENT_TIMESTAMP` vs the connection `timezone:'+09:00'` + +| Path | Who decides the time | Relationship to JST | +| --- | --- | --- | +| The app binds a `Date` (INSERT/UPDATE) | mysql2 + connection `timezone:'+09:00'` | Treated as JST on the wire (`datetime-wire` test) | +| `DEFAULT CURRENT_TIMESTAMP` / `ON UPDATE CURRENT_TIMESTAMP` | The MySQL server (session `time_zone`) | A **separate path** from the connection option. JST if the RDS `time_zone` is `+09:00`, UTC if UTC | + +`jstTimestamp` / `jstDatetime` only handle read/write pass-through and DATE normalization; they do not change the timezone of server-side defaults. For columns that need `ON UPDATE`, keep the DDL intent with `.$onUpdateFn(() => jstOnUpdateNow(6))`. diff --git a/docs/api-offline.md b/docs/api-offline.md new file mode 100644 index 0000000..a88d620 --- /dev/null +++ b/docs/api-offline.md @@ -0,0 +1,71 @@ +--- +title: 'API: Offline' +--- + +# API: `@rdlabo/workers-hono-kit/offline` + +Table-agnostic building blocks for product-owned REST ↔ DB method converters and their offline replica wire values. This subpath does not define table projections, Zod object shapes, public-column allowlists, schema hashes, or domain rules; those remain in each Hono application. + +This is an additive subpath: existing root and subpath exports are unchanged. Consumers can migrate converter internals independently without changing REST payloads, schema hashes, or persisted SQLite rows. For an `AUTO_INCREMENT` table, omit `id` from a create method's table scheme; keep the client-generated UUID in `local_id` and keep `server_id` null until the server confirms its id. + +| Export | Description | +| --- | --- | +| `defineRestDbMethodConverter(converter)` | Type a product-owned, pure `MethodScheme ↔ TableScheme` converter without hiding HTTP or persistence side effects. | +| `RestDbMethodConverter` | Product-owned converter contract. Select and insert bundles may differ; every represented table and column remains required. | +| `CompleteRestDbTableScheme` | Compile-time lock requiring every represented table key and row column. | +| `toReplicaIsoDatetime(value)` | `Date` / datetime string → canonical UTC ISO-8601 wire value. | +| `toReplicaDateOnly(value)` | `Date` / date string / `null` → canonical `YYYY-MM-DD` / `null`. | +| `replicaTimestampMs(value)` | Replica datetime → epoch milliseconds for legacy DTOs. | +| `toTinyIntFlag(value)` / `fromTinyIntFlag(value)` | Boolean-like value ↔ numeric tinyint flag. | +| `replicaNowIso(clock?)` | Injectable wall clock → canonical UTC ISO-8601 wire value. | + +```ts +import { + defineRestDbMethodConverter, + replicaNowIso, + toReplicaIsoDatetime, +} from '@rdlabo/workers-hono-kit/offline'; + +type Tables = { + foods: FoodRow[]; + allergens: AllergenRow[]; +}; + +export const foodMethodConverter = defineRestDbMethodConverter({ + toMethodScheme: ({ foods, allergens }) => ({ + ...foods[0], + allergens: allergens.map(({ value }) => value), + }), + toTableScheme: (method) => ({ + foods: [{ id: method.id, memo: method.memo ?? null }], + allergens: method.allergens.map((value) => ({ threadId: method.id, value })), + }), +}); +``` + +`toTableScheme` requires every key represented by its DB row types. This includes nullable/default columns that Drizzle marks optional in `$inferInsert`; write `memo: method.memo ?? null` instead of omitting `memo`. If a REST method intentionally does not own an `AUTO_INCREMENT` column, remove it from that method's product-owned table scheme explicitly: + +```ts +type CreateTables = { + foods: Omit[]; +}; +``` + +The converter then cannot demand or manufacture `id`; the server adds the generated id to the confirmed response before it is stored as `server_id`. + +When a write needs authenticated ownership or scope that is intentionally absent from the public REST body, use separate select/insert bundles and an explicit write context. The original two-generic form remains valid. + +```ts +defineRestDbMethodConverter({ + toMethodScheme: ({ foods, allergens }) => composeFood(foods, allergens), + toTableScheme: (method, { userId }) => ({ + foods: [{ userId, name: method.name, memo: method.memo ?? null }], + allergens: method.allergens.map((value) => ({ value })), + }), +}); +``` + +```ts +replicaNowIso(() => new Date('2026-07-23T10:00:00Z')); // '2026-07-23T10:00:00.000Z' +toReplicaIsoDatetime('2026-07-23T19:00:00+09:00'); // '2026-07-23T10:00:00.000Z' +``` diff --git a/docs/api-root.md b/docs/api-root.md new file mode 100644 index 0000000..10fc6e1 --- /dev/null +++ b/docs/api-root.md @@ -0,0 +1,75 @@ +--- +title: 'API: Root' +--- + +# API: `@rdlabo/workers-hono-kit` + +The root export is web-standard only: it runs on `workerd` and never depends on Node.js APIs or `mysql2`. The table below lists the helpers exported from the root entry point. + +| Export | Description | +| --- | --- | +| `finalizeResponse()` | Middleware that adds a weak `ETag` (delegates to `hono/etag`; also handles `If-None-Match` → `304`). | +| `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). | +| `createValidate({ sentry? })` | Bound `validate` factory. Pass `sentry` on Sentry apps; omit for console-only (review, cbs-ai). | +| `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. | +| `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). | +| `getAuthenticationSecret(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). | +| `getTemporaryCredentials(options)` / `GetTemporaryCredentialsOptions` / `StsCredentials` | STS `AssumeRole` via SigV4 `fetch` (global `sts.amazonaws.com`); returns temporary credentials for browser S3 uploads. | +| `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. | +| `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). | +| `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). | +| `createServiceAccountVerifier(serviceAccountJson)` | Cached verifier built from a service-account JSON, **with `IdentityToolkit`** (getUser/deleteUser). One per isolate, re-created only when the SA JSON changes. | +| `IdentityToolkit` / `ServiceAccount` / `SECURETOKEN_JWK_URL` | Identity Toolkit REST client + constants for `getUser` / `deleteUser`. | +| `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. | +| `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). | +| `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. | +| `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). | +| `HttpStatus` | Standard HTTP status code enum (IANA registry). | +| `createHttpErrorHandler(options?)` / `HttpErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to `{ statusCode, message, error? }` (`401` omits `error`). Optional custom error predicate and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). | +| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). | +| `createQueryFailedErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. | +| `classifyGenericMysqlDriverError(err)` | Default classifier: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. | +| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss). | +| `notFoundHandler(c)` | `app.notFound()` handler with `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. | +| `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. | +| `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. | +| `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. | +| `createIdentityAuthFailureBody()` / `createLegacyIdentityAuthFailureBody()` / `createAuthFailureBody(scope, code, message)` / `AuthFailureScope` | Stable wire contract for distinguishing a lost global identity (`identity`) from recent-login (`reauthentication`) and feature credential (`credential`) failures. The legacy helper tags products whose installed clients still require auth failure as `403`. | +| `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. | +| `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. | +| `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. | +| `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). | +| `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: both variants log background rejections without propagating them; `createWaitUntilDefer` also registers work via `ctx.waitUntil`. | +| `configureHibernationAutoResponse` / `upgradeHibernationWebSocket` / `broadcastHibernationWebSockets` | Hibernation WebSocket room primitives: runtime ping/pong without waking JavaScript, attachment-before-accept upgrade, and broadcast through sockets restored by `getWebSockets()`. | +| `acknowledgeHibernationWebSocketClose` / `closeHibernationWebSocket` | Safe close helpers, including normalization of reserved received-only close codes. | +| `retryDurableObjectOperation(operation, options?)` / `isRetryableDurableObjectError(error)` | Retry idempotent DO work only for `retryable && !overloaded`, with jittered exponential backoff. `operation` runs per attempt so callers create a fresh stub after an exception. | +| `createIdempotencyInput(...)` / `runIdempotentMutation(...)` | Canonical payload hashing and a transaction-bound mutation state machine. Missing keys preserve legacy behavior; replay/conflict/in-flight semantics are shared while each app owns its schema and ORM adapter. | +| `withIdempotencyHttpErrors(run)` | Maps only standard idempotency failures to 400/409/503 and rethrows unrelated failures. | +| `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). | +| `KVCache` / `KVNamespace` / `KVCacheOptions` / `KVCacheErrorContext` / `KVCacheOperation` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application; optional `onError(error, context)` observes fail-soft read/parse/serialize/write/delete failures. Context contains only the operation and logical table, not cache types, keys, ids, or values. | +| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). | +| `extractStripeFailureReason(source)` / `StripeFailureReason` | Duck-type a Stripe `PaymentIntent` / `Invoice` / `{ paymentIntent?, invoice? }` / thrown error into a normalized `{ code, declineCode, message, paymentIntentId, invoiceId, subscriptionId }` (SDK-free), or `null`. | +| `stripeFailureMessageJa(reason)` | Render a `StripeFailureReason` (or `null`) as a single user-facing Japanese sentence (`decline_code` > `code`; fraud codes masked; unknown → generic). | +| `PaymentDeclinedError` / `toPaymentDeclinedError(error, status?)` / `PaymentDeclinedBody` | `HTTPException` carrying a verbatim `{ statusCode, message, code?, declineCode? }` body for a synchronous card decline (defaults to `400`). `toPaymentDeclinedError` returns `null` for non-declines (re-throw → 500). | +| `classifyStripeReconcile(subscription)` / `StripeReconcileAction` | Classify an expanded Stripe subscription into `trial` / `clear` / `canceled` / `failed` / `action_required` / `none` (termination evaluated before `succeeded`). Consumer does the DB write. | +| `serializePaymentFailure(record)` / `parsePaymentFailure(receipt)` / `PaymentFailureRecord` / `PaymentFailureReason` / `PaymentFailureSource` | (De)serialize the `payment_failed.receipt` JSON. `parsePaymentFailure` restores both a full Stripe record and a bare IAP reason. | +| `serializeIapFailureReason(reason)` / `IapFailureReason` | Serialize an IAP reason (`billing_retry` / `auto_renew_off` / `subscription_canceled` / `subscription_gone` + provider codes) directly, without the source/timestamp wrapper. | +| `paymentFailureMessageJa(input)` / `PaymentFailureStatus` / `PaymentFailureType` / `UNRESOLVED_PAYMENT_STATUSES` | Provider-agnostic Japanese message for a `payment_failed` row (`canceled` re-subscribe prompt, IAP `failed` App Store/Google Play prompt, else Stripe wording). `UNRESOLVED_PAYMENT_STATUSES` = everything except `resolved` for read/resolve `WHERE`. | +| `iapFailureKey(input)` | Provider-native `payment_failed.recursions_id`: iOS `${original_transaction_id}:${expires_date_ms}`, Android `${orderId}` (provider is in the `type` column). | +| `verifyAppleReceipt(receipt, opts)` / `classifyAppleRenewal(verify, now)` / `AppleRenewalClassification` / `AppleRenewalState` / `AppleVerifyReceiptResponse` / `ApplePendingRenewalInfo` / `AppleLatestReceiptInfo` | Verify an App Store receipt (production → sandbox fallback; inject `password` / `fetchImpl`) and classify it into `billing_retry` / `lapsed` / `active` / `unknown` plus the raw fields used (`statusCode` / `billingRetryStatus` / `autoRenewStatus`, latest `original_transaction_id` / `expires_date_ms`). | +| `googleAccessToken(creds, fetch?)` / `getGoogleSubscription(opts)` / `classifyGoogleSubscription(purchase, now)` / `GoogleSubscriptionClassification` / `GoogleSubscriptionState` / `GoogleSubscriptionPurchase` / `GoogleOAuthCredentials` | Exchange a refresh token for an Android Publisher access token (throws on `invalid_grant`), fetch a subscription purchase, and classify it into `canceled` / `gone` / `active` / `unknown` plus raw `statusCode` / `cancelReason`. | +| `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). | +| `processBatch(batch, handler, options?)` / `isNonRetryableQueueError(error)` / `NonRetryableQueueErrorLike` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency. Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acked as permanent failures; all other errors are retried. | +| `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt, except permanent failures which are reported immediately). | +| `assertStripeCustomerUpdated(options)` | Preserve the shared Stripe UPDATE→existence-check algorithm. `createNotFoundError(customerId)` can supply a domain-specific error without forking the algorithm. | +| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape used by lifecycle-compatible APIs and deferred work helpers. | + +Permanent Queue failures must opt in with the Queue-specific marker; unrelated `retryable` fields are ignored: + +```ts +import type { NonRetryableQueueErrorLike } from '@rdlabo/workers-hono-kit'; + +class CustomerLinkMissingError extends Error implements NonRetryableQueueErrorLike { + readonly queueDisposition = 'discard' as const; +} +``` diff --git a/docs/api-testing.md b/docs/api-testing.md new file mode 100644 index 0000000..83d470a --- /dev/null +++ b/docs/api-testing.md @@ -0,0 +1,20 @@ +--- +title: 'API: Testing' +--- + +# API: `@rdlabo/workers-hono-kit/testing` + +Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boilerplate. + +| Export | Description | +| --- | --- | +| `createTestDb(options)` / `TestDb` / `CreateTestDbOptions` / `TestDbConnection` | Test database built from committed Drizzle migrations as the single source of truth: `resetSchema` / `createTestPool` / `truncateAll` / `seed` / `mysqlReachable`. | +| `FakeFirebaseVerifier` | In-memory `FirebaseVerifier` for offline route tests (`register` / `verifyIdToken` / `getUser` / `deleteUser`). | +| `createPoolDatabase(options)` / `CreatePoolDatabaseOptions` | A `Database` backed by a single pool used as both primary and replica. | +| `createNoopDatabase()` | A `Database` stub that throws on `write` / `transaction` to catch accidental DB use in DB-less routes. | +| `authHeaders(token, opts?)` | Build interceptor-compatible auth headers for requests. | +| `registerFirebaseToken(firebase, uid, record?, token?)` | Register a token in a `FakeFirebaseVerifier` (no DB). | +| `provisionUser(pool, firebase, opts)` | Register a token and provision a conventional `users(id, firebase_uid, agree)` row; returns the user id (idempotent). | +| `configurableFake(impl, name?)` | Build a test double from a partial implementation; un-stubbed members throw `"${name}.${method} not configured"`. | +| `fakeApiList` / `fakePaymentIntent` / `fakeStripeEvent` / `fakeCheckoutSession` / `fakeCustomer` / `fakePrice` / `fakeSubscription` | Stripe object fixtures with sensible defaults, overridable per test. | +| `fakeKv()` / `fakeQueue()` / `FakeQueue` | In-memory Workers KV / Queues producer doubles (`sent` + `batchCount` on queues for subrequest-bound assertions). | diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..72d7f23 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,15 @@ +--- +title: API +--- + +# API + +`@rdlabo/workers-hono-kit` exposes five entry points. This page maps each entry point to its dedicated reference page. For feature-level examples, see [`/docs/usage`](/docs/usage). + +| Entry point | Description | Reference | +| --- | --- | --- | +| `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV, queues, idempotency). | [`/docs/api-root`](/docs/api-root) | +| `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle), JST column helpers, baseline migrations. | [`/docs/api-db`](/docs/api-db) | +| `@rdlabo/workers-hono-kit/business-time` | JST business calendar and date-time conversions. | [`/docs/api-business-time`](/docs/api-business-time) | +| `@rdlabo/workers-hono-kit/offline` | Table-agnostic REST/DB method converters and replica wire helpers. | [`/docs/api-offline`](/docs/api-offline) | +| `@rdlabo/workers-hono-kit/testing` | Drizzle-backed test DB, fakes, fixtures, and binding doubles. | [`/docs/api-testing`](/docs/api-testing) | diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..559240c --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,37 @@ +--- +title: CLI +--- + +# CLI + +The package ships `bin` commands that can be run with `npx` or wired into npm scripts in the consuming app. They are operational helpers: AWS credential sync, subrequest fan-out gating, and brownfield database baselining. + +| Command | Use | +| --- | --- | +| `workers-hono-kit-sync-dev-aws ` | 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=

workers-hono-kit-sync-dev-aws dev --var APP_ENV:development`. | +| `workers-hono-kit-check-subrequest-fanout [dir…]` | CI gate that greps for per-item external-call fan-outs (`runWithConcurrency(` / `PromisePool` / `.withConcurrency(`) that would eventually exceed the Workers subrequest cap. Annotate a genuinely-safe site with `subrequest-ok`. Scans `src` by default; exits 1 on an un-annotated marker. | +| `workers-hono-kit-db-baseline [--migrations ./drizzle]` | Brownfield first-deploy helper: record the baseline `0000` migration as *already applied* on an existing MySQL DB without running its DDL (the CLI wrapper around `baselineMigrations` / `readBaselineEntry`). Reads DB credentials from `DB_SECRET` (AWS RDS managed secret) or the individual `DB_*` env vars. | + +## `workers-hono-kit-sync-dev-aws` + +Use this in the `dev` npm script when you want AWS credentials from the active profile to be available inside `wrangler dev` without committing them to `.dev.vars`. It resolves short-lived SSO or temporary credentials and passes them as `--var` arguments. Nothing is written to disk. + +```bash +AWS_PROFILE=my-sso-profile workers-hono-kit-sync-dev-aws dev --var APP_ENV:development +``` + +## `workers-hono-kit-check-subrequest-fanout` + +Run this in CI to catch per-item external call patterns (for example `runWithConcurrency`, `PromisePool`, or `.withConcurrency`) that could fan out beyond the Workers subrequest cap. If a call site is safe, annotate it with `subrequest-ok`. The command scans `src` by default and exits with `1` if it finds an un-annotated marker. + +```bash +workers-hono-kit-check-subrequest-fanout src +``` + +## `workers-hono-kit-db-baseline` + +Use this for a brownfield first deploy against a MySQL database that already matches the schema in your first migration (`0000_*`). It records that migration as already applied without running its DDL, so later migrations can apply normally. Database credentials are read from `DB_SECRET` (an AWS RDS managed-secret JSON string) or from individual `DB_*` environment variables. + +```bash +workers-hono-kit-db-baseline --migrations ./drizzle +``` diff --git a/docs/data-layer.md b/docs/data-layer.md new file mode 100644 index 0000000..955ed48 --- /dev/null +++ b/docs/data-layer.md @@ -0,0 +1,44 @@ +Import database helpers from `@rdlabo/workers-hono-kit/db`. This entry point requires `drizzle-orm` and `mysql2`. + +## Hyperdrive database + +`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. Reads use the replica query runner; writes and transactions use the primary Drizzle instance. Workers owns connection cleanup at invocation end. + +```ts +import { createHyperdriveDatabase } from '@rdlabo/workers-hono-kit/db'; +import { drizzle } from 'drizzle-orm/mysql2'; + +const db = createHyperdriveDatabase({ + primaryHyperdrive: env.DB_PRIMARY, + replicaHyperdrive: env.DB_REPLICA, + createOrm: (primary) => drizzle(primary, { schema }), +}); + +const rows = await db.read('SELECT * FROM items WHERE id = ?', [id]); +await db.write((dz) => dz.insert(items).values(input)); +await db.transaction((tx) => tx.insert(items).values(input)); +``` + +Use `hyperdriveConnectionOptions()` when constructing lower-level mysql2 connections. The default JavaScript date conversion timezone is `+09:00`; it does not change the MySQL session timezone. + +## Writes and retries + +- `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with exponential backoff. +- `insertIdOf()`, `affectedRowsOf()`, and `insertedIdsOf()` normalize mysql2 write results. +- `withMysqlConnections()` opens primary and replica connections in parallel for a scoped operation. + +## Drizzle and JST helpers + +Use `jstTimestamp`, `jstDatetime`, `jstDate`, and `decimalNumber` for shared column behavior. Pair update timestamps with `jstOnUpdateNow()` because custom timestamp types do not expose Drizzle's `.onUpdateNow()`. + +The `/business-time` entry point converts instants and business dates in the JST business timezone: + +```ts +import { addBusinessDays, toBusinessDateTime } from '@rdlabo/workers-hono-kit/business-time'; + +toBusinessDateTime(new Date('2026-07-05T21:00:00Z')); +// '2026-07-06 06:00:00' + +addBusinessDays('2026-07-06', 3); +// '2026-07-09' +``` diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..e2fa6c2 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,36 @@ +--- +title: Development +--- + +# Development + +These commands are used when working on the package itself: + +```bash +npm install +npm run typecheck # tsc --noEmit +npm run lint # eslint +npm test # vitest +npm run build # tsc -p tsconfig.build.json → dist/ +``` + +## Local development / linking + +If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`: + +```jsonc +{ + "compilerOptions": { + "baseUrl": ".", + "paths": { + "zod": ["node_modules/zod"], + "zod/*": ["node_modules/zod/*"], + "@hono/zod-validator": ["node_modules/@hono/zod-validator"] + } + } +} +``` + +When installed from npm normally, package managers dedupe `zod` to a single copy and this is not needed. + +When developing against the kit via a direct `file:` link, run `npm install` in the kit repo itself to satisfy its peers (do not add `overrides` on the consumer side). diff --git a/docs/http-auth.md b/docs/http-auth.md new file mode 100644 index 0000000..b57253d --- /dev/null +++ b/docs/http-auth.md @@ -0,0 +1,36 @@ +## Validation + +`validate(target, schema, options?)` adapts a Zod schema to Hono and returns a NestJS `ValidationPipe`-shaped `400` response. Use `createValidate({ sentry })` to bind optional reporting once. + +```ts +import { createValidate, zNumOptional } from '@rdlabo/workers-hono-kit'; +import { z } from 'zod'; + +const validate = createValidate({ sentry }); +const querySchema = z.object({ page: zNumOptional() }); + +app.get('/items', validate('query', querySchema), async (c) => { + const query = c.req.valid('query'); + return c.json(await listItems(query.page)); +}); +``` + +## Authentication + +`createAuthMiddleware()` reads a token header, verifies a Firebase ID token, optionally resolves the application user ID, and stores the result on the Hono context. Use `createRemoteFirebaseVerifier(projectId)` for cached remote JWKS verification or `createServiceAccountVerifier()` when Identity Toolkit `getUser` and `deleteUser` operations are required. + +Keep identity, reauthentication, and feature credential failures distinct with the stable auth-failure body helpers. + +## Error and routing contracts + +- `createAppErrorHandler()` composes query failure classification, generic mysql2 classification, and optional reporting. +- `createHttpErrorHandler()` maps `HTTPException` to the shared JSON error body. +- `notFoundHandler()` returns `Cannot METHOD path` with a 404 status. +- `normalizeTrailingSlash()` removes trailing slashes without redirecting, preserving request bodies. +- `finalizeResponse()` adds weak ETags and handles matching `If-None-Match` requests. + +Mount `createMaintenanceMiddleware()` after CORS and before container or database middleware so maintenance responses do not initialize expensive infrastructure. + +## Deferred work and observability + +`createWaitUntilDefer(ctx)` registers background work through `waitUntil` and logs rejected work. `perfLog()` emits per-request application latency, colo, cold/warm state, route, and status to Workers Logs and optionally Analytics Engine. diff --git a/docs/realtime-offline.md b/docs/realtime-offline.md new file mode 100644 index 0000000..5b0a208 --- /dev/null +++ b/docs/realtime-offline.md @@ -0,0 +1,27 @@ +## Durable Object realtime + +The root and `/realtime` entry points expose the same focused realtime primitives: + +- `configureHibernationAutoResponse()` configures runtime ping/pong without waking JavaScript. +- `upgradeHibernationWebSocket()` attaches state before accepting the socket. +- `broadcastHibernationWebSockets()` broadcasts through sockets restored by `getWebSockets()`. +- `acknowledgeHibernationWebSocketClose()` and `closeHibernationWebSocket()` normalize close handling. +- `retryDurableObjectOperation()` retries only errors marked `retryable` and not `overloaded`. Create a fresh stub inside the operation for every attempt. +- `invokeDurableObjectFetch()` preserves the structured response/error contract for DO calls. + +WebSocket protocol parsers validate offered subprotocols before upgrade. + +## Offline replica contracts + +`@rdlabo/workers-hono-kit/offline` is table-agnostic. Product schemas, Zod objects, public-column allowlists, schema hashes, and domain policy stay in the application. + +`defineRestDbMethodConverter()` types a pure REST method ↔ table converter. Every represented table and column is required, including nullable/default columns. Omit an auto-increment `id` from the product-owned table scheme when a create method intentionally does not own it. + +Wire helpers canonicalize values: + +- `toReplicaIsoDatetime()` → UTC ISO-8601 +- `toReplicaDateOnly()` → `YYYY-MM-DD` or `null` +- `toTinyIntFlag()` / `fromTinyIntFlag()` → boolean/tinyint conversion +- `replicaNowIso(clock?)` → injectable current time + +Journal helpers enforce cursor coverage, retention, mutation transactions, and rebaseline behavior. Wire compatibility helpers let an application accept explicit previous fingerprints while maintaining a canonical current fingerprint. diff --git a/docs/role-policies.md b/docs/role-policies.md new file mode 100644 index 0000000..43e356f --- /dev/null +++ b/docs/role-policies.md @@ -0,0 +1,52 @@ +--- +title: Role Policies +--- + +# Storage-agnostic role policies + +`createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The application can resolve roles from a membership table, a `users.role` column, token claims, or any other source. + +```ts +import { createRolePolicy } from '@rdlabo/workers-hono-kit'; + +type Role = 'owner' | 'admin' | 'member' | 'read'; +type Permission = 'organization.manage' | 'resource.write' | 'resource.read'; + +const policy = createRolePolicy({ + permissions: { + owner: ['organization.manage', 'resource.write', 'resource.read'], + admin: ['resource.write', 'resource.read'], + member: ['resource.write', 'resource.read'], + read: ['resource.read'], + }, + assignableRoles: { + owner: ['admin', 'member', 'read'], + admin: ['member', 'read'], + member: [], + read: [], + }, + manageableRoles: { + owner: ['admin', 'member', 'read'], + admin: ['member', 'read'], + member: [], + read: [], + }, +}); +``` + +## Policy fields + +- `permissions` maps a role to the set of permissions it grants. +- `assignableRoles` defines which roles an actor may grant to another subject. +- `manageableRoles` defines which existing subject roles an actor may manage. + +The resulting `RolePolicy` has four pure checks: + +```ts +policy.hasPermission('member', 'resource.write'); // true +policy.canAssignRole('admin', 'member'); // true +policy.canManageRole('owner', 'admin'); // true +policy.canChangeRole('owner', 'admin', 'member'); // true +``` + +`canChangeRole(actor, current, next)` is a combination: the actor must be able to manage the subject's current role and also be allowed to assign the next role. Keeping role lookup and policy checks separate means the same policy can be reused no matter where roles are stored. diff --git a/docs/testing-operations.md b/docs/testing-operations.md new file mode 100644 index 0000000..ab0a844 --- /dev/null +++ b/docs/testing-operations.md @@ -0,0 +1,25 @@ +## Testing entry point + +`@rdlabo/workers-hono-kit/testing` requires the database peers and is never loaded by production code. + +| Helper | Use | +| --------------------------------------------------------------- | --------------------------------------------------------------------- | +| `createTestDb()` | Build a Drizzle-migration-backed test database. | +| `FakeFirebaseVerifier` | Verify registered in-memory Firebase tokens. | +| `createPoolDatabase()` / `createNoopDatabase()` | Provide database implementations for tests. | +| `authHeaders()` / `registerFirebaseToken()` / `provisionUser()` | Prepare authenticated route tests. | +| `configurableFake()` | Create a partial fake that fails explicitly for unconfigured members. | +| `fakeKv()` / `fakeQueue()` | Use in-memory Workers binding fakes. | +| Stripe fixture factories | Create typed events, sessions, subscriptions, prices, and intents. | + +## Queues + +`sendInChunks()` bounds queue sends under Workers subrequest limits. `processBatch()` handles a message batch sequentially, bounding concurrent subrequests to one; errors explicitly marked with `queueDisposition: 'discard'` are acknowledged, while other failures retry. `createQueueErrorHandler()` adds logging and optional final-attempt reporting. + +## Operational CLI + +The package publishes commands for synchronizing development AWS credentials, checking subrequest fanout, creating database baselines, checking realtime bundles, and querying Durable Object metrics. Run the exact CLI shipped with the installed package version and review its `--help` before changing infrastructure. + +## Trust boundaries + +AWS, Firebase, AI Gateway, Stripe, and database clients are configured by the consuming application. Do not place domain-specific credentials, schemas, or authorization policy inside the shared kit. Use `createRolePolicy()` only for storage-agnostic role and relation mapping; the application still owns its roles and permissions. diff --git a/package.json b/package.json index 2799a11..ab256c5 100644 --- a/package.json +++ b/package.json @@ -43,6 +43,7 @@ "files": [ "dist", "scripts", + "docs", "!src/**/*.spec.ts" ], "bin": { From 09fd12a9bb02e782d7ccf22e19a361e18d755ef2 Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 19 Aug 2026 13:32:28 +0900 Subject: [PATCH 2/2] docs: fix extra GitHub API map links and drop leftover YAML Point the API index at sibling markdown files, include the realtime entry point, and stop rendering front matter on GitHub. --- docs/api-business-time.md | 4 ---- docs/api-db.md | 4 ---- docs/api-offline.md | 4 ---- docs/api-root.md | 4 ---- docs/api-testing.md | 4 ---- docs/api.md | 17 +++++++---------- docs/cli.md | 4 ---- docs/development.md | 4 ---- docs/role-policies.md | 4 ---- 9 files changed, 7 insertions(+), 42 deletions(-) diff --git a/docs/api-business-time.md b/docs/api-business-time.md index 083504f..a0fde39 100644 --- a/docs/api-business-time.md +++ b/docs/api-business-time.md @@ -1,7 +1,3 @@ ---- -title: 'API: Business Time' ---- - # API: `@rdlabo/workers-hono-kit/business-time` String-level JST business-time conversions (Workers UTC instant ↔ business calendar date / date-time), with **no `mysql2` / `drizzle-orm` dependency**. This is a different layer from the `./db` column helpers (which handle the MySQL wire format): the DB stays on JST, and the app handles JST explicitly through this module instead of relying implicitly on the connection `timezone`. diff --git a/docs/api-db.md b/docs/api-db.md index 81ce2bf..e0b1572 100644 --- a/docs/api-db.md +++ b/docs/api-db.md @@ -1,7 +1,3 @@ ---- -title: 'API: DB' ---- - # API: `@rdlabo/workers-hono-kit/db` Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in. diff --git a/docs/api-offline.md b/docs/api-offline.md index a88d620..ffdbd48 100644 --- a/docs/api-offline.md +++ b/docs/api-offline.md @@ -1,7 +1,3 @@ ---- -title: 'API: Offline' ---- - # API: `@rdlabo/workers-hono-kit/offline` Table-agnostic building blocks for product-owned REST ↔ DB method converters and their offline replica wire values. This subpath does not define table projections, Zod object shapes, public-column allowlists, schema hashes, or domain rules; those remain in each Hono application. diff --git a/docs/api-root.md b/docs/api-root.md index 10fc6e1..36b887b 100644 --- a/docs/api-root.md +++ b/docs/api-root.md @@ -1,7 +1,3 @@ ---- -title: 'API: Root' ---- - # API: `@rdlabo/workers-hono-kit` The root export is web-standard only: it runs on `workerd` and never depends on Node.js APIs or `mysql2`. The table below lists the helpers exported from the root entry point. diff --git a/docs/api-testing.md b/docs/api-testing.md index 83d470a..bdb0564 100644 --- a/docs/api-testing.md +++ b/docs/api-testing.md @@ -1,7 +1,3 @@ ---- -title: 'API: Testing' ---- - # API: `@rdlabo/workers-hono-kit/testing` Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boilerplate. diff --git a/docs/api.md b/docs/api.md index 72d7f23..3ce5fdc 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,15 +1,12 @@ ---- -title: API ---- - # API -`@rdlabo/workers-hono-kit` exposes five entry points. This page maps each entry point to its dedicated reference page. For feature-level examples, see [`/docs/usage`](/docs/usage). +`@rdlabo/workers-hono-kit` exposes these entry points. This page maps each entry point to its dedicated reference page. For feature-level examples, see [HTTP and Authentication](./http-auth.md), [Data Layer](./data-layer.md), [Realtime and Offline](./realtime-offline.md), and [Testing and Operations](./testing-operations.md). | Entry point | Description | Reference | | --- | --- | --- | -| `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV, queues, idempotency). | [`/docs/api-root`](/docs/api-root) | -| `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle), JST column helpers, baseline migrations. | [`/docs/api-db`](/docs/api-db) | -| `@rdlabo/workers-hono-kit/business-time` | JST business calendar and date-time conversions. | [`/docs/api-business-time`](/docs/api-business-time) | -| `@rdlabo/workers-hono-kit/offline` | Table-agnostic REST/DB method converters and replica wire helpers. | [`/docs/api-offline`](/docs/api-offline) | -| `@rdlabo/workers-hono-kit/testing` | Drizzle-backed test DB, fakes, fixtures, and binding doubles. | [`/docs/api-testing`](/docs/api-testing) | +| `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV, queues, idempotency). | [Root](./api-root.md) | +| `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle), JST column helpers, baseline migrations. | [DB](./api-db.md) | +| `@rdlabo/workers-hono-kit/business-time` | JST business calendar and date-time conversions. | [Business time](./api-business-time.md) | +| `@rdlabo/workers-hono-kit/offline` | Table-agnostic REST/DB method converters and replica wire helpers. | [Offline](./api-offline.md) | +| `@rdlabo/workers-hono-kit/realtime` | Durable Object WebSocket and retry helpers. | [Realtime and Offline](./realtime-offline.md) | +| `@rdlabo/workers-hono-kit/testing` | Drizzle-backed test DB, fakes, fixtures, and binding doubles. | [Testing](./api-testing.md) | diff --git a/docs/cli.md b/docs/cli.md index 559240c..9eb7ef4 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,7 +1,3 @@ ---- -title: CLI ---- - # CLI The package ships `bin` commands that can be run with `npx` or wired into npm scripts in the consuming app. They are operational helpers: AWS credential sync, subrequest fan-out gating, and brownfield database baselining. diff --git a/docs/development.md b/docs/development.md index e2fa6c2..43c6807 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,7 +1,3 @@ ---- -title: Development ---- - # Development These commands are used when working on the package itself: diff --git a/docs/role-policies.md b/docs/role-policies.md index 43e356f..dcc369a 100644 --- a/docs/role-policies.md +++ b/docs/role-policies.md @@ -1,7 +1,3 @@ ---- -title: Role Policies ---- - # Storage-agnostic role policies `createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The application can resolve roles from a membership table, a `users.role` column, token claims, or any other source.