@rdlabo/workers-hono-kit 0.12.2-beta.pr50.shac9087a59c62a → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +17 -23
  2. package/dist/index.d.ts +0 -2
  3. package/dist/index.js +0 -1
  4. package/docs/api-db.md +1 -1
  5. package/docs/data-layer.md +25 -22
  6. package/docs/http-auth.md +5 -0
  7. package/docs/realtime-offline.md +5 -0
  8. package/docs/testing-operations.md +5 -0
  9. package/package.json +3 -3
  10. package/dist/firebase/social-auth.d.ts +0 -13
  11. package/dist/firebase/social-auth.js +0 -37
  12. package/docs/quickstart.md +0 -71
package/README.md CHANGED
@@ -2,9 +2,24 @@
2
2
 
3
3
  Shared Hono building blocks for Cloudflare Workers APIs: weak ETags, NestJS-shaped validation and
4
4
  error bodies, Firebase auth middleware, AWS helpers, AI Gateway wiring, Stripe, KV, queues,
5
- realtime, and offline contracts.
5
+ realtime, and offline contracts. Domain logic and database schemas stay in the consuming
6
+ application.
6
7
 
7
- [Try a Hono API locally](./docs/quickstart.md): send a health request, inspect its weak ETag, and see the missing-route JSON response. No Cloudflare account or open port is needed for the first exercise.
8
+ ## Choose an entry point
9
+
10
+ | Import | Responsibility |
11
+ | ---------------------------------------- | -------------------------------------------------------------------- |
12
+ | `@rdlabo/workers-hono-kit` | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives |
13
+ | `@rdlabo/workers-hono-kit/mysql` | Hono container adapter for `@rdlabo/workers-mysql` |
14
+ | `@rdlabo/workers-hono-kit/offline` | Offline replica wire, cursor, journal, and compatibility contracts |
15
+ | `@rdlabo/workers-hono-kit/realtime` | Durable Object WebSocket and retry helpers |
16
+ | `@rdlabo/workers-hono-kit/testing` | Auth helpers, fakes, Stripe fixtures, and compatibility test exports |
17
+ | `@rdlabo/workers-hono-kit/db` | Deprecated compatibility path for `@rdlabo/workers-mysql` |
18
+ | `@rdlabo/workers-hono-kit/business-time` | Deprecated compatibility path for `@rdlabo/workers-timezone` |
19
+
20
+ The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers
21
+ install the standalone package, which owns `mysql2`; Hono-specific wiring stays in the `/mysql`
22
+ adapter.
8
23
 
9
24
  ## Install
10
25
 
@@ -57,22 +72,6 @@ app.get('/health', (c) => c.json({ ok: true }));
57
72
  export default app;
