@fieldnotes/sync-redis 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Irakli Iremashvili
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Irakli Iremashvili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -66,6 +66,79 @@ new RedisHubBackend(client, { keyPrefix: 'myapp:room:' });
 Persistence and shared state work with any number of relay instances — every instance reads and writes the
 same Redis, so room state survives restarts and is visible to all of them.
 
-However, for clients connected to **different** relay instances to see each other's **live** ops, you also
-need cross-instance fan-out (Redis pub/sub) — a planned follow-up. A **single** relay instance is fully live
-today.
+For clients connected to **different** relay instances to see each other's **live** ops, you also need
+cross-instance fan-out (Redis pub/sub) — available via `RedisHubFanout` (below). A **single** relay instance
+is fully live on its own.
+
+## Cross-instance fan-out (`RedisHubFanout`)
+
+`RedisHubFanout` is a `HubFanout` (from `@fieldnotes/sync-server`) over Redis pub/sub: each relay instance
+publishes its live ops to a single channel and every other instance forwards them to its local connections.
+Like the backend, it has **no Redis dependency of its own** — you inject two connections via the
+`RedisPublisher` / `RedisSubscriber` seams.
+
+> **The subscriber MUST be a dedicated connection.** Redis forbids any other command on a connection that is
+> in subscribe mode, so publish and subscribe cannot share one connection — that is why `RedisHubFanout`
+> takes two.
+
+### node-redis v4
+
+```ts
+import { createClient } from 'redis';
+import { createSyncServer } from '@fieldnotes/sync-server';
+import { RedisHubBackend, RedisHubFanout } from '@fieldnotes/sync-redis';
+
+const hash = createClient({ url: process.env.REDIS_URL });
+await hash.connect(); // HASH backend (persistence)
+
+const publisher = createClient({ url: process.env.REDIS_URL });
+await publisher.connect();
+const subscriber = publisher.duplicate();
+await subscriber.connect(); // DEDICATED subscriber — a subscriber connection cannot also publish
+
+createSyncServer({
+  port: 8080,
+  backend: new RedisHubBackend(hash),
+  fanout: new RedisHubFanout(publisher, subscriber),
+});
+```
+
+### ioredis
+
+ioredis lowercases `publish`/`subscribe` and delivers messages via a `'message'` event, so wrap each client:
+
+```ts
+import Redis from 'ioredis';
+import { RedisHubFanout } from '@fieldnotes/sync-redis';
+
+const pubIo = new Redis(process.env.REDIS_URL); // publish connection
+const subIo = new Redis(process.env.REDIS_URL); // SECOND, dedicated subscriber connection
+
+const publisher = { publish: (c: string, m: string) => pubIo.publish(c, m) };
+const subscriber = {
+  subscribe: (channel: string, listener: (m: string) => void) => {
+    subIo.on('message', (ch, msg) => {
+      if (ch === channel) listener(msg);
+    });
+    return subIo.subscribe(channel);
+  },
+};
+
+const fanout = new RedisHubFanout(publisher, subscriber);
+```
+
+### Channel
+
+All instances must share one channel (default `fieldnotes:fanout`, configurable):
+
+```ts
+new RedisHubFanout(publisher, subscriber, { channel: 'myapp:fanout' });
+```
+
+### Precondition: shared fanout AND shared backend
+
+Multi-instance **live** sync requires **both** a shared fanout **and** a shared backend (both Redis). The
+fanout forwards live ops; the shared backend keeps snapshots consistent. A shared fanout **without** a shared
+backend leaves a new joiner's snapshot stale — it would catch up from whichever instance it happened to hit,
+missing edits applied elsewhere. Pair `RedisHubFanout` with `RedisHubBackend` for full multi-instance
+real-time sync.

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  RedisHubBackend: () => RedisHubBackend
+  RedisHubBackend: () => RedisHubBackend,
+  RedisHubFanout: () => RedisHubFanout
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -58,8 +59,45 @@ var RedisHubBackend = class {
     else if (op.kind === "clear") await this.client.del(key);
   }
 };
