@fieldnotes/sync-redis 0.2.0 → 0.3.1

package/README.md

@@ -1,144 +1,148 @@
-# @fieldnotes/sync-redis
-
-A `HubBackend` that persists Field Notes relay room state in Redis — state survives relay restarts and is
-shared across relay instances.
-
-## Install
-
-```bash
-pnpm add @fieldnotes/sync-redis
-# plus your Redis client of choice, e.g.:
-pnpm add redis        # node-redis v4
-# or
-pnpm add ioredis
-```
-
-`@fieldnotes/sync-redis` has **no Redis dependency of its own** — you inject a client that satisfies a
-minimal `RedisHashClient` interface (`hGetAll` / `hSet` / `hDel` / `del`).
-
-## node-redis v4 (direct)
-
-node-redis v4's client already matches `RedisHashClient`, so you can pass it straight through:
-
-```ts
-import { createClient } from 'redis';
-import { createSyncServer } from '@fieldnotes/sync-server';
-import { RedisHubBackend } from '@fieldnotes/sync-redis';
-
-const client = createClient({ url: process.env.REDIS_URL });
-await client.connect();
-createSyncServer({ port: 8080, backend: new RedisHubBackend(client) });
-```
-
-## ioredis (shim)
-
-ioredis uses lowercased method names, so wrap it in a small adapter:
-
-```ts
-import Redis from 'ioredis';
-import { RedisHubBackend } from '@fieldnotes/sync-redis';
-
-const io = new Redis(process.env.REDIS_URL);
-const client = {
-  hGetAll: (k: string) => io.hgetall(k),
-  hSet: (k: string, f: string, v: string) => io.hset(k, f, v),
-  hDel: (k: string, f: string) => io.hdel(k, f),
-  del: (k: string) => io.del(k),
-};
-const backend = new RedisHubBackend(client);
-```
-
-## Key schema
-
-Each room is stored as a Redis **HASH** at `{keyPrefix}{room}` (default prefix `fieldnotes:room:`):
-
-- **field** = element id
-- **value** = `JSON.stringify(element)`
-
-The prefix is configurable:
-
-```ts
-new RedisHubBackend(client, { keyPrefix: 'myapp:room:' });
-```
-
-## Single vs. multiple relay instances
-
-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.
-
-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.
+# @fieldnotes/sync-redis
+
+A `HubBackend` that persists Field Notes relay room state in Redis — state survives relay restarts and is
+shared across relay instances.
+
+## Install
+
+```bash
+pnpm add @fieldnotes/sync-redis
+# plus your Redis client of choice, e.g.:
+pnpm add redis        # node-redis v4
+# or
+pnpm add ioredis
+```
+
+`@fieldnotes/sync-redis` has **no Redis dependency of its own** — you inject a client that satisfies a
+minimal `RedisHashClient` interface (`hGetAll` / `hGet` / `hSet` / `hDel` / `del`).
+
+## node-redis v4 (direct)
+
+node-redis v4's client already matches `RedisHashClient`, so you can pass it straight through:
+
+```ts
+import { createClient } from 'redis';
+import { createSyncServer } from '@fieldnotes/sync-server';
+import { RedisHubBackend } from '@fieldnotes/sync-redis';
+
+const client = createClient({ url: process.env.REDIS_URL });
+await client.connect();
+createSyncServer({ port: 8080, backend: new RedisHubBackend(client) });
+```
+
+## ioredis (shim)
+
+ioredis uses lowercased method names, so wrap it in a small adapter:
+
+```ts
+import Redis from 'ioredis';
+import { RedisHubBackend } from '@fieldnotes/sync-redis';
+
+const io = new Redis(process.env.REDIS_URL);
+const client = {
+  hGetAll: (k: string) => io.hgetall(k),
+  hGet: (k: string, f: string) => io.hget(k, f),
+  hSet: (k: string, f: string, v: string) => io.hset(k, f, v),
+  hDel: (k: string, f: string) => io.hdel(k, f),
+  del: (k: string) => io.del(k),
+};
+const backend = new RedisHubBackend(client);
+```
+
+## Key schema
+
+Each room is stored as a Redis **HASH** at `{keyPrefix}{room}` (default prefix `fieldnotes:room:`):
+
+- **field** = element id
+- **value** = `JSON.stringify(element)`
+
+node-redis v4 conforms to `RedisHashClient` directly (it has `hGet`); `RedisHubBackend.get(room, id)`
+(via `HGET`) powers the relay's ownership lookups for write authorization (D2).
+
+The prefix is configurable:
+
+```ts
+new RedisHubBackend(client, { keyPrefix: 'myapp:room:' });
+```
+
+## Single vs. multiple relay instances
+
+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.
+
+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

