remote-state-sync 1.0.3 → 1.0.4

package/README.md

@@ -48,9 +48,10 @@ const userState = usersNs.sync<UserState>('data', {
 });
 
 // 1. snapshotGetter implementation via HTTP endpoint
-app.get('/snapshot/:namespace', (c) => {
+app.get('/snapshot/:namespace/:key', (c) => {
   const ns = c.req.param('namespace');
-  return c.json(provider.getStateSnapshot(ns));
+  const key = c.req.param('key');
+  return c.json(provider.getStateSnapshot(ns, key));
 });
 
 io.on('connection', (socket) => {
@@ -78,8 +79,8 @@ 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}`);
+  snapshotGetter: async (namespace, key) => {
+    const res = await fetch(`http://localhost:3000/snapshot/${namespace}/${key}`);
     return res.json();
   },
 });
@@ -93,7 +94,7 @@ async function main() {
   const usersNs = await receiver.register('users_space');
 
   type UserState = { connected: number; history: string[] };
-  const userState = usersNs.sync<UserState>('data');
+  const userState = await usersNs.sync<UserState>('data');
 
   // Output: { connected: 1, history: [] }
   console.log(userState.toValue());
@@ -129,8 +130,8 @@ const settings = appNs.sync<SettingsState>('settings', {
 });
 
 // 1. snapshotGetter via ipcMain.handle
-ipcMain.handle('get-sync-snapshot', (_, namespace) => {
-  return provider.getStateSnapshot(namespace);
+ipcMain.handle('get-sync-snapshot', (_, namespace, key) => {
+  return provider.getStateSnapshot(namespace, key);
 });
 
 // 2. Broadcast patches to all renderer windows
@@ -155,7 +156,7 @@ import { watch } from 'vue';
 
 const receiver = new SyncReceiver({
   // 1. Fetch the snapshot via ipcRenderer.invoke
-  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+  snapshotGetter: (namespace, key) => ipcRenderer.invoke('get-sync-snapshot', namespace, key),
 });
 
 // 2. Listen for patches from Main process
@@ -165,7 +166,7 @@ ipcRenderer.on('sync-update', (_, namespace, patches) => {
 
 async function setup() {
   const appNs = await receiver.register('app_ns');
-  const settings = appNs.sync<SettingsState>('settings');
+  const settings = await appNs.sync<SettingsState>('settings');
 
   // Vue Reactivity directly tied to the remote state!
   const settingsRef = settings.toRef();

package/README.zh-CN.md

@@ -49,9 +49,10 @@ const userState = usersNs.sync<UserState>('data', {
 
 // 第一步：利用 Hono 提供 HTTP 接口
 // 向客户端暴露 Snapshot
-app.get('/snapshot/:namespace', (c) => {
+app.get('/snapshot/:namespace/:key', (c) => {
   const ns = c.req.param('namespace');
-  return c.json(provider.getStateSnapshot(ns));
+  const key = c.req.param('key');
+  return c.json(provider.getStateSnapshot(ns, key));
 });
 
 io.on('connection', (socket) => {
@@ -77,21 +78,24 @@ 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);
-  }));
+const receiver = new SyncReceiver({
+  // 第一步：通过 HTTP 拉取远端快照，作为初始化状态
+  snapshotGetter: async (namespace, key) => {
+    const res = await fetch(`http://localhost:3000/snapshot/${namespace}/${key}`);
+    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');
+  const userState = await usersNs.sync<UserState>('data');
 
   // Output: { connected: 1, history: [] }
   console.log(userState.toValue());
@@ -126,8 +130,8 @@ const settings = appNs.sync<SettingsState>('settings', {
 });
 
 // 第一步：通过 ipcMain.handle 暴露 snapshot 获取能力
-ipcMain.handle('get-sync-snapshot', (_, namespace) => {
-  return provider.getStateSnapshot(namespace);
+ipcMain.handle('get-sync-snapshot', (_, namespace, key) => {
+  return provider.getStateSnapshot(namespace, key);
 });
 
 // 第二步：将状态补丁通过 ipcEvent 主动投递给所有渲染进程
@@ -152,7 +156,7 @@ import { watch } from 'vue';
 
 const receiver = new SyncReceiver({
   // 第一步：利用 ipcRenderer.invoke 异步请求 Snapshot
-  snapshotGetter: (namespace) => ipcRenderer.invoke('get-sync-snapshot', namespace),
+  snapshotGetter: (namespace, key) => ipcRenderer.invoke('get-sync-snapshot', namespace, key),
 });
 
 // 第二步：监听来自主进程投递的 Patches
@@ -162,7 +166,7 @@ ipcRenderer.on('sync-update', (_, namespace, patches) => {
 
 async function setup() {
   const appNs = await receiver.register('app_ns');
-  const settings = appNs.sync<SettingsState>('settings');
+  const settings = await appNs.sync<SettingsState>('settings');
 
   // 第三步：将远端状态一键接入 Vue 的响应式生态内！
   const settingsRef = settings.toRef(); // 或 toShallowRef()

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { SuperJSONResult } from 'superjson';
 import Nanobus from 'nanobus';
-import { Ref, ShallowRef } from '@vue/reactivity';
+import { Ref, DeepReadonly, ShallowRef } from '@vue/reactivity';
 
 type PatchOperation = 'set' | 'delete' | 'clear' | 'add';
 interface Patch {
@@ -10,7 +10,7 @@ interface Patch {
     value?: unknown;
 }
 interface SyncOptions {
-    snapshotGetter: (namespace: string) => Promise<SyncSnapshot>;
+    snapshotGetter: (namespace: string, key: string) => Promise<SyncStateSnapshot>;
 }
 type SyncUpdater<T> = (state: T) => T | void;
 type SyncBusDefinition = {
@@ -20,14 +20,14 @@ type SyncBusDefinition = {
 type ReceiverItemBusDefinition<T> = {
     update: (newValue: T, oldValue: T, patches: Patch[]) => void;
 };
-type SyncSnapshot = SuperJSONResult;
+type SyncStateSnapshot = SuperJSONResult;
 
 declare class SyncProvider {
-    private namespaces;
     readonly bus: Nanobus<SyncBusDefinition>;
+    private namespaces;
     constructor();
     register(namespace: string): SyncNamespaceProvider;
-    getStateSnapshot(namespace: string): SyncSnapshot;
+    getStateSnapshot(namespace: string, key: string): SyncStateSnapshot;
 }
 declare class SyncNamespaceProvider {
     readonly namespace: string;
@@ -37,7 +37,7 @@ declare class SyncNamespaceProvider {
     private emitTimeout;
     constructor(namespace: string, bus: Nanobus<SyncBusDefinition>);
     sync<T>(key: string, initialValue?: T): SyncItemProvider<T>;
-    getSnapshot(): SyncSnapshot;
+    getSnapshot(key: string): SyncStateSnapshot;
     private queuePatch;
     private emitPatches;
 }
@@ -45,9 +45,11 @@ declare class SyncItemProvider<T> {
     readonly key: string;
     private onPatch;
     private value;
+    private rawValue;
     constructor(key: string, initialValue: T | undefined, onPatch: (patch: Patch) => void);
     set(valOrUpdater: T | SyncUpdater<T>): void;
-    toValue(): T;
+    get raw(): Readonly<T>;
+    toStructure(): SyncStateSnapshot;
     private setValue;
 }
 
@@ -60,27 +62,24 @@ declare class SyncReceiver {
 }
 declare class SyncNamespaceReceiver {
     readonly namespace: string;
-    private snapshot;
+    private snapshotGetter;
     private items;
-    constructor(namespace: string, snapshot: SyncSnapshot);
-    sync<T>(key: string): SyncItemReceiver<T>;
+    constructor(namespace: string, snapshotGetter: (namespace: string, key: string) => Promise<SyncStateSnapshot>);
+    sync<T>(key: string): Promise<SyncItemReceiver<T>>;
     applyPatches(patches: Patch[]): void;
-    private applyPatchToObject;
 }
 declare class SyncItemReceiver<T> {
     readonly key: string;
+    readonly bus: Nanobus<ReceiverItemBusDefinition<T>>;
     private value;
     private _ref;
     private _shallowRef;
-    readonly 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>;
+    get raw(): Readonly<T>;
+    toRef(): Readonly<Ref<DeepReadonly<T>>>;
+    toShallowRef(): Readonly<ShallowRef<DeepReadonly<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 SyncSnapshot, type SyncUpdater };
+export { type Patch, type PatchOperation, type ReceiverItemBusDefinition, type SyncBusDefinition, SyncItemProvider, SyncItemReceiver, SyncNamespaceProvider, SyncNamespaceReceiver, type SyncOptions, SyncProvider, SyncReceiver, type SyncStateSnapshot, type SyncUpdater };

package/dist/index.js

@@ -1,8 +1,9 @@
 // src/provider.ts
 import Nanobus from "nanobus";
-import SuperJSON from "superjson";
+import SuperJSON2 from "superjson";
 
 // src/utils.ts
+import SuperJSON from "superjson";
 function isObject(val) {
   return val !== null && typeof val === "object";
 }
@@ -52,6 +53,9 @@ function clearValue(current) {
     current.clear();
   }
 }
+function deepStructureClone(raw) {
+  return SuperJSON.deserialize(SuperJSON.serialize(raw));
+}
 
 // src/proxy.ts
 function createDeepProxy(target, rootKey, path, onPatch) {
@@ -238,8 +242,8 @@ function createSetProxy(target, rootKey, path, onPatch) {
 
 // src/provider.ts
 var SyncProvider = class {
-  namespaces = /* @__PURE__ */ new Map();
   bus = new Nanobus("SyncProvider");
+  namespaces = /* @__PURE__ */ new Map();
   constructor() {
   }
   register(namespace) {
@@ -251,12 +255,12 @@ var SyncProvider = class {
     this.bus.emit("register", namespace);
     return ns;
   }
-  getStateSnapshot(namespace) {
+  getStateSnapshot(namespace, key) {
     const ns = this.namespaces.get(namespace);
     if (!ns) {
       throw new Error(`Namespace ${namespace} not found`);
     }
-    return ns.getSnapshot();
+    return ns.getSnapshot(key);
   }
 };
 var SyncNamespaceProvider = class {
@@ -277,12 +281,12 @@ var SyncNamespaceProvider = class {
     this.items.set(key, item);
     return item;
   }
-  getSnapshot() {
-    const snapshot = {};
-    for (const [key, item] of this.items.entries()) {
-      snapshot[key] = item.toValue();
+  getSnapshot(key) {
+    const item = this.items.get(key);
+    if (!item) {
+      throw new Error(`Item ${key} not found in namespace ${this.namespace}`);
     }
-    return SuperJSON.serialize(snapshot);
+    return item.toStructure();
   }
   queuePatch(patch) {
     this.queuedPatches.push(patch);
@@ -309,6 +313,7 @@ var SyncItemProvider = class {
     }
   }
   value;
+  rawValue;
   set(valOrUpdater) {
     if (typeof valOrUpdater === "function") {
       const updater = valOrUpdater;
@@ -320,10 +325,14 @@ var SyncItemProvider = class {
       this.setValue(valOrUpdater);
     }
   }
-  toValue() {
-    return this.value;
+  get raw() {
+    return this.rawValue;
+  }
+  toStructure() {
+    return SuperJSON2.serialize(this.rawValue);
   }
   setValue(newVal) {
+    this.rawValue = newVal;
     this.onPatch({
       op: "set",
       key: this.key,
@@ -336,8 +345,13 @@ var SyncItemProvider = class {
 
 // src/receiver.ts
 import Nanobus2 from "nanobus";
-import { shallowRef, ref, triggerRef } from "@vue/reactivity";
-import SuperJSON2 from "superjson";
+import SuperJSON3 from "superjson";
+import {
+  shallowRef,
+  ref,
+  triggerRef,
+  readonly
+} from "@vue/reactivity";
 var SyncReceiver = class {
   constructor(options) {
     this.options = options;
@@ -347,8 +361,7 @@ var SyncReceiver = class {
     if (this.namespaces.has(namespace)) {
       return this.namespaces.get(namespace);
     }
-    const snapshot = await this.options.snapshotGetter(namespace);
-    const ns = new SyncNamespaceReceiver(namespace, snapshot);
+    const ns = new SyncNamespaceReceiver(namespace, this.options.snapshotGetter);
     this.namespaces.set(namespace, ns);
     return ns;
   }
@@ -360,17 +373,17 @@ var SyncReceiver = class {
   }
 };
 var SyncNamespaceReceiver = class {
-  constructor(namespace, snapshot) {
+  constructor(namespace, snapshotGetter) {
     this.namespace = namespace;
-    this.snapshot = snapshot;
+    this.snapshotGetter = snapshotGetter;
   }
   items = /* @__PURE__ */ new Map();
-  sync(key) {
+  async sync(key) {
     if (this.items.has(key)) {
       return this.items.get(key);
     }
-    const snapshot = SuperJSON2.deserialize(this.snapshot);
-    const val = snapshot[key];
+    const snapshot = await this.snapshotGetter(this.namespace, key);
+    const val = SuperJSON3.deserialize(snapshot);
     const item = new SyncItemReceiver(key, val);
     this.items.set(key, item);
     return item;
@@ -382,36 +395,15 @@ var SyncNamespaceReceiver = class {
       const item = this.items.get(key);
       if (item) {
         if (!affectedItems.has(item)) {
-          affectedItems.set(item, { oldVal: item.toValue(), patches: [] });
+          affectedItems.set(item, { oldVal: item.raw, 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) {
-    const fullPath = [patch.key, ...patch.path];
-    if (patch.op === "clear" || patch.op === "add") {
-      const target = navigatePath(obj, fullPath, 0, fullPath.length);
-      if (patch.op === "clear") {
-        clearValue(target);
-      } else {
-        addValueToSet(target, patch.value);
-      }
-      return;
-    }
-    const current = navigatePath(obj, fullPath, 0, fullPath.length - 1);
-    const lastKey = fullPath[fullPath.length - 1];
-    if (patch.op === "set") {
-      setValueAtPath(current, lastKey, patch.value);
-    } else if (patch.op === "delete") {
-      deleteValueAtPath(current, lastKey);
+      item.bus.emit("update", item.raw, data.oldVal, data.patches);
     }
   }
 };
@@ -420,27 +412,24 @@ var SyncItemReceiver = class {
     this.key = key;
     this.value = initialValue;
   }
+  bus = new Nanobus2("SyncItemReceiver");
   value;
   _ref = null;
   _shallowRef = null;
-  bus = new Nanobus2("SyncItemReceiver");
-  on(event, cb) {
-    this.bus.on(event, cb);
-  }
-  toValue() {
+  get raw() {
     return this.value;
   }
   toRef() {
     if (!this._ref) {
-      this._ref = ref(this.value);
+      this._ref = ref(deepStructureClone(this.value));
     }
-    return this._ref;
+    return readonly(this._ref);
   }
   toShallowRef() {
     if (!this._shallowRef) {
       this._shallowRef = shallowRef(this.value);
     }
-    return this._shallowRef;
+    return readonly(this._shallowRef);
   }
   applyPatch(patch) {
     if (patch.path.length === 0) {
@@ -499,10 +488,6 @@ var SyncItemReceiver = class {
       triggerRef(this._shallowRef);
     }
   }
-  dispose() {
-    this._ref = null;
-    this._shallowRef = null;
-  }
 };
 export {
   SyncItemProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-state-sync",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A lightweight, fully type-safe unidirectional remote state synchronization library.",
   "type": "module",
   "repository": {