@kyneta/yjs-schema 1.1.0 → 1.3.0

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

@@ -0,0 +1,325 @@
+// bind-constraints — compile-time and runtime tests for yjs.bind() caps 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.
+
+import {
+  type BoundSchema,
+  type ExtractCaps,
+  json,
+  Schema,
+} from "@kyneta/schema"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import { yjs } from "../bind-yjs.js"
+
+// ===========================================================================
+// §1 — Compile-time acceptance: schemas that yjs.bind() SHOULD accept
+// ===========================================================================
+
+describe("yjs.bind() accepts Yjs-compatible schemas", () => {
+  it("plain schema (no caps)", () => {
+    const schema = Schema.struct({
+      name: Schema.string(),
+      count: Schema.number(),
+      active: Schema.boolean(),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+    expect(bound.schema).toBe(schema)
+    expectTypeOf(bound).toMatchTypeOf<BoundSchema<typeof schema>>()
+  })
+
+  it("schema with text", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+    expect(bound.schema).toBe(schema)
+  })
+
+  it("schema with text + plain scalars", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      count: Schema.number(),
+      active: Schema.boolean(),
+      tags: Schema.list(Schema.string()),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+
+  it("deeply nested text is accepted", () => {
+    const schema = Schema.struct({
+      channels: Schema.list(
+        Schema.struct({
+          meta: Schema.record(
+            Schema.struct({
+              description: Schema.text(),
+            }),
+          ),
+        }),
+      ),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+
+  it("optional text field alongside plain scalars is accepted", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      draft: Schema.text(),
+      count: Schema.number(),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+
+  it("preserves full schema type through bind()", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      items: Schema.list(
+        Schema.struct({ name: Schema.string(), done: Schema.boolean() }),
+      ),
+    })
+    const bound = yjs.bind(schema)
+    expectTypeOf(bound.schema).toEqualTypeOf(schema)
+  })
+
+  it("json merge boundary is accepted", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      metadata: Schema.struct.json({
+        version: Schema.number(),
+        tags: Schema.list(Schema.string()),
+      }),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+})
+
+// ===========================================================================
+// §2 — Compile-time rejection: schemas that yjs.bind() SHOULD reject
+// ===========================================================================
+
+describe("yjs.bind() rejects schemas with unsupported caps", () => {
+  it("rejects counter", () => {
+    const schema = Schema.struct({
+      count: Schema.counter(),
+    })
+    // @ts-expect-error — counter is not in YjsCaps
+    yjs.bind(schema)
+  })
+
+  it("rejects movableList", () => {
+    const schema = Schema.struct({
+      items: Schema.movableList(Schema.string()),
+    })
+    // @ts-expect-error — movable is not in YjsCaps
+    yjs.bind(schema)
+  })
+
+  it("rejects tree", () => {
+    const schema = Schema.struct({
+      hierarchy: Schema.tree(Schema.struct({ label: Schema.string() })),
+    })
+    // @ts-expect-error — tree is not in YjsCaps
+    yjs.bind(schema)
+  })
+
+  it("rejects set", () => {
+    const schema = Schema.struct({
+      tags: Schema.set(Schema.string()),
+    })
+    // @ts-expect-error — set is not in YjsCaps
+    yjs.bind(schema)
+  })
+
+  it("rejects deeply nested counter", () => {
+    const schema = Schema.struct({
+      items: Schema.list(
+        Schema.struct({
+          meta: Schema.record(Schema.struct({ hits: Schema.counter() })),
+        }),
+      ),
+    })
+    // @ts-expect-error — counter is deeply nested but still caught
+    yjs.bind(schema)
+  })
+
+  it("rejects mix of supported and unsupported (text + counter)", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      views: Schema.counter(),
+    })
+    // @ts-expect-error — counter is not in YjsCaps
+    yjs.bind(schema)
+  })
+
+  it("rejects counter inside list", () => {
+    const schema = Schema.struct({
+      scores: Schema.list(Schema.struct({ value: Schema.counter() })),
+    })
+    // @ts-expect-error — counter nested inside list struct
+    yjs.bind(schema)
+  })
+})
+
+// ===========================================================================
+// §3 — Cross-substrate: same schema, different bind targets
+// ===========================================================================
+
+describe("cross-substrate: universal schema vs substrate-specific schema", () => {
+  // A schema using only universally-supported features
+  const universalSchema = Schema.struct({
+    title: Schema.text(),
+    items: Schema.list(
+      Schema.struct({
+        name: Schema.string(),
+        done: Schema.boolean(),
+      }),
+    ),
+  })
+
+  // A schema using Loro-specific features (counter, movable)
+  const loroSpecificSchema = Schema.struct({
+    title: Schema.text(),
+    count: Schema.counter(),
+    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("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("universal schema binds to yjs", () => {
+    const bound = yjs.bind(universalSchema)
+    expect(bound).toBeDefined()
+    expect(bound.schema).toBe(universalSchema)
+  })
+
+  it("Loro-specific schema is rejected by yjs.bind()", () => {
+    // @ts-expect-error — counter and movable not in YjsCaps
+    yjs.bind(loroSpecificSchema)
+  })
+
+  it("json.bind() accepts schemas with all caps (AllowedCaps = string)", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      count: Schema.counter(),
+      tasks: Schema.movableList(Schema.string()),
+    })
+    const bound = json.bind(schema)
+    expect(bound).toBeDefined()
+    expect(bound.schema).toBe(schema)
+  })
+})
+
+// ===========================================================================
+// §4 — Edge cases: discriminated unions, multiple text fields
+// ===========================================================================
+
+describe("bind constraint edge cases", () => {
+  it("discriminated union with all-plain variants is accepted", () => {
+    const schema = Schema.struct({
+      content: Schema.discriminatedUnion("type", [
+        Schema.struct({
+          type: Schema.string("text"),
+          body: Schema.string(),
+        }),
+        Schema.struct({
+          type: Schema.string("image"),
+          url: Schema.string(),
+        }),
+      ]),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+
+  it("struct with counter alongside plain variants is rejected", () => {
+    const schema = Schema.struct({
+      content: Schema.discriminatedUnion("type", [
+        Schema.struct({
+          type: Schema.string("text"),
+          body: Schema.string(),
+        }),
+        Schema.struct({
+          type: Schema.string("image"),
+          url: Schema.string(),
+        }),
+      ]),
+      hits: Schema.counter(),
+    })
+    // @ts-expect-error — counter taints the whole schema
+    yjs.bind(schema)
+  })
+
+  it("multiple text fields are all accepted", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      body: Schema.text(),
+      summary: Schema.text(),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+
+  it("plain-only schema (no caps at all) is accepted", () => {
+    const schema = Schema.struct({
+      name: Schema.string(),
+      age: Schema.number(),
+      active: Schema.boolean(),
+      tags: Schema.list(Schema.string()),
+      address: Schema.struct({
+        street: Schema.string(),
+        city: Schema.string(),
+      }),
+      metadata: Schema.record(Schema.any()),
+    })
+    const bound = yjs.bind(schema)
+    expect(bound).toBeDefined()
+  })
+})
+
+// ===========================================================================
+// §5 — Root kind rejection: bind() requires a product (struct) root
+// ===========================================================================
+
+describe("yjs.bind() rejects non-product root schemas", () => {
+  it("rejects bare list at root", () => {
+    // @ts-expect-error — SequenceSchema is not ProductSchema
+    yjs.bind(Schema.list(Schema.string()))
+  })
+
+  it("rejects bare record at root", () => {
+    // @ts-expect-error — MapSchema is not ProductSchema
+    yjs.bind(Schema.record(Schema.string()))
+  })
+
+  it("rejects bare text at root", () => {
+    // @ts-expect-error — TextSchema is not ProductSchema
+    yjs.bind(Schema.text())
+  })
+
+  it("rejects bare scalar at root", () => {
+    // @ts-expect-error — ScalarSchema is not ProductSchema
+    yjs.bind(Schema.string())
+  })
+
+  it("rejects list of structs at root", () => {
+    // @ts-expect-error — SequenceSchema<ProductSchema> is still not ProductSchema
+    yjs.bind(Schema.list(Schema.struct({ name: Schema.string() })))
+  })
+})

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

@@ -1,17 +1,27 @@
-import { change, RawPath, Schema } from "@kyneta/schema"
+import {
+  change,
+  createRef,
+  exportEntirety,
+  RawPath,
+  Schema,
+  unwrap,
+} from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
-import { bindYjs } from "../bind-yjs.js"
-import { createYjsDoc } from "../create.js"
-import { yjsSubstrateFactory } from "../substrate.js"
-import { yjs } from "../yjs-escape.js"
+import { yjs } from "../bind-yjs.js"
+
+// ===========================================================================
+// Helper — createDoc using the generic API
+// ===========================================================================
+
+import { createDoc } from "@kyneta/schema"
 
 // ===========================================================================
 // Schemas used across tests
 // ===========================================================================
 
-const TodoSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const TodoSchema = Schema.struct({
+  title: Schema.text(),
   items: Schema.list(
     Schema.struct({
       name: Schema.string(),
@@ -20,8 +30,8 @@ const TodoSchema = Schema.doc({
   ),
 })
 
-const SimpleSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const SimpleSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
 })
 
@@ -29,26 +39,26 @@ const SimpleSchema = Schema.doc({
 // Tests
 // ===========================================================================
 
-describe("bindYjs", () => {
+describe("yjs.bind", () => {
   // -------------------------------------------------------------------------
   // BoundSchema shape
   // -------------------------------------------------------------------------
 
   describe("BoundSchema", () => {
-    it("creates BoundSchema with causal strategy", () => {
-      const bound = bindYjs(TodoSchema)
+    it("creates BoundSchema with collaborative strategy", () => {
+      const bound = yjs.bind(TodoSchema)
       expect(bound._brand).toBe("BoundSchema")
       expect(bound.schema).toBe(TodoSchema)
-      expect(bound.strategy).toBe("causal")
+      expect(bound.strategy).toBe("collaborative")
     })
 
     it("has a factory builder function", () => {
-      const bound = bindYjs(TodoSchema)
+      const bound = yjs.bind(TodoSchema)
       expect(typeof bound.factory).toBe("function")
     })
 
     it("preserves the schema reference", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       expect(bound.schema).toBe(SimpleSchema)
     })
   })
@@ -59,10 +69,10 @@ describe("bindYjs", () => {
 
   describe("factory builder", () => {
     it("produces a working SubstrateFactory", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "peer-1" })
 
-      const substrate = factory.create(SimpleSchema)
+      const _substrate = factory.create(SimpleSchema)
 
       // Populate via the substrate's writable context
       const doc = createYjsDocFromFactory(factory, SimpleSchema)
@@ -76,7 +86,7 @@ describe("bindYjs", () => {
     })
 
     it("factory supports fromEntirety", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "peer-1" })
 
       // Create and populate
@@ -85,8 +95,7 @@ describe("bindYjs", () => {
         d.title.insert(0, "Snap")
         d.count.set(42)
       })
-      const substrate1 = (unwrap as any)(doc1)
-      const snapshot = substrate1.exportEntirety()
+      const snapshot = exportEntirety(doc1)
 
       // Restore
       const substrate2 = factory.fromEntirety(snapshot, SimpleSchema)
@@ -95,7 +104,7 @@ describe("bindYjs", () => {
     })
 
     it("factory supports parseVersion", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "peer-1" })
 
       const substrate = factory.create(SimpleSchema)
@@ -112,34 +121,44 @@ describe("bindYjs", () => {
 
   describe("deterministic clientID", () => {
     it("same peerId produces same clientID across multiple factory calls", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "stable-peer-id" })
 
-      const s1 = factory.create(SimpleSchema)
-      const s2 = factory.create(SimpleSchema)
+      const _s1 = factory.create(SimpleSchema)
+      const _s2 = factory.create(SimpleSchema)
 
       // Both docs should have the same clientID
-      const doc1 = yjs(createYjsDocFromFactory(factory, SimpleSchema))
-      const doc2 = yjs(createYjsDocFromFactory(factory, SimpleSchema))
+      const doc1 = unwrap(
+        createYjsDocFromFactory(factory, SimpleSchema),
+      ) as Y.Doc
+      const doc2 = unwrap(
+        createYjsDocFromFactory(factory, SimpleSchema),
+      ) as Y.Doc
 
       expect(doc1.clientID).toBe(doc2.clientID)
     })
 
     it("different peerIds produce different clientIDs", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory1 = bound.factory({ peerId: "peer-alpha" })
       const factory2 = bound.factory({ peerId: "peer-beta" })
 
-      const doc1 = yjs(createYjsDocFromFactory(factory1, SimpleSchema))
-      const doc2 = yjs(createYjsDocFromFactory(factory2, SimpleSchema))
+      const doc1 = unwrap(
+        createYjsDocFromFactory(factory1, SimpleSchema),
+      ) as Y.Doc
+      const doc2 = unwrap(
+        createYjsDocFromFactory(factory2, SimpleSchema),
+      ) as Y.Doc
 
       expect(doc1.clientID).not.toBe(doc2.clientID)
     })
 
     it("clientID is a valid uint32", () => {
-      const bound = bindYjs(SimpleSchema)
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "test-peer-id-12345" })
-      const doc = yjs(createYjsDocFromFactory(factory, SimpleSchema))
+      const doc = unwrap(
+        createYjsDocFromFactory(factory, SimpleSchema),
+      ) as Y.Doc
 
       expect(typeof doc.clientID).toBe("number")
       expect(doc.clientID).toBeGreaterThanOrEqual(0)
@@ -151,63 +170,72 @@ describe("bindYjs", () => {
       const peerId = "deterministic-check-peer"
 
       // Simulate two separate "sessions" — both should hash to the same value
-      const bound1 = bindYjs(SimpleSchema)
+      const bound1 = yjs.bind(SimpleSchema)
       const factory1 = bound1.factory({ peerId })
-      const doc1 = yjs(createYjsDocFromFactory(factory1, SimpleSchema))
+      const doc1 = unwrap(
+        createYjsDocFromFactory(factory1, SimpleSchema),
+      ) as Y.Doc
 
-      const bound2 = bindYjs(SimpleSchema)
+      const bound2 = yjs.bind(SimpleSchema)
       const factory2 = bound2.factory({ peerId })
-      const doc2 = yjs(createYjsDocFromFactory(factory2, SimpleSchema))
+      const doc2 = unwrap(
+        createYjsDocFromFactory(factory2, SimpleSchema),
+      ) as Y.Doc
 
       expect(doc1.clientID).toBe(doc2.clientID)
     })
   })
 
   // -------------------------------------------------------------------------
-  // yjs() escape hatch
+  // unwrap() escape hatch
   // -------------------------------------------------------------------------
 
-  describe("yjs() escape hatch", () => {
-    it("returns the underlying Y.Doc from a createYjsDoc ref", () => {
-      const doc = createYjsDoc(SimpleSchema)
+  describe("unwrap() escape hatch", () => {
+    it("returns the underlying Y.Doc from a createDoc ref", () => {
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Escape")
         d.count.set(0)
       })
-      const yjsDoc = yjs(doc)
+      const yjsDoc = unwrap(doc) as Y.Doc
 
       expect(yjsDoc).toBeInstanceOf(Y.Doc)
       expect(yjsDoc.getMap("root").get("count")).toBe(0)
     })
 
     it("returns a Y.Doc with the correct root map state", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Hello")
         d.count.set(42)
       })
-      const yjsDoc = yjs(doc)
+      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)
     })
 
-    it("throws for non-Yjs refs (plain object)", () => {
-      expect(() => yjs({})).toThrow("yjs() requires a ref")
+    it("returns undefined for non-refs (plain object)", () => {
+      expect(unwrap({} as any)).toBeUndefined()
     })
 
-    it("throws for non-Yjs refs (random object with properties)", () => {
+    it("returns undefined for non-refs (random object with properties)", () => {
       const fake = {
         title: () => "fake",
         count: () => 0,
       }
-      expect(() => yjs(fake)).toThrow("yjs() requires a ref")
+      expect(unwrap(fake as any)).toBeUndefined()
+    })
+
+    it("throws for primitives", () => {
+      expect(() => unwrap(null as any)).toThrow("unwrap() requires a ref")
+      expect(() => unwrap(undefined as any)).toThrow("unwrap() requires a ref")
     })
 
     it("mutations through escape hatch are visible via kyneta ref", () => {
-      const doc = createYjsDoc(SimpleSchema)
-      const yjsDoc = yjs(doc)
+      const doc = createDoc(yjs.bind(SimpleSchema))
+      const yjsDoc = unwrap(doc) as Y.Doc
 
       // Mutate via raw Yjs
       yjsDoc.getMap("root").set("count", 99)
@@ -215,11 +243,11 @@ describe("bindYjs", () => {
     })
 
     it("text mutations through escape hatch are visible", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Hello")
       })
-      const yjsDoc = yjs(doc)
+      const yjsDoc = unwrap(doc) as Y.Doc
 
       const text = yjsDoc.getMap("root").get("title") as Y.Text
       text.insert(5, " World")
@@ -233,14 +261,6 @@ describe("bindYjs", () => {
 // ===========================================================================
 
 import type { Schema as SchemaType, SubstrateFactory } from "@kyneta/schema"
-import {
-  changefeed,
-  interpret,
-  readable,
-  registerSubstrate,
-  unwrap,
-  writable,
-} from "@kyneta/schema"
 
 /**
  * Helper to create a kyneta ref from a factory (mimicking what exchange.get does).
@@ -251,16 +271,5 @@ function createYjsDocFromFactory(
   schema: SchemaType,
 ): any {
   const substrate = factory.create(schema)
-  const doc: any = (interpret as any)(schema, substrate.context())
-    .with(readable)
-    .with(writable)
-    .with(changefeed)
-    .done()
-
-  // Register for escape hatch — createYjsSubstrate already registered
-  // substrate → Y.Doc internally, but we also need ref → substrate
-  // for unwrap() (used by the yjs() escape hatch).
-  registerSubstrate(doc, substrate)
-
-  return doc
+  return createRef(schema, substrate)
 }