58
73
  ```
59
74
 
60
- ## Choose an entry point
61
-
62
- | Import | Responsibility |
63
- | ---------------------------------------- | -------------------------------------------------------------------- |
64
- | `@rdlabo/workers-hono-kit` | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives |
65
- | `@rdlabo/workers-hono-kit/mysql` | Hono container adapter for `@rdlabo/workers-mysql` |
66
- | `@rdlabo/workers-hono-kit/offline` | Offline replica wire, cursor, journal, and compatibility contracts |
67
- | `@rdlabo/workers-hono-kit/realtime` | Durable Object WebSocket and retry helpers |
68
- | `@rdlabo/workers-hono-kit/testing` | Auth helpers, fakes, Stripe fixtures, and compatibility test exports |
69
- | `@rdlabo/workers-hono-kit/db` | Deprecated compatibility path for `@rdlabo/workers-mysql` |
70
- | `@rdlabo/workers-hono-kit/business-time` | Deprecated compatibility path for `@rdlabo/workers-timezone` |
71
-
72
- The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers
73
- install the standalone package, which owns `mysql2`; Hono-specific wiring stays in the `/mysql`
74
- adapter.
75
-
76
75
  ### Compatibility import deprecations
77
76
 
78
77
  Kit `/db`, `/business-time`, and the DB-related `/testing` exports (`createTestDb`, pool/noop
@@ -82,11 +81,6 @@ compatibility aliases keep the same runtime identity and signatures; there is no
82
81
  Kit-owned helpers such as `reopenGuardedPaymentFailedSet`, `/mysql` `createContainerRuntime`, and
83
82
  Firebase/auth/KV/Stripe test helpers are not deprecated by this migration.
84
83
 
85
- Google and Apple login endpoints can use the root exports `verifyGoogleIdentityToken`,
86
- `verifyAppleIdentityToken`, and `hasFirebaseProviderIdentity`. Apple token exchange can additionally
87
- use `createAppleClientSecret`. Applications keep ownership of HTTP responses, persistence, and
88
- provider token exchange or revocation; the Kit owns only reusable token verification and signing.
89
-
90
84
  ## Documentation
91
85
 
92
86
  - [HTTP and Authentication](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/http-auth)
package/dist/index.d.ts CHANGED
@@ -91,5 +91,3 @@ export { FirebaseIdTokenValidationError, JoseFirebaseVerifier, SECURETOKEN_JWK_U
91
91
  export { IdentityToolkit } from './firebase/identity-toolkit.js';
92
92
  export type { ServiceAccount } from './firebase/identity-toolkit.js';
93
93
  export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';
94
- export { APPLE_IDENTITY_ISSUER, GOOGLE_IDENTITY_ISSUERS, createAppleClientSecret, hasFirebaseProviderIdentity, verifyAppleIdentityToken, verifyGoogleIdentityToken, } from './firebase/social-auth.js';
95
- export type { AppleClientSecretConfig } from './firebase/social-auth.js';
package/dist/index.js CHANGED
@@ -67,4 +67,3 @@ export { getTemporaryCredentials } from './aws/sts.js';
67
67
  export { FirebaseIdTokenValidationError, JoseFirebaseVerifier, SECURETOKEN_JWK_URL, } from './firebase/jose-firebase-verifier.js';
68
68
  export { IdentityToolkit } from './firebase/identity-toolkit.js';
69
69
  export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';
70
- export { APPLE_IDENTITY_ISSUER, GOOGLE_IDENTITY_ISSUERS, createAppleClientSecret, hasFirebaseProviderIdentity, verifyAppleIdentityToken, verifyGoogleIdentityToken, } from './firebase/social-auth.js';
package/docs/api-db.md CHANGED
@@ -27,7 +27,7 @@ compatibility_flags = ["nodejs_compat"]
27
27
  | `Database` / `DisposableDatabase` / `HyperdriveDatabase` / `ReadTransaction` / `QueryRunner` / `TxOf` | The `read` / `query` / `readTransaction` / `write` / `transaction` API and its supporting types. |
28
28
  | `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. |
29
29
  | `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. |
30
- | `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with a wait of `delay × attempt` between attempts. |
30
+ | `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. |
31
31
  | `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
