@rdlabo/workers-hono-kit 0.10.3 → 0.10.5

package/dist/offline/index.d.ts

@@ -14,3 +14,7 @@ export { decodeOfflineSnapshotCursor, encodeOfflineSnapshotCursor } from './snap
 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';
+export { defineOfflineWireCompatibility, resolveOfflineWireCompatibility } from './wire-compatibility.js';
+export type { OfflineWireAcceptedFingerprint, OfflineWireCompatibility, OfflineWireCompatibilityResolution, OfflineWireFingerprint, } from './wire-compatibility.js';

package/dist/offline/index.js

@@ -11,3 +11,5 @@ 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';
+export { defineOfflineWireCompatibility, resolveOfflineWireCompatibility } from './wire-compatibility.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/wire-compatibility.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Exact offline wire protocol identity: integer version plus content hash.
+ *
+ * Products own how the hash is computed; this kit never materializes schema
+ * projections or storage. Resolution always requires an exact `{version,hash}` pair.
+ */
+export interface OfflineWireFingerprint {
+    /** Monotonic published protocol version. */
+    readonly version: number;
+    /** Content fingerprint for that published version. */
+    readonly hash: string;
+}
+/**
+ * A previously published fingerprint that remains accepted until an explicit expiry.
+ *
+ * Non-current entries must name the product adapter/projection that serves that wire
+ * shape. Silently allowlisting a hash alone is forbidden.
+ */
+export interface OfflineWireAcceptedFingerprint extends OfflineWireFingerprint {
+    /** Instant at which acceptance ends (exclusive); later clocks reject the fingerprint. */
+    readonly expiresAt: Date;
+    /** Product-owned adapter or projection identifier for this prior wire shape. */
+    readonly adapterId: string;
+}
+/**
+ * Validated current fingerprint plus optional accepted prior fingerprints.
+ *
+ * Produced only by {@link defineOfflineWireCompatibility}.
+ */
+export interface OfflineWireCompatibility {
+    /** The currently published protocol fingerprint. */
+    readonly current: OfflineWireFingerprint;
+    /** Prior fingerprints accepted until their explicit expiry. */
+    readonly accepted: readonly OfflineWireAcceptedFingerprint[];
+}
+/**
+ * Successful resolution of an incoming fingerprint against a compatibility table.
+ *
+ * Unmatched, expired, or inexact fingerprints resolve to `undefined` so products can map
+ * the miss to their own conflict response (for example HTTP 409).
+ */
+export type OfflineWireCompatibilityResolution = {
+    readonly kind: 'current';
+    readonly fingerprint: OfflineWireFingerprint;
+} | {
+    readonly kind: 'accepted';
+    readonly fingerprint: OfflineWireFingerprint;
+    readonly adapterId: string;
+    readonly expiresAt: Date;
+};
+/**
+ * Validates a current fingerprint plus optional accepted prior fingerprints.
+ *
+ * Rejects duplicate versions, duplicate hashes, invalid fingerprints, invalid expiry
+ * instants, and accepted entries that omit a product adapter/projection identifier.
+ *
+ * @param options - Current fingerprint and optional accepted prior fingerprints.
+ * @returns A validated compatibility table safe to pass to {@link resolveOfflineWireCompatibility}.
+ */
+export declare function defineOfflineWireCompatibility(options: {
+    readonly current: OfflineWireFingerprint;
+    readonly accepted?: readonly OfflineWireAcceptedFingerprint[];
+}): OfflineWireCompatibility;
+/**
+ * Resolves an incoming `{version,hash}` against a validated compatibility table.
+ *
+ * Matches only exact fingerprints. Current always wins; accepted prior fingerprints match
+ * only while the injectable clock is strictly before their `expiresAt`.
+ *
+ * @param compatibility - Table from {@link defineOfflineWireCompatibility}.
+ * @param fingerprint - Incoming client fingerprint.
+ * @param clock - Injectable wall clock; defaults to the system wall clock.
+ * @returns The match, or `undefined` when the fingerprint is unknown, inexact, or expired.
+ */
+export declare function resolveOfflineWireCompatibility(compatibility: OfflineWireCompatibility, fingerprint: OfflineWireFingerprint, clock?: () => Date): OfflineWireCompatibilityResolution | undefined;

package/dist/offline/wire-compatibility.js

