rwsdk 1.2.12 → 1.2.13-test.20260618142113

package/dist/use-synced-state/SyncedStateServerHibernation.d.mts

@@ -0,0 +1,57 @@
+import { DurableObject } from "cloudflare:workers";
+import type { RequestInfo } from "../runtime/requestInfo/types";
+import { type SyncedStateValue } from "./protocol-hibernation.mjs";
+export type SyncedStateServerHibernationAttachment = {
+    clientId: string;
+    subscriptions: Array<{
+        userKey: string;
+        storageKey: string;
+    }>;
+};
+type OnSetHandler = (key: string, value: SyncedStateValue, stub: DurableObjectStub<SyncedStateServerHibernation>) => void;
+type OnGetHandler = (key: string, value: SyncedStateValue | undefined, stub: DurableObjectStub<SyncedStateServerHibernation>) => void;
+type OnKeyHandler = (key: string, stub: DurableObjectStub<SyncedStateServerHibernation>) => Promise<string>;
+type OnRoomHandler = (roomId: string | undefined, requestInfo: RequestInfo | null) => Promise<string>;
+type OnSubscribeHandler = (key: string, stub: DurableObjectStub<SyncedStateServerHibernation>) => void;
+type OnUnsubscribeHandler = (key: string, stub: DurableObjectStub<SyncedStateServerHibernation>) => void;
+/**
+ * Durable Object that keeps shared state for multiple clients and notifies
+ * subscribers, using the Cloudflare Hibernation WebSocket API so idle
+ * connections do not keep the object active.
+ *
+ * The implementation copies the hibernation lifecycle pattern from the older
+ * RealtimeDurableObject but replaces its RSC/action protocol with a small
+ * JSON state-sync protocol.
+ *
+ * Keys are expected to arrive already transformed by the worker proxy (via
+ * registerKeyHandler). The DO stores and broadcasts using the `storageKey`
+ * provided in each message, but sends user-facing `key` values back to the
+ * client.
+ */
+export declare class SyncedStateServerHibernation extends DurableObject {
+    #private;
+    static registerKeyHandler(handler: OnKeyHandler | null): void;
+    static getKeyHandler(): OnKeyHandler | null;
+    static registerRoomHandler(handler: OnRoomHandler | null): void;
+    static getRoomHandler(): OnRoomHandler | null;
+    static registerNamespace(namespace: DurableObjectNamespace<SyncedStateServerHibernation>, durableObjectName?: string): void;
+    static getNamespace(): DurableObjectNamespace<SyncedStateServerHibernation> | null;
+    static getDurableObjectName(): string;
+    static registerSetStateHandler(handler: OnSetHandler | null): void;
+    static registerGetStateHandler(handler: OnGetHandler | null): void;
+    static registerSubscribeHandler(handler: OnSubscribeHandler | null): void;
+    static registerUnsubscribeHandler(handler: OnUnsubscribeHandler | null): void;
+    static getSubscribeHandler(): OnSubscribeHandler | null;
+    static getUnsubscribeHandler(): OnUnsubscribeHandler | null;
+    state: DurableObjectState;
+    env: Env;
+    storage: DurableObjectStorage;
+    constructor(state: DurableObjectState, env: Env);
+    setStub(stub: DurableObjectStub<SyncedStateServerHibernation>): void;
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: WebSocket): Promise<void>;
+    getState(key: string): Promise<SyncedStateValue | undefined>;
+    setState(value: SyncedStateValue, key: string): Promise<void>;
+}
+export {};

package/dist/use-synced-state/SyncedStateServerHibernation.mjs