32
32
  | `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). |
33
33
  | `MYSQL_TIMEZONE` | Default mysql2 connection `timezone` (`'+09:00'`) for the JST DB deployment. |
package/docs/data-layer.md CHANGED
@@ -3,6 +3,11 @@
3
3
  Standalone MySQL / Hyperdrive access for Workers, plus the thin Hono container adapter. Fixed
4
4
  `+09:00` storage helpers are independent of IANA display timezones.
5
5
 
6
+ - [HTTP and Authentication](./http-auth.md)
7
+ - [Realtime and Offline](./realtime-offline.md)
8
+ - [Testing and Operations](./testing-operations.md)
9
+ - [API reference](./api.md)
10
+
6
11
  Import database helpers from `@rdlabo/workers-mysql`. The package installs `mysql2` directly. Add
7
12
  `drizzle-orm` only when using the `/drizzle` or `/testing` entry point. The old
8
13
  `@rdlabo/workers-hono-kit/db` path is a deprecated compatibility re-export.
@@ -21,11 +26,27 @@ npm install -D @types/node@20
21
26
 
22
27
  For candidate tarball installation, see [Development](./development.md).
23
28
 
29
+ ## Migrating from workers-hono-kit
30
+
31
+ The package boundary is a breaking change in `0.12.0`. Update these imports before
32
+ upgrading:
33
+
34
+ | Current import | Replacement |
35
+ | ------------------------------------------------------- | ----------------------------------------------------- |
36
+ | `createContainerRuntime` from the kit root | `@rdlabo/workers-hono-kit/mysql` |
37
+ | `retryWhenDeadlock` from the kit root | `@rdlabo/workers-mysql` |
38
+ | DB helpers from `@rdlabo/workers-hono-kit/db` | `@rdlabo/workers-mysql`, `/drizzle`, or `/migrations` |
39
+ | DB test helpers from `@rdlabo/workers-hono-kit/testing` | `@rdlabo/workers-mysql/testing` |
40
+
41
+ The old `/db` and DB-related `/testing` exports remain available for backward compatibility.
42
+ Their individual functions and types carry `@deprecated` notices pointing to the standalone
43
+ package. No removal release is scheduled. The kit-owned `/mysql` adapter is not deprecated.
44
+ Because `/testing` statically re-exports DB helpers, all kit `/testing` consumers must install the
45
+ MySQL package and `drizzle-orm`, including consumers of non-DB helpers such as Firebase or KV fakes.
46
+
24
47
  ## Hyperdrive database
25
48
 
26
- `createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings.
27
- For read/write paths, retry boundaries, and invocation lifetime, see
28
- [Workers MySQL Runtime](https://docs.rdlabo.dev/projects/workers-mysql/docs/runtime).
49
+ `createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. `read()` uses the replica query runner; `query()` provides an explicit raw primary SELECT for read-after-write consistency; writes and transactions use the primary Drizzle instance. `readTransaction()` runs Drizzle and raw reads against one primary repeatable-read snapshot. Read transactions are serialized on one separately cached connection so their boundaries cannot mix with each other or with ordinary primary operations. After a fatal mysql2 connection error, a single read or the complete read-only transaction opens a fresh connection and repeats at most once. Writes and write transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
29
50
 
30
51
  ```ts
31
52
  import { createHyperdriveDatabase } from '@rdlabo/workers-mysql';
@@ -63,7 +84,7 @@ import { createContainerRuntime } from '@rdlabo/workers-hono-kit/mysql';
63
84
 
64
85
  ## Writes and retries
65
86
 
66
- - `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with a wait of `delay × attempt` between attempts.
87
+ - `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with exponential backoff.
67
88
  - `insertIdOf()`, `affectedRowsOf()`, and `insertedIdsOf()` normalize mysql2 write results.
68
89
  - `withMysqlConnections()` opens primary and replica connections in parallel for a scoped operation.
69
90
 
@@ -89,24 +110,6 @@ addBusinessDays('2026-07-06', 3);
89
110
  // '2026-07-09'
90
111
  ```
91
112
 
92
- ## Migrating from workers-hono-kit
93
-
94
- The package boundary is a breaking change in `0.12.0`. Update these imports before
95
- upgrading:
96
-
97
- | Current import | Replacement |
98
- | ------------------------------------------------------- | ----------------------------------------------------- |
99
- | `createContainerRuntime` from the kit root | `@rdlabo/workers-hono-kit/mysql` |
100
- | `retryWhenDeadlock` from the kit root | `@rdlabo/workers-mysql` |
101
- | DB helpers from `@rdlabo/workers-hono-kit/db` | `@rdlabo/workers-mysql`, `/drizzle`, or `/migrations` |
102
- | DB test helpers from `@rdlabo/workers-hono-kit/testing` | `@rdlabo/workers-mysql/testing` |
103
-
104
- The old `/db` and DB-related `/testing` exports remain available for backward compatibility.
105
- Their individual functions and types carry `@deprecated` notices pointing to the standalone
106
- package. No removal release is scheduled. The kit-owned `/mysql` adapter is not deprecated.
107
- Because `/testing` statically re-exports DB helpers, all kit `/testing` consumers must install the
108
- MySQL package and `drizzle-orm`, including consumers of non-DB helpers such as Firebase or KV fakes.
109
-
110
113
  ## Next step
111
114
 
112
115
  Continue to [Realtime and Offline](./realtime-offline.md), or see
package/docs/http-auth.md CHANGED
@@ -3,6 +3,11 @@
3
3
  Validation, Firebase authentication, shared NestJS-shaped error bodies, and response finalization
4
4
  for Hono Workers APIs.
5
5
 
6
+ - [Data Layer](./data-layer.md)
7
+ - [Realtime and Offline](./realtime-offline.md)
8
+ - [Testing and Operations](./testing-operations.md)
9
+ - [API reference](./api.md)
10
+
6
11
  ## Validation
7
12
 
8
13
  `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.
package/docs/realtime-offline.md CHANGED
@@ -3,6 +3,11 @@
3
3
  Durable Object WebSocket helpers and table-agnostic offline replica contracts. Product schemas,
4
4
  Zod shapes, and domain policy stay in the application.
5
5
 
6
+ - [HTTP and Authentication](./http-auth.md)
7
+ - [Data Layer](./data-layer.md)
8
+ - [Testing and Operations](./testing-operations.md)
9
+ - [API reference](./api.md)
10
+
6
11
  ## Durable Object realtime
7
12
 
8
13
  The root and `/realtime` entry points expose the same focused realtime primitives:
package/docs/testing-operations.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  Test helpers, queue batching, operational CLIs, and trust boundaries for Hono Workers applications.
4
4
 
5
+ - [HTTP and Authentication](./http-auth.md)
6
+ - [Data Layer](./data-layer.md)
7
+ - [Realtime and Offline](./realtime-offline.md)
8
+ - [API reference](./api.md)
9
+
5
10
  ## Testing entry point
6
11
 
7
12
  `@rdlabo/workers-hono-kit/testing` is never loaded by production code. Its DB helpers are deprecated
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rdlabo/workers-hono-kit",
3
- "version": "0.12.2-beta.pr50.shac9087a59c62a",
3
+ "version": "0.12.2",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -108,8 +108,8 @@
108
108
  },
