@kyneta/yjs-schema 1.0.0 → 1.2.0

package/src/__tests__/substrate.test.ts

@@ -1,34 +1,27 @@
-import { describe, expect, it, vi } from "vitest"
+import { change, RawPath, Schema, subscribe } from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
-import { Schema, change, subscribe, RawPath } from "@kyneta/schema"
-import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
-import { YjsVersion } from "../version.js"
-import { createYjsDoc, createYjsDocFromSnapshot } from "../create.js"
-import {
-  version,
-  exportSnapshot,
-  exportSince,
-  importDelta,
-} from "../sync.js"
+import { createYjsDoc, createYjsDocFromEntirety } from "../create.js"
 import { ensureContainers } from "../populate.js"
+import { yjsSubstrateFactory } from "../substrate.js"
+import { exportEntirety, exportSince, merge, version } from "../sync.js"
+import { YjsVersion } from "../version.js"
 
 // ===========================================================================
 // Helpers
 // ===========================================================================
 
-
-
 // ===========================================================================
 // Schemas used across tests
 // ===========================================================================
 
-const SimpleSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const SimpleSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   items: Schema.list(Schema.string()),
 })
 
-const StructListSchema = Schema.doc({
+const StructListSchema = Schema.struct({
   tasks: Schema.list(
     Schema.struct({
       name: Schema.string(),
@@ -37,8 +30,8 @@ const StructListSchema = Schema.doc({
   ),
 })
 
-const FullSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const FullSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   active: Schema.boolean(),
   items: Schema.list(Schema.string()),
@@ -66,10 +59,10 @@ describe("YjsSubstrate", () => {
   describe("factory create", () => {
     it("creates a substrate with empty containers", () => {
       const substrate = yjsSubstrateFactory.create(SimpleSchema)
-      expect(substrate.store.read(RawPath.empty.field("title"))).toBe("")
+      expect(substrate.reader.read(RawPath.empty.field("title"))).toBe("")
       // Plain scalars return structural zeros
-      expect(substrate.store.read(RawPath.empty.field("count"))).toBe(0)
-      expect(substrate.store.read(RawPath.empty.field("items"))).toEqual([])
+      expect(substrate.reader.read(RawPath.empty.field("count"))).toBe(0)
+      expect(substrate.reader.read(RawPath.empty.field("items"))).toEqual([])
     })
 
     it("creates a substrate and populates via change()", () => {
@@ -188,8 +181,10 @@ describe("YjsSubstrate", () => {
   describe("export/import snapshot", () => {
     it("exports a binary payload", () => {
       const doc = createYjsDoc(SimpleSchema)
-      change(doc, (d: any) => { d.title.insert(0, "Snapshot") })
-      const payload = exportSnapshot(doc)
+      change(doc, (d: any) => {
+        d.title.insert(0, "Snapshot")
+      })
+      const payload = exportEntirety(doc)
       expect(payload.encoding).toBe("binary")
       expect(payload.data).toBeInstanceOf(Uint8Array)
     })
@@ -207,8 +202,8 @@ describe("YjsSubstrate", () => {
         d.title.insert(5, " World")
       })
 
-      const payload = exportSnapshot(doc1)
-      const doc2 = createYjsDocFromSnapshot(SimpleSchema, payload)
+      const payload = exportEntirety(doc1)
+      const doc2 = createYjsDocFromEntirety(SimpleSchema, payload)
 
       expect(doc2.title()).toBe("Hello World")
       expect(doc2.count()).toBe(42)
@@ -221,13 +216,12 @@ describe("YjsSubstrate", () => {
   // -------------------------------------------------------------------------
 
   describe("delta sync", () => {
-    it("exportSince → importDelta syncs state", () => {
+    it("exportSince → merge syncs state", () => {
       const doc1 = createYjsDoc(SimpleSchema)
-      change(doc1, (d: any) => { d.title.insert(0, "Start") })
-      const doc2 = createYjsDocFromSnapshot(
-        SimpleSchema,
-        exportSnapshot(doc1),
-      )
+      change(doc1, (d: any) => {
+        d.title.insert(0, "Start")
+      })
+      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
 
       const v1Before = version(doc1)
 
@@ -239,17 +233,14 @@ describe("YjsSubstrate", () => {
       const delta = exportSince(doc1, v1Before)
       expect(delta).not.toBeNull()
 
-      importDelta(doc2, delta!)
+      merge(doc2, delta!)
       expect(doc2.title()).toBe("Start Edited")
       expect(doc2.count()).toBe(99)
     })
 
     it("concurrent sync — two substrates converge after bidirectional sync", () => {
       const doc1 = createYjsDoc(SimpleSchema)
-      const doc2 = createYjsDocFromSnapshot(
-        SimpleSchema,
-        exportSnapshot(doc1),
-      )
+      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
 
       const v1Before = version(doc1)
       const v2Before = version(doc2)
@@ -271,8 +262,8 @@ describe("YjsSubstrate", () => {
       const d1to2 = exportSince(doc1, v2Before)
       const d2to1 = exportSince(doc2, v1Before)
 
-      importDelta(doc2, d1to2!)
-      importDelta(doc1, d2to1!)
+      merge(doc2, d1to2!)
+      merge(doc1, d2to1!)
 
       // Should now be equal
       expect(version(doc1).compare(version(doc2))).toBe("equal")
@@ -293,13 +284,12 @@ describe("YjsSubstrate", () => {
   // -------------------------------------------------------------------------
 
   describe("changefeed", () => {
-    it("fires on importDelta", () => {
+    it("fires on merge", () => {
       const doc1 = createYjsDoc(SimpleSchema)
-      change(doc1, (d: any) => { d.title.insert(0, "A") })
-      const doc2 = createYjsDocFromSnapshot(
-        SimpleSchema,
-        exportSnapshot(doc1),
-      )
+      change(doc1, (d: any) => {
+        d.title.insert(0, "A")
+      })
+      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
 
       const v2Before = version(doc2)
 
@@ -313,7 +303,7 @@ describe("YjsSubstrate", () => {
       })
 
       const delta = exportSince(doc1, v2Before)
-      importDelta(doc2, delta!)
+      merge(doc2, delta!)
 
       expect(received.length).toBeGreaterThanOrEqual(1)
       expect(doc2.count()).toBe(42)
@@ -354,19 +344,19 @@ describe("YjsSubstrate", () => {
       expect(received.length).toBe(1)
     })
 
-    it("nested struct field changefeed fires on importDelta", () => {
+    it("nested struct field changefeed fires on merge", () => {
       const doc1 = createYjsDoc(StructListSchema)
-      const doc2 = createYjsDocFromSnapshot(
+      const _doc2 = createYjsDocFromEntirety(
         StructListSchema,
-        exportSnapshot(doc1),
+        exportEntirety(doc1),
       )
 
       // Add a struct item on doc1, sync to doc2
       change(doc1, (d: any) => {
         d.tasks.push({ name: "Buy milk", done: false })
       })
-      const snap = exportSnapshot(doc1)
-      const doc2b = createYjsDocFromSnapshot(StructListSchema, snap)
+      const snap = exportEntirety(doc1)
+      const doc2b = createYjsDocFromEntirety(StructListSchema, snap)
 
       const taskB = [...doc2b.tasks][0] as any
       expect(taskB.done()).toBe(false)
@@ -385,7 +375,7 @@ describe("YjsSubstrate", () => {
 
       // Sync the toggle to doc2b
       const delta = exportSince(doc1, v2)!
-      importDelta(doc2b, delta)
+      merge(doc2b, delta)
 
       // Value should be updated
       expect(taskB.done()).toBe(true)
@@ -396,16 +386,16 @@ describe("YjsSubstrate", () => {
       unsub()
     })
 
-    it("multi-key struct update fires per-field changefeeds on importDelta", () => {
+    it("multi-key struct update fires per-field changefeeds on merge", () => {
       const doc1 = createYjsDoc(StructListSchema)
 
       // Add a struct item, sync to doc2
       change(doc1, (d: any) => {
         d.tasks.push({ name: "Buy milk", done: false })
       })
-      const doc2 = createYjsDocFromSnapshot(
+      const doc2 = createYjsDocFromEntirety(
         StructListSchema,
-        exportSnapshot(doc1),
+        exportEntirety(doc1),
       )
 
       const taskB = [...doc2.tasks][0] as any
@@ -428,7 +418,7 @@ describe("YjsSubstrate", () => {
 
       // Sync to doc2
       const delta = exportSince(doc1, v2)!
-      importDelta(doc2, delta)
+      merge(doc2, delta)
 
       // Both field-level changefeeds should have fired
       expect(nameChanges.length).toBeGreaterThanOrEqual(1)
@@ -522,50 +512,41 @@ describe("YjsSubstrate", () => {
   // Counter annotation throws
   // -------------------------------------------------------------------------
 
-  describe("unsupported annotations", () => {
-    it("counter annotation throws clear error at construction", () => {
-      const CounterSchema = Schema.doc({
-        count: Schema.annotated("counter"),
+  describe("unsupported kinds", () => {
+    it("counter throws clear error at construction", () => {
+      const CounterSchema = Schema.struct({
+        count: Schema.counter(),
       })
 
-      expect(() =>
-        yjsSubstrateFactory.create(CounterSchema),
-      ).toThrow("counter")
+      expect(() => yjsSubstrateFactory.create(CounterSchema)).toThrow("counter")
     })
 
-    it("movable annotation throws clear error at construction", () => {
-      const MovableSchema = Schema.doc({
-        items: Schema.annotated("movable", Schema.list(Schema.string())),
+    it("movableList throws clear error at construction", () => {
+      const MovableSchema = Schema.struct({
+        items: Schema.movableList(Schema.string()),
       })
 
-      expect(() =>
-        yjsSubstrateFactory.create(MovableSchema),
-      ).toThrow("movable")
+      expect(() => yjsSubstrateFactory.create(MovableSchema)).toThrow("movable")
     })
 
-    it("tree annotation throws clear error at construction", () => {
-      const TreeSchema = Schema.doc({
-        tree: Schema.annotated(
-          "tree",
-          Schema.struct({ label: Schema.string() }),
-        ),
+    it("tree throws clear error at construction", () => {
+      const TreeSchema = Schema.struct({
+        tree: Schema.tree(Schema.struct({ label: Schema.string() })),
       })
 
-      expect(() =>
-        yjsSubstrateFactory.create(TreeSchema),
-      ).toThrow("tree")
+      expect(() => yjsSubstrateFactory.create(TreeSchema)).toThrow("tree")
     })
   })
 
   // -------------------------------------------------------------------------
-  // fromSnapshot
+  // fromEntirety
   // -------------------------------------------------------------------------
 
-  describe("fromSnapshot", () => {
+  describe("fromEntirety", () => {
     it("rejects non-binary payloads", () => {
       expect(() =>
-        yjsSubstrateFactory.fromSnapshot(
-          { encoding: "json", data: "{}" },
+        yjsSubstrateFactory.fromEntirety(
+          { kind: "entirety", encoding: "json", data: "{}" },
           SimpleSchema,
         ),
       ).toThrow("binary")
@@ -579,8 +560,8 @@ describe("YjsSubstrate", () => {
         d.items.push("x")
       })
 
-      const payload = exportSnapshot(doc)
-      const doc2 = createYjsDocFromSnapshot(SimpleSchema, payload)
+      const payload = exportEntirety(doc)
+      const doc2 = createYjsDocFromEntirety(SimpleSchema, payload)
 
       expect(doc2.title()).toBe("Snapshot Test")
       expect(doc2.count()).toBe(77)
@@ -601,4 +582,4 @@ describe("YjsSubstrate", () => {
       expect(parsed.compare(v)).toBe("equal")
     })
   })
-})
+})

package/src/__tests__/version.test.ts

@@ -36,7 +36,7 @@ describe("YjsVersion", () => {
     })
 
     it("round-trips a version vector with one peer", () => {
-      const v = versionAfterOps((doc) => {
+      const v = versionAfterOps(doc => {
         doc.getMap("root").set("title", "Hello")
       })
       const serialized = v.serialize()
@@ -66,7 +66,7 @@ describe("YjsVersion", () => {
     })
 
     it("serialized form is a non-empty string", () => {
-      const v = versionAfterOps((doc) => {
+      const v = versionAfterOps(doc => {
         doc.getMap("root").set("count", 42)
       })
       const s = v.serialize()
@@ -89,7 +89,7 @@ describe("YjsVersion", () => {
 
   describe("compare", () => {
     it("returns 'equal' for the same version vector", () => {
-      const v = versionAfterOps((doc) => {
+      const v = versionAfterOps(doc => {
         doc.getMap("root").set("t", "hi")
       })
       expect(v.compare(v)).toBe("equal")
@@ -152,10 +152,7 @@ describe("YjsVersion", () => {
       doc2.getMap("root").set("t", "B")
 
       // Sync doc1 → doc2 only (doc2 knows about both, doc1 only knows itself)
-      const update = Y.encodeStateAsUpdate(
-        doc1,
-        Y.encodeStateVector(doc2),
-      )
+      const update = Y.encodeStateAsUpdate(doc1, Y.encodeStateVector(doc2))
       Y.applyUpdate(doc2, update)
 
       const v1 = new YjsVersion(Y.encodeStateVector(doc1))
@@ -175,14 +172,8 @@ describe("YjsVersion", () => {
       doc2.getMap("root").set("t", "B")
 
       // Bidirectional sync
-      const u1to2 = Y.encodeStateAsUpdate(
-        doc1,
-        Y.encodeStateVector(doc2),
-      )
-      const u2to1 = Y.encodeStateAsUpdate(
-        doc2,
-        Y.encodeStateVector(doc1),
-      )
+      const u1to2 = Y.encodeStateAsUpdate(doc1, Y.encodeStateVector(doc2))
+      const u2to1 = Y.encodeStateAsUpdate(doc2, Y.encodeStateVector(doc1))
       Y.applyUpdate(doc2, u1to2)
       Y.applyUpdate(doc1, u2to1)
 
@@ -196,6 +187,7 @@ describe("YjsVersion", () => {
       const fake = {
         serialize: () => "fake",
         compare: () => "equal" as const,
+        meet: () => fake,
       }
       expect(() => v.compare(fake)).toThrow(
         "YjsVersion can only be compared with another YjsVersion",
@@ -224,4 +216,78 @@ describe("YjsVersion", () => {
       expect(late.compare(earlyParsed)).toBe("ahead")
     })
   })
-})
+
+  // -------------------------------------------------------------------------
+  // meet
+  // -------------------------------------------------------------------------
+
+  describe("YjsVersion.meet()", () => {
+    it("meet of concurrent versions produces component-wise minimum", () => {
+      // Create two docs with independent edits
+      const doc1 = new Y.Doc()
+      const doc2 = new Y.Doc()
+
+      doc1.getMap("root").set("a", 1)
+      doc1.getMap("root").set("b", 2)
+      doc2.getMap("root").set("c", 3)
+
+      const v1 = new YjsVersion(Y.encodeStateVector(doc1))
+      const v2 = new YjsVersion(Y.encodeStateVector(doc2))
+
+      // meet of concurrent versions — result ≤ both
+      const meet = v1.meet(v2) as YjsVersion
+      expect(meet.compare(v1)).not.toBe("ahead")
+      expect(meet.compare(v2)).not.toBe("ahead")
+    })
+
+    it("meet of identical versions returns an equal version", () => {
+      const doc = new Y.Doc()
+      doc.getMap("root").set("x", 1)
+      const v = new YjsVersion(Y.encodeStateVector(doc))
+
+      const meet = v.meet(v) as YjsVersion
+      expect(meet.compare(v)).toBe("equal")
+    })
+
+    it("meet round-trips through Yjs decode correctly", () => {
+      // The custom encodeStateVector must produce bytes that Yjs can decode
+      const doc1 = new Y.Doc()
+      const doc2 = new Y.Doc()
+
+      doc1.getMap("root").set("x", 1)
+      doc1.getMap("root").set("y", 2)
+
+      // Sync doc1 → doc2, then doc2 makes independent edits
+      Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
+      doc2.getMap("root").set("z", 3)
+
+      const v1 = new YjsVersion(Y.encodeStateVector(doc1))
+      const v2 = new YjsVersion(Y.encodeStateVector(doc2))
+
+      // v1 is behind v2 (v2 has all of v1's ops plus its own)
+      expect(v1.compare(v2)).toBe("behind")
+
+      // meet(v1, v2) should equal v1 (the behind one)
+      const meet = v1.meet(v2) as YjsVersion
+      expect(meet.compare(v1)).toBe("equal")
+
+      // The meet's state vector bytes can be decoded by Yjs
+      const decoded = Y.decodeStateVector(meet.sv)
+      expect(decoded.size).toBeGreaterThan(0)
+    })
+
+    it("meet of two behind-ahead versions gives the behind one", () => {
+      const doc = new Y.Doc()
+      doc.getMap("root").set("a", 1)
+      const early = new YjsVersion(Y.encodeStateVector(doc))
+
+      doc.getMap("root").set("b", 2)
+      const late = new YjsVersion(Y.encodeStateVector(doc))
+
+      expect(early.compare(late)).toBe("behind")
+
+      const meet = early.meet(late) as YjsVersion
+      expect(meet.compare(early)).toBe("equal")
+    })
+  })
+})