@fieldnotes/sync-redis 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,71 @@
+# @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.
+
+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.

package/dist/index.cjs

@@ -0,0 +1,65 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RedisHubBackend: () => RedisHubBackend
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/redis-hub-backend.ts
+var import_sync = require("@fieldnotes/sync");
+var RedisHubBackend = class {
+  client;
+  keyPrefix;
+  constructor(client, options = {}) {
+    this.client = client;
+    this.keyPrefix = options.keyPrefix ?? "fieldnotes:room:";
+  }
+  key(room) {
+    return `${this.keyPrefix}${room}`;
+  }
+  async snapshot(room) {
+    const map = await this.client.hGetAll(this.key(room));
+    const out = [];
+    for (const value of Object.values(map)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        continue;
+      }
+      if ((0, import_sync.isValidElement)(parsed)) out.push(parsed);
+    }
+    return out;
+  }
+  async apply(room, op) {
+    const key = this.key(room);
+    if (op.kind === "upsert")
+      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));
+    else if (op.kind === "remove") await this.client.hDel(key, op.id);
+    else if (op.kind === "clear") await this.client.del(key);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RedisHubBackend
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,24 @@
+import { SyncOp } from '@fieldnotes/sync';
+import { CanvasElement } from '@fieldnotes/core';
+import { HubBackend } from '@fieldnotes/sync-server';
+
+interface RedisHashClient {
+    hGetAll(key: string): Promise<Record<string, string>>;
+    hSet(key: string, field: string, value: string): Promise<unknown>;
+    hDel(key: string, field: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+
+interface RedisHubBackendOptions {
+    keyPrefix?: string;
+}
+declare class RedisHubBackend implements HubBackend {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(client: RedisHashClient, options?: RedisHubBackendOptions);
+    private key;
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { SyncOp } from '@fieldnotes/sync';
+import { CanvasElement } from '@fieldnotes/core';
+import { HubBackend } from '@fieldnotes/sync-server';
+
+interface RedisHashClient {
+    hGetAll(key: string): Promise<Record<string, string>>;
+    hSet(key: string, field: string, value: string): Promise<unknown>;
+    hDel(key: string, field: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+
+interface RedisHubBackendOptions {
+    keyPrefix?: string;
+}
+declare class RedisHubBackend implements HubBackend {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(client: RedisHashClient, options?: RedisHubBackendOptions);
+    private key;
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+export { type RedisHashClient, RedisHubBackend, type RedisHubBackendOptions };

package/dist/index.js

@@ -0,0 +1,38 @@
+// src/redis-hub-backend.ts
+import { isValidElement } from "@fieldnotes/sync";
+var RedisHubBackend = class {
+  client;
+  keyPrefix;
+  constructor(client, options = {}) {
+    this.client = client;
+    this.keyPrefix = options.keyPrefix ?? "fieldnotes:room:";
+  }
+  key(room) {
+    return `${this.keyPrefix}${room}`;
+  }
+  async snapshot(room) {
+    const map = await this.client.hGetAll(this.key(room));
+    const out = [];
+    for (const value of Object.values(map)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        continue;
+      }
+      if (isValidElement(parsed)) out.push(parsed);
+    }
+    return out;
+  }
+  async apply(room, op) {
+    const key = this.key(room);
+    if (op.kind === "upsert")
+      await this.client.hSet(key, op.element.id, JSON.stringify(op.element));
+    else if (op.kind === "remove") await this.client.hDel(key, op.id);
+    else if (op.kind === "clear") await this.client.del(key);
+  }
+};
+export {
+  RedisHubBackend
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fieldnotes/sync-redis",
+  "version": "0.1.0",
+  "description": "Redis-backed HubBackend for Field Notes real-time sync relay",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IrakliDevelop/fieldnotes.git",
+    "directory": "packages/sync-redis"
+  },
+  "bugs": {
+    "url": "https://github.com/IrakliDevelop/fieldnotes/issues"
+  },
+  "homepage": "https://github.com/IrakliDevelop/fieldnotes/tree/master/packages/sync-redis#readme",
+  "keywords": [
+    "realtime",
+    "sync",
+    "redis",
+    "persistence",
+    "fieldnotes"
+  ],
+  "dependencies": {
+    "@fieldnotes/sync": "0.4.0"
+  },
+  "devDependencies": {
+    "@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"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}