Features

Why mutative-yjs?

// any operation supported by mutativebinder.update((state)=>{state.nested[0].key={id:123,p1:'a',p2:['a','b','c'],};});

Y.transact(state.doc,()=>{constval=newY.Map();val.set('id',123);val.set('p1','a');constarr=newY.Array();arr.push(['a','b','c']);val.set('p2',arr);state.get('nested').get(0).set('key',val);});

Installation

npm install mutative-yjs mutative yjs# oryarn add mutative-yjs mutative yjs# orpnpm add mutative-yjs mutative yjs

Quick Start

import*asYfrom'yjs';import{bind}from'mutative-yjs';// Create a Yjs documentconstdoc=newY.Doc();constyMap=doc.getMap('data');// Bind the Yjs data structureconstbinder=bind<{count:number;items:string[]}>(yMap);// Initialize with databinder.update((state)=>{state.count=0;state.items=['apple','banana'];});// Update state using Mutative's draft APIbinder.update((state)=>{state.count++;state.items.push('orange');});// Get current snapshotconsole.log(binder.get());// { count: 1, items: ['apple', 'banana', 'orange'] }// Subscribe to changesconstunsubscribe=binder.subscribe((snapshot)=>{console.log('State updated:',snapshot);});// Changes from Yjs are automatically reflectedyMap.set('count',5);console.log(binder.get().count);// 5// Clean upunsubscribe();binder.unbind();

Demo

API Reference

bind(source, options?)

constdoc=newY.Doc();constyMap=doc.getMap('myData');constbinder=bind<MyDataType>(yMap);

createBinder(source, initialState, options?)

constdoc=newY.Doc();constyMap=doc.getMap('myData');constbinder=createBinder(yMap,{count:0,items:[]});

Binder API

binder.get()

constsnapshot=binder.get();

binder.update(fn)

binder.update((state)=>{state.user.name='John';state.items.push({id:1,title:'New Item'});});

binder.subscribe(fn, options?)

// Basic subscriptionconstunsubscribe=binder.subscribe((snapshot)=>{console.log('State changed:',snapshot);});// Subscribe with immediate executionbinder.subscribe((snapshot)=>{console.log('Current state:',snapshot);},{immediate:true});// Later...unsubscribe();

binder.unbind()

binder.unbind();

Advanced Usage

Structural Sharing

constsnapshot1=binder.get();binder.update((state)=>{state.todos[0].done=true;});constsnapshot2=binder.get();// changed properties have new referencessnapshot1.todos!==snapshot2.todos;snapshot1.todos[0]!==snapshot2.todos[0];// unchanged properties keep the same referencesnapshot1.todos[1]===snapshot2.todos[1];snapshot1.todos[2]===snapshot2.todos[2];

Custom Patch Application

