@kyneta/yjs-schema 1.7.0 → 2.0.0

package/src/__tests__/eager-write-coherence.test.ts

@@ -0,0 +1,321 @@
+// eager-write-coherence — pins the post-Phase-3 contract for the Yjs
+// substrate's write path:
+//
+//   1. Re-entry: subscriber callbacks may freely `batch()` the doc.
+//      Substrate writes land synchronously; both reads (σ via the
+//      Reader) AND subsequent writes (λ via applyChangeToYjs) succeed
+//      against the new state.
+//   2. Projection law: `σ ≡ Π(λ)` holds at every prepare boundary
+//      (asserted via deep-equal between the substrate's reader view
+//      and a fresh `materializeYjsShadow` after a non-trivial
+//      mutation sequence).
+//   3. Json-boundary storage: `struct.json` / `record.json` subtrees
+//      round-trip as plain JSON values in the parent Y.Map entry, not
+//      as nested Y.Map containers.
+//
+// Yjs doesn't need a nested-commit semantics test (4.7) because its
+// native `Y.transact` already collapses re-entrant nesting for free.
+
+import {
+  batch,
+  interpret,
+  observation,
+  readable,
+  Schema,
+  subscribe,
+  unwrap,
+  writable,
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
+import * as Y from "yjs"
+import { materializeYjsShadow } from "../materialize.js"
+import { ensureContainers } from "../populate.js"
+import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+function build<S extends ReturnType<typeof Schema.struct>>(schema: S) {
+  const substrate = yjsSubstrateFactory.create(schema)
+  const doc = interpret(schema, substrate.context())
+    .with(readable)
+    .with(writable)
+    .with(observation)
+    .done() as any
+  return { substrate, doc }
+}
+
+// Unbound variant — bypasses the trivialBinding that identity-keys
+// product fields, so raw-name `materializeYjsShadow(doc, schema)` /
+// `rootMap.get(name)` calls in tests round-trip with the substrate.
+function buildUnbound<S extends ReturnType<typeof Schema.struct>>(schema: S) {
+  const doc = new Y.Doc()
+  ensureContainers(doc, schema)
+  const substrate = createYjsSubstrate(doc, schema)
+  const view = interpret(schema, substrate.context())
+    .with(readable)
+    .with(writable)
+    .with(observation)
+    .done() as any
+  return { substrate, doc: view }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Re-entry — subscriber writes after subscriber push
+// ---------------------------------------------------------------------------
+
+describe("Yjs re-entry: subscriber writes after subscriber push", () => {
+  it("substrate-write timing: push then set inside the just-pushed item", () => {
+    const schema = Schema.struct({
+      events: Schema.list(
+        Schema.struct({ kind: Schema.string(), body: Schema.string() }),
+      ),
+    })
+    const { doc } = build(schema)
+
+    subscribe(doc.events, () => {
+      if ((doc.events as any).length !== 1) return
+      batch(doc, (d: any) => {
+        d.events.push({ kind: "assistant", body: "" })
+      })
+      batch(doc, (d: any) => {
+        d.events.at(1).body.set("hello")
+      })
+    })
+
+    expect(() => {
+      batch(doc, (d: any) => {
+        d.events.push({ kind: "user", body: "hi" })
+      })
+    }).not.toThrow()
+
+    expect((doc.events as any).length).toBe(2)
+    expect((doc.events as any).at(1).body()).toBe("hello")
+  })
+
+  it("read-your-writes: re-entrant read inside subscriber sees just-pushed item", () => {
+    const schema = Schema.struct({
+      items: Schema.list(Schema.struct({ name: Schema.string() })),
+    })
+    const { doc } = build(schema)
+
+    let observed: string | undefined
+    subscribe(doc.items, () => {
+      if ((doc.items as any).length !== 1) return
+      batch(doc, (d: any) => {
+        d.items.push({ name: "synthesised" })
+      })
+      observed = (doc.items as any).at(1).name()
+    })
+
+    batch(doc, (d: any) => {
+      d.items.push({ name: "user" })
+    })
+
+    expect(observed).toBe("synthesised")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Projection law σ ≡ Π(λ)
+// ---------------------------------------------------------------------------
+
+describe("Yjs projection law", () => {
+  it("shadow equals materialized projection of native doc after a mixed mutation sequence", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      items: Schema.list(
+        Schema.struct({ name: Schema.string(), done: Schema.boolean() }),
+      ),
+      meta: Schema.struct.json({
+        tags: Schema.string(),
+        version: Schema.number(),
+      }),
+      peers: Schema.record(Schema.boolean()),
+    })
+    const { doc } = buildUnbound(schema)
+
+    batch(doc, (d: any) => {
+      d.title.insert(0, "Hello")
+      d.items.push({ name: "a", done: false })
+    })
+    batch(doc, (d: any) => {
+      d.items.at(0).done.set(true)
+      d.items.push({ name: "b", done: false })
+    })
+    batch(doc, (d: any) => {
+      d.meta.set({ tags: "kyneta", version: 2 })
+      d.peers.set("alice", true)
+      d.peers.set("bob", false)
+    })
+
+    const nativeDoc = unwrap(doc) as Y.Doc
+    const projected = materializeYjsShadow(nativeDoc, schema)
+    expect(projected).toEqual({
+      title: "Hello",
+      items: [
+        { name: "a", done: true },
+        { name: "b", done: false },
+      ],
+      meta: { tags: "kyneta", version: 2 },
+      peers: { alice: true, bob: false },
+    })
+    expect((doc.title as any)()).toBe("Hello")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. JSON boundary: plain JS values in the parent Y.Map entry
+// ---------------------------------------------------------------------------
+
+describe("Yjs json-boundary storage", () => {
+  it("struct.json field stores a plain JS value at the parent boundary key", () => {
+    const schema = Schema.struct({
+      config: Schema.struct.json({
+        tags: Schema.string(),
+        retries: Schema.number(),
+      }),
+    })
+    const { doc } = build(schema)
+
+    batch(doc, (d: any) => {
+      d.config.set({ tags: "ci", retries: 3 })
+    })
+    expect(doc.config()).toEqual({ tags: "ci", retries: 3 })
+
+    batch(doc, (d: any) => {
+      d.config.tags.set("prod")
+    })
+    expect(doc.config()).toEqual({ tags: "prod", retries: 3 })
+
+    // Direct CRDT inspection: the boundary slot in the root Y.Map
+    // holds a plain JS object — NOT a Y.Map. Yjs Y.Map instances
+    // would respond to `instanceof Y.Map`.
+    const native = unwrap(doc) as Y.Doc
+    const rootMap = native.getMap("root")
+    const rootKeys: string[] = []
+    rootMap.forEach((_v, k) => {
+      rootKeys.push(k)
+    })
+    expect(rootKeys.length).toBe(1)
+    const key = rootKeys[0]
+    if (key === undefined) throw new Error("rootKeys[0] missing")
+    const value = rootMap.get(key)
+    expect(value).toEqual({ tags: "prod", retries: 3 })
+    expect(value instanceof Y.Map).toBe(false)
+  })
+
+  it("list.json items round-trip and replace cleanly on field-inside-item writes", () => {
+    const schema = Schema.struct({
+      todos: Schema.list.json(
+        Schema.struct({ title: Schema.string(), done: Schema.boolean() }),
+      ),
+    })
+    const { doc } = build(schema)
+
+    batch(doc, (d: any) => {
+      d.todos.push({ title: "first", done: false })
+    })
+    batch(doc, (d: any) => {
+      d.todos.push({ title: "second", done: false })
+    })
+    expect(doc.todos()).toEqual([
+      { title: "first", done: false },
+      { title: "second", done: false },
+    ])
+
+    batch(doc, (d: any) => {
+      d.todos.at(0).done.set(true)
+    })
+    expect(doc.todos()).toEqual([
+      { title: "first", done: true },
+      { title: "second", done: false },
+    ])
+  })
+
+  it("record.json entries round-trip through the json-boundary path", () => {
+    const schema = Schema.struct({
+      profiles: Schema.record.json(Schema.struct({ email: Schema.string() })),
+    })
+    const { doc } = build(schema)
+
+    batch(doc, (d: any) => {
+      d.profiles.set("alice", { email: "alice@example.com" })
+      d.profiles.set("bob", { email: "bob@example.com" })
+    })
+    expect(doc.profiles()).toEqual({
+      alice: { email: "alice@example.com" },
+      bob: { email: "bob@example.com" },
+    })
+
+    batch(doc, (d: any) => {
+      d.profiles.at("alice").email.set("alice@new.example.com")
+    })
+    expect(doc.profiles()).toEqual({
+      alice: { email: "alice@new.example.com" },
+      bob: { email: "bob@example.com" },
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Three-primitive-substrate (jj:ryquprut): read-your-writes carries through
+// to Yjs; abort produces one batched native event with net-zero delta.
+// ---------------------------------------------------------------------------
+
+describe("Yjs three-primitive substrate (jj:ryquprut)", () => {
+  it("multi-push in one batch() block appends in order against the CRDT", () => {
+    const schema = Schema.struct({
+      todos: Schema.list(Schema.string()),
+    })
+    const { doc } = build(schema)
+
+    batch(doc, (d: any) => {
+      d.todos.push("a")
+      d.todos.push("b")
+      d.todos.push("c")
+    })
+
+    expect((doc.todos as any)()).toEqual(["a", "b", "c"])
+  })
+
+  it("abort restores state on outermost throw", () => {
+    const schema = Schema.struct({
+      a: Schema.string(),
+      b: Schema.string(),
+    })
+    const { doc } = build(schema)
+
+    expect(() => {
+      batch(doc, (d: any) => {
+        d.a.set("set-a")
+        d.b.set("set-b")
+        throw new Error("abort")
+      })
+    }).toThrow("abort")
+
+    expect((doc.a as any)()).toBe("")
+    expect((doc.b as any)()).toBe("")
+  })
+
+  it("abort fires one Changeset with aborted: true on the Yjs stack", () => {
+    const schema = Schema.struct({ a: Schema.string() })
+    const { doc } = build(schema)
+
+    let aborted = false
+    subscribe(doc.a, (cs: any) => {
+      if (cs.aborted) aborted = true
+    })
+
+    expect(() => {
+      batch(doc, (d: any) => {
+        d.a.set("hello")
+        throw new Error("abort")
+      })
+    }).toThrow("abort")
+
+    expect(aborted).toBe(true)
+    expect((doc.a as any)()).toBe("")
+  })
+})

package/src/__tests__/materialize.test.ts

@@ -9,7 +9,7 @@
 import type { ProductSchema, SchemaBinding } from "@kyneta/schema"
 import {
   BACKING_DOC,
-  change,
+  batch,
   createDoc,
   deriveSchemaBinding,
   KIND,
@@ -80,7 +80,7 @@ const FullSchema = Schema.struct({
 describe("materializeYjsShadow", () => {
   it("materializes text fields", () => {
     const doc = createDoc(yjs.bind(TextSchema))
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.title.insert(0, "hello")
     })
 
@@ -93,7 +93,7 @@ describe("materializeYjsShadow", () => {
 
   it("materializes scalar fields", () => {
     const doc = createDoc(yjs.bind(ScalarSchema))
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.name.set("Alice")
       d.age.set(30)
       d.active.set(true)
@@ -108,11 +108,11 @@ describe("materializeYjsShadow", () => {
 
   it("materializes sequence fields", () => {
     const doc = createDoc(yjs.bind(SequenceSchema))
-    // Separate change() calls for list pushes to preserve order
+    // Separate batch() calls for list pushes to preserve order
     // (Yjs reverses order within a single transaction)
-    change(doc, (d: any) => d.items.push("alpha"))
-    change(doc, (d: any) => d.items.push("beta"))
-    change(doc, (d: any) => d.items.push("gamma"))
+    batch(doc, (d: any) => d.items.push("alpha"))
+    batch(doc, (d: any) => d.items.push("beta"))
+    batch(doc, (d: any) => d.items.push("gamma"))
 
     const yDoc = getYDoc(doc)
     const binding = trivialBinding(SequenceSchema)
@@ -123,7 +123,7 @@ describe("materializeYjsShadow", () => {
 
   it("materializes nested struct fields", () => {
     const doc = createDoc(yjs.bind(NestedSchema))
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.meta.author.set("Bob")
       d.meta.version.set(42)
     })
@@ -154,7 +154,7 @@ describe("materializeYjsShadow", () => {
 
   it("uses raw field names, not identity hashes", () => {
     const doc = createDoc(yjs.bind(TextSchema))
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.title.insert(0, "test")
     })
 
@@ -175,14 +175,14 @@ describe("materializeYjsShadow", () => {
   it("materializes a complex document with multiple field types", () => {
     const doc = createDoc(yjs.bind(FullSchema))
 
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.title.insert(0, "My Doc")
       d.theme.set("dark")
       d.settings.darkMode.set(true)
       d.settings.fontSize.set(16)
     })
-    change(doc, (d: any) => d.tags.push("important"))
-    change(doc, (d: any) => d.tags.push("urgent"))
+    batch(doc, (d: any) => d.tags.push("important"))
+    batch(doc, (d: any) => d.tags.push("urgent"))
 
     const yDoc = getYDoc(doc)
     const binding = trivialBinding(FullSchema)
@@ -198,7 +198,7 @@ describe("materializeYjsShadow", () => {
 
   it("materializes without binding (undefined binding)", () => {
     const doc = createDoc(yjs.bind(TextSchema))
-    change(doc, (d: any) => {
+    batch(doc, (d: any) => {
       d.title.insert(0, "no binding")
     })
 

package/src/__tests__/position.test.ts

@@ -8,7 +8,7 @@
 //         resolve correctly on the converged state.
 
 import {
-  change,
+  batch,
   createRef,
   hasPosition,
   type Instruction,
@@ -55,7 +55,7 @@ function createYjsEnv(initialText: string): PositionTestEnv {
 
   // Seed the initial text content
   if (initialText.length > 0) {
-    change(ref, (d: any) => {
+    batch(ref, (d: any) => {
       d.title.insert(0, initialText)
     })
   }
@@ -71,7 +71,7 @@ function createYjsEnv(initialText: string): PositionTestEnv {
     positions,
 
     insert(index: number, text: string): readonly Instruction[] {
-      const ops = change(ref, (d: any) => {
+      const ops = batch(ref, (d: any) => {
         d.title.insert(index, text)
       })
       const textOp = ops.find(op => isTextChange(op.change))
@@ -82,7 +82,7 @@ function createYjsEnv(initialText: string): PositionTestEnv {
     },
 
     delete(index: number, count: number): readonly Instruction[] {
-      const ops = change(ref, (d: any) => {
+      const ops = batch(ref, (d: any) => {
         d.title.delete(index, count)
       })
       const textOp = ops.find(op => isTextChange(op.change))
@@ -111,7 +111,7 @@ describe("YjsPosition: concurrent edits", () => {
     ensureContainers(doc1, TextSchema)
     const substrate1 = createYjsSubstrate(doc1, TextSchema)
     const ref1 = createRef(TextSchema, substrate1) as any
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "hello")
     })
 
@@ -136,10 +136,10 @@ describe("YjsPosition: concurrent edits", () => {
     const pos2 = textRef2[POSITION].createPosition(4, "left") // before "o"
 
     // --- Concurrent edits ---
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "AA") // doc1: "AAhello"
     })
-    change(ref2, (d: any) => {
+    batch(ref2, (d: any) => {
       d.title.insert(5, "BB") // doc2: "helloBBo"
     })
 
@@ -168,7 +168,7 @@ describe("YjsPosition: concurrent edits", () => {
     ensureContainers(doc1, TextSchema)
     const substrate1 = createYjsSubstrate(doc1, TextSchema)
     const ref1 = createRef(TextSchema, substrate1) as any
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "abc")
     })
 
@@ -190,10 +190,10 @@ describe("YjsPosition: concurrent edits", () => {
     const rightPos = textRef2[POSITION].createPosition(1, "right")
 
     // --- Both insert at index 1 concurrently ---
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(1, "X")
     })
-    change(ref2, (d: any) => {
+    batch(ref2, (d: any) => {
       d.title.insert(1, "Y")
     })
 
@@ -222,7 +222,7 @@ describe("YjsPosition: concurrent edits", () => {
     ensureContainers(doc1, TextSchema)
     const substrate1 = createYjsSubstrate(doc1, TextSchema)
     const ref1 = createRef(TextSchema, substrate1) as any
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "abcde")
     })
 
@@ -240,7 +240,7 @@ describe("YjsPosition: concurrent edits", () => {
     expect(pos.resolve()).toBe(3)
 
     // Doc2 deletes the range covering position 3
-    change(ref2, (d: any) => {
+    batch(ref2, (d: any) => {
       d.title.delete(1, 3) // "ae"
     })
 
@@ -255,7 +255,7 @@ describe("YjsPosition: concurrent edits", () => {
     expect(afterDelete!).toBeLessThanOrEqual(ref1.title().length)
 
     // Now insert new content near the collapsed position
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(1, "XYZ")
     })
 
@@ -272,7 +272,7 @@ describe("YjsPosition: concurrent edits", () => {
     ensureContainers(doc1, TextSchema)
     const substrate1 = createYjsSubstrate(doc1, TextSchema)
     const ref1 = createRef(TextSchema, substrate1) as any
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "hello world")
     })
 
@@ -304,7 +304,7 @@ describe("YjsPosition: concurrent edits", () => {
     ensureContainers(doc1, TextSchema)
     const substrate1 = createYjsSubstrate(doc1, TextSchema)
     const ref1 = createRef(TextSchema, substrate1) as any
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "0123456789")
     })
 
@@ -334,13 +334,13 @@ describe("YjsPosition: concurrent edits", () => {
     const posC = t3[POSITION].createPosition(8, "right")
 
     // Concurrent edits from all three peers
-    change(ref1, (d: any) => {
+    batch(ref1, (d: any) => {
       d.title.insert(0, "AA")
     })
-    change(ref2, (d: any) => {
+    batch(ref2, (d: any) => {
       d.title.insert(5, "BB")
     })
-    change(ref3, (d: any) => {
+    batch(ref3, (d: any) => {
       d.title.delete(7, 2)
     })