+
+// src/redis-hub-fanout.ts
+var RedisHubFanout = class {
+  publisher;
+  subscriber;
+  channel;
+  onError;
+  handlers = /* @__PURE__ */ new Set();
+  subscribed = false;
+  constructor(publisher, subscriber, options = {}) {
+    this.publisher = publisher;
+    this.subscriber = subscriber;
+    this.channel = options.channel ?? "fieldnotes:fanout";
+    this.onError = options.onError ?? (() => void 0);
+  }
+  publish(payload) {
+    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);
+  }
+  subscribe(handler) {
+    this.handlers.add(handler);
+    if (!this.subscribed) {
+      this.subscribed = true;
+      Promise.resolve(
+        this.subscriber.subscribe(this.channel, (message) => {
+          for (const h of this.handlers) {
+            try {
+              h(message);
+            } catch {
+            }
+          }
+        })
+      ).catch(this.onError);
+    }
+    return () => this.handlers.delete(handler);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  RedisHubBackend
+  RedisHubBackend,
+  RedisHubFanout
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/redis-hub-backend.ts"],"sourcesContent":["export { RedisHubBackend } from './redis-hub-backend';\nexport type { RedisHubBackendOptions } from './redis-hub-backend';\nexport type { RedisHashClient } from './redis-hash-client';\n","import { isValidElement, type SyncOp } from '@fieldnotes/sync';\nimport type { CanvasElement } from '@fieldnotes/core';\nimport type { HubBackend } from '@fieldnotes/sync-server';\nimport type { RedisHashClient } from './redis-hash-client';\n\nexport interface RedisHubBackendOptions {\n  keyPrefix?: string; // default 'fieldnotes:room:'\n}\n\nexport class RedisHubBackend implements HubBackend {\n  private readonly client: RedisHashClient;\n  private readonly keyPrefix: string;\n\n  constructor(client: RedisHashClient, options: RedisHubBackendOptions = {}) {\n    this.client = client;\n    this.keyPrefix = options.keyPrefix ?? 'fieldnotes:room:';\n  }\n\n  private key(room: string): string {\n    return `${this.keyPrefix}${room}`;\n  }\n\n  async snapshot(room: string): Promise<CanvasElement[]> {\n    const map = await this.client.hGetAll(this.key(room));\n    const out: CanvasElement[] = [];\n    for (const value of Object.values(map)) {\n      let parsed: unknown;\n      try {\n        parsed = JSON.parse(value);\n      } catch {\n        continue; // skip a corrupt stored value rather than throwing the whole snapshot\n      }\n      if (isValidElement(parsed)) out.push(parsed);\n    }\n    return out;\n  }\n\n  async apply(room: string, op: SyncOp): Promise<void> {\n    const key = this.key(room);\n    if (op.kind === 'upsert')\n      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));\n    else if (op.kind === 'remove') await this.client.hDel(key, op.id);\n    else if (op.kind === 'clear') await this.client.del(key);\n    // request-snapshot/snapshot never reach apply (the hub only applies data ops)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA4C;AASrC,IAAM,kBAAN,MAA4C;AAAA,EAChC;AAAA,EACA;AAAA,EAEjB,YAAY,QAAyB,UAAkC,CAAC,GAAG;AACzE,SAAK,SAAS;AACd,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AAAA,EAEQ,IAAI,MAAsB;AAChC,WAAO,GAAG,KAAK,SAAS,GAAG,IAAI;AAAA,EACjC;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,UAAM,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK,IAAI,IAAI,CAAC;AACpD,UAAM,MAAuB,CAAC;AAC9B,eAAW,SAAS,OAAO,OAAO,GAAG,GAAG;AACtC,UAAI;AACJ,UAAI;AACF,iBAAS,KAAK,MAAM,KAAK;AAAA,MAC3B,QAAQ;AACN;AAAA,MACF;AACA,cAAI,4BAAe,MAAM,EAAG,KAAI,KAAK,MAAM;AAAA,IAC7C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,UAAM,MAAM,KAAK,IAAI,IAAI;AACzB,QAAI,GAAG,SAAS;AACd,YAAM,KAAK,OAAO,KAAK,KAAK,GAAG,QAAQ,IAAI,KAAK,UAAU,GAAG,OAAO,CAAC;AAAA,aAC9D,GAAG,SAAS,SAAU,OAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE;AAAA,aACvD,GAAG,SAAS,QAAS,OAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EAEzD;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/redis-hub-backend.ts","../src/redis-hub-fanout.ts"],"sourcesContent":["export { RedisHubBackend } from './redis-hub-backend';\nexport type { RedisHubBackendOptions } from './redis-hub-backend';\nexport type { RedisHashClient } from './redis-hash-client';\nexport { RedisHubFanout } from './redis-hub-fanout';\nexport type { RedisHubFanoutOptions } from './redis-hub-fanout';\nexport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\n","import { isValidElement, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from '@fieldnotes/sync-server';\r\nimport type { RedisHashClient } from './redis-hash-client';\r\n\r\nexport interface RedisHubBackendOptions {\r\n  keyPrefix?: string; // default 'fieldnotes:room:'\r\n}\r\n\r\nexport class RedisHubBackend implements HubBackend {\r\n  private readonly client: RedisHashClient;\r\n  private readonly keyPrefix: string;\r\n\r\n  constructor(client: RedisHashClient, options: RedisHubBackendOptions = {}) {\r\n    this.client = client;\r\n    this.keyPrefix = options.keyPrefix ?? 'fieldnotes:room:';\r\n  }\r\n\r\n  private key(room: string): string {\r\n    return `${this.keyPrefix}${room}`;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    const map = await this.client.hGetAll(this.key(room));\r\n    const out: CanvasElement[] = [];\r\n    for (const value of Object.values(map)) {\r\n      let parsed: unknown;\r\n      try {\r\n        parsed = JSON.parse(value);\r\n      } catch {\r\n        continue; // skip a corrupt stored value rather than throwing the whole snapshot\r\n      }\r\n      if (isValidElement(parsed)) out.push(parsed);\r\n    }\r\n    return out;\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    const key = this.key(room);\r\n    if (op.kind === 'upsert')\r\n      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));\r\n    else if (op.kind === 'remove') await this.client.hDel(key, op.id);\r\n    else if (op.kind === 'clear') await this.client.del(key);\r\n    // request-snapshot/snapshot never reach apply (the hub only applies data ops)\r\n  }\r\n}\r\n","import type { HubFanout } from '@fieldnotes/sync-server';\nimport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\n\nexport interface RedisHubFanoutOptions {\n  channel?: string;\n  onError?: (err: unknown) => void;\n}\n\nexport class RedisHubFanout implements HubFanout {\n  private readonly publisher: RedisPublisher;\n  private readonly subscriber: RedisSubscriber;\n  private readonly channel: string;\n  private readonly onError: (err: unknown) => void;\n  private readonly handlers = new Set<(payload: string) => void>();\n  private subscribed = false;\n\n  constructor(\n    publisher: RedisPublisher,\n    subscriber: RedisSubscriber,\n    options: RedisHubFanoutOptions = {},\n  ) {\n    this.publisher = publisher;\n    this.subscriber = subscriber;\n    this.channel = options.channel ?? 'fieldnotes:fanout';\n    this.onError = options.onError ?? (() => undefined);\n  }\n\n  publish(payload: string): void {\n    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);\n  }\n\n  subscribe(handler: (payload: string) => void): () => void {\n    this.handlers.add(handler);\n    if (!this.subscribed) {\n      this.subscribed = true;\n      Promise.resolve(\n        this.subscriber.subscribe(this.channel, (message) => {\n          for (const h of this.handlers) {\n            try {\n              h(message);\n            } catch {\n              /* isolate handlers */\n            }\n          }\n        }),\n      ).catch(this.onError);\n    }\n    return () => this.handlers.delete(handler);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA4C;AASrC,IAAM,kBAAN,MAA4C;AAAA,EAChC;AAAA,EACA;AAAA,EAEjB,YAAY,QAAyB,UAAkC,CAAC,GAAG;AACzE,SAAK,SAAS;AACd,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AAAA,EAEQ,IAAI,MAAsB;AAChC,WAAO,GAAG,KAAK,SAAS,GAAG,IAAI;AAAA,EACjC;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,UAAM,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK,IAAI,IAAI,CAAC;AACpD,UAAM,MAAuB,CAAC;AAC9B,eAAW,SAAS,OAAO,OAAO,GAAG,GAAG;AACtC,UAAI;AACJ,UAAI;AACF,iBAAS,KAAK,MAAM,KAAK;AAAA,MAC3B,QAAQ;AACN;AAAA,MACF;AACA,cAAI,4BAAe,MAAM,EAAG,KAAI,KAAK,MAAM;AAAA,IAC7C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,UAAM,MAAM,KAAK,IAAI,IAAI;AACzB,QAAI,GAAG,SAAS;AACd,YAAM,KAAK,OAAO,KAAK,KAAK,GAAG,QAAQ,IAAI,KAAK,UAAU,GAAG,OAAO,CAAC;AAAA,aAC9D,GAAG,SAAS,SAAU,OAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE;AAAA,aACvD,GAAG,SAAS,QAAS,OAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EAEzD;AACF;;;ACrCO,IAAM,iBAAN,MAA0C;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW,oBAAI,IAA+B;AAAA,EACvD,aAAa;AAAA,EAErB,YACE,WACA,YACA,UAAiC,CAAC,GAClC;AACA,SAAK,YAAY;AACjB,SAAK,aAAa;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,UAAU,QAAQ,YAAY,MAAM;AAAA,EAC3C;AAAA,EAEA,QAAQ,SAAuB;AAC7B,YAAQ,QAAQ,KAAK,UAAU,QAAQ,KAAK,SAAS,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO;AAAA,EACnF;AAAA,EAEA,UAAU,SAAgD;AACxD,SAAK,SAAS,IAAI,OAAO;AACzB,QAAI,CAAC,KAAK,YAAY;AACpB,WAAK,aAAa;AAClB,cAAQ;AAAA,QACN,KAAK,WAAW,UAAU,KAAK,SAAS,CAAC,YAAY;AACnD,qBAAW,KAAK,KAAK,UAAU;AAC7B,gBAAI;AACF,gBAAE,OAAO;AAAA,YACX,QAAQ;AAAA,YAER;AAAA,UACF;AAAA,QACF,CAAC;AAAA,MACH,EAAE,MAAM,KAAK,OAAO;AAAA,IACtB;AACA,WAAO,MAAM,KAAK,SAAS,OAAO,OAAO;AAAA,EAC3C;AACF;","names":[]}

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { SyncOp } from '@fieldnotes/sync';
 import { CanvasElement } from '@fieldnotes/core';
-import { HubBackend } from '@fieldnotes/sync-server';
+import { HubBackend, HubFanout } from '@fieldnotes/sync-server';
 
 interface RedisHashClient {
     hGetAll(key: string): Promise<Record<string, string>>;
@@ -21,4 +21,27 @@ declare class RedisHubBackend implements HubBackend {
     apply(room: string, op: SyncOp): Promise<void>;
 }
 
-export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions };
+interface RedisPublisher {
+    publish(channel: string, message: string): Promise<unknown> | unknown;
+}
+interface RedisSubscriber {
+    subscribe(channel: string, listener: (message: string) => void): Promise<unknown> | unknown;
+}
+
+interface RedisHubFanoutOptions {
+    channel?: string;
+    onError?: (err: unknown) => void;
+}
+declare class RedisHubFanout implements HubFanout {
+    private readonly publisher;
+    private readonly subscriber;
+    private readonly channel;
+    private readonly onError;
+    private readonly handlers;
+    private subscribed;
+    constructor(publisher: RedisPublisher, subscriber: RedisSubscriber, options?: RedisHubFanoutOptions);
+    publish(payload: string): void;
+    subscribe(handler: (payload: string) => void): () => void;
+}
+
+export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions, RedisHubFanout, type RedisHubFanoutOptions, type RedisPublisher, type RedisSubscriber };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { SyncOp } from '@fieldnotes/sync';
 import { CanvasElement } from '@fieldnotes/core';
-import { HubBackend } from '@fieldnotes/sync-server';
+import { HubBackend, HubFanout } from '@fieldnotes/sync-server';
 
 interface RedisHashClient {
     hGetAll(key: string): Promise<Record<string, string>>;
@@ -21,4 +21,27 @@ declare class RedisHubBackend implements HubBackend {
     apply(room: string, op: SyncOp): Promise<void>;
 }
 
-export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions };
+interface RedisPublisher {
+    publish(channel: string, message: string): Promise<unknown> | unknown;
+}
+interface RedisSubscriber {
+    subscribe(channel: string, listener: (message: string) => void): Promise<unknown> | unknown;
+}
+
+interface RedisHubFanoutOptions {
+    channel?: string;
+    onError?: (err: unknown) => void;
+}
+declare class RedisHubFanout implements HubFanout {
+    private readonly publisher;
+    private readonly subscriber;
+    private readonly channel;
+    private readonly onError;
+    private readonly handlers;
+    private subscribed;
+    constructor(publisher: RedisPublisher, subscriber: RedisSubscriber, options?: RedisHubFanoutOptions);
+    publish(payload: string): void;
+    subscribe(handler: (payload: string) => void): () => void;
+}
+
+export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions, RedisHubFanout, type RedisHubFanoutOptions, type RedisPublisher, type RedisSubscriber };