@@ -0,0 +1,329 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _SyncedStateServerHibernation_instances, _a, _SyncedStateServerHibernation_keyHandler, _SyncedStateServerHibernation_roomHandler, _SyncedStateServerHibernation_setStateHandler, _SyncedStateServerHibernation_getStateHandler, _SyncedStateServerHibernation_subscribeHandler, _SyncedStateServerHibernation_unsubscribeHandler, _SyncedStateServerHibernation_namespace, _SyncedStateServerHibernation_durableObjectName, _SyncedStateServerHibernation_stub, _SyncedStateServerHibernation_stateStore, _SyncedStateServerHibernation_getState, _SyncedStateServerHibernation_setState, _SyncedStateServerHibernation_subscriptions, _SyncedStateServerHibernation_subscribe, _SyncedStateServerHibernation_unsubscribe, _SyncedStateServerHibernation_broadcastUpdate, _SyncedStateServerHibernation_getAttachment, _SyncedStateServerHibernation_getSubscriptionsFromAttachment, _SyncedStateServerHibernation_setSubscriptionsInAttachment, _SyncedStateServerHibernation_ensureSubscriptionsLoaded, _SyncedStateServerHibernation_getStubForHandlers, _SyncedStateServerHibernation_send, _SyncedStateServerHibernation_sendError;
+import { DurableObject } from "cloudflare:workers";
+import { unpackClientMessage, packMessage, } from "./protocol-hibernation.mjs";
+/**
+ * Durable Object that keeps shared state for multiple clients and notifies
+ * subscribers, using the Cloudflare Hibernation WebSocket API so idle
+ * connections do not keep the object active.
+ *
+ * The implementation copies the hibernation lifecycle pattern from the older
+ * RealtimeDurableObject but replaces its RSC/action protocol with a small
+ * JSON state-sync protocol.
+ *
+ * Keys are expected to arrive already transformed by the worker proxy (via
+ * registerKeyHandler). The DO stores and broadcasts using the `storageKey`
+ * provided in each message, but sends user-facing `key` values back to the
+ * client.
+ */
+export class SyncedStateServerHibernation extends DurableObject {
+    static registerKeyHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_keyHandler);
+    }
+    static getKeyHandler() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_keyHandler);
+    }
+    static registerRoomHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_roomHandler);
+    }
+    static getRoomHandler() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_roomHandler);
+    }
+    static registerNamespace(namespace, durableObjectName) {
+        __classPrivateFieldSet(_a, _a, namespace, "f", _SyncedStateServerHibernation_namespace);
+        if (durableObjectName) {
+            __classPrivateFieldSet(_a, _a, durableObjectName, "f", _SyncedStateServerHibernation_durableObjectName);
+        }
+    }
+    static getNamespace() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_namespace);
+    }
+    static getDurableObjectName() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_durableObjectName);
+    }
+    static registerSetStateHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_setStateHandler);
+    }
+    static registerGetStateHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_getStateHandler);
+    }
+    static registerSubscribeHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_subscribeHandler);
+    }
+    static registerUnsubscribeHandler(handler) {
+        __classPrivateFieldSet(_a, _a, handler, "f", _SyncedStateServerHibernation_unsubscribeHandler);
+    }
+    static getSubscribeHandler() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_subscribeHandler);
+    }
+    static getUnsubscribeHandler() {
+        return __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_unsubscribeHandler);
+    }
+    constructor(state, env) {
+        super(state, env);
+        _SyncedStateServerHibernation_instances.add(this);
+        _SyncedStateServerHibernation_stub.set(this, null);
+        // ---------------------------------------------------------------------------
+        // State storage
+        // ---------------------------------------------------------------------------
+        _SyncedStateServerHibernation_stateStore.set(this, new Map());
+        // ---------------------------------------------------------------------------
+        // Subscriptions
+        // ---------------------------------------------------------------------------
+        // Map from storage key to the subscribers for that key. We store the
+        // user-facing key per subscriber so broadcasts can send each socket the key
+        // it originally subscribed to.
+        _SyncedStateServerHibernation_subscriptions.set(this, new Map());
+        this.state = state;
+        this.env = env;
+        this.storage = state.storage;
+    }
+    setStub(stub) {
+        __classPrivateFieldSet(this, _SyncedStateServerHibernation_stub, stub, "f");
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        const clientId = url.searchParams.get("clientId") ?? crypto.randomUUID();
+        const { 0: client, 1: server } = new WebSocketPair();
+        const attachment = {
+            clientId,
+            subscriptions: [],
+        };
+        server.serializeAttachment(attachment);
+        this.state.acceptWebSocket(server);
+        return new Response(null, { status: 101, webSocket: client });
+    }
+    async webSocketMessage(ws, data) {
+        if (typeof data !== "string") {
+            __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_sendError).call(this, ws, "Expected text WebSocket message");
+            return;
+        }
+        let message;
+        try {
+            message = unpackClientMessage(data);
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_sendError).call(this, ws, error instanceof Error ? error.message : "Invalid protocol message");
+            return;
+        }
+        const storageKey = message.storageKey ?? message.key;
+        // After hibernation the in-memory subscription map is empty. Rehydrate it
+        // from the socket attachment before handling any message that depends on
+        // knowing this socket's subscriptions (especially broadcasts on setState).
+        __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_ensureSubscriptionsLoaded).call(this, ws);
+        switch (message.kind) {
+            case "getState": {
+                const value = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getState).call(this, storageKey);
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_send).call(this, ws, {
+                    kind: "getState",
+                    key: message.key,
+                    value,
+                    id: message.id,
+                });
+                break;
+            }
+            case "setState": {
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_setState).call(this, storageKey, message.value);
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_send).call(this, ws, {
+                    kind: "setState",
+                    key: message.key,
+                    id: message.id,
+                });
+                break;
+            }
+            case "subscribe": {
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_subscribe).call(this, ws, storageKey, message.key);
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_send).call(this, ws, {
+                    kind: "subscribe",
+                    key: message.key,
+                    id: message.id,
+                });
+                break;
+            }
+            case "unsubscribe": {
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_unsubscribe).call(this, ws, storageKey, message.key);
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_send).call(this, ws, {
+                    kind: "unsubscribe",
+                    key: message.key,
+                    id: message.id,
+                });
+                break;
+            }
+            default: {
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_sendError).call(this, ws, "Unknown message kind", message.id);
+            }
+        }
+    }
+    async webSocketClose(ws) {
+        // context(justinvdm, 18 Jun 2026): Remove this socket from all in-memory
+        // subscription sets. The attachment is dropped by the runtime, so no
+        // persistent cleanup is required.
+        for (const subscribers of __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").values()) {
+            for (const entry of subscribers) {
+                if (entry.ws === ws) {
+                    subscribers.delete(entry);
+                    break;
+                }
+            }
+        }
+        for (const [key, subscribers] of __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f")) {
+            if (subscribers.size === 0) {
+                __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").delete(key);
+            }
+        }
+    }
+    // Public RPC surface exposed to handler callbacks and other Workers RPC callers.
+    async getState(key) {
+        return __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getState).call(this, key);
+    }
+    async setState(value, key) {
+        __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_setState).call(this, key, value);
+    }
+}
+_a = SyncedStateServerHibernation, _SyncedStateServerHibernation_stub = new WeakMap(), _SyncedStateServerHibernation_stateStore = new WeakMap(), _SyncedStateServerHibernation_subscriptions = new WeakMap(), _SyncedStateServerHibernation_instances = new WeakSet(), _SyncedStateServerHibernation_getState = function _SyncedStateServerHibernation_getState(key) {
+    const value = __classPrivateFieldGet(this, _SyncedStateServerHibernation_stateStore, "f").get(key);
+    if (__classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_getStateHandler)) {
+        const stub = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getStubForHandlers).call(this);
+        if (stub) {
+            __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_getStateHandler).call(_a, key, value, stub);
+        }
+    }
+    return value;
+}, _SyncedStateServerHibernation_setState = function _SyncedStateServerHibernation_setState(key, value) {
+    __classPrivateFieldGet(this, _SyncedStateServerHibernation_stateStore, "f").set(key, value);
+    if (__classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_setStateHandler)) {
+        const stub = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getStubForHandlers).call(this);
+        if (stub) {
+            __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_setStateHandler).call(_a, key, value, stub);
+        }
+    }
+    __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_broadcastUpdate).call(this, key, value);
+}, _SyncedStateServerHibernation_subscribe = function _SyncedStateServerHibernation_subscribe(ws, storageKey, userKey) {
+    if (!__classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").has(storageKey)) {
+        __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").set(storageKey, new Set());
+    }
+    __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").get(storageKey).add({ ws, userKey });
+    const subscribeHandler = __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_subscribeHandler);
+    if (subscribeHandler) {
+        const stub = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getStubForHandlers).call(this);
+        if (stub) {
+            subscribeHandler(storageKey, stub);
+        }
+    }
+    // Persist the subscription in the socket attachment so it survives
+    // hibernation.
+    const subs = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getSubscriptionsFromAttachment).call(this, ws);
+    if (!subs.some((s) => s.userKey === userKey && s.storageKey === storageKey)) {
+        subs.push({ userKey, storageKey });
+        __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_setSubscriptionsInAttachment).call(this, ws, subs);
+    }
+}, _SyncedStateServerHibernation_unsubscribe = function _SyncedStateServerHibernation_unsubscribe(ws, storageKey, userKey) {
+    const subscribers = __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").get(storageKey);
+    if (subscribers) {
+        for (const entry of subscribers) {
+            if (entry.ws === ws && entry.userKey === userKey) {
+                subscribers.delete(entry);
+                break;
+            }
+        }
+        if (subscribers.size === 0) {
+            __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").delete(storageKey);
+        }
+    }
+    const unsubscribeHandler = __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_unsubscribeHandler);
+    if (unsubscribeHandler) {
+        const stub = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getStubForHandlers).call(this);
+        if (stub) {
+            unsubscribeHandler(storageKey, stub);
+        }
+    }
+    const subs = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getSubscriptionsFromAttachment).call(this, ws).filter((s) => !(s.userKey === userKey && s.storageKey === storageKey));
+    __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_setSubscriptionsInAttachment).call(this, ws, subs);
+}, _SyncedStateServerHibernation_broadcastUpdate = function _SyncedStateServerHibernation_broadcastUpdate(key, value) {
+    const subscribers = __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").get(key);
+    if (!subscribers || subscribers.size === 0) {
+        return;
+    }
+    for (const { ws, userKey } of subscribers) {
+        const message = {
+            kind: "update",
+            key: userKey,
+            value,
+        };
+        try {
+            ws.send(packMessage(message));
+        }
+        catch {
+            // Socket is already closed; it will be cleaned up via webSocketClose.
+        }
+    }
+}, _SyncedStateServerHibernation_getAttachment = function _SyncedStateServerHibernation_getAttachment(ws) {
+    const raw = ws.deserializeAttachment();
+    if (raw &&
+        typeof raw === "object" &&
+        "subscriptions" in raw &&
+        Array.isArray(raw.subscriptions)) {
+        return raw;
+    }
+    return { clientId: "", subscriptions: [] };
+}, _SyncedStateServerHibernation_getSubscriptionsFromAttachment = function _SyncedStateServerHibernation_getSubscriptionsFromAttachment(ws) {
+    return __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getAttachment).call(this, ws).subscriptions;
+}, _SyncedStateServerHibernation_setSubscriptionsInAttachment = function _SyncedStateServerHibernation_setSubscriptionsInAttachment(ws, subscriptions) {
+    const attachment = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getAttachment).call(this, ws);
+    attachment.subscriptions = subscriptions;
+    ws.serializeAttachment(attachment);
+}, _SyncedStateServerHibernation_ensureSubscriptionsLoaded = function _SyncedStateServerHibernation_ensureSubscriptionsLoaded(ws) {
+    const subs = __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_getSubscriptionsFromAttachment).call(this, ws);
+    for (const { userKey, storageKey } of subs) {
+        if (!__classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").has(storageKey)) {
+            __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").set(storageKey, new Set());
+        }
+        const subscribers = __classPrivateFieldGet(this, _SyncedStateServerHibernation_subscriptions, "f").get(storageKey);
+        let exists = false;
+        for (const entry of subscribers) {
+            if (entry.ws === ws && entry.userKey === userKey) {
+                exists = true;
+                break;
+            }
+        }
+        if (!exists) {
+            subscribers.add({ ws, userKey });
+        }
+    }
+}, _SyncedStateServerHibernation_getStubForHandlers = function _SyncedStateServerHibernation_getStubForHandlers() {
+    if (__classPrivateFieldGet(this, _SyncedStateServerHibernation_stub, "f")) {
+        return __classPrivateFieldGet(this, _SyncedStateServerHibernation_stub, "f");
+    }
+    const namespace = __classPrivateFieldGet(_a, _a, "f", _SyncedStateServerHibernation_namespace);
+    if (namespace) {
+        return namespace.get(this.ctx.id);
+    }
+    return null;
+}, _SyncedStateServerHibernation_send = function _SyncedStateServerHibernation_send(ws, message) {
+    try {
+        ws.send(packMessage(message));
+    }
+    catch {
+        // Ignore send failures on closed sockets.
+    }
+}, _SyncedStateServerHibernation_sendError = function _SyncedStateServerHibernation_sendError(ws, message, id) {
+    __classPrivateFieldGet(this, _SyncedStateServerHibernation_instances, "m", _SyncedStateServerHibernation_send).call(this, ws, { kind: "error", message, id });
+};
+_SyncedStateServerHibernation_keyHandler = { value: null };
+_SyncedStateServerHibernation_roomHandler = { value: null };
+_SyncedStateServerHibernation_setStateHandler = { value: null };
+_SyncedStateServerHibernation_getStateHandler = { value: null };
+_SyncedStateServerHibernation_subscribeHandler = { value: null };
+_SyncedStateServerHibernation_unsubscribeHandler = { value: null };
+_SyncedStateServerHibernation_namespace = { value: null };
+_SyncedStateServerHibernation_durableObjectName = { value: "syncedStateHibernation" };

