@homeostate/core 0.0.0 → 0.1.2

package/dist/sync-engine.js

@@ -1,136 +1,110 @@
-import { defaultSyncFilter } from './types.js';
-import { patchSharedType, patchState } from './patching.js';
+import { defaultSyncFilter } from "./types.js";
+import { patchState } from "./patching.js";
 /**
- * Creates a sync engine that manages bidirectional synchronization
- * between any store (via adapter) and a Yjs document.
+ * Creates a sync engine that keeps a store (via its adapter) and a CRDT backend
+ * in sync in both directions.
  *
- * This is the core abstraction that makes the sync logic state-manager agnostic.
+ * This is the core abstraction that makes the sync logic state-manager and
+ * CRDT-library agnostic.
+ *
+ * On `connect()` the two sides are reconciled per key over the filtered view: a key the
+ * backend holds wins over the store's value, and a synced key the backend lacks stays in
+ * the store and is seeded into the backend unless `seed` is `'never'`. Afterwards the
+ * backend owns the synced document: every write replaces it with the store's filtered
+ * state, and a key removed from the backend is removed from the store.
  *
  * @example
  * ```typescript
- * const doc = new Y.Doc();
+ * const backend = createYjsBackend(new Y.Doc(), 'shared');
  * const adapter = new ZustandAdapter(store);
- * const engine = createSyncEngine(doc, adapter, { name: 'shared' });
+ * const engine = createSyncEngine(backend, adapter);
  * engine.connect();
  * ```
  */
