remote-state-sync 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ButterCookies
+
+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,182 @@
+# Remote State Sync
+
+A lightweight, fully type-safe unidirectional remote state synchronization library. Effortlessly sync complex states with fine-grained precision from a Provider (e.g., Server or Electron Main) to a Receiver (e.g., Web Client or Electron Renderer).
+
+English | [中文](./README.zh-CN.md)
+
+## Features
+
+- **Unidirectional Sync**: Safely sync state from A to B with an efficient patch-based diffing system.
+- **Deep Reactivity & Proxies**: Built-in, automatic support for intercepting deep changes across `Object`, `Map`, and `Set` structures.
+- **Batch Patching**: Automatically queues and batches rapid state mutations into singular, optimized events for high performance.
+- **Framework Agnostic Transport**: Bring your own transport layer (WebSocket, Socket.io, Electron IPC, HTTP, etc).
+- **Vue Integration**: Seamlessly connects to Vue's Reactivity system out of the box (`toValue()`, `toRef()`, `toShallowRef()`).
+
+## Installation
+
+```bash
+npm install remote-state-sync
+```
+
+## Examples
+
+### 1. Hono + Socket.IO (Server & Client Web)
+
+**Server (Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { Hono } from 'hono';
+import { Server } from 'socket.io';
+
+const app = new Hono();
+const io = new Server(3000);
+
+const provider = new SyncProvider();
+const usersNs = provider.register('users_space');
+
+// Define a state
+type UserState = {
+  connected: number;
+  history: string[];
+};
+
+// Initialize the state
+const userState = usersNs.sync<UserState>('data', {
+  connected: 0,
+  history: [],
+});
+
+// 1. snapshotGetter implementation via HTTP endpoint
+app.get('/snapshot/:namespace', (c) => {
+  const ns = c.req.param('namespace');
+  return c.json(provider.getStateSnapshot(ns));
+});
+
+io.on('connection', (socket) => {
+  // Mutating deeply tracks changes and queues patches automatically
+  userState.set((state) => void state.connected++);
+
+  socket.on('disconnect', () => {
+    userState.set((state) => void state.connected--);
+  });
+});
+
+// 2. Broadcast patches triggered by deeper modifications over WebSocket
+provider.bus.on('update', (namespace, patches) => {
+  io.emit('state-update', namespace, patches);
+});
+```
+
+**Client (Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { io } from 'socket.io-client';
+
+const socket = io('ws://localhost:3000');
+
+const receiver = new SyncReceiver({
+  // 1. Fetch the initial snapshot over HTTP
+  snapshotGetter: async (namespace) => {
+    const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
+    return res.json();
+  },
+});
+
+// 2. Receive and apply patches incrementally
+socket.on('state-update', (namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function main() {
+  const usersNs = await receiver.register('users_space');
+
+  type UserState = { connected: number; history: string[] };
+  const userState = usersNs.sync<UserState>('data');
+
+  // Output: { connected: 1, history: [] }
+  console.log(userState.toValue());
+
+  // Listen to specific item changes!
+  userState.on('update', (newVal, oldVal, patches) => {
+    console.log('State updated!', newVal.connected);
+  });
+}
+main();
+```
+
+### 2. Electron (`ipcMain` + `ipcRenderer`)
+
+**Main Process (Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { ipcMain, BrowserWindow } from 'electron';
+
+const provider = new SyncProvider();
+const appNs = provider.register('app_ns');
+
+type SettingsState = {
+  theme: 'dark' | 'light';
+  version: string;
+};
+
+// Initialize the state
+const settings = appNs.sync<SettingsState>('settings', {
+  theme: 'dark',
+  version: '1.0.0',
+});
+
+// 1. snapshotGetter via ipcMain.handle
+ipcMain.handle('get-sync-snapshot', (_, namespace) => {
+  return provider.getStateSnapshot(namespace);
+});
+
+// 2. Broadcast patches to all renderer windows
+provider.bus.on('update', (namespace, patches) => {
+  BrowserWindow.getAllWindows().forEach((win) => {
+    win.webContents.send('sync-update', namespace, patches);
+  });
+});
+
+// Example modification later down the line
+setTimeout(() => {
+  settings.set((state) => void (state.theme = 'light'));
+}, 5000);
+```
+
+**Renderer Process (Receiver with Vue)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { ipcRenderer } from 'electron';
+import { watch } from 'vue';
+
+const receiver = new SyncReceiver({
+  // 1. Fetch the snapshot via ipcRenderer.invoke
+  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+});
+
+// 2. Listen for patches from Main process
+ipcRenderer.on('sync-update', (_, namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function setup() {
+  const appNs = await receiver.register('app_ns');
+  const settings = appNs.sync<SettingsState>('settings');
+
+  // Vue Reactivity directly tied to the remote state!
+  const settingsRef = settings.toRef();
+
+  watch(
+    settingsRef,
+    (newSettings) => {
+      console.log('Renderer theme changed to:', newSettings.theme);
+    },
+    { deep: true },
+  );
+}
+setup();
+```

package/README.zh-CN.md

@@ -0,0 +1,179 @@
+# Remote State Sync
+
+轻量级、完全类型安全的单向远程状态同步库。轻松将复杂状态以细小粒度从 Provider（如：服务端 Server 或 Electron 主进程）同步到 Receiver（如：Web 客户端 Client 或 Electron 渲染进程）。
+
+[English](./README.md) | 中文
+
+## 特性
+
+- **单向同步**：通过高效的增量 Patch (补丁) 算法，将状态从 A 端安全地同步到 B 端。
+- **深度响应与代理拦截**：内建支持对 `Object`、`Map` 和 `Set` 数据类型结构进行深层侦听、拦截与同步同步。
+- **补丁按需批处理**：高频次、连续的状态变更会在底层自动批量打包合并为单次事件分发，最大化性能。
+- **多端传输解耦**：不强绑定任何传输协议。可以灵活适配 WebSocket、Socket.io、Electron IPC、HTTP 等任意传输层网络！
+- **完美兼容 Vue**：提供无缝的 `@vue/reactivity` 支持能力，开箱即用（支持 `.toValue()`、`.toRef()` 和 `.toShallowRef()`）。
+
+## 安装
+
+```bash
+npm install remote-state-sync
+```
+
+## 场景示例
+
+### 1. 组合：Hono + Socket.IO (Server端与Web端通信)
+
+**服务端 Server (提供方 Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { Hono } from 'hono';
+import { Server } from 'socket.io';
+
+const app = new Hono();
+const io = new Server(3000);
+
+const provider = new SyncProvider();
+const usersNs = provider.register('users_space');
+
+// 定义一个状态
+type UserState = {
+  connected: number;
+  history: string[];
+};
+
+// 初始化这个状态
+const userState = usersNs.sync<UserState>('data', {
+  connected: 0,
+  history: [],
+});
+
+// 第一步：利用 Hono 提供 HTTP 接口
+// 向客户端暴露 Snapshot
+app.get('/snapshot/:namespace', (c) => {
+  const ns = c.req.param('namespace');
+  return c.json(provider.getStateSnapshot(ns));
+});
+
+io.on('connection', (socket) => {
+  // 修改复杂对象会自动生成补丁（得益于内部 Proxy）
+  userState.set((state) => void state.connected++);
+
+  socket.on('disconnect', () => {
+    userState.set((state) => void state.connected--);
+  });
+});
+
+// 第二步：通过 WebSocket 向外部广播由于变更生成的批量 Patches
+provider.bus.on('update', (namespace, patches) => {
+  io.emit('state-update', namespace, patches);
+});
+```
+
+**Web客户端 Client (接收方 Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { io } from 'socket.io-client';
+
+const socket = io('ws://localhost:3000');
+
+// 第一步：通过 HTTP 拉取远端快照，作为初始化状态
+snapshotGetter: (async (namespace) => {
+  const res = await fetch(`http://localhost:3000/snapshot/${namespace}`);
+  return res.json();
+},
+  // 第二步：接管增量 Patches，增量更新本地状态树
+  socket.on('state-update', (namespace, patches) => {
+    receiver.applyPatches(namespace, patches);
+  }));
+
+async function main() {
+  const usersNs = await receiver.register('users_space');
+
+  type UserState = { connected: number; history: string[] };
+  const userState = usersNs.sync<UserState>('data');
+
+  // Output: { connected: 1, history: [] }
+  console.log(userState.toValue());
+
+  userState.on('update', (newVal, oldVal, patches) => {
+    console.log('状态更新', newVal.connected);
+  });
+}
+main();
+```
+
+### 2.组合：Electron (`ipcMain` + `ipcRenderer`)
+
+**主进程 Main Process (提供方 Provider)**
+
+```typescript
+import { SyncProvider } from 'remote-state-sync';
+import { ipcMain, BrowserWindow } from 'electron';
+
+const provider = new SyncProvider();
+const appNs = provider.register('app_ns');
+
+type SettingsState = {
+  theme: 'dark' | 'light';
+  version: string;
+};
+
+// 初始化状态
+const settings = appNs.sync<SettingsState>('settings', {
+  theme: 'dark',
+  version: '1.0.0',
+});
+
+// 第一步：通过 ipcMain.handle 暴露 snapshot 获取能力
+ipcMain.handle('get-sync-snapshot', (_, namespace) => {
+  return provider.getStateSnapshot(namespace);
+});
+
+// 第二步：将状态补丁通过 ipcEvent 主动投递给所有渲染进程
+provider.bus.on('update', (namespace, patches) => {
+  BrowserWindow.getAllWindows().forEach((win) => {
+    win.webContents.send('sync-update', namespace, patches);
+  });
+});
+
+// 修改示例
+setTimeout(() => {
+  settings.set((state) => void (state.theme = 'light'));
+}, 5000);
+```
+
+**渲染进程 Renderer Process (结合Vue使用的 Receiver)**
+
+```typescript
+import { SyncReceiver } from 'remote-state-sync';
+import { ipcRenderer } from 'electron';
+import { watch } from 'vue';
+
+const receiver = new SyncReceiver({
+  // 第一步：利用 ipcRenderer.invoke 异步请求 Snapshot
+  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+});
+
+// 第二步：监听来自主进程投递的 Patches
+ipcRenderer.on('sync-update', (_, namespace, patches) => {
+  receiver.applyPatches(namespace, patches);
+});
+
+async function setup() {
+  const appNs = await receiver.register('app_ns');
+  const settings = appNs.sync<SettingsState>('settings');
+
+  // 第三步：将远端状态一键接入 Vue 的响应式生态内！
+  const settingsRef = settings.toRef(); // 或 toShallowRef()
+
+  watch(
+    settingsRef,
+    (newSettings) => {
+      console.log('Renderer theme changed to:', newSettings.theme);
+    },
+    { deep: true },
+  );
+}
+setup();
+```

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import Nanobus from 'nanobus';
+import { Ref, ShallowRef } from '@vue/reactivity';
+
+type PatchOperation = 'set' | 'delete' | 'clear' | 'add';
+interface Patch {
+    op: PatchOperation;
+    path: (string | number)[];
+    value?: unknown;
+}
+interface SyncOptions {
+    snapshotGetter: (namespace: string) => Promise<Record<string, unknown>>;
+}
+type SyncUpdater<T> = (state: T) => T | void;
+type SyncBusDefinition = {
+    update: (namespace: string, patches: Patch[]) => void;
+};
+type ReceiverItemBusDefinition<T> = {
+    update: (newValue: T, oldValue: T, patches: Patch[]) => void;
+};
+
+declare class SyncProvider {
+    private namespaces;
+    bus: Nanobus<SyncBusDefinition>;
+    constructor();
+    register(namespace: string): SyncNamespaceProvider;
+    getStateSnapshot(namespace: string): Promise<Record<string, unknown>>;
+}
+declare class SyncNamespaceProvider {
+    readonly namespace: string;
+    private bus;
+    private items;
+    private queuedPatches;
+    private emitTimeout;
+    constructor(namespace: string, bus: Nanobus<SyncBusDefinition>);
+    sync<T>(key: string, initialValue?: T): SyncItemProvider<T>;
+    getSnapshot(): Record<string, unknown>;
+    private queuePatch;
+    private emitPatches;
+}
+declare class SyncItemProvider<T> {
+    readonly key: string;
+    private onPatch;
+    private value;
+    constructor(key: string, initialValue: T | undefined, onPatch: (patch: Patch) => void);
+    set(valOrUpdater: T | SyncUpdater<T>): void;
+    toValue(): T;
+    private setValue;
+}
+
+declare class SyncReceiver {
+    private options;
+    private namespaces;
+    constructor(options: SyncOptions);
+    register(namespace: string): Promise<SyncNamespaceReceiver>;
+    applyPatches(namespace: string, patches: Patch[]): void;
+}
+declare class SyncNamespaceReceiver {
+    readonly namespace: string;
+    private snapshot;
+    private items;
+    constructor(namespace: string, snapshot: Record<string, unknown>);
+    sync<T>(key: string): SyncItemReceiver<T>;
+    applyPatches(patches: Patch[]): void;
+    private applyPatchToObject;
+}
+declare class SyncItemReceiver<T> {
+    readonly key: string;
+    private value;
+    private _ref;
+    private _shallowRef;
+    bus: Nanobus<ReceiverItemBusDefinition<T>>;
+    constructor(key: string, initialValue: T);
+    on(event: 'update', cb: (newValue: T, oldValue: T, patches: Patch[]) => void): void;
+    toValue(): T;
+    toRef(): Ref<T>;
+    toShallowRef(): ShallowRef<T>;
+    applyPatch(patch: Patch): void;
+    triggerReactivity(): void;
+    dispose(): void;
+}
+
+export { type Patch, type PatchOperation, type ReceiverItemBusDefinition, type SyncBusDefinition, SyncItemProvider, SyncItemReceiver, SyncNamespaceProvider, SyncNamespaceReceiver, type SyncOptions, SyncProvider, SyncReceiver, type SyncUpdater };

package/dist/index.js

@@ -0,0 +1,502 @@
+// src/provider.ts
+import Nanobus from "nanobus";
+
+// src/utils.ts
+function isObject(val) {
+  return val !== null && typeof val === "object";
+}
+function shouldProxy(val) {
+  if (!isObject(val)) return false;
+  if (typeof val === "function") return false;
+  if (val instanceof Date) return false;
+  if (val instanceof RegExp) return false;
+  return true;
+}
+function navigatePath(obj, path, startIdx, endIdx) {
+  let current = obj;
+  for (let i = startIdx; i < endIdx; i++) {
+    if (current === void 0 || current === null) return current;
+    const step = path[i];
+    if (current instanceof Map) {
+      current = current.get(step);
+    } else {
+      current = current[step];
+    }
+  }
+  return current;
+}
+function setValueAtPath(current, key, value) {
+  if (!current) return;
+  if (current instanceof Map) {
+    current.set(key, value);
+  } else {
+    current[key] = value;
+  }
+}
+function deleteValueAtPath(current, key) {
+  if (!current) return;
+  if (current instanceof Map) {
+    current.delete(key);
+  } else {
+    delete current[key];
+  }
+}
+function addValueToSet(current, value) {
+  if (current instanceof Set) {
+    current.add(value);
+  }
+}
+function clearValue(current) {
+  if (current && typeof current.clear === "function") {
+    current.clear();
+  }
+}
+
+// src/proxy.ts
+function createDeepProxy(target, path, onPatch) {
+  if (!shouldProxy(target)) {
+    return target;
+  }
+  if (target instanceof Map) {
+    return createMapProxy(target, path, onPatch);
+  }
+  if (target instanceof Set) {
+    return createSetProxy(target, path, onPatch);
+  }
+  return createObjectProxy(target, path, onPatch);
+}
+function createObjectProxy(target, path, onPatch) {
+  const handler = {
+    get(obj, prop, receiver) {
+      const value = Reflect.get(obj, prop, receiver);
+      if (typeof prop === "symbol") {
+        return value;
+      }
+      if (shouldProxy(value)) {
+        return createDeepProxy(value, [...path, prop], onPatch);
+      }
+      return value;
+    },
+    set(obj, prop, value, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.set(obj, prop, value, receiver);
+      }
+      const success = Reflect.set(obj, prop, value, receiver);
+      if (success) {
+        onPatch({
+          op: "set",
+          path: [...path, prop],
+          value
+        });
+      }
+      return success;
+    },
+    deleteProperty(obj, prop) {
+      if (typeof prop === "symbol") {
+        return Reflect.deleteProperty(obj, prop);
+      }
+      const success = Reflect.deleteProperty(obj, prop);
+      if (success) {
+        onPatch({
+          op: "delete",
+          path: [...path, prop]
+        });
+      }
+      return success;
+    }
+  };
+  return new Proxy(target, handler);
+}
+function createMapProxy(target, path, onPatch) {
+  const handler = {
+    get(obj, prop) {
+      const value = Reflect.get(obj, prop);
+      if (typeof prop === "symbol") {
+        return typeof value === "function" ? value.bind(obj) : value;
+      }
+      if (typeof value === "function") {
+        if (prop === "set") {
+          return function(key, val) {
+            const result = obj.set(key, val);
+            onPatch({
+              op: "set",
+              path: [...path, key],
+              value: val
+            });
+            return result;
+          };
+        }
+        if (prop === "delete") {
+          return function(key) {
+            const hasKey = obj.has(key);
+            const result = obj.delete(key);
+            if (hasKey) {
+              onPatch({
+                op: "delete",
+                path: [...path, key]
+              });
+            }
+            return result;
+          };
+        }
+        if (prop === "clear") {
+          return function() {
+            if (obj.size > 0) {
+              const result = obj.clear();
+              onPatch({
+                op: "clear",
+                path
+              });
+              return result;
+            }
+          };
+        }
+        if (prop === "get") {
+          return function(key) {
+            const getVal = obj.get(key);
+            if (shouldProxy(getVal)) {
+              return createDeepProxy(getVal, [...path, key], onPatch);
+            }
+            return getVal;
+          };
+        }
+        return value.bind(obj);
+      }
+      return value;
+    }
+  };
+  return new Proxy(target, handler);
+}
+function createSetProxy(target, path, onPatch) {
+  const handler = {
+    get(obj, prop) {
+      const value = Reflect.get(obj, prop);
+      if (typeof prop === "symbol") {
+        return typeof value === "function" ? value.bind(obj) : value;
+      }
+      if (typeof value === "function") {
+        if (prop === "add") {
+          return function(val) {
+            const hasVal = obj.has(val);
+            const result = obj.add(val);
+            if (!hasVal) {
+              onPatch({
+                op: "add",
+                // For set, we don't have a key to navigate, but we can pass the value
+                // In a true Sync scenario, Set diffing is tricky. Path is just the Set itself.
+                path,
+                value: val
+              });
+            }
+            return result;
+          };
+        }
+        if (prop === "delete") {
+          return function(val) {
+            const hasVal = obj.has(val);
+            const result = obj.delete(val);
+            if (hasVal) {
+              onPatch({
+                op: "delete",
+                path,
+                // Similarly, deleting from set happens at Set boundary
+                value: val
+                // use value to identify what to delete
+              });
+            }
+            return result;
+          };
+        }
+        if (prop === "clear") {
+          return function() {
+            if (obj.size > 0) {
+              const result = obj.clear();
+              onPatch({
+                op: "clear",
+                path
+              });
+              return result;
+            }
+          };
+        }
+        return value.bind(obj);
+      }
+      return value;
+    }
+  };
+  return new Proxy(target, handler);
+}
+
+// src/provider.ts
+var SyncProvider = class {
+  namespaces = /* @__PURE__ */ new Map();
+  bus = new Nanobus("SyncProvider");
+  constructor() {
+  }
+  register(namespace) {
+    if (this.namespaces.has(namespace)) {
+      return this.namespaces.get(namespace);
+    }
+    const ns = new SyncNamespaceProvider(namespace, this.bus);
+    this.namespaces.set(namespace, ns);
+    return ns;
+  }
+  async getStateSnapshot(namespace) {
+    const ns = this.namespaces.get(namespace);
+    if (!ns) {
+      throw new Error(`Namespace ${namespace} not found`);
+    }
+    return ns.getSnapshot();
+  }
+};
+var SyncNamespaceProvider = class {
+  constructor(namespace, bus) {
+    this.namespace = namespace;
+    this.bus = bus;
+  }
+  items = /* @__PURE__ */ new Map();
+  queuedPatches = [];
+  emitTimeout = null;
+  sync(key, initialValue) {
+    if (this.items.has(key)) {
+      throw new Error(`Item ${key} already registered in namespace ${this.namespace}`);
+    }
+    const item = new SyncItemProvider(key, initialValue, (patch) => {
+      this.queuePatch(patch);
+    });
+    this.items.set(key, item);
+    return item;
+  }
+  getSnapshot() {
+    const snapshot = {};
+    for (const [key, item] of this.items.entries()) {
+      snapshot[key] = item.toValue();
+    }
+    return snapshot;
+  }
+  queuePatch(patch) {
+    this.queuedPatches.push(patch);
+    if (!this.emitTimeout) {
+      this.emitTimeout = setTimeout(() => {
+        this.emitPatches();
+      }, 0);
+    }
+  }
+  emitPatches() {
+    if (this.queuedPatches.length === 0) return;
+    const patches = [...this.queuedPatches];
+    this.queuedPatches = [];
+    this.emitTimeout = null;
+    this.bus.emit("update", this.namespace, patches);
+  }
+};
+var SyncItemProvider = class {
+  constructor(key, initialValue, onPatch) {
+    this.key = key;
+    this.onPatch = onPatch;
+    if (initialValue !== void 0) {
+      this.setValue(initialValue);
+    }
+  }
+  value;
+  set(valOrUpdater) {
+    if (typeof valOrUpdater === "function") {
+      const updater = valOrUpdater;
+      const returnVal = updater(this.value);
+      if (returnVal !== void 0) {
+        this.setValue(returnVal);
+      }
+    } else {
+      this.setValue(valOrUpdater);
+    }
+  }
+  toValue() {
+    return this.value;
+  }
+  setValue(newVal) {
+    this.onPatch({
+      op: "set",
+      path: [this.key],
+      value: newVal
+    });
+    this.value = createDeepProxy(newVal, [this.key], this.onPatch);
+  }
+};
+
+// src/receiver.ts
+import Nanobus2 from "nanobus";
+import { shallowRef, ref, triggerRef } from "@vue/reactivity";
+var SyncReceiver = class {
+  constructor(options) {
+    this.options = options;
+  }
+  namespaces = /* @__PURE__ */ new Map();
+  async register(namespace) {
+    if (this.namespaces.has(namespace)) {
+      return this.namespaces.get(namespace);
+    }
+    const snapshot = await this.options.snapshotGetter(namespace);
+    const ns = new SyncNamespaceReceiver(namespace, snapshot);
+    this.namespaces.set(namespace, ns);
+    return ns;
+  }
+  applyPatches(namespace, patches) {
+    const ns = this.namespaces.get(namespace);
+    if (ns) {
+      ns.applyPatches(patches);
+    }
+  }
+};
+var SyncNamespaceReceiver = class {
+  constructor(namespace, snapshot) {
+    this.namespace = namespace;
+    this.snapshot = snapshot;
+  }
+  items = /* @__PURE__ */ new Map();
+  sync(key) {
+    if (this.items.has(key)) {
+      return this.items.get(key);
+    }
+    const val = this.snapshot[key];
+    const item = new SyncItemReceiver(key, val);
+    this.items.set(key, item);
+    return item;
+  }
+  applyPatches(patches) {
+    const affectedItems = /* @__PURE__ */ new Map();
+    for (const patch of patches) {
+      if (patch.path.length === 0) continue;
+      const key = patch.path[0];
+      const item = this.items.get(key);
+      if (item) {
+        if (!affectedItems.has(item)) {
+          affectedItems.set(item, { oldVal: item.toValue(), patches: [] });
+        }
+        item.applyPatch(patch);
+        affectedItems.get(item).patches.push(patch);
+      } else {
+        this.applyPatchToObject(this.snapshot, patch);
+      }
+    }
+    for (const [item, data] of affectedItems.entries()) {
+      item.triggerReactivity();
+      item.bus.emit("update", item.toValue(), data.oldVal, data.patches);
+    }
+  }
+  applyPatchToObject(obj, patch) {
+    if (patch.path.length === 0) return;
+    if (patch.op === "clear" || patch.op === "add") {
+      const target = navigatePath(obj, patch.path, 0, patch.path.length);
+      if (patch.op === "clear") {
+        clearValue(target);
+      } else {
+        addValueToSet(target, patch.value);
+      }
+      return;
+    }
+    const current = navigatePath(obj, patch.path, 0, patch.path.length - 1);
+    const lastKey = patch.path[patch.path.length - 1];
+    if (patch.op === "set") {
+      setValueAtPath(current, lastKey, patch.value);
+    } else if (patch.op === "delete") {
+      deleteValueAtPath(current, lastKey);
+    }
+  }
+};
+var SyncItemReceiver = class {
+  constructor(key, initialValue) {
+    this.key = key;
+    this.value = initialValue;
+  }
+  value;
+  _ref = null;
+  _shallowRef = null;
+  bus = new Nanobus2("SyncItemReceiver");
+  on(event, cb) {
+    this.bus.on(event, cb);
+  }
+  toValue() {
+    return this.value;
+  }
+  toRef() {
+    if (!this._ref) {
+      this._ref = ref(this.value);
+    }
+    return this._ref;
+  }
+  toShallowRef() {
+    if (!this._shallowRef) {
+      this._shallowRef = shallowRef(this.value);
+    }
+    return this._shallowRef;
+  }
+  applyPatch(patch) {
+    if (patch.path.length === 1) {
+      if (patch.op === "set") {
+        this.value = patch.value;
+        if (this._ref) this._ref.value = patch.value;
+        if (this._shallowRef) this._shallowRef.value = patch.value;
+      }
+      return;
+    }
+    const lastKey = patch.path[patch.path.length - 1];
+    if (patch.op === "set") {
+      const current = navigatePath(this.value, patch.path, 1, patch.path.length - 1);
+      const refCurrent = navigatePath(
+        this._ref ? this._ref.value : null,
+        patch.path,
+        1,
+        patch.path.length - 1
+      );
+      setValueAtPath(current, lastKey, patch.value);
+      setValueAtPath(refCurrent, lastKey, patch.value);
+    } else if (patch.op === "delete") {
+      const current = navigatePath(this.value, patch.path, 1, patch.path.length - 1);
+      const refCurrent = navigatePath(
+        this._ref ? this._ref.value : null,
+        patch.path,
+        1,
+        patch.path.length - 1
+      );
+      deleteValueAtPath(current, lastKey);
+      deleteValueAtPath(refCurrent, lastKey);
+    } else if (patch.op === "add") {
+      const target = navigatePath(this.value, patch.path, 1, patch.path.length);
+      const refTarget = navigatePath(
+        this._ref ? this._ref.value : null,
+        patch.path,
+        1,
+        patch.path.length
+      );
+      addValueToSet(target, patch.value);
+      addValueToSet(refTarget, patch.value);
+    } else if (patch.op === "clear") {
+      const target = navigatePath(this.value, patch.path, 1, patch.path.length);
+      const refTarget = navigatePath(
+        this._ref ? this._ref.value : null,
+        patch.path,
+        1,
+        patch.path.length
+      );
+      clearValue(target);
+      clearValue(refTarget);
+    }
+  }
+  triggerReactivity() {
+    if (this._shallowRef) {
+      triggerRef(this._shallowRef);
+    }
+  }
+  dispose() {
+    this._ref = null;
+    this._shallowRef = null;
+  }
+};
+export {
+  SyncItemProvider,
+  SyncItemReceiver,
+  SyncNamespaceProvider,
+  SyncNamespaceReceiver,
+  SyncProvider,
+  SyncReceiver
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "remote-state-sync",
+  "version": "1.0.0",
+  "description": "A lightweight, fully type-safe unidirectional remote state synchronization library.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Coooookies/remote-state-sync.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Coooookies",
+    "email": "admin@mitay.net"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsup src/index.ts --watch",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@vue/reactivity": "^3.5.28",
+    "nanobus": "^4.5.0"
+  }
+}