@@ -0,0 +1,94 @@
+/**
+ * Validates a current fingerprint plus optional accepted prior fingerprints.
+ *
+ * Rejects duplicate versions, duplicate hashes, invalid fingerprints, invalid expiry
+ * instants, and accepted entries that omit a product adapter/projection identifier.
+ *
+ * @param options - Current fingerprint and optional accepted prior fingerprints.
+ * @returns A validated compatibility table safe to pass to {@link resolveOfflineWireCompatibility}.
+ */
+export function defineOfflineWireCompatibility(options) {
+    const current = normalizeFingerprint(options.current, 'current');
+    const acceptedInput = options.accepted ?? [];
+    const versions = new Set([current.version]);
+    const hashes = new Set([current.hash]);
+    const accepted = [];
+    for (const [index, entry] of acceptedInput.entries()) {
+        const label = `accepted[${index}]`;
+        const fingerprint = normalizeFingerprint(entry, label);
+        if (versions.has(fingerprint.version)) {
+            throw new Error(`Offline wire compatibility rejects duplicate version ${fingerprint.version}.`);
+        }
+        if (hashes.has(fingerprint.hash)) {
+            throw new Error(`Offline wire compatibility rejects duplicate hash '${fingerprint.hash}'.`);
+        }
+        if (!(entry.expiresAt instanceof Date) || Number.isNaN(entry.expiresAt.getTime())) {
+            throw new RangeError(`Offline wire compatibility ${label}.expiresAt must be a valid Date.`);
+        }
+        const adapterId = entry.adapterId;
+        if (typeof adapterId !== 'string' || adapterId.trim().length === 0) {
+            throw new Error(`Offline wire compatibility ${label} requires a non-empty product adapter/projection identifier.`);
+        }
+        versions.add(fingerprint.version);
+        hashes.add(fingerprint.hash);
+        accepted.push({
+            version: fingerprint.version,
+            hash: fingerprint.hash,
+            expiresAt: entry.expiresAt,
+            adapterId,
+        });
+    }
+    return { current, accepted };
+}
+/**
+ * Resolves an incoming `{version,hash}` against a validated compatibility table.
+ *
+ * Matches only exact fingerprints. Current always wins; accepted prior fingerprints match
+ * only while the injectable clock is strictly before their `expiresAt`.
+ *
+ * @param compatibility - Table from {@link defineOfflineWireCompatibility}.
+ * @param fingerprint - Incoming client fingerprint.
+ * @param clock - Injectable wall clock; defaults to the system wall clock.
+ * @returns The match, or `undefined` when the fingerprint is unknown, inexact, or expired.
+ */
+export function resolveOfflineWireCompatibility(compatibility, fingerprint, clock = () => new Date()) {
+    const incoming = normalizeFingerprint(fingerprint, 'incoming');
+    if (incoming.version === compatibility.current.version) {
+        if (incoming.hash !== compatibility.current.hash) {
+            return undefined;
+        }
+        return { kind: 'current', fingerprint: compatibility.current };
+    }
+    const now = clock();
+    if (Number.isNaN(now.getTime())) {
+        throw new RangeError('Offline wire compatibility clock must return a valid Date.');
+    }
+    const nowMs = now.getTime();
+    for (const entry of compatibility.accepted) {
+        if (entry.version !== incoming.version) {
+            continue;
+        }
+        if (entry.hash !== incoming.hash) {
+            return undefined;
+        }
+        if (nowMs >= entry.expiresAt.getTime()) {
+            return undefined;
+        }
+        return {
+            kind: 'accepted',
+            fingerprint: { version: entry.version, hash: entry.hash },
+            adapterId: entry.adapterId,
+            expiresAt: entry.expiresAt,
+        };
+    }
+    return undefined;
+}
+function normalizeFingerprint(fingerprint, label) {
+    if (!Number.isSafeInteger(fingerprint.version) || fingerprint.version < 0) {
+        throw new RangeError(`Offline wire compatibility ${label}.version must be a non-negative safe integer.`);
+    }
+    if (typeof fingerprint.hash !== 'string' || fingerprint.hash.trim().length === 0) {
+        throw new Error(`Offline wire compatibility ${label}.hash must be a non-empty string.`);
+    }
+    return { version: fingerprint.version, hash: fingerprint.hash };
+}

package/package.json

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