@kyneta/yjs-schema 1.6.1 → 1.8.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 `change()` 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 {
+  change,
+  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
+      change(doc, (d: any) => {
+        d.events.push({ kind: "assistant", body: "" })
+      })
+      change(doc, (d: any) => {
+        d.events.at(1).body.set("hello")
+      })
+    })
+
+    expect(() => {
+      change(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
+      change(doc, (d: any) => {
+        d.items.push({ name: "synthesised" })
+      })
+      observed = (doc.items as any).at(1).name()
+    })
+
+    change(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)
+
+    change(doc, (d: any) => {
+      d.title.insert(0, "Hello")
+      d.items.push({ name: "a", done: false })
+    })
+    change(doc, (d: any) => {
+      d.items.at(0).done.set(true)
+      d.items.push({ name: "b", done: false })
+    })
+    change(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)
+
+    change(doc, (d: any) => {
+      d.config.set({ tags: "ci", retries: 3 })
+    })
+    expect(doc.config()).toEqual({ tags: "ci", retries: 3 })
+
+    change(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)
+
+    change(doc, (d: any) => {
+      d.todos.push({ title: "first", done: false })
+    })
+    change(doc, (d: any) => {
+      d.todos.push({ title: "second", done: false })
+    })
+    expect(doc.todos()).toEqual([
+      { title: "first", done: false },
+      { title: "second", done: false },
+    ])
+
+    change(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)
+
+    change(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" },
+    })
+
+    change(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 change() block appends in order against the CRDT", () => {
+    const schema = Schema.struct({
+      todos: Schema.list(Schema.string()),
+    })
+    const { doc } = build(schema)
+
+    change(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(() => {
+      change(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(() => {
+      change(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

@@ -0,0 +1,227 @@
+// materialize — Tests for materializeYjsShadow.
+//
+// Validates that the Yjs→PlainState materialization produces correct
+// plain JS objects for all supported schema types: text, scalar,
+// sequence, nested struct, and empty documents.
+//
+// Yjs does not support counter, tree, or movableList — those are skipped.
+
+import type { ProductSchema, SchemaBinding } from "@kyneta/schema"
+import {
+  BACKING_DOC,
+  change,
+  createDoc,
+  deriveSchemaBinding,
+  KIND,
+  Schema,
+  type SchemaNode,
+  SUBSTRATE,
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
+import type * as Y from "yjs"
+import { yjs } from "../bind-yjs.js"
+import { materializeYjsShadow } from "../materialize.js"
+
+// ===========================================================================
+// Helpers
+// ===========================================================================
+
+function trivialBinding(schema: SchemaNode): SchemaBinding {
+  if (schema[KIND] === "product") {
+    return deriveSchemaBinding(schema as ProductSchema, {})
+  }
+  return { forward: new Map(), inverse: new Map() }
+}
+
+function getYDoc(docRef: unknown): Y.Doc {
+  const substrate = (docRef as any)[SUBSTRATE]
+  return (substrate as any)[BACKING_DOC] as Y.Doc
+}
+
+// ===========================================================================
+// Test schemas
+// ===========================================================================
+
+const TextSchema = Schema.struct({
+  title: Schema.text(),
+})
+
+const ScalarSchema = Schema.struct({
+  name: Schema.string(),
+  age: Schema.number(),
+  active: Schema.boolean(),
+})
+
+const SequenceSchema = Schema.struct({
+  items: Schema.list(Schema.string()),
+})
+
+const NestedSchema = Schema.struct({
+  meta: Schema.struct({
+    author: Schema.string(),
+    version: Schema.number(),
+  }),
+})
+
+const FullSchema = Schema.struct({
+  title: Schema.text(),
+  theme: Schema.string(),
+  tags: Schema.list(Schema.string()),
+  settings: Schema.struct({
+    darkMode: Schema.boolean(),
+    fontSize: Schema.number(),
+  }),
+})
+
+// ===========================================================================
+// Tests
+// ===========================================================================
+
+describe("materializeYjsShadow", () => {
+  it("materializes text fields", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "hello")
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(TextSchema)
+    const result = materializeYjsShadow(yDoc, TextSchema, binding)
+
+    expect(result).toEqual({ title: "hello" })
+  })
+
+  it("materializes scalar fields", () => {
+    const doc = createDoc(yjs.bind(ScalarSchema))
+    change(doc, (d: any) => {
+      d.name.set("Alice")
+      d.age.set(30)
+      d.active.set(true)
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(ScalarSchema)
+    const result = materializeYjsShadow(yDoc, ScalarSchema, binding)
+
+    expect(result).toEqual({ name: "Alice", age: 30, active: true })
+  })
+
+  it("materializes sequence fields", () => {
+    const doc = createDoc(yjs.bind(SequenceSchema))
+    // Separate change() 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"))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(SequenceSchema)
+    const result = materializeYjsShadow(yDoc, SequenceSchema, binding)
+
+    expect(result).toEqual({ items: ["alpha", "beta", "gamma"] })
+  })
+
+  it("materializes nested struct fields", () => {
+    const doc = createDoc(yjs.bind(NestedSchema))
+    change(doc, (d: any) => {
+      d.meta.author.set("Bob")
+      d.meta.version.set(42)
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(NestedSchema)
+    const result = materializeYjsShadow(yDoc, NestedSchema, binding)
+
+    expect(result).toEqual({
+      meta: { author: "Bob", version: 42 },
+    })
+  })
+
+  it("materializes empty document to structural zeros", () => {
+    const doc = createDoc(yjs.bind(FullSchema))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(FullSchema)
+    const result = materializeYjsShadow(yDoc, FullSchema, binding)
+
+    expect(result).toEqual({
+      title: "",
+      theme: "",
+      tags: [],
+      settings: { darkMode: false, fontSize: 0 },
+    })
+  })
+
+  it("uses raw field names, not identity hashes", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "test")
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(TextSchema)
+    const result = materializeYjsShadow(yDoc, TextSchema, binding)
+
+    // Keys should be the raw field name "title", not an identity hash
+    const keys = Object.keys(result as Record<string, unknown>)
+    expect(keys).toContain("title")
+    expect(keys).toHaveLength(1)
+    // No key should look like a hash (long alphanumeric string)
+    for (const key of keys) {
+      expect(key).toBe("title")
+    }
+  })
+
+  it("materializes a complex document with multiple field types", () => {
+    const doc = createDoc(yjs.bind(FullSchema))
+
+    change(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"))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(FullSchema)
+    const result = materializeYjsShadow(yDoc, FullSchema, binding)
+
+    expect(result).toEqual({
+      title: "My Doc",
+      theme: "dark",
+      tags: ["important", "urgent"],
+      settings: { darkMode: true, fontSize: 16 },
+    })
+  })
+
+  it("materializes without binding (undefined binding)", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "no binding")
+    })
+
+    const yDoc = getYDoc(doc)
+    // Pass no binding — materialize should still work
+    const result = materializeYjsShadow(yDoc, TextSchema)
+
+    // Without binding, keys may be identity hashes — but the values
+    // should still be correct and the result should be an object.
+    expect(result).toBeDefined()
+    expect(typeof result).toBe("object")
+  })
+
+  it("nested nullable materializes to null on fresh doc", () => {
+    const schema = Schema.struct({
+      settings: Schema.struct({
+        theme: Schema.string().nullable(),
+      }),
+    })
+    const doc = createDoc(yjs.bind(schema))
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(schema)
+    const result = materializeYjsShadow(yDoc, schema, binding)
+    expect(result).toEqual({ settings: { theme: null } })
+  })
+})

package/src/__tests__/position.test.ts

@@ -20,7 +20,7 @@ import {
 import {
   type PositionTestEnv,
   positionConformance,
-} from "@kyneta/schema/src/__tests__/position-conformance.js"
+} from "@kyneta/schema/testing"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
 import { ensureContainers } from "../populate.js"
@@ -118,7 +118,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork from doc1's state ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -175,7 +175,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -229,7 +229,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -285,7 +285,7 @@ describe("YjsPosition: concurrent edits", () => {
     // Decode on a different doc that has the same state
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -310,13 +310,13 @@ describe("YjsPosition: concurrent edits", () => {
 
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
     const doc3 = new Y.Doc()
     Y.applyUpdate(doc3, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc3, TextSchema, true)
+    ensureContainers(doc3, TextSchema)
     const substrate3 = createYjsSubstrate(doc3, TextSchema)
     const ref3 = createRef(TextSchema, substrate3) as any