109
109
  "peerDependencies": {
110
110
  "@hono/zod-validator": "^0.8.0",
111
- "@rdlabo/workers-mysql": "0.12.2-beta.pr50.shac9087a59c62a",
112
- "@rdlabo/workers-timezone": "0.12.2-beta.pr50.shac9087a59c62a",
111
+ "@rdlabo/workers-mysql": "^0.12.2",
112
+ "@rdlabo/workers-timezone": "^0.12.2",
113
113
  "ai": "^6.0.0",
114
114
  "ai-gateway-provider": "^3.1.0",
115
115
  "aws4fetch": "^1.0.20",
package/dist/firebase/social-auth.d.ts DELETED
@@ -1,13 +0,0 @@
1
- import type { JWTVerifyGetKey } from 'jose';
2
- import type { DecodedIdToken } from './firebase-verifier.js';
3
- export declare const APPLE_IDENTITY_ISSUER = "https://appleid.apple.com";
4
- export declare const GOOGLE_IDENTITY_ISSUERS: readonly ["https://accounts.google.com", "accounts.google.com"];
5
- export declare const verifyAppleIdentityToken: (idToken: string, audience: string, getKey?: JWTVerifyGetKey) => Promise<string>;
6
- export declare const verifyGoogleIdentityToken: (idToken: string, audience: string | readonly string[], getKey?: JWTVerifyGetKey) => Promise<string>;
7
- export declare const hasFirebaseProviderIdentity: (token: DecodedIdToken, providerId: string, subject: string, requireSignInProvider?: boolean) => boolean;
8
- export interface AppleClientSecretConfig {
9
- privateKey: string;
10
- keyId: string;
11
- teamId: string;
12
- }
13
- export declare const createAppleClientSecret: (config: AppleClientSecretConfig, clientId: string, now?: number) => Promise<string>;
package/dist/firebase/social-auth.js DELETED
@@ -1,37 +0,0 @@
1
- import { SignJWT, createRemoteJWKSet, importPKCS8, jwtVerify } from 'jose';
2
- export const APPLE_IDENTITY_ISSUER = 'https://appleid.apple.com';
3
- export const GOOGLE_IDENTITY_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
4
- const appleJwks = createRemoteJWKSet(new URL(`${APPLE_IDENTITY_ISSUER}/auth/keys`));
5
- const googleJwks = createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs'));
6
- export const verifyAppleIdentityToken = async (idToken, audience, getKey = appleJwks) => {
7
- const { payload } = await jwtVerify(idToken, getKey, { issuer: APPLE_IDENTITY_ISSUER, audience });
8
- if (!payload.sub) {
9
- throw new Error('Apple identity token has no subject');
10
- }
11
- return payload.sub;
12
- };
13
- export const verifyGoogleIdentityToken = async (idToken, audience, getKey = googleJwks) => {
14
- const { payload } = await jwtVerify(idToken, getKey, {
15
- issuer: [...GOOGLE_IDENTITY_ISSUERS],
16
- audience: typeof audience === 'string' ? audience : [...audience],
17
- });
18
- if (!payload.sub) {
19
- throw new Error('Google identity token has no subject');
20
- }
21
- return payload.sub;
22
- };
23
- export const hasFirebaseProviderIdentity = (token, providerId, subject, requireSignInProvider = false) => {
24
- const firebase = token;
25
- const subjects = firebase.firebase?.identities?.[providerId];
26
- return (Array.isArray(subjects) &&
27
- subjects.includes(subject) &&
28
- (!requireSignInProvider || firebase.firebase?.sign_in_provider === providerId));
29
- };
30
- export const createAppleClientSecret = async (config, clientId, now = Math.floor(Date.now() / 1000)) => new SignJWT({})
31
- .setProtectedHeader({ alg: 'ES256', kid: config.keyId })
32
- .setIssuer(config.teamId)
33
- .setIssuedAt(now)
34
- .setExpirationTime(now + 120)
35
- .setAudience(APPLE_IDENTITY_ISSUER)
36
- .setSubject(clientId)
37
- .sign(await importPKCS8(config.privateKey, 'ES256'));
package/docs/quickstart.md DELETED
@@ -1,71 +0,0 @@
1
- ---
2
- title: Try a Hono API locally
3
- ---
4
-
5
- Give a Hono API consistent HTTP behavior: a health response with a weak ETag and a predictable JSON response for missing routes. You will see both without opening a port or creating a Cloudflare account.
6
-
7
- ## 1. Create a small project
8
-
9
- Use Node.js 24 and npm for this exercise. The commands pin the documented kit release. npm installs its required peers; package managers configured to omit peers must follow the [installation requirements](../README.md).
10
-
11
- ```sh
12
- mkdir hono-kit-demo
13
- cd hono-kit-demo
14
- npm init -y
15
- npm pkg set type=module
16
- npm install @rdlabo/workers-hono-kit@0.12.2 hono@4
17
- npm install --save-dev tsx@4
18
- ```
19
-
20
- ## 2. Send two requests
21
-
22
- Save this as `demo.ts`. `app.request()` exercises the Hono app in the current process.
23
-
24
- ```ts
25
- import { Hono } from 'hono';
26
- import { createAppErrorHandler, finalizeResponse, notFoundHandler } from '@rdlabo/workers-hono-kit';
27
-
28
- const app = new Hono();
29
- app.use('*', finalizeResponse());
30
- app.onError(createAppErrorHandler());
31
- app.notFound(notFoundHandler);
32
- app.get('/health', (c) => c.json({ ok: true }));
33
-
34
- const healthy = await app.request('/health');
35
- console.log(healthy.status, await healthy.text());
36
- console.log('weak etag:', healthy.headers.get('etag')?.startsWith('W/'));
37
-
38
- const missing = await app.request('/missing');
39
- console.log(missing.status, await missing.text());
40
- ```
41
-
42
- ```sh
43
- npx tsx demo.ts
44
- ```
45
-
46
- Expected output (JSON property order does not matter):
47
-
48
- ```text
49
- 200 {"ok":true}
50
- weak etag: true
51
- 404 {"message":"Cannot GET /missing","error":"Not Found","statusCode":404}
52
- ```
53
-
54
- You have checked the HTTP behavior added by the kit. This exercise does not provision Workers bindings, authenticate users, or test a deployed service.
55
-
56
- ## 3. Move into your application
57
-
58
- Keep the middleware and route registrations, remove the demonstration requests, and export `app` as your Worker handler. Continue with [HTTP and authentication](./http-auth.md). Add the [MySQL adapter](./data-layer.md) only when the application needs a database.
59
-
60
- Existing kit users should check [the 0.12 import migration](./data-layer.md) before upgrading. The old `/db` and `/business-time` paths are compatibility exports; new integrations use the standalone packages.
61
-
62
- ## Next steps
63
-
64
- | You need | Start with |
65
- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
66
- | Shared Hono HTTP, auth, or queue behavior | `@rdlabo/workers-hono-kit` |
67
- | MySQL access, with or without Hono | [Workers MySQL](https://docs.rdlabo.dev/projects/workers-mysql/docs/quickstart) |
68
- | Timezone conversions and checks on new code | [Workers Timezone + ESLint](https://docs.rdlabo.dev/projects/workers-timezone/docs/quickstart) |
69
- | Code conventions during development | [ESLint Plugin Rules](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/quickstart) |
70
-
71
- The kit supplies reusable infrastructure. Your routes, domain rules, credentials, and database schema remain in your application. Adopt one helper first; you do not need to adopt every entry point.