@kyneta/yjs-schema 1.3.0 → 1.4.0

package/src/__tests__/bind-constraints.test.ts

@@ -1,13 +1,14 @@
-// bind-constraints — compile-time and runtime tests for yjs.bind() caps enforcement.
+// bind-constraints — compile-time and runtime tests for yjs.bind() laws enforcement.
 //
-// Verifies that `yjs.bind()` rejects schemas containing capabilities
-// that Yjs doesn't support (counter, movable, tree, set) at COMPILE TIME
-// via the `RestrictCaps` / `AllowedCaps` mechanism, while accepting
-// capabilities it does support (text) and plain schemas.
+// Verifies that `yjs.bind()` rejects schemas containing composition laws
+// that Yjs doesn't support (additive, positional-ot-move, tree-move,
+// add-wins-per-key) at COMPILE TIME via the `RestrictLaws` / `AllowedLaws`
+// mechanism, while accepting laws it does support (lww, lww-per-key,
+// positional-ot, lww-tag-replaced) and plain schemas.
 
 import {
   type BoundSchema,
-  type ExtractCaps,
+  type ExtractLaws,
   json,
   Schema,
 } from "@kyneta/schema"
@@ -105,36 +106,36 @@ describe("yjs.bind() accepts Yjs-compatible schemas", () => {
 // §2 — Compile-time rejection: schemas that yjs.bind() SHOULD reject
 // ===========================================================================
 
-describe("yjs.bind() rejects schemas with unsupported caps", () => {
-  it("rejects counter", () => {
+describe("yjs.bind() rejects schemas with unsupported composition laws", () => {
+  it("rejects counter (additive not in YjsLaws)", () => {
     const schema = Schema.struct({
       count: Schema.counter(),
     })
-    // @ts-expect-error — counter is not in YjsCaps
+    // @ts-expect-error — "additive" is not in YjsLaws
     yjs.bind(schema)
   })
 
-  it("rejects movableList", () => {
+  it("rejects movableList (positional-ot-move not in YjsLaws)", () => {
     const schema = Schema.struct({
       items: Schema.movableList(Schema.string()),
     })
-    // @ts-expect-error — movable is not in YjsCaps
+    // @ts-expect-error — "positional-ot-move" is not in YjsLaws
     yjs.bind(schema)
   })
 
-  it("rejects tree", () => {
+  it("rejects tree (tree-move not in YjsLaws)", () => {
     const schema = Schema.struct({
       hierarchy: Schema.tree(Schema.struct({ label: Schema.string() })),
     })
-    // @ts-expect-error — tree is not in YjsCaps
+    // @ts-expect-error — "tree-move" is not in YjsLaws
     yjs.bind(schema)
   })
 
-  it("rejects set", () => {
+  it("rejects set (add-wins-per-key not in YjsLaws)", () => {
     const schema = Schema.struct({
       tags: Schema.set(Schema.string()),
     })
-    // @ts-expect-error — set is not in YjsCaps
+    // @ts-expect-error — "add-wins-per-key" is not in YjsLaws
     yjs.bind(schema)
   })
 
@@ -146,7 +147,7 @@ describe("yjs.bind() rejects schemas with unsupported caps", () => {
         }),
       ),
     })
-    // @ts-expect-error — counter is deeply nested but still caught
+    // @ts-expect-error — "additive" is deeply nested but still caught
     yjs.bind(schema)
   })
 
@@ -155,7 +156,7 @@ describe("yjs.bind() rejects schemas with unsupported caps", () => {
       title: Schema.text(),
       views: Schema.counter(),
     })
-    // @ts-expect-error — counter is not in YjsCaps
+    // @ts-expect-error — "additive" is not in YjsLaws
     yjs.bind(schema)
   })
 
@@ -163,7 +164,7 @@ describe("yjs.bind() rejects schemas with unsupported caps", () => {
     const schema = Schema.struct({
       scores: Schema.list(Schema.struct({ value: Schema.counter() })),
     })
-    // @ts-expect-error — counter nested inside list struct
+    // @ts-expect-error — "additive" nested inside list struct
     yjs.bind(schema)
   })
 })
@@ -191,16 +192,24 @@ describe("cross-substrate: universal schema vs substrate-specific schema", () =>
     tasks: Schema.movableList(Schema.struct({ name: Schema.string() })),
   })
 
-  it("universal schema is Yjs-compatible (ExtractCaps check)", () => {
-    type Caps = ExtractCaps<typeof universalSchema>
-    // Only "text" — in YjsCaps
-    expectTypeOf<Caps>().toEqualTypeOf<"text">()
+  it("universal schema is Yjs-compatible (ExtractLaws check)", () => {
+    type Laws = ExtractLaws<typeof universalSchema>
+    // lww-per-key (struct), positional-ot (text, list), lww (scalars) — all in YjsLaws
+    expectTypeOf<Laws>().toEqualTypeOf<
+      "lww-per-key" | "positional-ot" | "lww"
+    >()
   })
 
-  it("Loro-specific schema is NOT Yjs-compatible (ExtractCaps check)", () => {
-    type Caps = ExtractCaps<typeof loroSpecificSchema>
-    // Includes "counter" and "movable" which are NOT in YjsCaps
-    expectTypeOf<Caps>().toEqualTypeOf<"text" | "counter" | "movable">()
+  it("Loro-specific schema is NOT Yjs-compatible (ExtractLaws check)", () => {
+    type Laws = ExtractLaws<typeof loroSpecificSchema>
+    // Includes "additive" and "positional-ot-move" which are NOT in YjsLaws
+    expectTypeOf<Laws>().toEqualTypeOf<
+      | "lww-per-key"
+      | "positional-ot"
+      | "additive"
+      | "positional-ot-move"
+      | "lww"
+    >()
   })
 
   it("universal schema binds to yjs", () => {
@@ -210,11 +219,11 @@ describe("cross-substrate: universal schema vs substrate-specific schema", () =>
   })
 
   it("Loro-specific schema is rejected by yjs.bind()", () => {
-    // @ts-expect-error — counter and movable not in YjsCaps
+    // @ts-expect-error — "additive" and "positional-ot-move" not in YjsLaws
     yjs.bind(loroSpecificSchema)
   })
 
-  it("json.bind() accepts schemas with all caps (AllowedCaps = string)", () => {
+  it("json.bind() accepts schemas with all laws (AllowedLaws = string)", () => {
     const schema = Schema.struct({
       title: Schema.text(),
       count: Schema.counter(),
@@ -262,7 +271,7 @@ describe("bind constraint edge cases", () => {
       ]),
       hits: Schema.counter(),
     })
-    // @ts-expect-error — counter taints the whole schema
+    // @ts-expect-error — "additive" taints the whole schema
     yjs.bind(schema)
   })
 
@@ -276,7 +285,7 @@ describe("bind constraint edge cases", () => {
     expect(bound).toBeDefined()
   })
 
-  it("plain-only schema (no caps at all) is accepted", () => {
+  it("plain-only schema (no laws at all) is accepted", () => {
     const schema = Schema.struct({
       name: Schema.string(),
       age: Schema.number(),

package/src/__tests__/bind-yjs.test.ts

@@ -1,15 +1,25 @@
 import {
   change,
   createRef,
+  deriveIdentity,
   exportEntirety,
   RawPath,
   Schema,
+  SYNC_COLLABORATIVE,
   unwrap,
 } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
 import { yjs } from "../bind-yjs.js"
 
+// ===========================================================================
+// Identity-keying helpers
+// ===========================================================================
+
+function id(fieldName: string): string {
+  return deriveIdentity(fieldName, 1)
+}
+
 // ===========================================================================
 // Helper — createDoc using the generic API
 // ===========================================================================
@@ -45,11 +55,11 @@ describe("yjs.bind", () => {
   // -------------------------------------------------------------------------
 
   describe("BoundSchema", () => {
-    it("creates BoundSchema with collaborative strategy", () => {
+    it("creates BoundSchema with collaborative sync protocol", () => {
       const bound = yjs.bind(TodoSchema)
       expect(bound._brand).toBe("BoundSchema")
       expect(bound.schema).toBe(TodoSchema)
-      expect(bound.strategy).toBe("collaborative")
+      expect(bound.syncProtocol).toEqual(SYNC_COLLABORATIVE)
     })
 
     it("has a factory builder function", () => {
@@ -70,7 +80,10 @@ describe("yjs.bind", () => {
   describe("factory builder", () => {
     it("produces a working SubstrateFactory", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory = bound.factory({ peerId: "peer-1" })
+      const factory = bound.factory({
+        peerId: "peer-1",
+        binding: bound.identityBinding,
+      })
 
       const _substrate = factory.create(SimpleSchema)
 
@@ -87,7 +100,10 @@ describe("yjs.bind", () => {
 
     it("factory supports fromEntirety", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory = bound.factory({ peerId: "peer-1" })
+      const factory = bound.factory({
+        peerId: "peer-1",
+        binding: bound.identityBinding,
+      })
 
       // Create and populate
       const doc1 = createYjsDocFromFactory(factory, SimpleSchema)
@@ -105,7 +121,10 @@ describe("yjs.bind", () => {
 
     it("factory supports parseVersion", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory = bound.factory({ peerId: "peer-1" })
+      const factory = bound.factory({
+        peerId: "peer-1",
+        binding: bound.identityBinding,
+      })
 
       const substrate = factory.create(SimpleSchema)
       const v = substrate.version()
@@ -122,7 +141,10 @@ describe("yjs.bind", () => {
   describe("deterministic clientID", () => {
     it("same peerId produces same clientID across multiple factory calls", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory = bound.factory({ peerId: "stable-peer-id" })
+      const factory = bound.factory({
+        peerId: "stable-peer-id",
+        binding: bound.identityBinding,
+      })
 
       const _s1 = factory.create(SimpleSchema)
       const _s2 = factory.create(SimpleSchema)
@@ -140,8 +162,14 @@ describe("yjs.bind", () => {
 
     it("different peerIds produce different clientIDs", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory1 = bound.factory({ peerId: "peer-alpha" })
-      const factory2 = bound.factory({ peerId: "peer-beta" })
+      const factory1 = bound.factory({
+        peerId: "peer-alpha",
+        binding: bound.identityBinding,
+      })
+      const factory2 = bound.factory({
+        peerId: "peer-beta",
+        binding: bound.identityBinding,
+      })
 
       const doc1 = unwrap(
         createYjsDocFromFactory(factory1, SimpleSchema),
@@ -155,7 +183,10 @@ describe("yjs.bind", () => {
 
     it("clientID is a valid uint32", () => {
       const bound = yjs.bind(SimpleSchema)
-      const factory = bound.factory({ peerId: "test-peer-id-12345" })
+      const factory = bound.factory({
+        peerId: "test-peer-id-12345",
+        binding: bound.identityBinding,
+      })
       const doc = unwrap(
         createYjsDocFromFactory(factory, SimpleSchema),
       ) as Y.Doc
@@ -171,13 +202,19 @@ describe("yjs.bind", () => {
 
       // Simulate two separate "sessions" — both should hash to the same value
       const bound1 = yjs.bind(SimpleSchema)
-      const factory1 = bound1.factory({ peerId })
+      const factory1 = bound1.factory({
+        peerId,
+        binding: bound1.identityBinding,
+      })
       const doc1 = unwrap(
         createYjsDocFromFactory(factory1, SimpleSchema),
       ) as Y.Doc
 
       const bound2 = yjs.bind(SimpleSchema)
-      const factory2 = bound2.factory({ peerId })
+      const factory2 = bound2.factory({
+        peerId,
+        binding: bound2.identityBinding,
+      })
       const doc2 = unwrap(
         createYjsDocFromFactory(factory2, SimpleSchema),
       ) as Y.Doc
@@ -200,7 +237,7 @@ describe("yjs.bind", () => {
       const yjsDoc = unwrap(doc) as Y.Doc
 
       expect(yjsDoc).toBeInstanceOf(Y.Doc)
-      expect(yjsDoc.getMap("root").get("count")).toBe(0)
+      expect(yjsDoc.getMap("root").get(id("count"))).toBe(0)
     })
 
     it("returns a Y.Doc with the correct root map state", () => {
@@ -212,8 +249,8 @@ describe("yjs.bind", () => {
       const yjsDoc = unwrap(doc) as Y.Doc
       const rootMap = yjsDoc.getMap("root")
 
-      expect((rootMap.get("title") as Y.Text).toJSON()).toBe("Hello")
-      expect(rootMap.get("count")).toBe(42)
+      expect((rootMap.get(id("title")) as Y.Text).toJSON()).toBe("Hello")
+      expect(rootMap.get(id("count"))).toBe(42)
     })
 
     it("returns undefined for non-refs (plain object)", () => {
@@ -238,7 +275,7 @@ describe("yjs.bind", () => {
       const yjsDoc = unwrap(doc) as Y.Doc
 
       // Mutate via raw Yjs
-      yjsDoc.getMap("root").set("count", 99)
+      yjsDoc.getMap("root").set(id("count"), 99)
       expect(doc.count()).toBe(99)
     })
 
@@ -249,7 +286,7 @@ describe("yjs.bind", () => {
       })
       const yjsDoc = unwrap(doc) as Y.Doc
 
-      const text = yjsDoc.getMap("root").get("title") as Y.Text
+      const text = yjsDoc.getMap("root").get(id("title")) as Y.Text
       text.insert(5, " World")
       expect(doc.title()).toBe("Hello World")
     })