-export function createSyncEngine(doc, adapter, config) {
-    const { name, filter = defaultSyncFilter } = config;
-    // The root Y.Map that the store is written and read from
-    const yMap = doc.getMap(name);
+export function createSyncEngine(backend, adapter, config = {}) {
+    const { filter = defaultSyncFilter, seed = "if-empty" } = config;
     let connected = false;
     let storeUnsubscribe = null;
-    let isUpdatingFromYjs = false;
-    let isUpdatingFromStore = false;
-    /**
-     * Filter state to only include syncable properties
-     */
+    let backendUnsubscribe = null;
+    let applyingRemote = false;
     const filterState = (state) => {
-        if (typeof state !== 'object' || state === null) {
-            return state;
-        }
         const filtered = {};
         for (const [key, value] of Object.entries(state)) {
-            if (filter(key, value)) {
+            if (filter(key, value))
                 filtered[key] = value;
-            }
         }
         return filtered;
     };
+    const readBackend = () => {
+        const value = backend.read();
+        return value !== null && typeof value === "object" ? value : {};
+    };
     /**
-     * Sync store state to Yjs
+     * Builds the next store state from `remote`. With `keepLocalOnly`, a synced key the
+     * backend does not hold is left in place instead of being deleted; that is the
+     * connect-time reconciliation. Otherwise `remote` is the whole synced state.
      */
-    const syncToYjs = () => {
-        if (isUpdatingFromYjs)
-            return;
-        isUpdatingFromStore = true;
-        try {
-            const state = adapter.getState();
-            const filteredState = filterState(state);
-            doc.transact(() => {
-                patchSharedType(yMap, filteredState);
-            });
-        }
-        finally {
-            isUpdatingFromStore = false;
+    const mergeStates = (current, remote, keepLocalOnly) => {
+        const synced = filterState(current);
+        const target = keepLocalOnly ? { ...synced, ...remote } : remote;
+        const patched = patchState(synced, target);
+        if (patched === synced)
+            return current;
+        const merged = { ...current, ...patched };
+        for (const key of Object.keys(synced)) {
+            if (!(key in patched))
+                delete merged[key];
         }
+        return merged;
     };
-    /**
-     * Sync Yjs state to store
-     */
-    const syncToStore = () => {
-        if (isUpdatingFromStore)
+    const syncToBackend = () => {
+        if (applyingRemote)
             return;
-        isUpdatingFromYjs = true;
+        backend.write(filterState(adapter.getState()));
+    };
+    const applyRemote = (remote, keepLocalOnly) => {
+        applyingRemote = true;
         try {
-            const yjsState = yMap.toJSON();
-            const currentState = adapter.getState();
-            // Merge Yjs state with current state (preserving functions and non-synced props)
-            const mergedState = mergeStates(currentState, yjsState);
-            adapter.setState(mergedState, true);
+            const current = adapter.getState();
+            const merged = mergeStates(current, remote, keepLocalOnly);
+            if (merged !== current)
+                adapter.setState(merged);
         }
         finally {
-            isUpdatingFromYjs = false;
-        }
-    };
-    /**
-     * Merge Yjs state with current store state, preserving non-syncable properties
-     */
-    const mergeStates = (current, fromYjs) => {
-        if (typeof current !== 'object' || current === null) {
-            return fromYjs;
-        }
-        const currentObj = current;
-        const yjsObj = fromYjs;
-        // Start with current state (preserves functions, etc.)
-        const merged = { ...currentObj };
-        // Apply Yjs state using patching for proper deep merging
-        const patchedData = patchState({ ...merged }, yjsObj);
-        // Restore non-syncable properties (like functions)
-        for (const [key, value] of Object.entries(currentObj)) {
-            if (!filter(key, value)) {
-                patchedData[key] = value;
-            }
+            applyingRemote = false;
         }
-        return patchedData;
     };
-    /**
-     * Handler for Yjs changes
-     */
-    const handleYjsChange = () => {
-        syncToStore();
+    const syncToStore = () => {
+        applyRemote(filterState(readBackend()), false);
     };
     return {
         connect: () => {
             if (connected)
                 return;
-            // Initialize Yjs with current store state
-            const initialState = adapter.getInitialState();
-            const filteredInitial = filterState(initialState);
-            doc.transact(() => {
-                patchSharedType(yMap, filteredInitial);
-            });
-            // Subscribe to Yjs changes
-            yMap.observeDeep(handleYjsChange);
-            // Subscribe to store changes
-            storeUnsubscribe = adapter.subscribe(() => {
-                syncToYjs();
-            });
+            const remote = filterState(readBackend());
+            const local = filterState(adapter.getState());
+            const remoteKeys = new Set(Object.keys(remote));
+            const missing = Object.keys(local).filter((key) => !remoteKeys.has(key));
+            if (seed === "if-empty" && missing.length > 0) {
+                const seeded = { ...remote };
+                for (const key of missing)
+                    seeded[key] = local[key];
+                backend.write(seeded);
+            }
+            applyRemote(remote, true);
+            backendUnsubscribe = backend.subscribe(syncToStore);
+            storeUnsubscribe = adapter.subscribe(syncToBackend);
             connected = true;
         },
         disconnect: () => {
             if (!connected)
                 return;
-            // Unsubscribe from Yjs
-            yMap.unobserveDeep(handleYjsChange);
-            // Unsubscribe from store
-            if (storeUnsubscribe) {
-                storeUnsubscribe();
-                storeUnsubscribe = null;
-            }
+            backendUnsubscribe?.();
+            backendUnsubscribe = null;
+            storeUnsubscribe?.();
+            storeUnsubscribe = null;
             connected = false;
         },
-        getYMap: () => yMap,
         isConnected: () => connected,
     };
 }

package/dist/sync-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-engine.js","sourceRoot":"","sources":["../src/sync-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-engine.js","sourceRoot":"","sources":["../src/sync-engine.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAoB,EACpB,OAAwB,EACxB,SAA2B,EAAE;IAE7B,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,IAAI,GAAG,UAAU,EAAE,GAAG,MAAM,CAAC;IAEjE,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,gBAAgB,GAAuB,IAAI,CAAC;IAChD,IAAI,kBAAkB,GAAuB,IAAI,CAAC;IAClD,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,MAAM,WAAW,GAAG,CAAC,KAAa,EAAS,EAAE;QAC3C,MAAM,QAAQ,GAAU,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAChD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,GAAU,EAAE;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,WAAW,GAAG,CAClB,OAAU,EACV,MAAa,EACb,aAAsB,EACnB,EAAE;QACL,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QACjE,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,MAAM;YAAE,OAAO,OAAO,CAAC;QAEvC,MAAM,MAAM,GAAU,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACjD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC;gBAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,GAAS,EAAE;QAC/B,IAAI,cAAc;YAAE,OAAO;QAC3B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,MAAa,EAAE,aAAsB,EAAQ,EAAE;QAClE,cAAc,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;YAC3D,IAAI,MAAM,KAAK,OAAO;gBAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnD,CAAC;gBAAS,CAAC;YACT,cAAc,GAAG,KAAK,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,GAAS,EAAE;QAC7B,WAAW,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,GAAS,EAAE;YAClB,IAAI,SAAS;gBAAE,OAAO;YAEtB,MAAM,MAAM,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;YAC1C,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAEzE,IAAI,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,MAAM,GAAU,EAAE,GAAG,MAAM,EAAE,CAAC;gBACpC,KAAK,MAAM,GAAG,IAAI,OAAO;oBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;gBACpD,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;YAED,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAE1B,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACpD,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;YACpD,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;QAED,UAAU,EAAE,GAAS,EAAE;YACrB,IAAI,CAAC,SAAS;gBAAE,OAAO;YAEvB,kBAAkB,EAAE,EAAE,CAAC;YACvB,kBAAkB,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,EAAE,CAAC;YACrB,gBAAgB,GAAG,IAAI,CAAC;YACxB,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QAED,WAAW,EAAE,GAAY,EAAE,CAAC,SAAS;KACtC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
- * Core types for the state-manager agnostic Yjs sync engine.
- * These interfaces allow any store manager to be connected to Yjs for P2P sync.
+ * Core types for the state-manager and CRDT-backend agnostic sync engine.
+ * These interfaces let any store be kept in sync through any replicated backend.
  */
 /**
  * Unsubscribe function returned by subscribe
@@ -9,47 +9,73 @@ export type Unsubscribe = () => void;
 /**
  * Adapter interface that bridges a specific state manager with the sync engine.
  * Implement this interface to add support for any state manager (Zustand, Redux, MobX, etc.)
+ *
+ * State must be plain JSON: objects, arrays, strings, numbers, booleans, and null.
+ * Functions are dropped by the default filter; other values such as Date, Map, or Set
+ * are neither diffed nor synced.
  */
-export interface StoreAdapter<S> {
+export interface StoreAdapter<S extends object> {
     /** Get the current state from the store */
     getState: () => S;
     /**
-     * Set state in the store.
-     * @param state - New state to set
-     * @param fromSync - If true, this update came from Yjs sync and should not trigger sync back
+     * Replace the store state. Called only for changes coming from the backend; the
+     * engine ignores store notifications raised while it runs, so the adapter needs no
+     * echo suppression of its own.
      */
-    setState: (state: S, fromSync?: boolean) => void;
+    setState: (state: S) => void;
     /**
-     * Subscribe to store changes that should trigger Yjs sync.
+     * Subscribe to store changes that should be written to the backend.
      * @returns Unsubscribe function
      */
     subscribe: (onStoreChange: () => void) => Unsubscribe;
-    /** Get the initial state of the store */
-    getInitialState: () => S;
 }
+/**
+ * Backend that holds the synced subtree in a CRDT or any other replicated store.
+ * The engine only ever exchanges plain JSON with it.
+ */
+export interface CrdtBackend {
+    /** Plain JSON snapshot of the synced subtree. Must not alias backend internals. */
+    read: () => unknown;
+    /**
+     * Make the backend equal to `next` in one atomic transaction.
+     * The backend decides the granularity of the operations; `getChanges` is exported for that.
+     */
+    write: (next: unknown) => void;
+    /**
+     * Notify about changes that did not come through this backend's own `write`.
+     * @returns Unsubscribe function
+     */
+    subscribe: (onRemoteChange: () => void) => Unsubscribe;
+}
+/**
+ * Whether `connect()` may write the store's synced keys that the backend does not hold.
+ * Reconciliation is per key over the filtered view: a key the backend holds always wins
+ * over the store's value, a key only the store holds always stays in the store.
+ * - `'if-empty'`: seed the keys the backend lacks, in one write (default)
+ * - `'never'`: leave seeding to the caller; the keys are written on the next local change
+ */
+export type SeedStrategy = "if-empty" | "never";
 /**
  * Configuration options for the sync engine
  */
 export interface SyncEngineConfig {
-    /** Name of the Y.Map in the Y.Doc to store the state */
-    name: string;
     /**
-     * Filter function to determine which state keys should be synced.
+     * Filter function to determine which state keys should be synced, in both directions.
      * Return true to sync the key, false to exclude it.
      * By default, functions are excluded from sync.
      */
     filter?: (key: string, value: unknown) => boolean;
+    /** Seeding strategy used by `connect()`; defaults to `'if-empty'` */
+    seed?: SeedStrategy;
 }
 /**
- * The sync engine interface - manages bidirectional sync between store and Yjs
+ * The sync engine interface - manages bidirectional sync between a store and a backend
  */
 export interface SyncEngine {
     /** Start synchronization */
     connect: () => void;
     /** Stop synchronization and cleanup */
     disconnect: () => void;
-    /** Get the underlying Y.Map */
-    getYMap: () => unknown;
     /** Check if engine is connected */
     isConnected: () => boolean;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC,CAAC;IAElB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAEjD;;;OAGG;IACH,SAAS,EAAE,CAAC,aAAa,EAAE,MAAM,IAAI,KAAK,WAAW,CAAC;IAEtD,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,uCAAuC;IACvC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,mCAAmC;IACnC,WAAW,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,OAEhE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC5C,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC,CAAC;IAElB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAE7B;;;OAGG;IACH,SAAS,EAAE,CAAC,aAAa,EAAE,MAAM,IAAI,KAAK,WAAW,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,IAAI,EAAE,MAAM,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAE/B;;;OAGG;IACH,SAAS,EAAE,CAAC,cAAc,EAAE,MAAM,IAAI,KAAK,WAAW,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAClD,qEAAqE;IACrE,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,uCAAuC;IACvC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,mCAAmC;IACnC,WAAW,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,OAEhE,CAAC"}

package/dist/types.js

@@ -1,11 +1,11 @@
 /**
- * Core types for the state-manager agnostic Yjs sync engine.
- * These interfaces allow any store manager to be connected to Yjs for P2P sync.
+ * Core types for the state-manager and CRDT-backend agnostic sync engine.
+ * These interfaces let any store be kept in sync through any replicated backend.
  */
 /**
  * Default filter that excludes functions from sync
  */
 export const defaultSyncFilter = (_key, value) => {
-    return typeof value !== 'function';
+    return typeof value !== "function";
 };
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4DH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE;IACzE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyFH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE;IACzE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeostate/core",
-  "version": "0.0.0",
-  "description": "State-manager agnostic sync engine between a store adapter and a Yjs document",
+  "version": "0.1.2",
+  "description": "State-manager and CRDT-backend agnostic sync engine between a store adapter and a CrdtBackend",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -9,12 +9,11 @@
     "url": "git+https://github.com/mixedrays/homeostate.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/mixedrays/homeostate#readme",
+  "homepage": "https://homeostate.pages.dev",
   "bugs": {
     "url": "https://github.com/mixedrays/homeostate/issues"
   },
   "keywords": [
-    "yjs",
     "crdt",
     "sync",
     "state-management",
@@ -30,19 +29,16 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/__tests__",
     "README.md",
     "LICENSE",
-    "THIRD_PARTY_NOTICES.md"
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
-    "yjs": "^13.6.0"
-  },
-  "devDependencies": {
-    "yjs": "^13.6.23"
-  },
   "scripts": {
     "build": "tsc -b"
   }

package/src/apply.ts

@@ -0,0 +1,87 @@
+import { ChangeType, type Change } from "./change.js";
+
+type Plain = Record<string, unknown>;
+
+/**
+ * How one store writes into its containers. `applyChanges` decides *what* to write; an
+ * implementation of this decides *how*, so the same edit script drives a MobX observable
+ * tree, a Valtio proxy, or a plain object.
+ *
+ * Every method receives a container that already lives in the store, never a copy.
+ */
+export interface ApplyOps {
+  /** Assign `value` at `key`, creating the property if the target is a record. */
+  set(target: object, key: string | number, value: unknown): void;
+  /** Remove the record property `key`. */
+  remove(target: object, key: string): void;
+  /** `Array.prototype.splice`: drop `deleteCount` elements at `index`, then add `inserted`. */
+  splice(
+    target: unknown[],
+    index: number,
+    deleteCount: number,
+    inserted: unknown[],
+  ): void;
+}
+
+/**
+ * Revises `value` by the character-level edit script `changes`, which is what `getChanges`
+ * returns for two strings. Each index addresses the string as revised by the steps before it.
+ */
+export const applyStringChanges = (value: string, changes: Change[]): string =>
+  changes.reduce((revised, [type, index, inserted]) => {
+    const at = index as number;
+    if (type === ChangeType.INSERT)
+      return revised.slice(0, at) + (inserted as string) + revised.slice(at);
+    if (type === ChangeType.DELETE)
+      return revised.slice(0, at) + revised.slice(at + 1);
+    return revised;
+  }, value);
+
+/**
+ * Applies `changes` to `target` in place, mutating only the paths the edit script names.
+ * Everything else keeps its identity, which is what fine-grained stores react to.
+ *
+ * `changes` must be `getChanges(before, after)` where `before` describes the shape `target`
+ * currently holds — an adapter gets that by diffing against the snapshot it last handed out.
+ * A `PENDING` step carries no replacement value, so it can only be followed by recursing into
+ * the container already there; a target that does not mirror `before` leaves such a step
+ * unapplied rather than writing something wrong.
+ *
+ * @param target The container to mutate — a record, or an array for a positional edit script.
+ * @param changes The edit script to apply, in order.
+ * @param ops How this store writes; see {@link ApplyOps}.
+ */
+export const applyChanges = (
+  target: object,
+  changes: Change[],
+  ops: ApplyOps,
+): void => {
+  const array = Array.isArray(target) ? (target as unknown[]) : null;
+
+  for (const [type, key, value] of changes) {
+    switch (type) {
+      case ChangeType.PENDING: {
+        const child = (target as Plain)[key as string];
+        if (typeof child === "string")
+          ops.set(target, key, applyStringChanges(child, value as Change[]));
+        else if (child !== null && typeof child === "object")
+          applyChanges(child, value as Change[], ops);
+        break;
+      }
+
+      case ChangeType.DELETE:
+        if (array) ops.splice(array, key as number, 1, []);
+        else ops.remove(target, key as string);
+        break;
+
+      case ChangeType.INSERT:
+        if (array) ops.splice(array, key as number, 0, [value]);
+        else ops.set(target, key, value);
+        break;
+
+      case ChangeType.UPDATE:
+        ops.set(target, key, value);
+        break;
+    }
+  }
+};

package/src/change.ts

@@ -0,0 +1,23 @@
+/**
+ * Describes the change that needs to be made.
+ */
+export enum ChangeType {
+  /** A value was inserted. */
+  INSERT = "insert",
+  /** A value was replaced. */
+  UPDATE = "update",
+  /** A value was deleted. */
+  DELETE = "delete",
+  /** The value requires a recursive diff to identify further changes. */
+  PENDING = "pending",
+}
+
+/**
+ * One step in turning a container into another: `[type, key, value]`.
+ *
+ * Steps apply in order. A numeric key addresses the array or string as revised by the
+ * steps before it, so appliers never sort or clamp. `value` is the inserted or replacing
+ * value (a string insert may carry several characters), `undefined` for a delete, and the
+ * nested `Change[]` for a pending entry.
+ */
+export type Change = [ChangeType, string | number, unknown];