@rdlabo/workers-hono-kit 0.9.0 → 0.9.1

package/README.md

@@ -44,6 +44,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 > | `.` | `@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
@@ -86,6 +87,8 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `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. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
@@ -192,6 +195,70 @@ 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. Its table scheme requires every represented table and column, including optional nullable/default keys from `$inferInsert`. |
+| `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<FoodMethodScheme, Tables>({
+  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<typeof foods.$inferInsert, 'id'>[];
+};
+```
+
+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`.
+
+```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.

package/dist/idempotency/idempotency.d.ts

@@ -0,0 +1,77 @@
+/** Scalar values that may identify an idempotency scope. */
+export type IdempotencyScopeValue = string | number;
+/** A stable business scope for an idempotency key, such as user and tenant ids. */
+export type IdempotencyScope = Readonly<Record<string, IdempotencyScopeValue>>;
+/** Validated input persisted by an idempotency store. */
+export interface IdempotencyInput<TScope extends IdempotencyScope = IdempotencyScope> {
+    /** Caller-supplied idempotency key. */
+    key: string;
+    /** SHA-256 of the canonical request payload. */
+    payloadHash: string;
+    /** Application-defined isolation scope. */
+    scope: TScope;
+}
+/** Options used to validate an idempotency key and hash its payload. */
+export interface CreateIdempotencyInputOptions<TScope extends IdempotencyScope> {
+    /** Header value. `undefined` disables idempotency for backward compatibility. */
+    key: string | undefined;
+    /** Request payload whose semantic identity must remain stable across retries. */
+    payload: unknown;
+    /** Application-defined isolation scope. */
+    scope: TScope;
+    /** Maximum accepted key length. Defaults to 255. */
+    maxKeyLength?: number;
+}
+/** Raised when an idempotency key is empty or exceeds the configured limit. */
+export declare class IdempotencyKeyValidationError extends Error {
+    constructor(message?: string);
+}
+/** Raised when a payload contains a value that cannot be represented by JSON. */
+export declare class IdempotencyPayloadValidationError extends Error {
+    constructor(message?: string);
+}
+/** Raised when a key is reused with a different canonical payload. */
+export declare class IdempotencyConflictError extends Error {
+    constructor(message?: string);
+}
+/** Raised when another request currently owns the same idempotency key. */
+export declare class IdempotencyInFlightError extends Error {
+    constructor(message?: string);
+}
+/** Result returned by the store reservation step. */
+export type IdempotencyReservation<TResponse> = {
+    kind: 'acquired';
+} | {
+    kind: 'replay';
+    response: TResponse;
+};
+/** 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. */
+    reserve(input: IdempotencyInput<TScope>): Promise<IdempotencyReservation<TResponse>>;
+    /** Persist the mutation response in the same transaction as the domain write. */
+    complete(input: IdempotencyInput<TScope>, response: TResponse): Promise<void>;
+}
+/** Deterministically serialize JSON data with locale-independent, UTF-16 code-unit key ordering. */
+export declare function canonicalJson(value: unknown): string;
+/** Hash a value after canonical JSON serialization using the Workers Web Crypto API. */
+export declare function sha256CanonicalJson(value: unknown): Promise<string>;
+/** Validate an optional idempotency key and build its persistence input. */
+export declare function createIdempotencyInput<TScope extends IdempotencyScope>(options: CreateIdempotencyInputOptions<TScope>): Promise<IdempotencyInput<TScope> | undefined>;
+/**
+ * Execute a mutation with store-provided reservation and completion steps.
+ *
+ * @remarks
+ * The caller must bind `store` and `mutate` to the same database transaction. This function owns
+ * the state machine; the consuming application owns its schema and ORM adapter.
+ */
+export declare function runIdempotentMutation<TScope extends IdempotencyScope, TResponse>(options: {
+    /** Optional input; omitted keys preserve legacy non-idempotent behavior. */
+    input: IdempotencyInput<TScope> | undefined;
+    /** Transaction-bound persistence adapter. */
+    store: IdempotentMutationStore<TScope, TResponse>;
+    /** Domain mutation executed only after this request acquires the key. */
+    mutate: () => Promise<TResponse>;
+}): Promise<TResponse>;
+/** Map standard idempotency failures to Hono HTTP exceptions without hiding unrelated errors. */
+export declare function withIdempotencyHttpErrors<T>(run: () => Promise<T>): Promise<T>;

