Merge pull request #909 from streamich/node-api

High-level JSON CRDT node API

Author: streamich

biome.json

@@ -35,7 +35,8 @@
 				"noAssignInExpressions": "off",
 				"noConfusingLabels": "off",
 				"noConfusingVoidType": "off",
-				"noConstEnum": "off"
+				"noConstEnum": "off",
+				"noSelfCompare": "off"
 			},
 			"complexity": {
 				"noStaticOnlyClass": "off",

package.json

@@ -87,7 +87,7 @@
     "@jsonjoy.com/base64": "^1.1.2",
     "@jsonjoy.com/json-expression": "^1.0.0",
     "@jsonjoy.com/json-pack": "^1.1.0",
-    "@jsonjoy.com/json-pointer": "^1.0.0",
+    "@jsonjoy.com/json-pointer": "^1.0.1",
     "@jsonjoy.com/json-type": "^1.0.0",
     "@jsonjoy.com/util": "^1.6.0",
     "arg": "^5.0.2",

src/json-crdt/__demos__/type-safety.ts

@@ -58,7 +58,7 @@ console.log(model.view().text);
 console.log(model.view().flags[0]);
 // true
 
-console.log(model.find.val.toApi() + '');
+console.log(model.s.toApi() + '');
 // ObjectApi
 // └─ ObjNode 1234.1
 //    ├─ "num"
@@ -74,7 +74,7 @@ console.log(model.find.val.toApi() + '');
 //              └─ [1]: ValNode 1234.13
 //                      └─ ConNode 1234.12 { false }
 
-console.log(model.find.val.flags.toApi() + '');
+console.log(model.s.flags.toApi() + '');
 // ArrApi
 // └─ ArrNode 1234.9
 //    └─ ArrChunk 1234.14!2 len:2
@@ -83,20 +83,20 @@ console.log(model.find.val.flags.toApi() + '');
 //       └─ [1]: ValNode 1234.13
 //               └─ ConNode 1234.12 { false }
 
-console.log(model.find.val.flags[1].toApi() + '');
+console.log(model.s.flags[1].toApi() + '');
 // ValApi
 // └─ ValNode 1234.13
 //    └─ ConNode 1234.12 { false }
 
-console.log(model.find.val.flags[1].val.toApi() + '');
+console.log(model.s.flags[1].val.toApi() + '');
 // ConApi
 // └─ ConNode 1234.12 { false }
 
-console.log(model.find.val.num.toApi() + '');
+console.log(model.s.num.toApi() + '');
 // ConApi
 // └─ ConNode 1234.2 { 123 }
 
-console.log(model.find.val.text.toApi() + '');
+console.log(model.s.text.toApi() + '');
 // StrApi
 // └─ StrNode 1234.3 { "hello" }
 //    └─ StrChunk 1234.4!5 len:5 { "hello" }

src/json-crdt/model/Model.ts

@@ -6,10 +6,10 @@ import {ModelApi} from './api/ModelApi';
 import {ORIGIN, SESSION, SYSTEM_SESSION_TIME} from '../../json-crdt-patch/constants';
 import {randomSessionId} from './util';
 import {RootNode, ValNode, VecNode, ObjNode, StrNode, BinNode, ArrNode} from '../nodes';
-import type {SchemaToJsonNode} from '../schema/types';
 import {printTree} from 'tree-dump/lib/printTree';
 import {Extensions} from '../extensions/Extensions';
 import {AvlMap} from 'sonic-forest/lib/avl/AvlMap';
+import type {SchemaToJsonNode} from '../schema/types';
 import type {JsonCrdtPatchOperation, Patch} from '../../json-crdt-patch/Patch';
 import type {JsonNode, JsonNodeView} from '../nodes/types';
 import type {Printable} from 'tree-dump/lib/types';
@@ -269,23 +269,22 @@ export class Model<N extends JsonNode = JsonNode<any>> implements Printable {
     return this._api;
   }
 
-  /**
-   * Experimental node retrieval API using proxy objects.
-   */
-  public get find() {
-    return this.api.r.proxy();
-  }
-
   /**
    * Experimental node retrieval API using proxy objects. Returns a strictly
    * typed proxy wrapper around the value of the root node.
-   *
-   * @todo consider renaming this to `_`.
    */
   public get s() {
     return this.api.r.proxy().val;
   }
 
+  /**
+   * Experimental strictly typed node retrieval API using proxy objects.
+   * Automatically resolves nested "val" nodes.
+   */
+  public get $() {
+    return this.api.$;
+  }
+
   /**
    * Tracks number of times the `applyPatch` was called.
    *

src/json-crdt/model/api/ModelApi.ts

@@ -1,11 +1,12 @@
 import {FanOut} from 'thingies/lib/fanout';
 import {VecNode, ConNode, ObjNode, ArrNode, BinNode, StrNode, ValNode} from '../../nodes';
 import {type ApiPath, ArrApi, BinApi, ConApi, type NodeApi, ObjApi, StrApi, VecApi, ValApi} from './nodes';
-import type {Patch} from '../../../json-crdt-patch/Patch';
 import {PatchBuilder} from '../../../json-crdt-patch/PatchBuilder';
-import type {SyncStore} from '../../../util/events/sync-store';
 import {MergeFanOut, MicrotaskBufferFanOut} from './fanout';
+import {type JsonNodeToProxyPathNode, proxy$} from './proxy';
 import {ExtNode} from '../../extensions/ExtNode';
+import type {Patch} from '../../../json-crdt-patch/Patch';
+import type {SyncStore} from '../../../util/events/sync-store';
 import type {Model} from '../Model';
 import type {JsonNode, JsonNodeView} from '../../nodes';
 
@@ -106,11 +107,25 @@ export class ModelApi<N extends JsonNode = JsonNode> implements SyncStore<JsonNo
     return new ValApi(this.model.root, this);
   }
 
-  /** @ignore */
+  /**
+   * @ignore
+   *
+   * @todo Remove this getter?
+   */
   public get node() {
     return this.r.get();
   }
 
+  public get $(): JsonNodeToProxyPathNode<N> {
+    return proxy$((path) => {
+      try {
+        return this.wrap(this.find(path));
+      } catch {
+        return;
+      }
+    }, '$') as any;
+  }
+
   /**
    * Traverses the model starting from the root node and returns a local
    * changes API for a node at the given path.
@@ -266,6 +281,34 @@ export class ModelApi<N extends JsonNode = JsonNode> implements SyncStore<JsonNo
     return this.model.view();
   }
 
+  public select(path?: ApiPath, leaf?: boolean) {
+    return this.r.select(path, leaf);
+  }
+
+  /**
+   * Reads the value at the given path in the model. If no path is provided,
+   * returns the root node's view.
+   *
+   * @param path Path at which to read the value.
+   * @returns The value at the given path, or the root node's view if no path
+   *     is provided.
+   */
+  public read(path?: ApiPath): unknown {
+    return this.r.read(path);
+  }
+
+  public add(path: ApiPath, value: unknown): boolean {
+    return this.r.add(path, value);
+  }
+
+  public replace(path: ApiPath, value: unknown): boolean {
+    return this.r.replace(path, value);
+  }
+
+  public remove(path: ApiPath, length?: number): boolean {
+    return this.r.remove(path, length);
+  }
+
   private inTx = false;
   public transaction(callback: () => void) {
     if (this.inTx) callback();

src/json-crdt/model/api/__tests__/BinaryApi.spec.ts

@@ -33,5 +33,5 @@ test('.length()', () => {
       bin: s.bin(new Uint8Array([1, 2, 3])),
     }),
   );
-  expect(doc.find.val.bin.toApi().length()).toBe(3);
+  expect(doc.api.r.proxy().val.bin.toApi().length()).toBe(3);
 });

