@rdlabo/workers-hono-kit 0.10.2 → 0.10.4

package/README.md

@@ -84,14 +84,14 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `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: `defaultDefer` swallows rejections (tests); `createWaitUntilDefer` registers work via `ctx.waitUntil`. |
+| `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` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
+| `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). |
@@ -626,6 +626,17 @@ await cache.set('users', 'byId', userId, user, 600);
 const hit = await cache.get<User>('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

package/dist/cache/kv-cache.d.ts

@@ -4,7 +4,9 @@
  * Provides a thin, JSON-serializing wrapper around a {@link KVNamespace} for the common
  * "look in cache, fall back to the source of truth" pattern. Reads and writes are best-effort:
  * any KV error, serialization failure, or oversized key is swallowed so callers transparently
- * fall through to their backing store instead of throwing.
+ * fall through to their backing store instead of throwing. An optional error reporter makes
+ * operational failures observable; kit-generated context omits cache types, keys, identifiers,
+ * and values.
  *
  * Cache keys are namespaced as `<appName><version><table>_<type>_<id>`, where a string `id` is
  * hashed with SHA-256 (hex) and a numeric `id` is used verbatim.
@@ -57,6 +59,15 @@ export interface KVNamespace {
      */
     delete(key: string): Promise<void>;
 }
+/** The cache stage that failed while performing a fail-soft operation. */
+export type KVCacheOperation = 'read' | 'parse' | 'serialize' | 'write' | 'delete';
+/** Non-sensitive context supplied to {@link KVCacheOptions.onError}. */
+export interface KVCacheErrorContext {
+    /** The cache stage that failed. */
+    operation: KVCacheOperation;
+    /** Logical table name; cache types, raw keys, identifiers, and values are intentionally omitted. */
+    table: string;
+}
 /**
  * Configuration for a {@link KVCache} instance.
  */
@@ -81,6 +92,11 @@ export interface KVCacheOptions {
      * Defaults to `600`.
      */
     defaultLifetime?: number;
+    /**
+     * Optional synchronous observer for failures that the cache intentionally handles as misses.
+     * Reporter failures are isolated from cache callers and logged separately.
+     */
+    onError?: (error: unknown, context: KVCacheErrorContext) => void;
 }
 /**
  * A single entry to store via {@link KVCache.setMany}.
@@ -145,8 +161,8 @@ export declare class KVCache {
      * JSON-serialize and store a value.
      *
      * Falsy `data` is ignored. The effective TTL is `max(minTtlSeconds, lifetime ?? defaultLifetime)`,
-     * honoring the KV 60-second floor. Oversized keys and serialization/write failures are silently
-     * skipped.
+     * honoring the KV 60-second floor. Oversized keys are skipped; serialization/write failures are
+     * skipped and reported when an observer is configured.
      *
      * @param table - Logical table or entity name.
      * @param type - Sub-key discriminator.
@@ -198,7 +214,7 @@ export declare class KVCache {
     /**
      * Remove a cached entry.
      *
-     * Oversized keys and delete failures are silently ignored.
+     * Oversized keys are ignored. Delete failures are reported when an observer is configured.
      *
      * @param table - Logical table or entity name.
      * @param type - Sub-key discriminator.

package/dist/cache/kv-cache.js

@@ -4,7 +4,9 @@
  * Provides a thin, JSON-serializing wrapper around a {@link KVNamespace} for the common
  * "look in cache, fall back to the source of truth" pattern. Reads and writes are best-effort:
  * any KV error, serialization failure, or oversized key is swallowed so callers transparently
- * fall through to their backing store instead of throwing.
+ * fall through to their backing store instead of throwing. An optional error reporter makes
+ * operational failures observable; kit-generated context omits cache types, keys, identifiers,
+ * and values.
  *
  * Cache keys are namespaced as `<appName><version><table>_<type>_<id>`, where a string `id` is
  * hashed with SHA-256 (hex) and a numeric `id` is used verbatim.
@@ -56,6 +58,7 @@ export class KVCache {
     #version;
     #minTtl;
     #defaultLifetime;
+    #onError;
     /**
      * Create a cache bound to a specific KV namespace.
      *
@@ -68,6 +71,16 @@ export class KVCache {
         this.#version = options.version ?? 'v8_';
         this.#minTtl = options.minTtlSeconds ?? 60;
         this.#defaultLifetime = options.defaultLifetime ?? 600;
+        this.#onError = options.onError;
+    }
+    /** Report an operational failure without letting observer code break the fail-soft contract. */
+    #reportError(error, context) {
+        try {
+            this.#onError?.(error, context);
+        }
+        catch (reporterError) {
+            console.error('[KVCache] error reporter failed', reporterError);
+        }
     }
     /**
      * Build the fully namespaced KV key for the given coordinates.
@@ -108,14 +121,22 @@ export class KVCache {
         if (!key) {
             return undefined;
         }
+        let data;
+        try {
+            data = await this.#kv.get(key);
+        }
+        catch (error) {
+            this.#reportError(error, { operation: 'read', table });
+            return undefined;
+        }
+        if (!data) {
+            return undefined;
+        }
         try {
-            const data = await this.#kv.get(key);
-            if (!data) {
-                return undefined;
-            }
             return JSON.parse(data);
         }
-        catch {
+        catch (error) {
+            this.#reportError(error, { operation: 'parse', table });
             return undefined;
         }
     }
@@ -123,8 +144,8 @@ export class KVCache {
      * JSON-serialize and store a value.
      *
      * Falsy `data` is ignored. The effective TTL is `max(minTtlSeconds, lifetime ?? defaultLifetime)`,
-     * honoring the KV 60-second floor. Oversized keys and serialization/write failures are silently
-     * skipped.
+     * honoring the KV 60-second floor. Oversized keys are skipped; serialization/write failures are
+     * skipped and reported when an observer is configured.
      *
      * @param table - Logical table or entity name.
      * @param type - Sub-key discriminator.
@@ -149,11 +170,18 @@ export class KVCache {
         try {
             payload = JSON.stringify(data);
         }
-        catch {
+        catch (error) {
+            this.#reportError(error, { operation: 'serialize', table });
+            return;
+        }
+        if (payload === undefined) {
+            this.#reportError(new TypeError('Cache value is not JSON-serializable'), { operation: 'serialize', table });
             return;
         }
         const ttl = Math.max(this.#minTtl, lifetime ?? this.#defaultLifetime);
-        await this.#kv.put(key, payload, { expirationTtl: ttl }).catch(() => undefined);
+        await this.#kv.put(key, payload, { expirationTtl: ttl }).catch((error) => {
+            this.#reportError(error, { operation: 'write', table });
+        });
     }
     /**
      * Store many values concurrently.
@@ -199,7 +227,7 @@ export class KVCache {
     /**
      * Remove a cached entry.
      *
-     * Oversized keys and delete failures are silently ignored.
+     * Oversized keys are ignored. Delete failures are reported when an observer is configured.
      *
      * @param table - Logical table or entity name.
      * @param type - Sub-key discriminator.
@@ -215,6 +243,8 @@ export class KVCache {
         if (!key) {
             return;
         }
-        await this.#kv.delete(key).catch(() => undefined);
+        await this.#kv.delete(key).catch((error) => {
+            this.#reportError(error, { operation: 'delete', table });
+        });
     }
 }

package/dist/http/defer.d.ts

@@ -9,8 +9,8 @@ import type { ExecutionContextLike } from './execution-context.js';
  */
 export type DeferExecutor = (promise: Promise<unknown>) => void;
 /**
- * Default defer implementation (NestJS `void promise` equivalent). Swallows rejections.
- * Used when no `ExecutionContext` is available (tests, partial scheduled paths).
+ * Default defer implementation (NestJS `void promise` equivalent). Reports rejections without
+ * propagating them. Used when no `ExecutionContext` is available (tests, partial scheduled paths).
  */
 export declare const defaultDefer: DeferExecutor;
 /**

package/dist/http/defer.js

@@ -1,9 +1,12 @@
+const reportDeferFailure = (error) => {
+    console.error('[defer] background task failed', error);
+};
 /**
- * Default defer implementation (NestJS `void promise` equivalent). Swallows rejections.
- * Used when no `ExecutionContext` is available (tests, partial scheduled paths).
+ * Default defer implementation (NestJS `void promise` equivalent). Reports rejections without
+ * propagating them. Used when no `ExecutionContext` is available (tests, partial scheduled paths).
  */
 export const defaultDefer = (promise) => {
-    void promise.catch(() => undefined);
+    void promise.catch(reportDeferFailure);
 };
 /**
  * Build a {@link DeferExecutor} that keeps the worker alive until `promise` settles.
@@ -12,6 +15,6 @@ export const defaultDefer = (promise) => {
  */
 export function createWaitUntilDefer(ctx) {
     return (promise) => {
-        ctx.waitUntil(promise.catch(() => undefined));
+        ctx.waitUntil(promise.catch(reportDeferFailure));
     };
 }

