fix(improve): fix some issue and improve features

Author: unadlib

.github/workflows/nodejs.yml

@@ -12,14 +12,15 @@ jobs:
         node-version: [20.x, 22.x]
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
+        cache: 'yarn'
     - name: yarn install, build, and test
       run: |
-        yarn install
+        yarn install --frozen-lockfile
         yarn build
         yarn test
       env:

README.md

@@ -136,6 +136,26 @@ const yMap = doc.getMap('myData');
 const binder = bind<MyDataType>(yMap);
 ```
 
+### `createBinder(source, initialState, options?)`
+
+Creates a binder with initial state in one call. This is a convenience function that combines `bind()` and initialization.
+
+**Parameters:**
+
+- `source`: `Y.Map<any> | Y.Array<any>` - The Yjs data type to bind
+- `initialState`: `S` - The initial state to set
+- `options?`: `Options<S>` - Optional configuration
+
+**Returns:** `Binder<S>` - A binder instance with the initial state applied
+
+**Example:**
+
+```typescript
+const doc = new Y.Doc();
+const yMap = doc.getMap('myData');
+const binder = createBinder(yMap, { count: 0, items: [] });
+```
+
 ### Binder API
 
 #### `binder.get()`
@@ -161,7 +181,7 @@ binder.update((state) => {
 });
 ```
 
-#### `binder.subscribe(fn)`
+#### `binder.subscribe(fn, options?)`
 
 Subscribes to state changes. The callback is invoked when:
 
@@ -171,14 +191,22 @@ Subscribes to state changes. The callback is invoked when:
 **Parameters:**
 
 - `fn`: `(snapshot: S) => void` - Callback function that receives the new snapshot
+- `options?`: `SubscribeOptions` - Optional subscription configuration
+  - `immediate?: boolean` - If true, calls the listener immediately with current snapshot
 
 **Returns:** `UnsubscribeFn` - A function to unsubscribe
 
 ```typescript
+// Basic subscription
 const unsubscribe = binder.subscribe((snapshot) => {
   console.log('State changed:', snapshot);
 });
 
+// Subscribe with immediate execution
+binder.subscribe((snapshot) => {
+  console.log('Current state:', snapshot);
+}, { immediate: true });
+
 // Later...
 unsubscribe();
 ```