package/dist/idempotency/idempotency.js

@@ -0,0 +1,152 @@
+import { HTTPException } from 'hono/http-exception';
+/** Raised when an idempotency key is empty or exceeds the configured limit. */
+export class IdempotencyKeyValidationError extends Error {
+    constructor(message = 'Invalid Idempotency-Key') {
+        super(message);
+        this.name = 'IdempotencyKeyValidationError';
+    }
+}
+/** Raised when a payload contains a value that cannot be represented by JSON. */
+export class IdempotencyPayloadValidationError extends Error {
+    constructor(message = 'Idempotency payload must contain only JSON values') {
+        super(message);
+        this.name = 'IdempotencyPayloadValidationError';
+    }
+}
+/** Raised when a key is reused with a different canonical payload. */
+export class IdempotencyConflictError extends Error {
+    constructor(message = 'Idempotency-Key was already used with a different payload') {
+        super(message);
+        this.name = 'IdempotencyConflictError';
+    }
+}
+/** Raised when another request currently owns the same idempotency key. */
+export class IdempotencyInFlightError extends Error {
+    constructor(message = 'Idempotent request is still processing') {
+        super(message);
+        this.name = 'IdempotencyInFlightError';
+    }
+}
+/** Deterministically serialize JSON data with locale-independent, UTF-16 code-unit key ordering. */
+export function canonicalJson(value) {
+    try {
+        return canonicalJsonValue(value, new Set());
+    }
+    catch (error) {
+        if (error instanceof IdempotencyPayloadValidationError) {
+            throw error;
+        }
+        throw new IdempotencyPayloadValidationError();
+    }
+}
+function canonicalJsonValue(value, ancestors) {
+    if (Array.isArray(value)) {
+        const keys = Reflect.ownKeys(value);
+        const expectedKeys = new Set(['length', ...Array.from({ length: value.length }, (_, index) => String(index))]);
+        if (keys.length !== expectedKeys.size || keys.some((key) => typeof key !== 'string' || !expectedKeys.has(key))) {
+            throw new IdempotencyPayloadValidationError();
+        }
+        const items = Array.from({ length: value.length }, (_, index) => {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor?.enumerable || !('value' in descriptor)) {
+                throw new IdempotencyPayloadValidationError();
+            }
+            return descriptor.value;
+        });
+        if (ancestors.has(value)) {
+            throw new IdempotencyPayloadValidationError();
+        }
+        ancestors.add(value);
+        const serialized = `[${items.map((item) => canonicalJsonValue(item, ancestors)).join(',')}]`;
+        ancestors.delete(value);
+        return serialized;
+    }
+    if (value !== null && typeof value === 'object') {
+        if (Object.getPrototypeOf(value) !== Object.prototype) {
+            throw new IdempotencyPayloadValidationError();
+        }
+        if (ancestors.has(value)) {
+            throw new IdempotencyPayloadValidationError();
+        }
+        const entries = Reflect.ownKeys(value).map((key) => {
+            if (typeof key !== 'string') {
+                throw new IdempotencyPayloadValidationError();
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor)) {
+                throw new IdempotencyPayloadValidationError();
+            }
+            return [key, descriptor.value];
+        });
+        ancestors.add(value);
+        const serialized = `{${entries
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJsonValue(item, ancestors)}`)
+            .join(',')}}`;
+        ancestors.delete(value);
+        return serialized;
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new IdempotencyPayloadValidationError();
+    }
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== 'string') {
+        throw new IdempotencyPayloadValidationError();
+    }
+    return serialized;
+}
+/** Hash a value after canonical JSON serialization using the Workers Web Crypto API. */
+export async function sha256CanonicalJson(value) {
+    const bytes = new TextEncoder().encode(canonicalJson(value));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Validate an optional idempotency key and build its persistence input. */
+export async function createIdempotencyInput(options) {
+    if (options.key === undefined) {
+        return undefined;
+    }
+    const maxKeyLength = options.maxKeyLength ?? 255;
+    if (options.key.length === 0 || options.key.length > maxKeyLength) {
+        throw new IdempotencyKeyValidationError();
+    }
+    return {
+        key: options.key,
+        payloadHash: await sha256CanonicalJson(options.payload),
+        scope: options.scope,
+    };
+}
+/**
+ * Execute a mutation with store-provided reservation and completion steps.
+ *
+ * @remarks
+ * The caller must bind `store` and `mutate` to the same database transaction. This function owns
+ * the state machine; the consuming application owns its schema and ORM adapter.
+ */
+export async function runIdempotentMutation(options) {
+    if (!options.input) {
+        return options.mutate();
+    }
+    const reservation = await options.store.reserve(options.input);
+    if (reservation.kind === 'replay') {
+        return reservation.response;
+    }
+    const response = await options.mutate();
+    await options.store.complete(options.input, response);
+    return response;
+}
+/** Map standard idempotency failures to Hono HTTP exceptions without hiding unrelated errors. */
+export async function withIdempotencyHttpErrors(run) {
+    return run().catch((error) => {
+        if (error instanceof IdempotencyKeyValidationError || error instanceof IdempotencyPayloadValidationError) {
+            throw new HTTPException(400, { message: error.message });
+        }
+        if (error instanceof IdempotencyConflictError) {
+            throw new HTTPException(409, { message: error.message });
+        }
+        if (error instanceof IdempotencyInFlightError) {
+            throw new HTTPException(503, { message: error.message });
+        }
+        throw error;
+    });
+}

package/dist/index.d.ts

@@ -47,6 +47,8 @@ export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export type { DeferExecutor } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
 export type { SentryExceptionReporterLike } from './http/http-error.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 { 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';

package/dist/index.js

@@ -35,6 +35,8 @@ export { createAppErrorHandler } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
+// idempotency
+export { canonicalJson, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, 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/offline/clock.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read the current wall-clock instant in canonical replica wire form.
+ *
+ * @param clock - Injectable clock; defaults to the system wall clock.
+ * @returns The current instant as an ISO-8601 string.
+ */
+export declare function replicaNowIso(clock?: () => Date): string;

package/dist/offline/clock.js

@@ -0,0 +1,10 @@
+import { toReplicaIsoDatetime } from './wire.js';
+/**
+ * Read the current wall-clock instant in canonical replica wire form.
+ *
+ * @param clock - Injectable clock; defaults to the system wall clock.
+ * @returns The current instant as an ISO-8601 string.
+ */
+export function replicaNowIso(clock = () => new Date()) {
+    return toReplicaIsoDatetime(clock());
+}

package/dist/offline/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Table-agnostic helpers for offline replica converters.
+ *
+ * Product table projections, Zod object schemas, allowlists, and domain
+ * validation intentionally remain in each consuming Hono application.
+ *
+ * @packageDocumentation
+ */
+export { fromTinyIntFlag, replicaTimestampMs, toReplicaDateOnly, toReplicaIsoDatetime, toTinyIntFlag } from './wire.js';
+export { replicaNowIso } from './clock.js';
+export { defineRestDbMethodConverter } from './rest-db-method-converter.js';
+export type { RestDbMethodConverter } from './rest-db-method-converter.js';

package/dist/offline/index.js

@@ -0,0 +1,11 @@
+/**
+ * Table-agnostic helpers for offline replica converters.
+ *
+ * Product table projections, Zod object schemas, allowlists, and domain
+ * validation intentionally remain in each consuming Hono application.
+ *
+ * @packageDocumentation
+ */
+export { fromTinyIntFlag, replicaTimestampMs, toReplicaDateOnly, toReplicaIsoDatetime, toTinyIntFlag } from './wire.js';
+export { replicaNowIso } from './clock.js';
+export { defineRestDbMethodConverter } from './rest-db-method-converter.js';

package/dist/offline/rest-db-method-converter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A product-owned table bundle used by one REST API method.
+ *
+ * Each property represents one DB table participating in the method. Products
+ * should use their exported Drizzle `$inferSelect` / `$inferInsert` types here;
+ * this package deliberately knows no table names or columns.
+ */
+/** Require every column represented by a product DB row type. */
+type CompleteDbRow<TRow> = {
+    [TKey in keyof TRow]-?: TRow[TKey];
+};
+type CompleteDbTableValue<TValue> = TValue extends (infer TRow)[] ? TRow extends object ? CompleteDbRow<TRow>[] : TValue : TValue extends readonly (infer TRow)[] ? TRow extends object ? readonly CompleteDbRow<TRow>[] : TValue : TValue extends object ? CompleteDbRow<TValue> : TValue;
+/**
+ * Require every table key and every represented row column.
+ *
+ * This also makes optional `$inferInsert` columns explicit. A method that
+ * intentionally does not own a generated column must exclude it from its
+ * product-owned scheme first, for example `Omit<InsertRow, 'id'>`.
+ */
+type CompleteRestDbTableScheme<TTableScheme extends object> = {
+    [TTableName in keyof TTableScheme]-?: CompleteDbTableValue<TTableScheme[TTableName]>;
+};
+/**
+ * Pure, bidirectional conversion between one REST method type and the DB table
+ * types participating in that method.
+ *
+ * Nullable/default DB columns remain required properties even when a Drizzle
+ * `$inferInsert` type marks them optional. Nullability does not make a column
+ * optional in the conversion contract.
+ */
+export interface RestDbMethodConverter<TMethodScheme, TTableScheme extends object> {
+    toMethodScheme(tableScheme: Readonly<CompleteRestDbTableScheme<TTableScheme>>): TMethodScheme;
+    toTableScheme(methodScheme: Readonly<TMethodScheme>): CompleteRestDbTableScheme<TTableScheme>;
+}
+/**
+ * Define a product-specific REST ↔ DB converter with contextual return types.
+ *
+ * This is intentionally an identity function: conversion remains explicit,
+ * synchronous, and free of hidden persistence or HTTP side effects.
+ */
+export declare function defineRestDbMethodConverter<TMethodScheme, TTableScheme extends object>(converter: RestDbMethodConverter<TMethodScheme, TTableScheme>): RestDbMethodConverter<TMethodScheme, TTableScheme>;
+export {};

package/dist/offline/rest-db-method-converter.js

@@ -0,0 +1,9 @@
+/**
+ * Define a product-specific REST ↔ DB converter with contextual return types.
+ *
+ * This is intentionally an identity function: conversion remains explicit,
+ * synchronous, and free of hidden persistence or HTTP side effects.
+ */
+export function defineRestDbMethodConverter(converter) {
+    return converter;
+}

package/dist/offline/wire.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical UTC ISO-8601 wire form for an offline replica datetime.
+ *
+ * @param value - A valid instant represented as a `Date` or parseable string.
+ * @returns The instant as an ISO-8601 string.
+ * @throws RangeError when the input is not a valid instant.
+ */
+export declare function toReplicaIsoDatetime(value: Date | string): string;
+/**
+ * Canonical `YYYY-MM-DD` wire form for an offline replica date.
+ *
+ * A date-only string is treated as a calendar value and therefore is not shifted
+ * through a timezone. Datetime inputs are converted from their UTC instant.
+ *
+ * @param value - A date, datetime string, `Date`, or `null`.
+ * @returns A canonical date-only string, or `null`.
+ * @throws RangeError when the input is not a valid date.
+ */
+export declare function toReplicaDateOnly(value: Date | string | null): string | null;
+/**
+ * Convert a replica datetime to epoch milliseconds for legacy status DTOs.
+ *
+ * @param value - A valid instant represented as a `Date` or parseable string.
+ * @returns Epoch milliseconds.
+ * @throws RangeError when the input is not a valid instant.
+ */
+export declare function replicaTimestampMs(value: Date | string): number;
+/**
+ * Convert a boolean-like value to a MySQL/SQLite tinyint flag.
+ *
+ * @param value - Boolean or numeric truth value.
+ * @returns `1` for truthy values and `0` otherwise.
+ */
+export declare function toTinyIntFlag(value: boolean | number): 0 | 1;
+/**
+ * Convert a MySQL/SQLite tinyint flag to a boolean.
+ *
+ * @param value - Numeric flag.
+ * @returns `false` only for zero.
+ */
+export declare function fromTinyIntFlag(value: number): boolean;

package/dist/offline/wire.js

@@ -0,0 +1,79 @@
+/**
+ * Canonical UTC ISO-8601 wire form for an offline replica datetime.
+ *
+ * @param value - A valid instant represented as a `Date` or parseable string.
+ * @returns The instant as an ISO-8601 string.
+ * @throws RangeError when the input is not a valid instant.
+ */
+export function toReplicaIsoDatetime(value) {
+    const instant = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(instant.getTime())) {
+        throw new RangeError(`Invalid replica datetime: ${String(value)}`);
+    }
+    return instant.toISOString();
+}
+/**
+ * Canonical `YYYY-MM-DD` wire form for an offline replica date.
+ *
+ * A date-only string is treated as a calendar value and therefore is not shifted
+ * through a timezone. Datetime inputs are converted from their UTC instant.
+ *
+ * @param value - A date, datetime string, `Date`, or `null`.
+ * @returns A canonical date-only string, or `null`.
+ * @throws RangeError when the input is not a valid date.
+ */
+export function toReplicaDateOnly(value) {
+    if (value === null) {
+        return null;
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new RangeError(`Invalid replica date: ${String(value)}`);
+        }
+        return value.toISOString().slice(0, 10);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        const canonicalDate = new Date(`${value}T00:00:00.000Z`);
+        if (Number.isNaN(canonicalDate.getTime()) || canonicalDate.toISOString().slice(0, 10) !== value) {
+            throw new RangeError(`Invalid replica date: ${value}`);
+        }
+        return value;
+    }
+    const instant = new Date(value);
+    if (Number.isNaN(instant.getTime())) {
+        throw new RangeError(`Invalid replica date: ${value}`);
+    }
+    return instant.toISOString().slice(0, 10);
+}
+/**
+ * Convert a replica datetime to epoch milliseconds for legacy status DTOs.
+ *
+ * @param value - A valid instant represented as a `Date` or parseable string.
+ * @returns Epoch milliseconds.
+ * @throws RangeError when the input is not a valid instant.
+ */
+export function replicaTimestampMs(value) {
+    const instant = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(instant.getTime())) {
+        throw new RangeError(`Invalid replica timestamp: ${String(value)}`);
+    }
+    return instant.getTime();
+}
+/**
+ * Convert a boolean-like value to a MySQL/SQLite tinyint flag.
+ *
+ * @param value - Boolean or numeric truth value.
+ * @returns `1` for truthy values and `0` otherwise.
+ */
+export function toTinyIntFlag(value) {
+    return value ? 1 : 0;
+}
+/**
+ * Convert a MySQL/SQLite tinyint flag to a boolean.
+ *
+ * @param value - Numeric flag.
+ * @returns `false` only for zero.
+ */
+export function fromTinyIntFlag(value) {
+    return value !== 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -61,6 +61,11 @@
       "import": "./dist/business-time/index.js",
       "default": "./dist/business-time/index.js"
     },
+    "./offline": {
+      "types": "./dist/offline/index.d.ts",
+      "import": "./dist/offline/index.js",
+      "default": "./dist/offline/index.js"
+    },
     "./realtime": {
       "types": "./dist/realtime/index.d.ts",
       "import": "./dist/realtime/index.js",