package/dist/index.js

@@ -32,7 +32,44 @@ var RedisHubBackend = class {
     else if (op.kind === "clear") await this.client.del(key);
   }
 };
+
+// src/redis-hub-fanout.ts
+var RedisHubFanout = class {
+  publisher;
+  subscriber;
+  channel;
+  onError;
+  handlers = /* @__PURE__ */ new Set();
+  subscribed = false;
+  constructor(publisher, subscriber, options = {}) {
+    this.publisher = publisher;
+    this.subscriber = subscriber;
+    this.channel = options.channel ?? "fieldnotes:fanout";
+    this.onError = options.onError ?? (() => void 0);
+  }
+  publish(payload) {
+    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);
+  }
+  subscribe(handler) {
+    this.handlers.add(handler);
+    if (!this.subscribed) {
+      this.subscribed = true;
+      Promise.resolve(
+        this.subscriber.subscribe(this.channel, (message) => {
+          for (const h of this.handlers) {
+            try {
+              h(message);
+            } catch {
+            }
+          }
+        })
+      ).catch(this.onError);
+    }
+    return () => this.handlers.delete(handler);
+  }
+};
 export {
-  RedisHubBackend
+  RedisHubBackend,
+  RedisHubFanout
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/redis-hub-backend.ts"],"sourcesContent":["import { isValidElement, type SyncOp } from '@fieldnotes/sync';\nimport type { CanvasElement } from '@fieldnotes/core';\nimport type { HubBackend } from '@fieldnotes/sync-server';\nimport type { RedisHashClient } from './redis-hash-client';\n\nexport interface RedisHubBackendOptions {\n  keyPrefix?: string; // default 'fieldnotes:room:'\n}\n\nexport class RedisHubBackend implements HubBackend {\n  private readonly client: RedisHashClient;\n  private readonly keyPrefix: string;\n\n  constructor(client: RedisHashClient, options: RedisHubBackendOptions = {}) {\n    this.client = client;\n    this.keyPrefix = options.keyPrefix ?? 'fieldnotes:room:';\n  }\n\n  private key(room: string): string {\n    return `${this.keyPrefix}${room}`;\n  }\n\n  async snapshot(room: string): Promise<CanvasElement[]> {\n    const map = await this.client.hGetAll(this.key(room));\n    const out: CanvasElement[] = [];\n    for (const value of Object.values(map)) {\n      let parsed: unknown;\n      try {\n        parsed = JSON.parse(value);\n      } catch {\n        continue; // skip a corrupt stored value rather than throwing the whole snapshot\n      }\n      if (isValidElement(parsed)) out.push(parsed);\n    }\n    return out;\n  }\n\n  async apply(room: string, op: SyncOp): Promise<void> {\n    const key = this.key(room);\n    if (op.kind === 'upsert')\n      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));\n    else if (op.kind === 'remove') await this.client.hDel(key, op.id);\n    else if (op.kind === 'clear') await this.client.del(key);\n    // request-snapshot/snapshot never reach apply (the hub only applies data ops)\n  }\n}\n"],"mappings":";AAAA,SAAS,sBAAmC;AASrC,IAAM,kBAAN,MAA4C;AAAA,EAChC;AAAA,EACA;AAAA,EAEjB,YAAY,QAAyB,UAAkC,CAAC,GAAG;AACzE,SAAK,SAAS;AACd,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AAAA,EAEQ,IAAI,MAAsB;AAChC,WAAO,GAAG,KAAK,SAAS,GAAG,IAAI;AAAA,EACjC;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,UAAM,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK,IAAI,IAAI,CAAC;AACpD,UAAM,MAAuB,CAAC;AAC9B,eAAW,SAAS,OAAO,OAAO,GAAG,GAAG;AACtC,UAAI;AACJ,UAAI;AACF,iBAAS,KAAK,MAAM,KAAK;AAAA,MAC3B,QAAQ;AACN;AAAA,MACF;AACA,UAAI,eAAe,MAAM,EAAG,KAAI,KAAK,MAAM;AAAA,IAC7C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,UAAM,MAAM,KAAK,IAAI,IAAI;AACzB,QAAI,GAAG,SAAS;AACd,YAAM,KAAK,OAAO,KAAK,KAAK,GAAG,QAAQ,IAAI,KAAK,UAAU,GAAG,OAAO,CAAC;AAAA,aAC9D,GAAG,SAAS,SAAU,OAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE;AAAA,aACvD,GAAG,SAAS,QAAS,OAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EAEzD;AACF;","names":[]}
+{"version":3,"sources":["../src/redis-hub-backend.ts","../src/redis-hub-fanout.ts"],"sourcesContent":["import { isValidElement, type SyncOp } from '@fieldnotes/sync';\r\nimport type { CanvasElement } from '@fieldnotes/core';\r\nimport type { HubBackend } from '@fieldnotes/sync-server';\r\nimport type { RedisHashClient } from './redis-hash-client';\r\n\r\nexport interface RedisHubBackendOptions {\r\n  keyPrefix?: string; // default 'fieldnotes:room:'\r\n}\r\n\r\nexport class RedisHubBackend implements HubBackend {\r\n  private readonly client: RedisHashClient;\r\n  private readonly keyPrefix: string;\r\n\r\n  constructor(client: RedisHashClient, options: RedisHubBackendOptions = {}) {\r\n    this.client = client;\r\n    this.keyPrefix = options.keyPrefix ?? 'fieldnotes:room:';\r\n  }\r\n\r\n  private key(room: string): string {\r\n    return `${this.keyPrefix}${room}`;\r\n  }\r\n\r\n  async snapshot(room: string): Promise<CanvasElement[]> {\r\n    const map = await this.client.hGetAll(this.key(room));\r\n    const out: CanvasElement[] = [];\r\n    for (const value of Object.values(map)) {\r\n      let parsed: unknown;\r\n      try {\r\n        parsed = JSON.parse(value);\r\n      } catch {\r\n        continue; // skip a corrupt stored value rather than throwing the whole snapshot\r\n      }\r\n      if (isValidElement(parsed)) out.push(parsed);\r\n    }\r\n    return out;\r\n  }\r\n\r\n  async apply(room: string, op: SyncOp): Promise<void> {\r\n    const key = this.key(room);\r\n    if (op.kind === 'upsert')\r\n      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));\r\n    else if (op.kind === 'remove') await this.client.hDel(key, op.id);\r\n    else if (op.kind === 'clear') await this.client.del(key);\r\n    // request-snapshot/snapshot never reach apply (the hub only applies data ops)\r\n  }\r\n}\r\n","import type { HubFanout } from '@fieldnotes/sync-server';\nimport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\n\nexport interface RedisHubFanoutOptions {\n  channel?: string;\n  onError?: (err: unknown) => void;\n}\n\nexport class RedisHubFanout implements HubFanout {\n  private readonly publisher: RedisPublisher;\n  private readonly subscriber: RedisSubscriber;\n  private readonly channel: string;\n  private readonly onError: (err: unknown) => void;\n  private readonly handlers = new Set<(payload: string) => void>();\n  private subscribed = false;\n\n  constructor(\n    publisher: RedisPublisher,\n    subscriber: RedisSubscriber,\n    options: RedisHubFanoutOptions = {},\n  ) {\n    this.publisher = publisher;\n    this.subscriber = subscriber;\n    this.channel = options.channel ?? 'fieldnotes:fanout';\n    this.onError = options.onError ?? (() => undefined);\n  }\n\n  publish(payload: string): void {\n    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);\n  }\n\n  subscribe(handler: (payload: string) => void): () => void {\n    this.handlers.add(handler);\n    if (!this.subscribed) {\n      this.subscribed = true;\n      Promise.resolve(\n        this.subscriber.subscribe(this.channel, (message) => {\n          for (const h of this.handlers) {\n            try {\n              h(message);\n            } catch {\n              /* isolate handlers */\n            }\n          }\n        }),\n      ).catch(this.onError);\n    }\n    return () => this.handlers.delete(handler);\n  }\n}\n"],"mappings":";AAAA,SAAS,sBAAmC;AASrC,IAAM,kBAAN,MAA4C;AAAA,EAChC;AAAA,EACA;AAAA,EAEjB,YAAY,QAAyB,UAAkC,CAAC,GAAG;AACzE,SAAK,SAAS;AACd,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AAAA,EAEQ,IAAI,MAAsB;AAChC,WAAO,GAAG,KAAK,SAAS,GAAG,IAAI;AAAA,EACjC;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,UAAM,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK,IAAI,IAAI,CAAC;AACpD,UAAM,MAAuB,CAAC;AAC9B,eAAW,SAAS,OAAO,OAAO,GAAG,GAAG;AACtC,UAAI;AACJ,UAAI;AACF,iBAAS,KAAK,MAAM,KAAK;AAAA,MAC3B,QAAQ;AACN;AAAA,MACF;AACA,UAAI,eAAe,MAAM,EAAG,KAAI,KAAK,MAAM;AAAA,IAC7C;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,UAAM,MAAM,KAAK,IAAI,IAAI;AACzB,QAAI,GAAG,SAAS;AACd,YAAM,KAAK,OAAO,KAAK,KAAK,GAAG,QAAQ,IAAI,KAAK,UAAU,GAAG,OAAO,CAAC;AAAA,aAC9D,GAAG,SAAS,SAAU,OAAM,KAAK,OAAO,KAAK,KAAK,GAAG,EAAE;AAAA,aACvD,GAAG,SAAS,QAAS,OAAM,KAAK,OAAO,IAAI,GAAG;AAAA,EAEzD;AACF;;;ACrCO,IAAM,iBAAN,MAA0C;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW,oBAAI,IAA+B;AAAA,EACvD,aAAa;AAAA,EAErB,YACE,WACA,YACA,UAAiC,CAAC,GAClC;AACA,SAAK,YAAY;AACjB,SAAK,aAAa;AAClB,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,UAAU,QAAQ,YAAY,MAAM;AAAA,EAC3C;AAAA,EAEA,QAAQ,SAAuB;AAC7B,YAAQ,QAAQ,KAAK,UAAU,QAAQ,KAAK,SAAS,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO;AAAA,EACnF;AAAA,EAEA,UAAU,SAAgD;AACxD,SAAK,SAAS,IAAI,OAAO;AACzB,QAAI,CAAC,KAAK,YAAY;AACpB,WAAK,aAAa;AAClB,cAAQ;AAAA,QACN,KAAK,WAAW,UAAU,KAAK,SAAS,CAAC,YAAY;AACnD,qBAAW,KAAK,KAAK,UAAU;AAC7B,gBAAI;AACF,gBAAE,OAAO;AAAA,YACX,QAAQ;AAAA,YAER;AAAA,UACF;AAAA,QACF,CAAC;AAAA,MACH,EAAE,MAAM,KAAK,OAAO;AAAA,IACtB;AACA,WAAO,MAAM,KAAK,SAAS,OAAO,OAAO;AAAA,EAC3C;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fieldnotes/sync-redis",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Redis-backed HubBackend for Field Notes real-time sync relay",
   "type": "module",
   "sideEffects": false,
@@ -42,8 +42,8 @@
     "@vitest/coverage-v8": "^4.1.0",
     "tsup": "^8.5.1",
     "vitest": "^4.1.0",
-    "@fieldnotes/core": "0.46.0",
-    "@fieldnotes/sync-server": "0.1.0"
+    "@fieldnotes/sync-server": "0.2.0",
+    "@fieldnotes/core": "0.46.0"
   },
   "scripts": {
     "build": "tsup",