@@ -470,6 +498,54 @@ interface Options<S extends Snapshot> {
 - **Transactions**: Updates are wrapped in Yjs transactions automatically for optimal performance
 - **Unsubscribe**: Always call `unbind()` when done to prevent memory leaks
 
+## Collaboration Semantics
+
+`mutative-yjs` implements smart collaboration semantics to preserve changes from multiple collaborators:
+
+### Array Element Replacement
+
+When replacing array elements with objects, the library performs **incremental updates** instead of delete+insert:
+
+```typescript
+// If both old and new values are objects
+binder.update((state) => {
+  state.items[0] = { ...state.items[0], name: 'Updated' };
+});
+// → Updates properties in-place, preserving other collaborators' changes
+```
+
+This prevents the "lost update" problem discussed in [immer-yjs#1](https://github.com/sep2/immer-yjs/issues/1).
+
+### Circular Update Protection
+
+The library uses transaction origins to prevent circular updates:
+
+```typescript
+const binder = bind(yMap);
+
+binder.subscribe((snapshot) => {
+  // Safe: won't cause infinite loop
+  if (snapshot.count < 10) {
+    binder.update((state) => {
+      state.count++;
+    });
+  }
+});
+```
+
+### Circular Reference Detection
+
+The library detects and rejects circular object references:
+
+```typescript
+const circular: any = { a: 1 };
+circular.self = circular;
+
+binder.update((state) => {
+  state.data = circular; // ❌ Throws: "Circular reference detected"
+});
+```
+
 ## Examples
 
 Check out the [test file](./test/indext.test.ts) for comprehensive examples including:
@@ -494,7 +570,7 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Related Projects
 
-- [Mutative](https://github.com/unadlibjs/mutative) - Efficient immutable updates with a mutable API
+- [Mutative](https://github.com/unadlib/mutative) - Efficient immutable updates with a mutable API
 - [Yjs](https://github.com/yjs/yjs) - A CRDT framework for building collaborative applications
 
 ## Acknowledgments

package.json

@@ -1,15 +1,16 @@
 {
   "name": "mutative-yjs",
   "description": "A library for building Yjs collaborative web applications with Mutative",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "author": "unadlib",
   "repository": {
     "type": "git",
     "url": "https://github.com/mutativejs/mutative-yjs.git"
   },
   "source": "./src/index.ts",
-  "main": "./dist/index.esm.js",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.esm.js",
   "types": "./dist/index.d.ts",
   "unpkg": "./dist/index.umd.js",
   "exports": {

src/bind.ts

@@ -12,6 +12,13 @@ import {
 
 export type Snapshot = JSONObject | JSONArray;
 
+/**
+ * Applies Yjs events to a base object.
+ * IMPORTANT: `base` must be a Mutative draft object. Direct mutations
+ * are safe only within a Mutative draft context.
+ * @param base The draft object to mutate (from Mutative's create)
+ * @param event The Yjs event describing the change
+ */
 function applyYEvent<T extends JSONValue>(base: T, event: Y.YEvent<any>) {
   if (event instanceof Y.YMapEvent && isJSONObject(base)) {
     const source = event.target as Y.Map<any>;
@@ -74,7 +81,7 @@ function defaultApplyPatch(target: Y.Map<any> | Y.Array<any>, patch: Patch) {
 
   if (!path.length) {
     if (op !== PATCH_REPLACE) {
-      notImplemented();
+      notImplemented(`Cannot apply ${op} operation to root level`);
     }
 
     if (target instanceof Y.Map && isJSONObject(value)) {
@@ -84,9 +91,11 @@ function defaultApplyPatch(target: Y.Map<any> | Y.Array<any>, patch: Patch) {
       }
     } else if (target instanceof Y.Array && isJSONArray(value)) {
       target.delete(0, target.length);
-      target.push(value.map(toYDataType));
+      target.push(value.map((v) => toYDataType(v)));
     } else {
-      notImplemented();
+      notImplemented(
+        `Cannot replace root of type ${target.constructor.name} with value type ${typeof value}`
+      );
     }
 
     return;
@@ -116,20 +125,39 @@ function defaultApplyPatch(target: Y.Map<any> | Y.Array<any>, patch: Patch) {
         base.insert(property, [toYDataType(value)]);
         break;
       case PATCH_REPLACE:
-        base.delete(property);
-        base.insert(property, [toYDataType(value)]);
+        // If both old and new values are objects, try incremental update
+        // to preserve other collaborators' changes
+        const oldValue = base.get(property);
+        if (oldValue instanceof Y.Map && isJSONObject(value)) {
+          // Incremental update: update properties instead of replacing
+          oldValue.clear();
+          Object.entries(value).forEach(([k, v]) => {
+            oldValue.set(k, toYDataType(v));
+          });
+        } else {
+          // For primitives or type changes, do full replacement
+          base.delete(property, 1);
+          base.insert(property, [toYDataType(value)]);
+        }
         break;
       case PATCH_REMOVE:
-        base.delete(property);
+        base.delete(property, 1);
         break;
     }
   } else if (base instanceof Y.Array && property === 'length') {
     if (value < base.length) {
+      // Shrink array
       const diff = base.length - value;
       base.delete(value, diff);
+    } else if (value > base.length) {
+      // Expand array with null values
+      const toAdd = new Array(value - base.length).fill(null);
+      base.push(toAdd);
     }
   } else {
-    notImplemented();
+    notImplemented(
+      `Unsupported patch operation: ${op} on ${base?.constructor?.name ?? 'unknown'}.${String(property)}`
+    );
   }
 }
 
@@ -148,18 +176,27 @@ function applyUpdate<S extends Snapshot>(
   fn: UpdateFn<S>,
   applyPatch: typeof defaultApplyPatch,
   patchesOptions: PatchesOptions
-) {
-  const [, patches] = create(snapshot, fn, {
+): S {
+  const [nextState, patches] = create(snapshot, fn, {
     enablePatches: patchesOptions,
   });
   for (const patch of patches) {
     applyPatch(source, patch);
   }
+  return nextState;
 }
 
 export type ListenerFn<S extends Snapshot> = (snapshot: S) => void;
 export type UnsubscribeFn = () => void;
 
+export type SubscribeOptions = {
+  /**
+   * If true, the listener will be called immediately with the current snapshot.
+   * @default false
+   */
+  immediate?: boolean;
+};
+
 export type Binder<S extends Snapshot> = {
   /**
    * Release the binder.
@@ -181,8 +218,10 @@ export type Binder<S extends Snapshot> = {
    * Subscribe to snapshot update, fired when:
    *   1. User called update(fn).
    *   2. y.js source.observeDeep() fired.
+   * @param fn Listener function that receives the new snapshot
+   * @param options Optional configuration for subscription behavior
    */
-  subscribe: (fn: ListenerFn<S>) => UnsubscribeFn;
+  subscribe: (fn: ListenerFn<S>, options?: SubscribeOptions) => UnsubscribeFn;
 };
 
 export type Options<S extends Snapshot> = {
@@ -210,6 +249,8 @@ export type Options<S extends Snapshot> = {
  * @param source The y.js data type to bind.
  * @param options Change default behavior, can be omitted.
  */
+const MUTATIVE_YJS_ORIGIN = Symbol('mutative-yjs');
+
 export function bind<S extends Snapshot>(
   source: Y.Map<any> | Y.Array<any>,
   options?: Options<S>
@@ -220,12 +261,18 @@ export function bind<S extends Snapshot>(
 
   const subscription = new Set<ListenerFn<S>>();
 
-  const subscribe = (fn: ListenerFn<S>) => {
+  const subscribe = (fn: ListenerFn<S>, options?: SubscribeOptions) => {
     subscription.add(fn);
+    if (options?.immediate) {
+      fn(get());
+    }
     return () => void subscription.delete(fn);
   };
 
-  const observer = (events: Y.YEvent<any>[]) => {
+  const observer = (events: Y.YEvent<any>[], transaction: Y.Transaction) => {
+    // Skip events originated from this binder to prevent circular updates
+    if (transaction.origin === MUTATIVE_YJS_ORIGIN) return;
+
     snapshot = applyYEvents(get(), events);
     subscription.forEach((fn) => fn(get()));
   };
@@ -256,13 +303,17 @@ export function bind<S extends Snapshot>(
     }
 
     const doApplyUpdate = () => {
-      applyUpdate(source, get(), fn, applyPatch, patchesOptionsInOption);
+      snapshot = applyUpdate(source, get(), fn, applyPatch, patchesOptionsInOption);
     };
 
     if (doc) {
-      Y.transact(doc, doApplyUpdate);
+      Y.transact(doc, doApplyUpdate, MUTATIVE_YJS_ORIGIN);
+      // Notify subscribers after transaction since observer skips our origin
+      subscription.forEach((fn) => fn(get()));
     } else {
+      // Without doc, manually update snapshot and notify subscribers
       doApplyUpdate();
+      subscription.forEach((fn) => fn(get()));
     }
   };
 

src/helpers.ts

@@ -0,0 +1,33 @@
+import * as Y from 'yjs';
+import { bind, type Binder, type Options } from './bind';
+import type { Snapshot } from './bind';
+
+/**
+ * Creates a binder with initial state in one call.
+ * This is a convenience function that combines bind() and update().
+ *
+ * @param source The Yjs data type to bind
+ * @param initialState The initial state to set
+ * @param options Optional configuration for the binder
+ * @returns A binder instance with the initial state applied
+ *
+ * @example
+ * ```ts
+ * const doc = new Y.Doc();
+ * const map = doc.getMap('data');
+ * const binder = createBinder(map, { count: 0, items: [] });
+ * ```
+ */
+export function createBinder<S extends Snapshot>(
+  source: Y.Map<any> | Y.Array<any>,
+  initialState: S,
+  options?: Options<S>
+): Binder<S> {
+  const binder = bind<S>(source, options);
+  binder.update(() => {
+    // Use type assertion to return the initial state
+    // This is safe because we're initializing the state
+    return initialState as any;
+  });
+  return binder;
+}

src/index.ts

@@ -1,3 +1,5 @@
 export * from './bind';
 export * from './types';
 export { applyJsonArray, applyJsonObject } from './util';
+export type { SubscribeOptions } from './bind';
+export { createBinder } from './helpers';