package/dist/use-synced-state/__tests__/SyncedStateServerHibernation.test.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/use-synced-state/__tests__/SyncedStateServerHibernation.test.mjs

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("cloudflare:workers", () => {
+    class DurableObject {
+    }
+    return { DurableObject };
+});
+import { SyncedStateServerHibernation } from "../SyncedStateServerHibernation.mjs";
+import { packMessage } from "../protocol-hibernation.mjs";
+// Minimal WebSocket stub that supports the methods we use.
+function createWebSocketStub() {
+    const sent = [];
+    const ws = {
+        attachment: null,
+        send(data) {
+            sent.push(data);
+        },
+        addEventListener(_event, _handler) {
+            // not used in DO tests
+        },
+        serializeAttachment(value) {
+            this.attachment = value;
+        },
+        deserializeAttachment() {
+            return this.attachment;
+        },
+        close() { },
+        _sent: sent,
+    };
+    return ws;
+}
+describe("SyncedStateServerHibernation", () => {
+    afterEach(() => {
+        SyncedStateServerHibernation.registerKeyHandler(null);
+        SyncedStateServerHibernation.registerRoomHandler(null);
+        SyncedStateServerHibernation.registerSetStateHandler(null);
+        SyncedStateServerHibernation.registerGetStateHandler(null);
+        SyncedStateServerHibernation.registerSubscribeHandler(null);
+        SyncedStateServerHibernation.registerUnsubscribeHandler(null);
+    });
+    it("stores and retrieves state by storageKey", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, packMessage({ kind: "setState", key: "counter", storageKey: "user:123:counter", value: 5, id: "1" }));
+        coordinator.webSocketMessage(ws, packMessage({ kind: "getState", key: "counter", storageKey: "user:123:counter", id: "2" }));
+        expect(ws._sent).toHaveLength(2);
+        const response = JSON.parse(ws._sent[1]);
+        expect(response).toMatchObject({ v: 1, kind: "getState", key: "counter", value: 5, id: "2" });
+    });
+    it("notifies subscribers when state changes", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, packMessage({ kind: "subscribe", key: "counter", storageKey: "counter", id: "1" }));
+        coordinator.webSocketMessage(ws, packMessage({ kind: "setState", key: "counter", storageKey: "counter", value: 7, id: "2" }));
+        const messages = ws._sent.map((m) => JSON.parse(m));
+        expect(messages).toContainEqual({ v: 1, kind: "update", key: "counter", value: 7 });
+    });
+    it("keeps transformed and user-facing keys isolated", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, packMessage({ kind: "setState", key: "counter", storageKey: "user:123:counter", value: 9, id: "1" }));
+        coordinator.webSocketMessage(ws, packMessage({ kind: "getState", key: "counter", id: "2" }));
+        const response = JSON.parse(ws._sent[1]);
+        expect(response.value).toBeUndefined();
+    });
+    it("invokes registered setState handler", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        coordinator.setStub({});
+        const calls = [];
+        SyncedStateServerHibernation.registerSetStateHandler((key, value) => {
+            calls.push({ key, value });
+        });
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, packMessage({ kind: "setState", key: "x", storageKey: "transformed:x", value: 1, id: "1" }));
+        expect(calls).toEqual([{ key: "transformed:x", value: 1 }]);
+    });
+    it("rehydrates subscriptions after simulated hibernation", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, packMessage({ kind: "subscribe", key: "counter", storageKey: "user:123:counter", id: "1" }));
+        // Simulate hibernation by clearing the in-memory subscription map.
+        coordinator["#subscriptions"]?.clear?.();
+        // A setState message should still trigger an update because the attachment
+        // is rehydrated when the message handler runs.
+        coordinator.webSocketMessage(ws, packMessage({ kind: "setState", key: "counter", storageKey: "user:123:counter", value: 42, id: "2" }));
+        const messages = ws._sent.map((m) => JSON.parse(m));
+        expect(messages).toContainEqual({ v: 1, kind: "update", key: "counter", value: 42 });
+    });
+    it("rejects unsupported protocol versions", () => {
+        const coordinator = new SyncedStateServerHibernation({}, {});
+        const ws = createWebSocketStub();
+        coordinator.webSocketMessage(ws, JSON.stringify({ v: 99, kind: "getState", key: "counter", id: "1" }));
+        const messages = ws._sent.map((m) => JSON.parse(m));
+        expect(messages).toHaveLength(1);
+        expect(messages[0]).toMatchObject({ v: 1, kind: "error" });
+        expect(messages[0].message).toContain("Unsupported hibernation protocol version");
+    });
+});