package/dist/http/http-error.d.ts

@@ -71,7 +71,7 @@ export interface HttpErrorHandlerOptions<E extends Env = Env> {
     isHttpError?: (err: unknown) => err is HttpErrorLike;
     /**
      * Hook invoked before an unexpected (non-HTTP) error is returned as a 500, typically used to report the
-     * error (e.g. to Sentry). Any exception thrown by this hook is swallowed so reporting cannot alter the
+     * error (e.g. to Sentry). Any exception thrown by this hook is logged and kept from altering the
      * error response.
      */
     onUnhandledError?: (err: unknown, c: Context<E>) => void;

package/dist/http/http-error.js

@@ -78,8 +78,10 @@ export function createHttpErrorHandler(options = {}) {
         try {
             onUnhandledError?.(err, c);
         }
-        catch {
-            // Reporting must never change the behavior of the error response.
+        catch (reportingError) {
+            // Reporting must never change the behavior of the error response, but its own failure must
+            // stay visible so a broken observability integration does not go unnoticed.
+            console.error('[httpError] onUnhandledError failed', reportingError);
         }
         if (findMysqlDriverError(err)) {
             logMysqlDriverError(err, 500);

package/dist/http/query-failed-error.js

@@ -40,8 +40,9 @@ export function createQueryFailedErrorHandler(options) {
                 try {
                     onUnhandledError?.(err, c);
                 }
-                catch {
-                    // Reporting must never change the error response.
+                catch (reportingError) {
+                    // Reporting must never change the error response, but a broken reporter must remain visible.
+                    console.error('[queryFailedError] onUnhandledError failed', reportingError);
                 }
             }
             return c.json({ statusCode: classified.statusCode, message: classified.message }, classified.statusCode);

package/dist/idempotency/idempotency.d.ts

@@ -45,6 +45,49 @@ export type IdempotencyReservation<TResponse> = {
     kind: 'replay';
     response: TResponse;
 };
+/** Locked persistence state for one leased idempotency key. */
+export type LeasedIdempotencyRecord<TResponse> = {
+    /** The operation is currently owned by one processing token. */
+    state: 'processing';
+    /** Canonical payload hash stored with the key. */
+    payloadHash: string;
+    /** Token of the current processing owner. */
+    processingToken: string;
+    /** Whether the current owner's lease may be reclaimed. */
+    leaseExpired: boolean;
+} | {
+    /** The operation completed and its response is replayable. */
+    state: 'completed';
+    /** Canonical payload hash stored with the key. */
+    payloadHash: string;
+    /** Persisted response returned to retries. */
+    response: TResponse;
+};
+/** Persistence primitives used by the shared leased-idempotency state machine. */
+export interface LeasedIdempotencyStore<TScope extends IdempotencyScope, TResponse> {
+    /** Insert a processing row if the scoped key does not already exist. */
+    insertProcessing(input: IdempotencyInput<TScope>, processingToken: string): Promise<void>;
+    /** Lock and return the scoped key after the insert attempt. */
+    lock(input: IdempotencyInput<TScope>): Promise<LeasedIdempotencyRecord<TResponse>>;
+    /** Atomically replace an expired processing token and restart its lease. */
+    reclaim(input: IdempotencyInput<TScope>, previousToken: string, processingToken: string): Promise<boolean>;
+    /** Persist the response only while `processingToken` still owns the key. */
+    complete(input: IdempotencyInput<TScope>, processingToken: string, response: TResponse): Promise<boolean>;
+    /** Remove an uncommitted reservation only while `processingToken` still owns it. */
+    release(input: IdempotencyInput<TScope>, processingToken: string): Promise<void>;
+}
+/** Result of reserving a leased idempotency key. */
+export type LeasedIdempotencyReservation<TResponse> = {
+    kind: 'acquired';
+    processingToken: string;
+} | {
+    kind: 'replay';
+    response: TResponse;
+};
+/** Reserve, replay, or safely reclaim one leased idempotency key. */
+export declare function reserveLeasedIdempotency<TScope extends IdempotencyScope, TResponse>(store: LeasedIdempotencyStore<TScope, TResponse>, input: IdempotencyInput<TScope>): Promise<LeasedIdempotencyReservation<TResponse>>;
+/** Complete a leased idempotent operation without accepting a stale owner. */
+export declare function completeLeasedIdempotency<TScope extends IdempotencyScope, TResponse>(store: LeasedIdempotencyStore<TScope, TResponse>, input: IdempotencyInput<TScope>, processingToken: string, response: TResponse): Promise<void>;
 /** Transaction-bound persistence operations required by {@link runIdempotentMutation}. */
 export interface IdempotentMutationStore<TScope extends IdempotencyScope, TResponse> {
     /** Atomically reserve a key or return its previously completed response. */

package/dist/idempotency/idempotency.js

@@ -27,6 +27,34 @@ export class IdempotencyInFlightError extends Error {
         this.name = 'IdempotencyInFlightError';
     }
 }
+/** Reserve, replay, or safely reclaim one leased idempotency key. */
+export async function reserveLeasedIdempotency(store, input) {
+    const processingToken = crypto.randomUUID();
+    await store.insertProcessing(input, processingToken);
+    const record = await store.lock(input);
+    if (record.payloadHash !== input.payloadHash) {
+        throw new IdempotencyConflictError();
+    }
+    if (record.state === 'completed') {
+        return { kind: 'replay', response: record.response };
+    }
+    if (record.processingToken === processingToken) {
+        return { kind: 'acquired', processingToken };
+    }
+    if (!record.leaseExpired) {
+        throw new IdempotencyInFlightError();
+    }
+    if (!(await store.reclaim(input, record.processingToken, processingToken))) {
+        throw new IdempotencyInFlightError('Idempotent request ownership changed during lease reclaim');
+    }
+    return { kind: 'acquired', processingToken };
+}
+/** Complete a leased idempotent operation without accepting a stale owner. */
+export async function completeLeasedIdempotency(store, input, processingToken, response) {
+    if (!(await store.complete(input, processingToken, response))) {
+        throw new IdempotencyInFlightError('Idempotent request ownership was lost before completion');
+    }
+}
 /** Deterministically serialize JSON data with locale-independent, UTF-16 code-unit key ordering. */
 export function canonicalJson(value) {
     try {

package/dist/index.d.ts

@@ -49,8 +49,8 @@ export { createSentryErrorReporter } from './http/http-error.js';
 export type { SentryExceptionReporterLike } from './http/http-error.js';
 export { AUTH_FAILURE_SCOPES, AUTH_IDENTITY_INVALID_CODE, createAuthFailureBody, createIdentityAuthFailureBody, createLegacyIdentityAuthFailureBody, } from './http/auth-failure.js';
 export type { AuthFailureBody, AuthFailureScope } from './http/auth-failure.js';
-export { canonicalJson, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
-export type { CreateIdempotencyInputOptions, IdempotencyInput, IdempotencyReservation, IdempotencyScope, IdempotencyScopeValue, IdempotentMutationStore, } from './idempotency/idempotency.js';
+export { canonicalJson, completeLeasedIdempotency, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, reserveLeasedIdempotency, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
+export type { CreateIdempotencyInputOptions, IdempotencyInput, LeasedIdempotencyRecord, LeasedIdempotencyReservation, LeasedIdempotencyStore, IdempotencyReservation, IdempotencyScope, IdempotencyScopeValue, IdempotentMutationStore, } from './idempotency/idempotency.js';
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.js';
 export type { HibernationAutoResponseOptions, HibernationUpgradeOptions, HibernationWebSocketLike, HibernationWebSocketStateLike, WebSocketAutoResponsePairFactory, WebSocketPairFactory, } from './realtime/hibernation.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './realtime/retry.js';
@@ -60,7 +60,7 @@ export type { DurableObjectFetchRequest, DurableObjectFetchStubLike, InvokeDurab
 export { parseRealtimeWebSocketProtocolOffer, parseWebSocketProtocols } from './realtime/protocol.js';
 export type { ParseRealtimeWebSocketProtocolOptions, RealtimeWebSocketProtocolOffer } from './realtime/protocol.js';
 export { KVCache } from './cache/kv-cache.js';
-export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
+export type { KVNamespace, KVCacheErrorContext, KVCacheOperation, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
 export type { CreateStripeClientOptions } from './stripe/client.js';
 export { extractStripeFailureReason, stripeFailureMessageJa, serializePaymentFailure, serializeIapFailureReason, parsePaymentFailure, PaymentDeclinedError, toPaymentDeclinedError, } from './stripe/failure.js';

package/dist/index.js

@@ -37,7 +37,7 @@ export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
 export { AUTH_FAILURE_SCOPES, AUTH_IDENTITY_INVALID_CODE, createAuthFailureBody, createIdentityAuthFailureBody, createLegacyIdentityAuthFailureBody, } from './http/auth-failure.js';
 // idempotency
-export { canonicalJson, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
+export { canonicalJson, completeLeasedIdempotency, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, reserveLeasedIdempotency, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
 // realtime
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.js';
 export { isRetryableDurableObjectError, retryDurableObjectOperation } from './realtime/retry.js';

package/dist/middleware/validation.d.ts

@@ -23,8 +23,8 @@ export interface ValidateOptions {
      *
      * @remarks
      * This never changes validation behavior — the response is always a NestJS `ValidationPipe`-shaped
-     * 400. Exceptions thrown by the hook are swallowed. The default is a no-op (4xx errors are not
-     * reported); pass a hook to forward failures to an error tracker.
+     * 400. Exceptions thrown by the hook are logged without changing the response. The default is a
+     * no-op (4xx errors are not reported); pass a hook to forward failures to an error tracker.
      *
      * @param error - The zod error describing the failed validation.
      * @param c - The Hono context for the failing request.

package/dist/middleware/validation.js

@@ -55,8 +55,9 @@ export function validate(target, schema, options) {
             try {
                 options?.onValidationError?.(result.error, c);
             }
-            catch {
-                // Reporting must never change validation error behavior.
+            catch (reportingError) {
+                // Reporting must never change validation behavior, but a broken reporter must remain visible.
+                console.error('[validation] onValidationError failed', reportingError);
             }
             return c.json({ statusCode: 400, message: messages, error: 'Bad Request' }, 400);
         }

package/dist/offline/index.d.ts

@@ -12,3 +12,7 @@ export { defineRestDbMethodConverter } from './rest-db-method-converter.js';
 export type { CompleteRestDbTableScheme, RestDbMethodConverter } from './rest-db-method-converter.js';
 export { decodeOfflineSnapshotCursor, encodeOfflineSnapshotCursor } from './snapshot-cursor.js';
 export type { OfflineSnapshotCursor } from './snapshot-cursor.js';
+export { assertOfflineJournalCursorRetained, compactOfflineJournal, OfflineJournalRebaselineRequiredError, } from './journal-retention.js';
+export type { CompactOfflineJournalOptions, OfflineJournalRetentionCandidate, OfflineJournalRetentionStore, OfflineJournalRetentionTransaction, } from './journal-retention.js';
+export { assertOfflineJournalCoverage, runOfflineJournalMutation } from './journal-mutation.js';
+export type { OfflineJournalMutationChange, OfflineJournalMutationStore, OfflineJournalMutationTransaction, } from './journal-mutation.js';

package/dist/offline/index.js

@@ -10,3 +10,5 @@ export { fromTinyIntFlag, replicaTimestampMs, toReplicaDateOnly, toReplicaIsoDat
 export { replicaNowIso } from './clock.js';
 export { defineRestDbMethodConverter } from './rest-db-method-converter.js';
 export { decodeOfflineSnapshotCursor, encodeOfflineSnapshotCursor } from './snapshot-cursor.js';
+export { assertOfflineJournalCursorRetained, compactOfflineJournal, OfflineJournalRebaselineRequiredError, } from './journal-retention.js';
+export { assertOfflineJournalCoverage, runOfflineJournalMutation } from './journal-mutation.js';

package/dist/offline/journal-mutation.d.ts

@@ -0,0 +1,44 @@
+/** One product-owned replica target affected by a domain mutation. */
+export interface OfflineJournalMutationChange<TScope, TSourceKey extends string = string> {
+    /** Product-defined authorization and replica partition. */
+    readonly scope: TScope;
+    /** Replica source whose hydrated value is invalidated by the mutation. */
+    readonly sourceKey: TSourceKey;
+    /** Stable server identity within the source. */
+    readonly serverId: string | number;
+    /** Optional Outbox acknowledgement metadata committed with the journal row. */
+    readonly command?: {
+        readonly userId: string | number;
+        readonly commandId?: string;
+    };
+}
+/** Transaction-bound adapter that persists journal changes beside the domain write. */
+export interface OfflineJournalMutationTransaction<TScope, TSourceKey extends string = string> {
+    /** Appends one journal entry using the product transaction. */
+    append(change: OfflineJournalMutationChange<TScope, TSourceKey>): Promise<void>;
+}
+/** Product adapter that owns the database transaction and journal schema. */
+export interface OfflineJournalMutationStore<TScope, TSourceKey extends string = string, TTransaction extends OfflineJournalMutationTransaction<TScope, TSourceKey> = OfflineJournalMutationTransaction<TScope, TSourceKey>> {
+    /**
+     * Runs the domain write and every journal append in one database transaction.
+     * A throw from either the domain mutation or `append` must roll back all writes.
+     */
+    transaction<TResult>(operation: (transaction: TTransaction) => Promise<TResult>): Promise<TResult>;
+}
+/**
+ * Commits one domain mutation and its complete replica journal footprint atomically.
+ *
+ * `mutate` returns both the business result and every affected replica target. The shared
+ * state machine appends all targets before the product transaction may commit.
+ */
+export declare function runOfflineJournalMutation<TScope, TSourceKey extends string, TResult, TTransaction extends OfflineJournalMutationTransaction<TScope, TSourceKey>>(options: {
+    readonly store: OfflineJournalMutationStore<TScope, TSourceKey, TTransaction>;
+    readonly mutate: (transaction: TTransaction) => Promise<{
+        readonly result: TResult;
+        readonly changes: readonly OfflineJournalMutationChange<TScope, TSourceKey>[];
+    }>;
+    /** Returns the canonical authorization/partition key for one product scope. */
+    readonly scopeKey: (scope: TScope) => string;
+}): Promise<TResult>;
+/** Fails CI when a product write route has no declared journal coverage decision. */
+export declare function assertOfflineJournalCoverage<TWriteId extends string>(writeIds: readonly TWriteId[], coverage: Readonly<Record<TWriteId, readonly string[] | 'not-replicated'>>): void;

package/dist/offline/journal-mutation.js

@@ -0,0 +1,59 @@
+/**
+ * Commits one domain mutation and its complete replica journal footprint atomically.
+ *
+ * `mutate` returns both the business result and every affected replica target. The shared
+ * state machine appends all targets before the product transaction may commit.
+ */
+export function runOfflineJournalMutation(options) {
+    return options.store.transaction(async (transaction) => {
+        const { result, changes } = await options.mutate(transaction);
+        const unique = new Map();
+        for (const change of changes) {
+            const scopeKey = options.scopeKey(change.scope);
+            if (!scopeKey || !change.sourceKey || String(change.serverId).length === 0) {
+                throw new Error('Offline journal mutation scope, source, and server keys must be non-empty.');
+            }
+            const serverKey = typeof change.serverId === 'number' ? `number:${change.serverId}` : `string:${change.serverId}`;
+            const key = `${scopeKey}\u0000${change.sourceKey}\u0000${serverKey}`;
+            const existing = unique.get(key);
+            if (existing === undefined) {
+                unique.set(key, change);
+                continue;
+            }
+            if (existing.command === undefined && change.command !== undefined) {
+                unique.set(key, { ...existing, command: change.command });
+                continue;
+            }
+            if (existing.command !== undefined &&
+                change.command !== undefined &&
+                (String(existing.command.userId) !== String(change.command.userId) ||
+                    existing.command.commandId !== change.command.commandId)) {
+                throw new Error(`Offline journal mutation key '${key}' has conflicting command metadata.`);
+            }
+        }
+        for (const change of unique.values()) {
+            await transaction.append(change);
+        }
+        return result;
+    });
+}
+/** Fails CI when a product write route has no declared journal coverage decision. */
+export function assertOfflineJournalCoverage(writeIds, coverage) {
+    const declared = Object.keys(coverage);
+    const missing = writeIds.filter((writeId) => !Object.hasOwn(coverage, writeId));
+    const unknown = declared.filter((writeId) => !writeIds.includes(writeId));
+    if (missing.length > 0 || unknown.length > 0) {
+        throw new Error(`Offline journal coverage mismatch: missing=[${missing.join(',')}], unknown=[${unknown.join(',')}].`);
+    }
+    for (const writeId of writeIds) {
+        const decision = coverage[writeId];
+        if (decision === 'not-replicated') {
+            continue;
+        }
+        if (decision.length === 0 ||
+            decision.some((sourceKey) => sourceKey.trim().length === 0) ||
+            new Set(decision).size !== decision.length) {
+            throw new Error(`Offline journal coverage for '${writeId}' must contain unique, non-empty source keys or 'not-replicated'.`);
+        }
+    }
+}

package/dist/offline/journal-retention.d.ts

@@ -0,0 +1,49 @@
+/** One retained product journal row considered for bounded cleanup. */
+export interface OfflineJournalRetentionCandidate<TScope> {
+    /** Monotonic journal position that becomes a client delta cursor. */
+    readonly cursor: number;
+    /** Product-defined authorization and retention partition. */
+    readonly scope: TScope;
+}
+/** Storage operations that must share one database transaction. */
+export interface OfflineJournalRetentionTransaction<TScope> {
+    /** Selects the oldest bounded cleanup candidates. */
+    listCandidates(cutoff: Date, limit: number): Promise<readonly OfflineJournalRetentionCandidate<TScope>[]>;
+    /** Locks existing scopes against concurrent pull floor validation. */
+    lockScopes(scopes: readonly TScope[]): Promise<readonly TScope[]>;
+    /** Monotonically advances each scope's retained-history floor. */
+    advanceFloors(floors: readonly {
+        scope: TScope;
+        cursor: number;
+    }[]): Promise<void>;
+    /** Deletes the complete candidate set, including rows for scopes that no longer exist. */
+    deleteCandidates(cursors: readonly number[]): Promise<void>;
+}
+/** Product adapter that owns schema-specific persistence and transaction creation. */
+export interface OfflineJournalRetentionStore<TScope> {
+    /** Runs the complete retention state machine in one database transaction. */
+    transaction<T>(operation: (tx: OfflineJournalRetentionTransaction<TScope>) => Promise<T>): Promise<T>;
+}
+/** Inputs for one bounded offline journal compaction pass. */
+export interface CompactOfflineJournalOptions<TScope> {
+    /** Product adapter that owns persistence and transaction creation. */
+    readonly store: OfflineJournalRetentionStore<TScope>;
+    /** Exclusive upper time boundary of journal rows eligible for cleanup. */
+    readonly cutoff: Date;
+    /** Maximum number of journal rows compacted in one pass. */
+    readonly limit: number;
+    /** Canonical identity used to deduplicate and compare product scopes. */
+    readonly scopeKey: (scope: TScope) => string;
+}
+/** Raised when a delta cursor predates the retained journal and must restart from a snapshot. */
+export declare class OfflineJournalRebaselineRequiredError extends Error {
+}
+/** Fail closed before reading deltas whose tombstones may already have been compacted. */
+export declare function assertOfflineJournalCursorRetained(cursor: number, floor: number): void;
+/**
+ * Advances retention floors and deletes one bounded journal batch atomically.
+ *
+ * Product adapters provide schema-specific queries. This state machine owns the
+ * safety order: candidates -> ordered opposing locks -> floors -> deletion.
+ */
+export declare function compactOfflineJournal<TScope>(options: CompactOfflineJournalOptions<TScope>): Promise<number>;

package/dist/offline/journal-retention.js

@@ -0,0 +1,68 @@
+/** Raised when a delta cursor predates the retained journal and must restart from a snapshot. */
+export class OfflineJournalRebaselineRequiredError extends Error {
+}
+/** Fail closed before reading deltas whose tombstones may already have been compacted. */
+export function assertOfflineJournalCursorRetained(cursor, floor) {
+    if (!Number.isSafeInteger(cursor) || cursor < 0 || !Number.isSafeInteger(floor) || floor < 0) {
+        throw new RangeError('Offline journal cursor and retention floor must be non-negative safe integers.');
+    }
+    if (cursor < floor) {
+        throw new OfflineJournalRebaselineRequiredError('Offline journal cursor predates retained history.');
+    }
+}
+/**
+ * Advances retention floors and deletes one bounded journal batch atomically.
+ *
+ * Product adapters provide schema-specific queries. This state machine owns the
+ * safety order: candidates -> ordered opposing locks -> floors -> deletion.
+ */
+export function compactOfflineJournal(options) {
+    if (!Number.isSafeInteger(options.limit) || options.limit <= 0) {
+        throw new RangeError('Offline journal retention limit must be a positive safe integer.');
+    }
+    if (Number.isNaN(options.cutoff.getTime())) {
+        throw new RangeError('Offline journal retention cutoff must be a valid date.');
+    }
+    return options.store.transaction(async (tx) => {
+        const candidates = await tx.listCandidates(options.cutoff, options.limit);
+        if (candidates.length === 0) {
+            return 0;
+        }
+        assertCandidates(candidates);
+        const scopeByKey = new Map(candidates.map((candidate) => [options.scopeKey(candidate.scope), candidate.scope]));
+        const scopes = [...scopeByKey.entries()]
+            .sort(([left], [right]) => compareCanonicalKeys(left, right))
+            .map(([, scope]) => scope);
+        const lockedKeys = new Set((await tx.lockScopes(scopes)).map(options.scopeKey));
+        const floorByKey = new Map();
+        for (const candidate of candidates) {
+            const key = options.scopeKey(candidate.scope);
+            if (!lockedKeys.has(key)) {
+                continue;
+            }
+            const current = floorByKey.get(key);
+            if (!current || candidate.cursor > current.cursor) {
+                floorByKey.set(key, { scope: candidate.scope, cursor: candidate.cursor });
+            }
+        }
+        if (floorByKey.size > 0) {
+            await tx.advanceFloors([...floorByKey.entries()]
+                .sort(([left], [right]) => compareCanonicalKeys(left, right))
+                .map(([, floor]) => floor));
+        }
+        await tx.deleteCandidates(candidates.map((candidate) => candidate.cursor));
+        return candidates.length;
+    });
+}
+function compareCanonicalKeys(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function assertCandidates(candidates) {
+    const cursors = new Set();
+    for (const candidate of candidates) {
+        if (!Number.isSafeInteger(candidate.cursor) || candidate.cursor <= 0 || cursors.has(candidate.cursor)) {
+            throw new Error('Offline journal retention candidates must have unique positive safe-integer cursors.');
+        }
+        cursors.add(candidate.cursor);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "private": false,
   "publishConfig": {
     "access": "public"