@@ -51,6 +51,16 @@ var RedisHubBackend = class {
     }
     return out;
   }
+  async get(room, id) {
+    const value = await this.client.hGet(this.key(room), id);
+    if (value == null) return void 0;
+    try {
+      const parsed = JSON.parse(value);
+      return (0, import_sync.isValidElement)(parsed) ? parsed : void 0;
+    } catch {
+      return void 0;
+    }
+  }
   async apply(room, op) {
     const key = this.key(room);
     if (op.kind === "upsert")

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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":[]}
+{"version":3,"sources":["../src/index.ts","../src/redis-hub-backend.ts","../src/redis-hub-fanout.ts"],"sourcesContent":["export { RedisHubBackend } from './redis-hub-backend';\r\nexport type { RedisHubBackendOptions } from './redis-hub-backend';\r\nexport type { RedisHashClient } from './redis-hash-client';\r\nexport { RedisHubFanout } from './redis-hub-fanout';\r\nexport type { RedisHubFanoutOptions } from './redis-hub-fanout';\r\nexport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\r\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 get(room: string, id: string): Promise<CanvasElement | undefined> {\r\n    const value = await this.client.hGet(this.key(room), id);\r\n    if (value == null) return undefined;\r\n    try {\r\n      const parsed: unknown = JSON.parse(value);\r\n      return isValidElement(parsed) ? parsed : undefined;\r\n    } catch {\r\n      return undefined;\r\n    }\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';\r\nimport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\r\n\r\nexport interface RedisHubFanoutOptions {\r\n  channel?: string;\r\n  onError?: (err: unknown) => void;\r\n}\r\n\r\nexport class RedisHubFanout implements HubFanout {\r\n  private readonly publisher: RedisPublisher;\r\n  private readonly subscriber: RedisSubscriber;\r\n  private readonly channel: string;\r\n  private readonly onError: (err: unknown) => void;\r\n  private readonly handlers = new Set<(payload: string) => void>();\r\n  private subscribed = false;\r\n\r\n  constructor(\r\n    publisher: RedisPublisher,\r\n    subscriber: RedisSubscriber,\r\n    options: RedisHubFanoutOptions = {},\r\n  ) {\r\n    this.publisher = publisher;\r\n    this.subscriber = subscriber;\r\n    this.channel = options.channel ?? 'fieldnotes:fanout';\r\n    this.onError = options.onError ?? (() => undefined);\r\n  }\r\n\r\n  publish(payload: string): void {\r\n    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);\r\n  }\r\n\r\n  subscribe(handler: (payload: string) => void): () => void {\r\n    this.handlers.add(handler);\r\n    if (!this.subscribed) {\r\n      this.subscribed = true;\r\n      Promise.resolve(\r\n        this.subscriber.subscribe(this.channel, (message) => {\r\n          for (const h of this.handlers) {\r\n            try {\r\n              h(message);\r\n            } catch {\r\n              /* isolate handlers */\r\n            }\r\n          }\r\n        }),\r\n      ).catch(this.onError);\r\n    }\r\n    return () => this.handlers.delete(handler);\r\n  }\r\n}\r\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,IAAI,MAAc,IAAgD;AACtE,UAAM,QAAQ,MAAM,KAAK,OAAO,KAAK,KAAK,IAAI,IAAI,GAAG,EAAE;AACvD,QAAI,SAAS,KAAM,QAAO;AAC1B,QAAI;AACF,YAAM,SAAkB,KAAK,MAAM,KAAK;AACxC,iBAAO,4BAAe,MAAM,IAAI,SAAS;AAAA,IAC3C,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;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;;;AChDO,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

@@ -4,6 +4,7 @@ import { HubBackend, HubFanout } from '@fieldnotes/sync-server';
 
 interface RedisHashClient {
     hGetAll(key: string): Promise<Record<string, string>>;
+    hGet(key: string, field: string): Promise<string | null>;
     hSet(key: string, field: string, value: string): Promise<unknown>;
     hDel(key: string, field: string): Promise<unknown>;
     del(key: string): Promise<unknown>;
@@ -18,6 +19,7 @@ declare class RedisHubBackend implements HubBackend {
     constructor(client: RedisHashClient, options?: RedisHubBackendOptions);
     private key;
     snapshot(room: string): Promise<CanvasElement[]>;
+    get(room: string, id: string): Promise<CanvasElement | undefined>;
     apply(room: string, op: SyncOp): Promise<void>;
 }
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { HubBackend, HubFanout } from '@fieldnotes/sync-server';
 
 interface RedisHashClient {
     hGetAll(key: string): Promise<Record<string, string>>;
+    hGet(key: string, field: string): Promise<string | null>;
     hSet(key: string, field: string, value: string): Promise<unknown>;
     hDel(key: string, field: string): Promise<unknown>;
     del(key: string): Promise<unknown>;
@@ -18,6 +19,7 @@ declare class RedisHubBackend implements HubBackend {
     constructor(client: RedisHashClient, options?: RedisHubBackendOptions);
     private key;
     snapshot(room: string): Promise<CanvasElement[]>;
+    get(room: string, id: string): Promise<CanvasElement | undefined>;
     apply(room: string, op: SyncOp): Promise<void>;
 }
 

package/dist/index.js

@@ -24,6 +24,16 @@ var RedisHubBackend = class {
     }
     return out;
   }
+  async get(room, id) {
+    const value = await this.client.hGet(this.key(room), id);
+    if (value == null) return void 0;
+    try {
+      const parsed = JSON.parse(value);
+      return isValidElement(parsed) ? parsed : void 0;
+    } catch {
+      return void 0;
+    }
+  }
   async apply(room, op) {
     const key = this.key(room);
     if (op.kind === "upsert")

package/dist/index.js.map

@@ -1 +1 @@
-{"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":[]}
+{"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 get(room: string, id: string): Promise<CanvasElement | undefined> {\r\n    const value = await this.client.hGet(this.key(room), id);\r\n    if (value == null) return undefined;\r\n    try {\r\n      const parsed: unknown = JSON.parse(value);\r\n      return isValidElement(parsed) ? parsed : undefined;\r\n    } catch {\r\n      return undefined;\r\n    }\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';\r\nimport type { RedisPublisher, RedisSubscriber } from './redis-fanout-client';\r\n\r\nexport interface RedisHubFanoutOptions {\r\n  channel?: string;\r\n  onError?: (err: unknown) => void;\r\n}\r\n\r\nexport class RedisHubFanout implements HubFanout {\r\n  private readonly publisher: RedisPublisher;\r\n  private readonly subscriber: RedisSubscriber;\r\n  private readonly channel: string;\r\n  private readonly onError: (err: unknown) => void;\r\n  private readonly handlers = new Set<(payload: string) => void>();\r\n  private subscribed = false;\r\n\r\n  constructor(\r\n    publisher: RedisPublisher,\r\n    subscriber: RedisSubscriber,\r\n    options: RedisHubFanoutOptions = {},\r\n  ) {\r\n    this.publisher = publisher;\r\n    this.subscriber = subscriber;\r\n    this.channel = options.channel ?? 'fieldnotes:fanout';\r\n    this.onError = options.onError ?? (() => undefined);\r\n  }\r\n\r\n  publish(payload: string): void {\r\n    Promise.resolve(this.publisher.publish(this.channel, payload)).catch(this.onError);\r\n  }\r\n\r\n  subscribe(handler: (payload: string) => void): () => void {\r\n    this.handlers.add(handler);\r\n    if (!this.subscribed) {\r\n      this.subscribed = true;\r\n      Promise.resolve(\r\n        this.subscriber.subscribe(this.channel, (message) => {\r\n          for (const h of this.handlers) {\r\n            try {\r\n              h(message);\r\n            } catch {\r\n              /* isolate handlers */\r\n            }\r\n          }\r\n        }),\r\n      ).catch(this.onError);\r\n    }\r\n    return () => this.handlers.delete(handler);\r\n  }\r\n}\r\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,IAAI,MAAc,IAAgD;AACtE,UAAM,QAAQ,MAAM,KAAK,OAAO,KAAK,KAAK,IAAI,IAAI,GAAG,EAAE;AACvD,QAAI,SAAS,KAAM,QAAO;AAC1B,QAAI;AACF,YAAM,SAAkB,KAAK,MAAM,KAAK;AACxC,aAAO,eAAe,MAAM,IAAI,SAAS;AAAA,IAC3C,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;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;;;AChDO,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.2.0",
+  "version": "0.3.1",
   "description": "Redis-backed HubBackend for Field Notes real-time sync relay",
   "type": "module",
   "sideEffects": false,
@@ -36,14 +36,14 @@
     "fieldnotes"
   ],
   "dependencies": {
-    "@fieldnotes/sync": "0.4.0"
+    "@fieldnotes/sync": "0.7.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",
     "tsup": "^8.5.1",
     "vitest": "^4.1.0",
-    "@fieldnotes/sync-server": "0.2.0",
-    "@fieldnotes/core": "0.46.0"
+    "@fieldnotes/core": "0.50.1",
+    "@fieldnotes/sync-server": "0.8.1"
   },
   "scripts": {
     "build": "tsup",