package/dist/use-synced-state/__tests__/client-core.test.js

@@ -279,6 +279,30 @@ describe("client-core reconnection", () => {
             expect(sharedCallback).toHaveBeenCalledWith("disconnected");
             unsubB();
         });
+        it("duplicates active subscriptions on every reconnect", async () => {
+            const client = getSyncedStateClient(ENDPOINT);
+            const handler = vi.fn();
+            await client.subscribe("counter", handler);
+            expect(__testing.activeSubscriptions.size).toBe(1);
+            // First reconnect
+            mockClients[0].simulateBreak();
+            vi.runOnlyPendingTimers();
+            await __testing.warmUp(ENDPOINT);
+            await vi.runAllTimersAsync();
+            // Second reconnect
+            mockClients[1].simulateBreak();
+            vi.runOnlyPendingTimers();
+            await __testing.warmUp(ENDPOINT);
+            await vi.runAllTimersAsync();
+            // Third reconnect
+            mockClients[2].simulateBreak();
+            vi.runOnlyPendingTimers();
+            await __testing.warmUp(ENDPOINT);
+            await vi.runAllTimersAsync();
+            // Should remain exactly one subscription per logical subscription.
+            // Buggy implementation doubles the set on every reconnect.
+            expect(__testing.activeSubscriptions.size).toBe(1);
+        });
         it("BUG: reconnect emits 'connected' and resets backoff even when subscribe() rejects", async () => {
             const client = getSyncedStateClient(ENDPOINT);
             const handler = vi.fn();

package/dist/use-synced-state/client-core-hibernation.d.ts

@@ -0,0 +1,61 @@
+export type SyncedStateStatus = "connected" | "disconnected" | "reconnecting";
+export type StatusChangeCallback = (status: SyncedStateStatus) => void;
+export type SyncedStateClient = {
+    getState(key: string): Promise<unknown>;
+    setState(value: unknown, key: string): Promise<void>;
+    subscribe(key: string, handler: (value: unknown) => void): Promise<void>;
+    unsubscribe(key: string, handler: (value: unknown) => void): Promise<void>;
+};
+type PendingRequest = {
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+};
+type Connection = {
+    ws: WebSocket;
+    nextId: number;
+    pending: Map<string, PendingRequest>;
+    isOpen: boolean;
+    subscribedKeys: Set<string>;
+    messageHandlers: Map<string, Set<(value: unknown) => void>>;
+};
+type Subscription = {
+    key: string;
+    handler: (value: unknown) => void;
+    client: SyncedStateClient;
+};
+/**
+ * Registers a callback that fires when the connection status changes for an endpoint.
+ * Returns an unsubscribe function.
+ */
+export declare const onStatusChange: (endpoint: string, callback: StatusChangeCallback) => (() => void);
+declare function getBackoffMs(attempt: number): number;
+/**
+ * Returns a cached client for the provided endpoint, creating it when necessary.
+ * The returned client is a thin wrapper around a raw WebSocket that speaks the
+ * hibernation JSON protocol.
+ */
+export declare const getSyncedStateClient: (endpoint?: string) => SyncedStateClient;
+/**
+ * Initializes and caches an RPC client instance for the sync state endpoint.
+ * The client is wrapped to track subscriptions for cleanup on page unload.
+ */
+export declare const initSyncedStateClient: (options?: {
+    endpoint?: string;
+}) => SyncedStateClient | null;
+/**
+ * Injects a client instance for tests and updates the cached endpoint.
+ * Also clears the subscription registry for test isolation.
+ */
+export declare const setSyncedStateClientForTesting: (client: SyncedStateClient | null, endpoint?: string) => void;
+export declare const __testing: {
+    activeSubscriptions: Set<Subscription>;
+    clientCache: Map<string, SyncedStateClient>;
+    backoffState: Map<string, {
+        attempt: number;
+        timer: ReturnType<typeof setTimeout> | null;
+    }>;
+    statusListeners: Map<string, StatusChangeCallback[]>;
+    connectionByEndpoint: Map<string, Connection>;
+    getBackoffMs: typeof getBackoffMs;
+};
+export {};