@kyneta/yjs-schema 1.0.0 → 1.2.0

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

@@ -0,0 +1,333 @@
+// 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,15 @@
+import { change, RawPath, Schema } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
-import { Schema, change, RawPath } from "@kyneta/schema"
-import { bindYjs } from "../bind-yjs.js"
-import { yjs } from "../yjs-escape.js"
+import { yjs } from "../bind-yjs.js"
 import { createYjsDoc } from "../create.js"
-import { yjsSubstrateFactory } from "../substrate.js"
 
 // ===========================================================================
 // 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 +18,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 +27,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 +57,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)
@@ -75,8 +73,8 @@ describe("bindYjs", () => {
       expect(doc.count()).toBe(7)
     })
 
-    it("factory supports fromSnapshot", () => {
-      const bound = bindYjs(SimpleSchema)
+    it("factory supports fromEntirety", () => {
+      const bound = yjs.bind(SimpleSchema)
       const factory = bound.factory({ peerId: "peer-1" })
 
       // Create and populate
@@ -86,18 +84,16 @@ describe("bindYjs", () => {
         d.count.set(42)
       })
       const substrate1 = (unwrap as any)(doc1)
-      const snapshot = substrate1.exportSnapshot()
+      const snapshot = substrate1.exportEntirety()
 
       // Restore
-      const substrate2 = factory.fromSnapshot(snapshot, SimpleSchema)
-      expect(substrate2.store.read(RawPath.empty.field("title"))).toBe(
-        "Snap",
-      )
-      expect(substrate2.store.read(RawPath.empty.field("count"))).toBe(42)
+      const substrate2 = factory.fromEntirety(snapshot, SimpleSchema)
+      expect(substrate2.reader.read(RawPath.empty.field("title"))).toBe("Snap")
+      expect(substrate2.reader.read(RawPath.empty.field("count"))).toBe(42)
     })
 
     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)
@@ -114,38 +110,34 @@ 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 = yjs.unwrap(createYjsDocFromFactory(factory, SimpleSchema))
+      const doc2 = yjs.unwrap(createYjsDocFromFactory(factory, SimpleSchema))
 
       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 = yjs.unwrap(createYjsDocFromFactory(factory1, SimpleSchema))
+      const doc2 = yjs.unwrap(createYjsDocFromFactory(factory2, SimpleSchema))
 
       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 = yjs.unwrap(createYjsDocFromFactory(factory, SimpleSchema))
 
       expect(typeof doc.clientID).toBe("number")
       expect(doc.clientID).toBeGreaterThanOrEqual(0)
@@ -157,13 +149,13 @@ 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 = yjs.unwrap(createYjsDocFromFactory(factory1, SimpleSchema))
 
-      const bound2 = bindYjs(SimpleSchema)
+      const bound2 = yjs.bind(SimpleSchema)
       const factory2 = bound2.factory({ peerId })
-      const doc2 = yjs(createYjsDocFromFactory(factory2, SimpleSchema))
+      const doc2 = yjs.unwrap(createYjsDocFromFactory(factory2, SimpleSchema))
 
       expect(doc1.clientID).toBe(doc2.clientID)
     })
@@ -173,14 +165,14 @@ describe("bindYjs", () => {
   // yjs() escape hatch
   // -------------------------------------------------------------------------
 
-  describe("yjs() escape hatch", () => {
+  describe("yjs.unwrap() escape hatch", () => {
     it("returns the underlying Y.Doc from a createYjsDoc ref", () => {
       const doc = createYjsDoc(SimpleSchema)
       change(doc, (d: any) => {
         d.title.insert(0, "Escape")
         d.count.set(0)
       })
-      const yjsDoc = yjs(doc)
+      const yjsDoc = yjs.unwrap(doc)
 
       expect(yjsDoc).toBeInstanceOf(Y.Doc)
       expect(yjsDoc.getMap("root").get("count")).toBe(0)
@@ -192,7 +184,7 @@ describe("bindYjs", () => {
         d.title.insert(0, "Hello")
         d.count.set(42)
       })
-      const yjsDoc = yjs(doc)
+      const yjsDoc = yjs.unwrap(doc)
       const rootMap = yjsDoc.getMap("root")
 
       expect((rootMap.get("title") as Y.Text).toJSON()).toBe("Hello")
@@ -200,7 +192,7 @@ describe("bindYjs", () => {
     })
 
     it("throws for non-Yjs refs (plain object)", () => {
-      expect(() => yjs({})).toThrow("yjs() requires a ref")
+      expect(() => yjs.unwrap({})).toThrow("yjs.unwrap() requires a ref")
     })
 
     it("throws for non-Yjs refs (random object with properties)", () => {
@@ -208,12 +200,12 @@ describe("bindYjs", () => {
         title: () => "fake",
         count: () => 0,
       }
-      expect(() => yjs(fake)).toThrow("yjs() requires a ref")
+      expect(() => yjs.unwrap(fake)).toThrow("yjs.unwrap() requires a ref")
     })
 
     it("mutations through escape hatch are visible via kyneta ref", () => {
       const doc = createYjsDoc(SimpleSchema)
-      const yjsDoc = yjs(doc)
+      const yjsDoc = yjs.unwrap(doc)
 
       // Mutate via raw Yjs
       yjsDoc.getMap("root").set("count", 99)
@@ -225,7 +217,7 @@ describe("bindYjs", () => {
       change(doc, (d: any) => {
         d.title.insert(0, "Hello")
       })
-      const yjsDoc = yjs(doc)
+      const yjsDoc = yjs.unwrap(doc)
 
       const text = yjsDoc.getMap("root").get("title") as Y.Text
       text.insert(5, " World")
@@ -238,9 +230,15 @@ describe("bindYjs", () => {
 // Helper — create a doc via a factory and return a ref with escape hatch
 // ===========================================================================
 
-import { interpret, readable, writable, changefeed, registerSubstrate, unwrap } from "@kyneta/schema"
-import type { SubstrateFactory } from "@kyneta/schema"
-import type { Schema as SchemaType } from "@kyneta/schema"
+import type { Schema as SchemaType, SubstrateFactory } from "@kyneta/schema"
+import {
+  interpret,
+  observation,
+  readable,
+  registerSubstrate,
+  unwrap,
+  writable,
+} from "@kyneta/schema"
 
 /**
  * Helper to create a kyneta ref from a factory (mimicking what exchange.get does).
@@ -254,7 +252,7 @@ function createYjsDocFromFactory(
   const doc: any = (interpret as any)(schema, substrate.context())
     .with(readable)
     .with(writable)
-    .with(changefeed)
+    .with(observation)
     .done()
 
   // Register for escape hatch — createYjsSubstrate already registered
@@ -263,4 +261,4 @@ function createYjsDocFromFactory(
   registerSubstrate(doc, substrate)
 
   return doc
-}
+}