constbinder=bind<MyDataType>(yMap,{applyPatch:(target,patch,defaultApplyPatch)=>{// Inspect or modify the patch before applyingconsole.log('Applying patch:',patch);// You can conditionally apply patches based on the pathif(patch.path[0]==='protected'){// Skip protected fieldsreturn;}// Delegate to default behaviordefaultApplyPatch(target,patch);// Or implement custom logic// ...},});

Patches Options

constbinder=bind<MyDataType>(yMap,{patchesOptions:{pathAsArray:true,arrayLengthAssignment:true,},});

Working with Y.Array

constdoc=newY.Doc();constyArray=doc.getArray('items');typeItem={id:string;name:string};constbinder=bind<Item[]>(yArray);binder.update((items)=>{items.push({id:'1',name:'First Item'});items.push({id:'2',name:'Second Item'});});// Array operations work as expectedbinder.update((items)=>{items[0].name='Updated Name';items.splice(1,1);// Remove second item});

Collaborative Editing Example

import*asYfrom'yjs';import{WebsocketProvider}from'y-websocket';import{bind}from'mutative-yjs';// Create document and connect to serverconstdoc=newY.Doc();constprovider=newWebsocketProvider('ws://localhost:1234','room-name',doc);constyMap=doc.getMap('shared-data');constbinder=bind<AppState>(yMap);// Subscribe to remote changesbinder.subscribe((snapshot)=>{// Update UI with new staterenderApp(snapshot);});// Make local changesfunctionhandleUserAction(){binder.update((state)=>{state.todos.push({id:generateId(),text:'New todo',completed:false,});});}

Integration with React

import{bind}from'mutative-yjs';import{useSyncExternalStoreWithSelector}from'use-sync-external-store/with-selector';import*asYfrom'yjs';// define state shapeinterfaceState{todos:Array<{id:string;text:string;done:boolean}>;user:{name:string;email:string};}constdoc=newY.Doc();// define storeconstbinder=bind<State>(doc.getMap('data'));// define a helper hookfunctionuseMutativeYjs<Selection>(selector:(state:State)=>Selection){constselection=useSyncExternalStoreWithSelector(binder.subscribe,binder.get,binder.get,selector);return[selection,binder.update]asconst;}// optionally set initial databinder.update((state)=>{state.todos=[];state.user={name:'Guest',email:''};});// use in componentfunctionTodoList(){const[todos,update]=useMutativeYjs((s)=>s.todos);constaddTodo=(text:string)=>{update((state)=>{state.todos.push({id:Math.random().toString(),        text,done:false,});});};consttoggleTodo=(id:string)=>{update((state)=>{consttodo=state.todos.find((t)=>t.id===id);if(todo)todo.done=!todo.done;});};// will only rerender when 'todos' array changesreturn(<div>{todos.map((todo)=>(<divkey={todo.id}onClick={()=>toggleTodo(todo.id)}>{todo.text}{todo.done ?'✓' :'○'}</div>))}</div>);}// when donebinder.unbind();

Integration with Other Frameworks

Utility Functions

applyJsonArray(dest, source)

import{applyJsonArray}from'mutative-yjs';import*asYfrom'yjs';constyArray=newY.Array();applyJsonArray(yArray,[1,2,3,{nested:'object'}]);

applyJsonObject(dest, source)

import{applyJsonObject}from'mutative-yjs';import*asYfrom'yjs';constyMap=newY.Map();applyJsonObject(yMap,{key1:'value1',key2:{nested:'value'},});

Type Definitions

typeJSONPrimitive=string|number|boolean|null;typeJSONValue=JSONPrimitive|JSONObject|JSONArray;typeJSONObject={[member:string]:JSONValue};interfaceJSONArrayextendsArray<JSONValue>{}typeSnapshot=JSONObject|JSONArray;typeUpdateFn<SextendsSnapshot>=(draft:S)=>void;typeListenerFn<SextendsSnapshot>=(snapshot:S)=>void;typeUnsubscribeFn=()=>void;interfaceBinder<SextendsSnapshot>{unbind:()=>void;get:()=>S;update:(fn:UpdateFn<S>)=>void;subscribe:(fn:ListenerFn<S>)=>UnsubscribeFn;}interfaceOptions<SextendsSnapshot>{applyPatch?:(target:Y.Map<any>|Y.Array<any>,patch:Patch,applyPatch:(target:Y.Map<any>|Y.Array<any>,patch:Patch)=>void)=>void;patchesOptions?:|true|{pathAsArray?:boolean;arrayLengthAssignment?:boolean;};}

How It Works

Performance Tips

Collaboration Semantics

Array Element Replacement

// If both old and new values are objectsbinder.update((state)=>{state.items[0]={ ...state.items[0],name:'Updated'};});// → Updates properties in-place, preserving other collaborators' changes

Circular Update Protection

constbinder=bind(yMap);binder.subscribe((snapshot)=>{// Safe: won't cause infinite loopif(snapshot.count<10){binder.update((state)=>{state.count++;});}});

Circular Reference Detection

constcircular:any={a:1};circular.self=circular;binder.update((state)=>{state.data=circular;// ❌ Throws: "Circular reference detected"});

Examples

Compatibility

Contributing

Related Projects

Acknowledgments

Credits

License