src/json-crdt/model/api/__tests__/ModelApi.proxy.spec.ts

@@ -1,5 +1,5 @@
 import {Model} from '../../Model';
-import {ConApi, ObjApi, StrApi, VecApi, ValApi, ArrApi, BinApi} from '../nodes';
+import {ConApi, ObjApi, StrApi, VecApi, ValApi, ArrApi, BinApi, NodeApi} from '../nodes';
 import {ConNode, RootNode, ObjNode, StrNode, type ValNode} from '../../../nodes';
 import {s} from '../../../../json-crdt-patch';
 import type {ProxyNodeVal} from '../proxy';
@@ -114,3 +114,82 @@ describe('supports all node types', () => {
     expect(model.s.obj.num.toView()).toStrictEqual(1234);
   });
 });
+
+describe('$ proxy', () => {
+  const schema = s.obj({
+    obj: s.obj({
+      str: s.str('asdf'),
+      num: s.con(1234),
+      address: s.obj({
+        city: s.str<string>('New York'),
+        zip: s.con(10001),
+      }),
+    }),
+    vec: s.vec(s.con('asdf'), s.con(1234), s.con(true), s.con(null)),
+    arr: s.arr([s.con('asdf'), s.val(s.con(0))]),
+    bin: s.bin(new Uint8Array([1, 2, 3])),
+  });
+
+  test('returns NodeApi? for un-typed model', () => {
+    const model1 = Model.create();
+    const model2 = Model.create<any>() as Model<any>;
+    model1.api.root(schema);
+    model2.api.root(schema);
+    const node1 = model1.api.$.obj.str.$;
+    const node2 = model2.api.$.obj.str.$;
+    const assertNodeApi = (node?: NodeApi) => {
+      expect(node instanceof NodeApi).toBe(true);
+    };
+    assertNodeApi(node1);
+    assertNodeApi(node2);
+    expect(node1?.asStr().view()).toBe('asdf');
+    expect(node2?.asStr().view()).toBe('asdf');
+  });
+
+  test('returns StrApi? for typed model', () => {
+    const model = Model.create(schema);
+    const node = model.api.$.obj.str.$;
+    const assertStrApi = (node?: StrApi) => {
+      expect(node instanceof StrApi).toBe(true);
+    };
+    assertStrApi(node);
+    expect(node?.view()).toBe('asdf');
+  });
+
+  test('can access various node types', () => {
+    const model = Model.create(schema);
+    expect(model.api.$.obj.str.$?.view()).toBe('asdf');
+    expect(model.api.$.obj.num.$?.view()).toBe(1234);
+    expect(model.api.$.obj.address.city.$?.view()).toBe('New York');
+    expect(model.api.$.obj.address.zip.$?.view()).toBe(10001);
+    expect(model.api.$.vec[0].$?.view()).toBe('asdf');
+    expect(model.api.$.vec[1].$?.view()).toBe(1234);
+    expect(model.api.$.vec[2].$?.view()).toBe(true);
+    expect(model.api.$.vec[3].$?.view()).toBe(null);
+    expect(model.api.$.arr[0].$?.view()).toBe('asdf');
+    expect(model.api.$.arr[1].$?.view()).toBe(0);
+    expect(model.api.$.bin.$?.view()).toEqual(new Uint8Array([1, 2, 3]));
+    expect(model.api.$.obj.address.$!.view()).toEqual({
+      city: 'New York',
+      zip: 10001,
+    });
+    expect(model.api.$.obj.address.$ instanceof ObjApi).toBe(true);
+  });
+
+  test('returns undefined if node not found', () => {
+    const model = Model.create(schema);
+    expect(model.api.$.vec[10].$?.view()).toBe(undefined);
+    expect(model.api.$.arr[111].$?.view()).toBe(undefined);
+    expect((model.api.$.arr as any).asdf.$?.view()).toBe(undefined);
+  });
+
+  test('returns undefined if node not found in un-typed model', () => {
+    const model = Model.create();
+    model.api.root(schema);
+    expect(model.api.$.asdfasdfasdf.$?.view()).toBe(undefined);
+    expect(model.api.$[0].$?.view()).toBe(undefined);
+    expect(model.api.$.vec[10].$?.view()).toBe(undefined);
+    expect(model.api.$.arr[111].$?.view()).toBe(undefined);
+    expect(model.api.$.arr.asdf.$?.view()).toBe(undefined);
+  });
+});

