feat(json-crdt): 🎸 change terminal node interface in proxy API

streamich · streamich · commit 37b3d141932c · 2025-06-30T19:46:41.000+02:00
diff --git a/src/json-crdt-extensions/ModelWithExt.ts b/src/json-crdt-extensions/ModelWithExt.ts
@@ -4,7 +4,6 @@ import {Extensions} from '../json-crdt/extensions/Extensions';
 import {Model} from '../json-crdt/model';
 import type {NodeBuilder} from '../json-crdt-patch';
 import type {SchemaToJsonNode} from '../json-crdt/schema/types';
-import type {JsonNode} from '../json-crdt/nodes';
 
 const extensions = new Extensions();
 
@@ -21,7 +20,7 @@ export class ModelWithExt {
   public static readonly create = <S extends NodeBuilder | unknown>(
     schema?: S,
     sidOrClock: clock.ClockVector | number = Model.sid(),
-  ): Model<S extends NodeBuilder ? SchemaToJsonNode<S> : JsonNode> => {
+  ) => {
     const model = Model.create(schema, sidOrClock);
     model.ext = extensions;
     return model;
diff --git a/src/json-crdt-extensions/mval/__tests__/MvalExt.spec.ts b/src/json-crdt-extensions/mval/__tests__/MvalExt.spec.ts
@@ -8,7 +8,7 @@ test('view should preserve identity', () => {
       mv: mval.new(1),
     }),
   );
-  expect(model.s.mv.toView()).toBe(model.s.mv.toView());
+  expect(model.s.mv.$.view()).toBe(model.s.mv.$.view());
 });
 
 test('can set new values in single fork', () => {
diff --git a/src/json-crdt-extensions/peritext/__tests__/extension.spec.ts b/src/json-crdt-extensions/peritext/__tests__/extension.spec.ts
@@ -16,7 +16,7 @@ const schema = s.obj({
 
 test('view should preserve identity', () => {
   const model = ModelWithExt.create(schema);
-  expect(model.s.nested.obj.text.toView()).toBe(model.s.nested.obj.text.toView());
+  expect(model.s.nested.obj.text.$.view()).toBe(model.s.nested.obj.text.$.view());
 });
 
 describe('non-typed access', () => {
@@ -94,7 +94,7 @@ describe('typed access', () => {
 
   test('can access PeritextApi using parent proxy selector', () => {
     const model = ModelWithExt.create(schema);
-    const api = model.s.nested.obj.text.toApi();
+    const api = model.s.nested.obj.text.$;
     expect(api).toBeInstanceOf(VecApi);
     let node = api.node.ext();
     expect(node).toBeInstanceOf(PeritextNode);
diff --git a/src/json-crdt-extensions/quill-delta/__tests__/extension.spec.ts b/src/json-crdt-extensions/quill-delta/__tests__/extension.spec.ts
@@ -15,7 +15,7 @@ const schema = s.obj({
 
 test('view should preserve identity', () => {
   const model = ModelWithExt.create(schema);
-  expect(model.s.nested.obj.text.toView()).toBe(model.s.nested.obj.text.toView());
+  expect(model.s.nested.obj.text.$.view()).toBe(model.s.nested.obj.text.$.view());
 });
 
 describe('typed access', () => {
@@ -43,7 +43,7 @@ describe('typed access', () => {
 
   test('can access Quill Delta node using parent proxy selector', () => {
     const model = ModelWithExt.create(schema);
-    const api = model.s.nested.obj.text.toApi();
+    const api = model.s.nested.obj.text.$;
     expect(api).toBeInstanceOf(VecApi);
     let node = api.node.ext();
     expect(node).toBeInstanceOf(QuillDeltaNode);
diff --git a/src/json-crdt/__demos__/type-safety.ts b/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.s.toApi() + '');
+console.log(model.s.$ + '');
 // ObjectApi
 // └─ ObjNode 1234.1
 //    ├─ "num"
@@ -74,7 +74,7 @@ console.log(model.s.toApi() + '');
 //              └─ [1]: ValNode 1234.13
 //                      └─ ConNode 1234.12 { false }
 
-console.log(model.s.flags.toApi() + '');
+console.log(model.s.flags.$ + '');
 // ArrApi
 // └─ ArrNode 1234.9
 //    └─ ArrChunk 1234.14!2 len:2
@@ -83,20 +83,20 @@ console.log(model.s.flags.toApi() + '');
 //       └─ [1]: ValNode 1234.13
 //               └─ ConNode 1234.12 { false }
 
-console.log(model.s.flags[1].toApi() + '');
+console.log(model.s.flags[1].$ + '');
 // ValApi
 // └─ ValNode 1234.13
 //    └─ ConNode 1234.12 { false }
 
-console.log(model.s.flags[1].val.toApi() + '');
+console.log(model.s.flags[1].val.$ + '');
 // ConApi
 // └─ ConNode 1234.12 { false }
 
-console.log(model.s.num.toApi() + '');
+console.log(model.s.num.$ + '');
 // ConApi
 // └─ ConNode 1234.2 { 123 }
 
-console.log(model.s.text.toApi() + '');
+console.log(model.s.text.$ + '');
 // StrApi
 // └─ StrNode 1234.3 { "hello" }
 //    └─ StrChunk 1234.4!5 len:5 { "hello" }
diff --git a/src/json-crdt/log/Log.ts b/src/json-crdt/log/Log.ts
@@ -47,7 +47,7 @@ export class Log<N extends JsonNode = JsonNode<any>> implements Printable {
   public static fromNewModel<N extends JsonNode = JsonNode<any>>(model: Model<N>): Log<N> {
     const sid = model.clock.sid;
     const log = new Log<N>(
-      () => Model.create<any>(undefined, sid) as Model<N>,
+      () => Model.create(undefined, sid) as unknown as Model<N>,
     ); /** @todo Maybe provide second arg to `new Log(...)` */
     const api = model.api;
     if (api.builder.patch.ops.length) log.end.applyPatch(api.flush());
diff --git a/src/json-crdt/log/__tests__/Log.spec.ts b/src/json-crdt/log/__tests__/Log.spec.ts
@@ -19,17 +19,17 @@ test('can create a new log from a new model with right starting logical clock',
   const model = Model.create(schema0);
   const sid = model.clock.sid;
   const log = Log.fromNewModel(model);
-  log.end.s.toApi().set({id: s.con('xyz') as any});
+  log.end.s.$.set({id: s.con('xyz') as any});
   log.end.api.flush();
-  log.end.s.age.toApi().set(35);
+  log.end.s.age.$.set(35);
   log.end.api.flush();
-  log.end.s.tags.toApi().del(0, 1);
+  log.end.s.tags.$.del(0, 1);
   log.end.api.flush();
-  log.end.s.name.toApi().del(0, 8);
-  log.end.s.name.toApi().ins(0, 'Va Da');
+  log.end.s.name.$.del(0, 8);
+  log.end.s.name.$.ins(0, 'Va Da');
   log.end.api.flush();
-  log.end.s.tags[0].toApi().del(0, 4);
-  log.end.s.tags[0].toApi().ins(0, 'happy');
+  log.end.s.tags[0].$.del(0, 4);
+  log.end.s.tags[0].$.ins(0, 'happy');
   log.end.api.flush();
   expect(log.start().clock.sid).toBe(sid);
   expect(log.start().clock.time).toBe(1);
diff --git a/src/json-crdt/model/Model.ts b/src/json-crdt/model/Model.ts
@@ -4,7 +4,8 @@ import {encoder, decoder} from '../codec/structural/binary/shared';
 import {ModelApi} from './api';
 import {ORIGIN, SESSION, SYSTEM_SESSION_TIME} from '../../json-crdt-patch/constants';
 import {randomSessionId} from './util';
-import {ConNode, RootNode, ValNode, VecNode, ObjNode, StrNode, BinNode, ArrNode} from '../nodes';
+import {RootNode, ValNode, VecNode, ObjNode, StrNode, BinNode, ArrNode} from '../nodes';
+import {ConNode} from '../nodes/const/ConNode';
 import {printTree} from 'tree-dump/lib/printTree';
 import {Extensions} from '../extensions/Extensions';
 import {AvlMap} from 'sonic-forest/lib/avl/AvlMap';
@@ -132,8 +133,8 @@ export class Model<N extends JsonNode = JsonNode<any>> implements Printable {
           ? new clock.ServerClockVector(SESSION.SERVER, 1)
           : new clock.ClockVector(sidOrClock, 1)
         : sidOrClock;
-    type Node = S extends undefined ? JsonNode : S extends NodeBuilder ? SchemaToJsonNode<S> : SchemaToJsonNode<nodes.json<S>>;
-    const model = new Model<Node>(cl);
+    type Node = undefined extends S ? JsonNode : S extends NodeBuilder ? SchemaToJsonNode<S> : SchemaToJsonNode<nodes.json<S>>;
+    const model: Model<Node> = new Model<Node>(cl);
     if (schema !== void 0) model.setSchema(schema instanceof NodeBuilder ? schema : s.json(schema), true);
     return model;
   };
diff --git a/src/json-crdt/model/__tests__/Model.applyLocalPatch.spec.ts b/src/json-crdt/model/__tests__/Model.applyLocalPatch.spec.ts
@@ -7,9 +7,9 @@ describe('.applyLocalPatch()', () => {
     const doc1 = Model.create(schema);
     const doc2 = doc1.clone();
     const time1 = doc1.clock.time;
-    doc1.s.toApi().set({a: 1});
+    doc1.s.$.set({a: 1});
     const time2 = doc1.clock.time;
-    doc2.s.toApi().set({b: 2});
+    doc2.s.$.set({b: 2});
     const time3 = doc1.clock.time;
     expect(time2 > time1).toBe(true);
     expect(time2).toBe(time3);
@@ -28,9 +28,9 @@ describe('.applyLocalPatch()', () => {
     const doc1 = Model.create(schema);
     const doc2 = doc1.fork();
     const time1 = doc1.clock.time;
-    doc1.s.toApi().set({a: 1});
+    doc1.s.$.set({a: 1});
     const time2 = doc1.clock.time;
-    doc2.s.toApi().set({b: 2});
+    doc2.s.$.set({b: 2});
     const time3 = doc1.clock.time;
     expect(time2 > time1).toBe(true);
     expect(time2).toBe(time3);
diff --git a/src/json-crdt/model/__tests__/Model.cloning.spec.ts b/src/json-crdt/model/__tests__/Model.cloning.spec.ts
@@ -245,9 +245,9 @@ describe('reset()', () => {
       }),
     );
     const doc2 = doc1.fork();
-    doc2.s.text.toApi().ins(4, 'o');
-    const str = doc1.s.text.toApi();
-    expect(str === doc2.s.text.toApi()).toBe(false);
+    doc2.s.text.$.ins(4, 'o');
+    const str = doc1.s.text.$;
+    expect(str === doc2.s.text.$).toBe(false);
     expect(str.view()).toBe('hell');
     doc1.reset(doc2);
     expect(str.view()).toBe('hello');
@@ -260,7 +260,7 @@ describe('reset()', () => {
       }),
     );
     const doc2 = doc1.fork();
-    doc2.s.text.toApi().ins(4, 'o');
+    doc2.s.text.$.ins(4, 'o');
     expect(doc1.clock).toBe(doc1.api.builder.clock);
     expect(doc2.clock).toBe(doc2.api.builder.clock);
     doc1.reset(doc2);
diff --git a/src/json-crdt/model/__tests__/Model.schema.spec.ts b/src/json-crdt/model/__tests__/Model.schema.spec.ts
@@ -10,8 +10,8 @@ describe('.setSchema()', () => {
         con: s.con(123),
       }),
     );
-    expect(model.s.str.toApi().view()).toBe('asdf');
-    expect(model.s.con.toApi().view()).toBe(123);
+    expect(model.s.str.$.view()).toBe('asdf');
+    expect(model.s.con.$.view()).toBe(123);
   });
 
   test('can set map schema', () => {
@@ -21,8 +21,8 @@ describe('.setSchema()', () => {
         con1: s.con(123),
       }),
     );
-    expect(model.s.str.toApi().view()).toBe('asdf');
-    expect(model.s.con1.toApi().view()).toBe(123);
+    expect(model.s.str.$.view()).toBe('asdf');
+    expect(model.s.con1.$.view()).toBe(123);
     expect(model.view().str).toBe('asdf');
     expect(model.view().con1).toBe(123);
     expect(model.view().anyKeyAllowed).toBe(undefined);
diff --git a/src/json-crdt/model/api/__tests__/BinaryApi.spec.ts b/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.api.r.proxy().val.bin.toApi().length()).toBe(3);
+  expect(doc.api.r.proxy().val.bin.$.length()).toBe(3);
 });
diff --git a/src/json-crdt/model/api/__tests__/ModelApi.proxy.spec.ts b/src/json-crdt/model/api/__tests__/ModelApi.proxy.spec.ts
@@ -16,28 +16,28 @@ test('proxy API supports object types', () => {
     bar: 1234,
   });
   const root = model.api.r.proxy();
-  const rootApi = root.toApi();
+  const rootApi = root.$;
   expect(rootApi).toBeInstanceOf(ValApi);
   expect(rootApi.node).toBeInstanceOf(RootNode);
   expect(rootApi.view()).toStrictEqual({
     foo: 'asdf',
     bar: 1234,
   });
   const obj = root.val;
-  const objApi: ObjApi = obj.toApi();
+  const objApi: ObjApi = obj.$;
   expect(objApi).toBeInstanceOf(ObjApi);
   expect(objApi.node).toBeInstanceOf(ObjNode);
   expect(objApi.view()).toStrictEqual({
     foo: 'asdf',
     bar: 1234,
   });
   const foo = obj.foo;
-  const fooApi: StrApi = foo.toApi();
+  const fooApi: StrApi = foo.$;
   expect(fooApi).toBeInstanceOf(StrApi);
   expect(fooApi.node).toBeInstanceOf(StrNode);
   expect(fooApi.view()).toStrictEqual('asdf');
   const bar = obj.bar;
-  const barApi: ConApi = bar.toApi();
+  const barApi: ConApi = bar.$;
   expect(barApi).toBeInstanceOf(ConApi);
   expect(barApi.node).toBeInstanceOf(ConNode);
   expect(barApi.view()).toStrictEqual(1234);
@@ -61,57 +61,57 @@ describe('supports all node types', () => {
   test('object as root node', () => {
     const proxy = model.api.r.proxy();
     const obj = proxy.val;
-    const objApi: ObjApi = obj.toApi();
+    const objApi: ObjApi = obj.$;
     expect(objApi).toBeInstanceOf(ObjApi);
     expect(objApi.node).toBeInstanceOf(ObjNode);
-    expect(obj.toView().obj).not.toBe(undefined);
-    expect(obj.toView().vec).not.toBe(undefined);
+    expect(obj.$.view().obj).not.toBe(undefined);
+    expect(obj.$.view().vec).not.toBe(undefined);
   });
 
   test('nested object', () => {
-    expect(model.s.obj.toApi()).toBeInstanceOf(ObjApi);
-    expect(model.s.obj.toView().str).not.toBe(undefined);
-    expect(model.s.obj.toView().num).not.toBe(undefined);
+    expect(model.s.obj.$).toBeInstanceOf(ObjApi);
+    expect(model.s.obj.$.view().str).not.toBe(undefined);
+    expect(model.s.obj.$.view().num).not.toBe(undefined);
   });
 
   test('str', () => {
-    expect(model.s.obj.str.toApi()).toBeInstanceOf(StrApi);
-    expect(model.s.obj.str.toView()).toStrictEqual('asdf');
+    expect(model.s.obj.str.$).toBeInstanceOf(StrApi);
+    expect(model.s.obj.str.$.view()).toStrictEqual('asdf');
   });
 
   test('bin', () => {
-    expect(model.s.bin.toApi()).toBeInstanceOf(BinApi);
-    expect(model.s.bin.toView()).toStrictEqual(new Uint8Array([1, 2, 3]));
+    expect(model.s.bin.$).toBeInstanceOf(BinApi);
+    expect(model.s.bin.$.view()).toStrictEqual(new Uint8Array([1, 2, 3]));
   });
 
   test('vec', () => {
-    expect(model.s.vec.toApi()).toBeInstanceOf(VecApi);
-    expect(model.s.vec.toView()).toStrictEqual(['asdf', 1234, true, null]);
+    expect(model.s.vec.$).toBeInstanceOf(VecApi);
+    expect(model.s.vec.$.view()).toStrictEqual(['asdf', 1234, true, null]);
   });
 
   test('arr', () => {
-    expect(model.s.arr.toApi()).toBeInstanceOf(ArrApi);
-    expect(model.s.arr.toView()).toStrictEqual(['asdf', 0]);
+    expect(model.s.arr.$).toBeInstanceOf(ArrApi);
+    expect(model.s.arr.$.view()).toStrictEqual(['asdf', 0]);
   });
 
   test('val', () => {
-    expect(model.s.arr[1].toApi()).toBeInstanceOf(ValApi);
-    expect(model.s.arr[1].toView()).toStrictEqual(0);
+    expect(model.s.arr[1].$).toBeInstanceOf(ValApi);
+    expect(model.s.arr[1].$.view()).toStrictEqual(0);
   });
 
   test('con', () => {
-    expect(model.s.arr[0].toApi()).toBeInstanceOf(ConApi);
-    expect(model.s.arr[0].toView()).toStrictEqual('asdf');
+    expect(model.s.arr[0].$).toBeInstanceOf(ConApi);
+    expect(model.s.arr[0].$.view()).toStrictEqual('asdf');
   });
 
   test('con - 2', () => {
-    expect((model.s.arr[1] as ProxyNodeVal<ValNode<ConNode<number>>>).val.toApi()).toBeInstanceOf(ConApi);
-    expect((model.s.arr[1] as ProxyNodeVal<ValNode<ConNode<number>>>).val.toView()).toStrictEqual(0);
+    expect((model.s.arr[1] as ProxyNodeVal<ValNode<ConNode<number>>>).val.$).toBeInstanceOf(ConApi);
+    expect((model.s.arr[1] as ProxyNodeVal<ValNode<ConNode<number>>>).val.$.view()).toStrictEqual(0);
   });
 
   test('con - 3', () => {
-    expect(model.s.obj.num.toApi()).toBeInstanceOf(ConApi);
-    expect(model.s.obj.num.toView()).toStrictEqual(1234);
+    expect(model.s.obj.num.$).toBeInstanceOf(ConApi);
+    expect(model.s.obj.num.$.view()).toStrictEqual(1234);
   });
 });
 
diff --git a/src/json-crdt/model/api/__tests__/StrApi.spec.ts b/src/json-crdt/model/api/__tests__/StrApi.spec.ts
@@ -33,7 +33,7 @@ test('.length()', () => {
       str: s.str('hello world'),
     }),
   );
-  expect(doc.s.str.toApi().length()).toBe(11);
+  expect(doc.s.str.$.length()).toBe(11);
 });
 
 describe('position tracking', () => {
@@ -43,7 +43,7 @@ describe('position tracking', () => {
         str: s.str('hello world'),
       }),
     );
-    const str = doc.s.str.toApi();
+    const str = doc.s.str.$;
     for (let i = -1; i < str.length(); i++) {
       const id = str.findId(i);
       expect(str.findPos(id)).toBe(i);
@@ -56,7 +56,7 @@ describe('position tracking', () => {
         str: s.str('123456'),
       }),
     );
-    const str = doc.s.str.toApi();
+    const str = doc.s.str.$;
     const ids: ITimestampStruct[] = [];
     for (let i = -1; i < str.length(); i++) ids.push(str.findId(i));
     str.ins(3, 'abc');
diff --git a/src/json-crdt/model/api/__tests__/VecApi.spec.ts b/src/json-crdt/model/api/__tests__/VecApi.spec.ts
diff --git a/src/json-crdt/model/api/nodes.ts b/src/json-crdt/model/api/nodes.ts
diff --git a/src/json-crdt/model/api/proxy.ts b/src/json-crdt/model/api/proxy.ts
