@kyneta/yjs-schema 1.1.0 → 1.3.0

package/src/__tests__/substrate.test.ts

@@ -1,10 +1,20 @@
-import { change, RawPath, Schema, subscribe } from "@kyneta/schema"
-import { describe, expect, it, vi } from "vitest"
+import {
+  change,
+  createDoc,
+  createRef,
+  exportEntirety,
+  exportSince,
+  merge,
+  RawPath,
+  Schema,
+  subscribe,
+  version,
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
-import { createYjsDoc, createYjsDocFromEntirety } from "../create.js"
+import { yjs } from "../bind-yjs.js"
 import { ensureContainers } from "../populate.js"
 import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
-import { exportEntirety, exportSince, merge, version } from "../sync.js"
 import { YjsVersion } from "../version.js"
 
 // ===========================================================================
@@ -15,13 +25,13 @@ import { YjsVersion } from "../version.js"
 // Schemas used across tests
 // ===========================================================================
 
-const SimpleSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const SimpleSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   items: Schema.list(Schema.string()),
 })
 
-const StructListSchema = Schema.doc({
+const StructListSchema = Schema.struct({
   tasks: Schema.list(
     Schema.struct({
       name: Schema.string(),
@@ -30,8 +40,8 @@ const StructListSchema = Schema.doc({
   ),
 })
 
-const FullSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const FullSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   active: Schema.boolean(),
   items: Schema.list(Schema.string()),
@@ -66,7 +76,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("creates a substrate and populates via change()", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Hello")
         d.count.set(42)
@@ -81,7 +91,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("creates a substrate with partial values (unset fields stay empty)", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Partial")
       })
@@ -91,7 +101,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("creates a substrate with nested struct values via change()", () => {
-      const doc = createYjsDoc(FullSchema)
+      const doc = createDoc(yjs.bind(FullSchema))
       change(doc, (d: any) => {
         d.meta.author.set("Alice")
       })
@@ -99,7 +109,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("creates a substrate with struct list values via change()", () => {
-      const doc = createYjsDoc(StructListSchema)
+      const doc = createDoc(yjs.bind(StructListSchema))
       // Separate change() calls for list pushes to preserve order
       change(doc, (d: any) => d.tasks.push({ name: "Task 1", done: false }))
       change(doc, (d: any) => d.tasks.push({ name: "Task 2", done: true }))
@@ -114,7 +124,7 @@ describe("YjsSubstrate", () => {
 
   describe("write round-trip", () => {
     it("text insert round-trips through prepare/flush", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Hello")
       })
@@ -122,7 +132,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("scalar set round-trips through prepare/flush", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.count.set(42)
       })
@@ -130,7 +140,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("list push round-trips through prepare/flush", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.items.push("a")
       })
@@ -148,7 +158,7 @@ describe("YjsSubstrate", () => {
 
   describe("version tracking", () => {
     it("version advances after mutations", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       const v1 = version(doc)
 
       change(doc, (d: any) => {
@@ -161,7 +171,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("version serialize/parse round-trips", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Test")
         d.count.set(5)
@@ -180,7 +190,7 @@ describe("YjsSubstrate", () => {
 
   describe("export/import snapshot", () => {
     it("exports a binary payload", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Snapshot")
       })
@@ -190,7 +200,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("reconstructs equivalent state from snapshot", () => {
-      const doc1 = createYjsDoc(SimpleSchema)
+      const doc1 = createDoc(yjs.bind(SimpleSchema))
       change(doc1, (d: any) => {
         d.title.insert(0, "Hello")
         d.count.set(42)
@@ -203,7 +213,7 @@ describe("YjsSubstrate", () => {
       })
 
       const payload = exportEntirety(doc1)
-      const doc2 = createYjsDocFromEntirety(SimpleSchema, payload)
+      const doc2 = createDoc(yjs.bind(SimpleSchema), payload)
 
       expect(doc2.title()).toBe("Hello World")
       expect(doc2.count()).toBe(42)
@@ -217,11 +227,11 @@ describe("YjsSubstrate", () => {
 
   describe("delta sync", () => {
     it("exportSince → merge syncs state", () => {
-      const doc1 = createYjsDoc(SimpleSchema)
+      const doc1 = createDoc(yjs.bind(SimpleSchema))
       change(doc1, (d: any) => {
         d.title.insert(0, "Start")
       })
-      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
+      const doc2 = createDoc(yjs.bind(SimpleSchema), exportEntirety(doc1))
 
       const v1Before = version(doc1)
 
@@ -239,8 +249,8 @@ describe("YjsSubstrate", () => {
     })
 
     it("concurrent sync — two substrates converge after bidirectional sync", () => {
-      const doc1 = createYjsDoc(SimpleSchema)
-      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
+      const doc1 = createDoc(yjs.bind(SimpleSchema))
+      const doc2 = createDoc(yjs.bind(SimpleSchema), exportEntirety(doc1))
 
       const v1Before = version(doc1)
       const v2Before = version(doc2)
@@ -285,11 +295,11 @@ describe("YjsSubstrate", () => {
 
   describe("changefeed", () => {
     it("fires on merge", () => {
-      const doc1 = createYjsDoc(SimpleSchema)
+      const doc1 = createDoc(yjs.bind(SimpleSchema))
       change(doc1, (d: any) => {
         d.title.insert(0, "A")
       })
-      const doc2 = createYjsDocFromEntirety(SimpleSchema, exportEntirety(doc1))
+      const doc2 = createDoc(yjs.bind(SimpleSchema), exportEntirety(doc1))
 
       const v2Before = version(doc2)
 
@@ -312,7 +322,10 @@ describe("YjsSubstrate", () => {
     it("fires on external Y.Doc mutation (raw Yjs API)", () => {
       const yjsDoc = new Y.Doc()
       ensureContainers(yjsDoc, SimpleSchema)
-      const doc = createYjsDoc(SimpleSchema, yjsDoc)
+      const doc = createRef(
+        SimpleSchema,
+        createYjsSubstrate(yjsDoc, SimpleSchema),
+      )
 
       const received: any[] = []
       subscribe(doc, (changeset: any) => {
@@ -328,7 +341,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("no double-fire on kyneta local writes", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
 
       const received: any[] = []
       subscribe(doc, (changeset: any) => {
@@ -345,18 +358,15 @@ describe("YjsSubstrate", () => {
     })
 
     it("nested struct field changefeed fires on merge", () => {
-      const doc1 = createYjsDoc(StructListSchema)
-      const doc2 = createYjsDocFromEntirety(
-        StructListSchema,
-        exportEntirety(doc1),
-      )
+      const doc1 = createDoc(yjs.bind(StructListSchema))
+      const _doc2 = createDoc(yjs.bind(StructListSchema), exportEntirety(doc1))
 
       // Add a struct item on doc1, sync to doc2
       change(doc1, (d: any) => {
         d.tasks.push({ name: "Buy milk", done: false })
       })
       const snap = exportEntirety(doc1)
-      const doc2b = createYjsDocFromEntirety(StructListSchema, snap)
+      const doc2b = createDoc(yjs.bind(StructListSchema), snap)
 
       const taskB = [...doc2b.tasks][0] as any
       expect(taskB.done()).toBe(false)
@@ -387,16 +397,13 @@ describe("YjsSubstrate", () => {
     })
 
     it("multi-key struct update fires per-field changefeeds on merge", () => {
-      const doc1 = createYjsDoc(StructListSchema)
+      const doc1 = createDoc(yjs.bind(StructListSchema))
 
       // Add a struct item, sync to doc2
       change(doc1, (d: any) => {
         d.tasks.push({ name: "Buy milk", done: false })
       })
-      const doc2 = createYjsDocFromEntirety(
-        StructListSchema,
-        exportEntirety(doc1),
-      )
+      const doc2 = createDoc(yjs.bind(StructListSchema), exportEntirety(doc1))
 
       const taskB = [...doc2.tasks][0] as any
       const v2 = version(doc2)
@@ -438,7 +445,7 @@ describe("YjsSubstrate", () => {
 
   describe("transaction support", () => {
     it("multi-op change() is atomic", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
 
       const received: any[] = []
       subscribe(doc, (changeset: any) => {
@@ -474,7 +481,7 @@ describe("YjsSubstrate", () => {
 
   describe("nested structure", () => {
     it("push struct into list, read back via navigation", () => {
-      const doc = createYjsDoc(StructListSchema)
+      const doc = createDoc(yjs.bind(StructListSchema))
 
       change(doc, (d: any) => {
         d.tasks.push({ name: "Task 1", done: false })
@@ -494,7 +501,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("nested struct write round-trip", () => {
-      const doc = createYjsDoc(FullSchema)
+      const doc = createDoc(yjs.bind(FullSchema))
       change(doc, (d: any) => {
         d.meta.author.set("Alice")
       })
@@ -512,29 +519,26 @@ describe("YjsSubstrate", () => {
   // Counter annotation throws
   // -------------------------------------------------------------------------
 
-  describe("unsupported annotations", () => {
-    it("counter annotation throws clear error at construction", () => {
-      const CounterSchema = Schema.doc({
-        count: Schema.annotated("counter"),
+  describe("unsupported kinds", () => {
+    it("counter throws clear error at construction", () => {
+      const CounterSchema = Schema.struct({
+        count: Schema.counter(),
       })
 
       expect(() => yjsSubstrateFactory.create(CounterSchema)).toThrow("counter")
     })
 
-    it("movable annotation throws clear error at construction", () => {
-      const MovableSchema = Schema.doc({
-        items: Schema.annotated("movable", Schema.list(Schema.string())),
+    it("movableList throws clear error at construction", () => {
+      const MovableSchema = Schema.struct({
+        items: Schema.movableList(Schema.string()),
       })
 
       expect(() => yjsSubstrateFactory.create(MovableSchema)).toThrow("movable")
     })
 
-    it("tree annotation throws clear error at construction", () => {
-      const TreeSchema = Schema.doc({
-        tree: Schema.annotated(
-          "tree",
-          Schema.struct({ label: Schema.string() }),
-        ),
+    it("tree throws clear error at construction", () => {
+      const TreeSchema = Schema.struct({
+        tree: Schema.tree(Schema.struct({ label: Schema.string() })),
       })
 
       expect(() => yjsSubstrateFactory.create(TreeSchema)).toThrow("tree")
@@ -556,7 +560,7 @@ describe("YjsSubstrate", () => {
     })
 
     it("reconstructs from snapshot with correct state", () => {
-      const doc = createYjsDoc(SimpleSchema)
+      const doc = createDoc(yjs.bind(SimpleSchema))
       change(doc, (d: any) => {
         d.title.insert(0, "Snapshot Test")
         d.count.set(77)
@@ -564,7 +568,7 @@ describe("YjsSubstrate", () => {
       })
 
       const payload = exportEntirety(doc)
-      const doc2 = createYjsDocFromEntirety(SimpleSchema, payload)
+      const doc2 = createDoc(yjs.bind(SimpleSchema), payload)
 
       expect(doc2.title()).toBe("Snapshot Test")
       expect(doc2.count()).toBe(77)

package/src/__tests__/version.test.ts

@@ -187,6 +187,7 @@ describe("YjsVersion", () => {
       const fake = {
         serialize: () => "fake",
         compare: () => "equal" as const,
+        meet: () => fake,
       }
       expect(() => v.compare(fake)).toThrow(
         "YjsVersion can only be compared with another YjsVersion",
@@ -215,4 +216,78 @@ describe("YjsVersion", () => {
       expect(late.compare(earlyParsed)).toBe("ahead")
     })
   })
+
+  // -------------------------------------------------------------------------
+  // meet
+  // -------------------------------------------------------------------------
+
+  describe("YjsVersion.meet()", () => {
+    it("meet of concurrent versions produces component-wise minimum", () => {
+      // Create two docs with independent edits
+      const doc1 = new Y.Doc()
+      const doc2 = new Y.Doc()
+
+      doc1.getMap("root").set("a", 1)
+      doc1.getMap("root").set("b", 2)
+      doc2.getMap("root").set("c", 3)
+
+      const v1 = new YjsVersion(Y.encodeStateVector(doc1))
+      const v2 = new YjsVersion(Y.encodeStateVector(doc2))
+
+      // meet of concurrent versions — result ≤ both
+      const meet = v1.meet(v2) as YjsVersion
+      expect(meet.compare(v1)).not.toBe("ahead")
+      expect(meet.compare(v2)).not.toBe("ahead")
+    })
+
+    it("meet of identical versions returns an equal version", () => {
+      const doc = new Y.Doc()
+      doc.getMap("root").set("x", 1)
+      const v = new YjsVersion(Y.encodeStateVector(doc))
+
+      const meet = v.meet(v) as YjsVersion
+      expect(meet.compare(v)).toBe("equal")
+    })
+
+    it("meet round-trips through Yjs decode correctly", () => {
+      // The custom encodeStateVector must produce bytes that Yjs can decode
+      const doc1 = new Y.Doc()
+      const doc2 = new Y.Doc()
+
+      doc1.getMap("root").set("x", 1)
+      doc1.getMap("root").set("y", 2)
+
+      // Sync doc1 → doc2, then doc2 makes independent edits
+      Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
+      doc2.getMap("root").set("z", 3)
+
+      const v1 = new YjsVersion(Y.encodeStateVector(doc1))
+      const v2 = new YjsVersion(Y.encodeStateVector(doc2))
+
+      // v1 is behind v2 (v2 has all of v1's ops plus its own)
+      expect(v1.compare(v2)).toBe("behind")
+
+      // meet(v1, v2) should equal v1 (the behind one)
+      const meet = v1.meet(v2) as YjsVersion
+      expect(meet.compare(v1)).toBe("equal")
+
+      // The meet's state vector bytes can be decoded by Yjs
+      const decoded = Y.decodeStateVector(meet.sv)
+      expect(decoded.size).toBeGreaterThan(0)
+    })
+
+    it("meet of two behind-ahead versions gives the behind one", () => {
+      const doc = new Y.Doc()
+      doc.getMap("root").set("a", 1)
+      const early = new YjsVersion(Y.encodeStateVector(doc))
+
+      doc.getMap("root").set("b", 2)
+      const late = new YjsVersion(Y.encodeStateVector(doc))
+
+      expect(early.compare(late)).toBe("behind")
+
+      const meet = early.meet(late) as YjsVersion
+      expect(meet.compare(early)).toBe("equal")
+    })
+  })
 })

package/src/bind-yjs.ts

@@ -1,34 +1,39 @@
-// bind-yjs — bindYjs() convenience wrapper for Yjs CRDT substrate.
+// bind-yjs — Yjs CRDT substrate namespace and factory.
 //
-// Binds a schema to the Yjs substrate with causal merge strategy.
-// The factory builder accepts { peerId } and returns a SubstrateFactory
-// that sets doc.clientID on every new Y.Doc, ensuring deterministic
-// peer identity across all documents in an exchange.
+// Provides the `yjs` substrate namespace (`yjs.bind()`, `yjs.replica()`)
+// and the internal factory builder that injects a deterministic numeric
+// Yjs clientID derived from the exchange's peerId.
 //
 // Yjs clientID is a uint32 number. We use FNV-1a hash truncated to
 // 32 bits, mirroring the Loro binding's hashPeerId pattern but
 // targeting Yjs's number type (not Loro's bigint/53-bit PeerID).
 //
 // Usage:
-//   import { bindYjs } from "@kyneta/yjs-schema"
+//   import { yjs } from "@kyneta/yjs-schema"
 //
-//   const TodoDoc = bindYjs(Schema.doc({
-//     title: Schema.annotated("text"),
+//   const TodoDoc = yjs.bind(Schema.struct({
+//     title: Schema.text(),
 //     items: Schema.list(Schema.struct({ name: Schema.string() })),
 //   }))
 //
 //   const doc = exchange.get("my-doc", TodoDoc)
 
 import type {
-  BoundSchema,
+  CrdtStrategy,
   Replica,
   Schema as SchemaNode,
   Substrate,
   SubstrateFactory,
+  SubstrateNamespace,
   SubstratePayload,
 } from "@kyneta/schema"
-import { BACKING_DOC, bind, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
+import {
+  BACKING_DOC,
+  createSubstrateNamespace,
+  STRUCTURAL_YJS_CLIENT_ID,
+} from "@kyneta/schema"
 import * as Y from "yjs"
+import type { YjsNativeMap } from "./native-map.js"
 import { ensureContainers } from "./populate.js"
 import {
   createYjsReplica,
@@ -127,42 +132,36 @@ function createYjsFactory(peerId: string): SubstrateFactory<YjsVersion> {
 }
 
 // ---------------------------------------------------------------------------
-// bindYjs — the convenience wrapper
+// yjs — the Yjs CRDT substrate namespace
 // ---------------------------------------------------------------------------
 
 /**
- * Bind a schema to the Yjs CRDT substrate with causal merge strategy.
- *
- * This is the recommended way to declare a Yjs-backed document type.
- * The factory builder injects a deterministic numeric Yjs clientID derived
- * from the exchange's string peerId, ensuring consistent change attribution
- * across all documents and sessions.
- *
- * **Unsupported annotations:** Yjs has no native counter, movable list,
- * or tree types. Schemas passed to `bindYjs` must not contain
- * `Schema.annotated("counter")`, `Schema.annotated("movable")`, or
- * `Schema.annotated("tree")`. These will throw at construction time.
+ * The Yjs CRDT substrate namespace.
  *
- * @example
- * ```ts
- * import { bindYjs } from "@kyneta/yjs-schema"
- * import { Schema } from "@kyneta/schema"
+ * - `yjs.bind(schema)` — collaborative sync (default)
+ * - `yjs.bind(schema, "ephemeral")` — ephemeral/presence broadcast
+ * - `yjs.replica()` — collaborative replication (default)
+ * - `yjs.replica("ephemeral")` — ephemeral replication
  *
- * const TodoDoc = bindYjs(Schema.doc({
- *   title: Schema.annotated("text"),
- *   items: Schema.list(Schema.struct({
- *     name: Schema.string(),
- *     done: Schema.boolean(),
- *   })),
- * }))
+ * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
+ * Passing `"authoritative"` is a compile error.
  *
- * const doc = exchange.get("my-todos", TodoDoc)
- * ```
+ * To access the underlying Y.Doc, use `unwrap(ref)` from `@kyneta/schema`.
  */
-export function bindYjs<S extends SchemaNode>(schema: S): BoundSchema<S> {
-  return bind({
-    schema,
-    factory: ctx => createYjsFactory(ctx.peerId),
-    strategy: "causal",
+/** The closed set of capability tags that the Yjs substrate supports. */
+export type YjsCaps = "text" | "json"
+
+export const yjs: SubstrateNamespace<CrdtStrategy, YjsCaps, YjsNativeMap> =
+  createSubstrateNamespace<CrdtStrategy, YjsCaps, YjsNativeMap>({
+    strategies: {
+      collaborative: {
+        factory: ctx => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory,
+      },
+      ephemeral: {
+        factory: ctx => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory,
+      },
+    },
+    defaultStrategy: "collaborative",
   })
-}