src/json-crdt/model/api/__tests__/ModelApi.spec.ts

@@ -2,7 +2,7 @@ import {Model} from '../../Model';
 
 describe('string manipulation', () => {
   test('can edit strings', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root('');
     api.str([]).ins(0, 'var foo = bar');
@@ -14,7 +14,7 @@ describe('string manipulation', () => {
   });
 
   test('can edit strings - 2', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({foo: [123, '', 5]});
     api.str(['foo', 1]).ins(0, 'var foo = bar');
@@ -30,7 +30,7 @@ describe('string manipulation', () => {
 
 describe('number manipulation', () => {
   test('can edit numbers in object', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({
       a: [
@@ -57,7 +57,7 @@ describe('number manipulation', () => {
   });
 
   test('can edit numbers in arrays', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({
       a: [123],
@@ -74,7 +74,7 @@ describe('number manipulation', () => {
 
 describe('array manipulation', () => {
   test('can edit arrays', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root([]);
     expect(doc.view()).toEqual([]);
@@ -91,7 +91,7 @@ describe('array manipulation', () => {
 
 describe('object manipulation', () => {
   test('can create objects', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({a: {}});
     expect(doc.view()).toEqual({a: {}});
@@ -102,7 +102,7 @@ describe('object manipulation', () => {
   });
 
   test('can delete object keys', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({a: 'a'});
     expect(doc.view()).toEqual({a: 'a'});
@@ -121,7 +121,7 @@ describe('object manipulation', () => {
   });
 
   test('can use ID to insert in object', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root({a: 'a'});
     expect(doc.view()).toEqual({a: 'a'});
@@ -133,7 +133,7 @@ describe('object manipulation', () => {
   });
 
   test('can use ID to insert in array', () => {
-    const doc = Model.withLogicalClock();
+    const doc = Model.create();
     const api = doc.api;
     api.root([1, 2]);
     expect(doc.view()).toEqual([1, 2]);