@kyneta/yjs-schema 1.1.0 → 1.2.0

package/src/__tests__/reader.test.ts

@@ -1,4 +1,4 @@
-import { RawPath, Schema } from "@kyneta/schema"
+import { KIND, RawPath, Schema } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
 import { ensureContainers } from "../populate.js"
@@ -16,7 +16,7 @@ import { yjsReader } from "../reader.js"
  * values. We populate values via raw Yjs API within a single transact.
  */
 function setup(
-  schema: ReturnType<typeof Schema.doc>,
+  schema: any,
   seed?: Record<string, unknown>,
 ) {
   const doc = new Y.Doc()
@@ -42,11 +42,11 @@ function setup(
  */
 function populateSeed(
   ymap: Y.Map<unknown>,
-  schema: ReturnType<typeof Schema.doc>,
+  schema: any,
   seed: Record<string, unknown>,
 ) {
-  const rootProduct = unwrapToProduct(schema)
-  if (!rootProduct) return
+  if (schema[KIND] !== "product") return
+  const rootProduct = schema
 
   for (const [key, value] of Object.entries(seed)) {
     if (value === undefined) continue
@@ -63,20 +63,15 @@ function populateField(
   fieldSchema: any,
   value: unknown,
 ) {
-  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-  if (tag === "text") {
-    // Text field — the Y.Text was already created by ensureContainers
-    const text = ymap.get(key) as Y.Text
-    if (text && typeof value === "string" && value.length > 0) {
-      text.insert(0, value)
+  switch (fieldSchema[KIND]) {
+    case "text": {
+      // Text field — the Y.Text was already created by ensureContainers
+      const text = ymap.get(key) as Y.Text
+      if (text && typeof value === "string" && value.length > 0) {
+        text.insert(0, value)
+      }
+      return
     }
-    return
-  }
-
-  const structural = unwrapAnnotations(fieldSchema)
-
-  switch (structural._kind) {
     case "product": {
       // Struct — recurse into the existing Y.Map
       const childMap = ymap.get(key) as Y.Map<unknown>
@@ -84,7 +79,7 @@ function populateField(
         for (const [childKey, childValue] of Object.entries(
           value as Record<string, unknown>,
         )) {
-          const childFieldSchema = (structural.fields as Record<string, any>)[
+          const childFieldSchema = (fieldSchema.fields as Record<string, any>)[
             childKey
           ]
           if (!childFieldSchema) continue
@@ -99,11 +94,11 @@ function populateField(
       const arr = ymap.get(key) as Y.Array<unknown>
       if (arr && Array.isArray(value)) {
         for (const item of value) {
-          const itemSchema = structural.item
-          if (itemSchema && unwrapAnnotations(itemSchema)._kind === "product") {
+          const itemSchema = fieldSchema.item
+          if (itemSchema && itemSchema[KIND] === "product") {
             // Struct items: create a Y.Map for each
             const itemMap = buildStructMap(
-              unwrapAnnotations(itemSchema),
+              itemSchema,
               item as Record<string, unknown>,
             )
             arr.push([itemMap])
@@ -150,22 +145,19 @@ function buildStructMap(
     const value = seed[key]
     if (value === undefined) continue
 
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-    if (tag === "text") {
-      const text = new Y.Text()
-      if (typeof value === "string" && value.length > 0) {
-        text.insert(0, value)
+    switch (fieldSchema[KIND]) {
+      case "text": {
+        const text = new Y.Text()
+        if (typeof value === "string" && value.length > 0) {
+          text.insert(0, value)
+        }
+        map.set(key, text)
+        break
       }
-      map.set(key, text)
-      continue
-    }
-
-    const structural = unwrapAnnotations(fieldSchema)
-    switch (structural._kind) {
       case "product": {
         map.set(
           key,
-          buildStructMap(structural, value as Record<string, unknown>),
+          buildStructMap(fieldSchema, value as Record<string, unknown>),
         )
         break
       }
@@ -173,14 +165,14 @@ function buildStructMap(
         const arr = new Y.Array()
         if (Array.isArray(value)) {
           for (const item of value) {
-            const itemSchema = structural.element ?? structural.schema
+            const itemSchema = fieldSchema.item
             if (
               itemSchema &&
-              unwrapAnnotations(itemSchema)._kind === "product"
+              itemSchema[KIND] === "product"
             ) {
               arr.push([
                 buildStructMap(
-                  unwrapAnnotations(itemSchema),
+                  itemSchema,
                   item as Record<string, unknown>,
                 ),
               ])
@@ -212,22 +204,7 @@ function buildStructMap(
   return map
 }
 
-function unwrapToProduct(schema: any): any {
-  let s = schema
-  while (s._kind === "annotated" && s.schema !== undefined) {
-    s = s.schema
-  }
-  if (s._kind === "product") return s
-  return null
-}
 
-function unwrapAnnotations(schema: any): any {
-  let s = schema
-  while (s._kind === "annotated" && s.schema !== undefined) {
-    s = s.schema
-  }
-  return s
-}
 
 /** Build a RawPath from variadic key/index segments. */
 function p(...segs: (string | number)[]): RawPath {
@@ -242,18 +219,18 @@ function p(...segs: (string | number)[]): RawPath {
 // Schemas used across tests
 // ===========================================================================
 
-const TextSchema = Schema.doc({
-  title: Schema.annotated("text"),
-  subtitle: Schema.annotated("text"),
+const TextSchema = Schema.struct({
+  title: Schema.text(),
+  subtitle: Schema.text(),
 })
 
-const ScalarSchema = Schema.doc({
+const ScalarSchema = Schema.struct({
   name: Schema.string(),
   count: Schema.number(),
   active: Schema.boolean(),
 })
 
-const NestedStructSchema = Schema.doc({
+const NestedStructSchema = Schema.struct({
   profile: Schema.struct({
     first: Schema.string(),
     last: Schema.string(),
@@ -264,7 +241,7 @@ const NestedStructSchema = Schema.doc({
   }),
 })
 
-const ListSchema = Schema.doc({
+const ListSchema = Schema.struct({
   items: Schema.list(Schema.string()),
   structs: Schema.list(
     Schema.struct({
@@ -274,12 +251,12 @@ const ListSchema = Schema.doc({
   ),
 })
 
-const MapSchema = Schema.doc({
+const MapSchema = Schema.struct({
   labels: Schema.record(Schema.string()),
 })
 
-const MixedSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const MixedSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   items: Schema.list(
     Schema.struct({

package/src/__tests__/record-text-spike.test.ts

@@ -1,10 +1,10 @@
 // record-text-spike — validate text-inside-struct patterns for Yjs backend.
 //
 // The Yjs analog of the Loro counter-in-record spike. Yjs doesn't support
-// counter annotations, but it DOES support text annotations. The same
-// structural bug exists: when a struct is dynamically inserted into a
-// record or list via .set() or .push(), text fields declared in the schema
-// but missing from the value object don't get Y.Text containers created.
+// counters, but it DOES support text. The same structural bug exists: when
+// a struct is dynamically inserted into a record or list via .set() or
+// .push(), text fields declared in the schema but missing from the value
+// object don't get Y.Text containers created.
 //
 // This spike tests:
 //   1. record(struct({ name: string(), bio: text() }))
@@ -26,7 +26,6 @@ import {
   merge,
   Schema,
   subscribe,
-  text,
   version,
 } from "../index.js"
 
@@ -34,16 +33,16 @@ import {
 // Schemas
 // ===========================================================================
 
-const ProfileSchema = Schema.doc({
+const ProfileSchema = Schema.struct({
   profiles: Schema.record(
     Schema.struct({
       displayName: Schema.string(),
-      bio: text(),
+      bio: Schema.text(),
     }),
   ),
 })
 
-const PlainRecordSchema = Schema.doc({
+const PlainRecordSchema = Schema.struct({
   profiles: Schema.record(
     Schema.struct({
       displayName: Schema.string(),
@@ -52,11 +51,11 @@ const PlainRecordSchema = Schema.doc({
   ),
 })
 
-const ListProfileSchema = Schema.doc({
+const ListProfileSchema = Schema.struct({
   players: Schema.list(
     Schema.struct({
       name: Schema.string(),
-      bio: text(),
+      bio: Schema.text(),
     }),
   ),
 })

package/src/__tests__/structural-merge.test.ts

@@ -9,16 +9,16 @@
 import { BACKING_DOC, Schema, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
-import { bindYjs } from "../bind-yjs.js"
+import { yjs } from "../bind-yjs.js"
 import { ensureContainers } from "../populate.js"
-import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
+import { yjsSubstrateFactory } from "../substrate.js"
 
 // ===========================================================================
 // Schemas used across tests
 // ===========================================================================
 
-const TestSchema = Schema.doc({
-  title: Schema.annotated("text"),
+const TestSchema = Schema.struct({
+  title: Schema.text(),
   count: Schema.number(),
   items: Schema.list(Schema.string()),
 })
@@ -138,20 +138,20 @@ describe("structural merge protocol (Yjs)", () => {
 
   it("field reordering in source doesn't affect structural ops", () => {
     // Schema A: fields in one order
-    const schemaA = Schema.doc({
+    const schemaA = Schema.struct({
       alpha: Schema.string(),
       beta: Schema.number(),
-      gamma: Schema.annotated("text"),
+      gamma: Schema.text(),
     })
 
     // Schema B: same fields, different insertion order
     // JavaScript objects preserve insertion order, so we construct
     // with a different order to verify alphabetical sort overrides it.
     const fields: Record<string, any> = {}
-    fields.gamma = Schema.annotated("text")
+    fields.gamma = Schema.text()
     fields.alpha = Schema.string()
     fields.beta = Schema.number()
-    const schemaB = Schema.doc(fields)
+    const schemaB = Schema.struct(fields)
 
     const docA = new Y.Doc()
     ensureContainers(docA, schemaA)
@@ -168,15 +168,15 @@ describe("structural merge protocol (Yjs)", () => {
   // ── Schema evolution ──
 
   it("add field after hydration, structural ops extend correctly", () => {
-    const v1Schema = Schema.doc({
-      title: Schema.annotated("text"),
+    const v1Schema = Schema.struct({
+      title: Schema.text(),
       count: Schema.number(),
     })
 
-    const v2Schema = Schema.doc({
+    const v2Schema = Schema.struct({
       count: Schema.number(),
-      notes: Schema.annotated("text"), // new field
-      title: Schema.annotated("text"),
+      notes: Schema.text(), // new field
+      title: Schema.text(),
     })
 
     // Peer A: create v1, write data, export
@@ -282,10 +282,10 @@ describe("structural merge protocol (Yjs)", () => {
     expect(root2.get("count")).toBe(123)
   })
 
-  // ── bindYjs integration ──
+  // ── yjs.bind integration ──
 
-  it("bindYjs factory produces deterministic structural ops across peers", () => {
-    const bound = bindYjs(TestSchema)
+  it("yjs.bind factory produces deterministic structural ops across peers", () => {
+    const bound = yjs.bind(TestSchema)
 
     const factoryA = bound.factory({ peerId: "alice" })
     const factoryB = bound.factory({ peerId: "bob" })
@@ -301,8 +301,8 @@ describe("structural merge protocol (Yjs)", () => {
     expect(stateA.data).toEqual(stateB.data)
   })
 
-  it("bindYjs peers merge without structural conflict", () => {
-    const bound = bindYjs(TestSchema)
+  it("yjs.bind peers merge without structural conflict", () => {
+    const bound = yjs.bind(TestSchema)
 
     const factoryA = bound.factory({ peerId: "alice" })
     const factoryB = bound.factory({ peerId: "bob" })

package/src/__tests__/substrate.test.ts

@@ -1,9 +1,9 @@
 import { change, RawPath, Schema, subscribe } from "@kyneta/schema"
-import { describe, expect, it, vi } from "vitest"
+import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
 import { createYjsDoc, createYjsDocFromEntirety } from "../create.js"
 import { ensureContainers } from "../populate.js"
-import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
+import { yjsSubstrateFactory } from "../substrate.js"
 import { exportEntirety, exportSince, merge, version } from "../sync.js"
 import { YjsVersion } from "../version.js"
 
@@ -15,13 +15,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 +30,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()),
@@ -346,7 +346,7 @@ describe("YjsSubstrate", () => {
 
     it("nested struct field changefeed fires on merge", () => {
       const doc1 = createYjsDoc(StructListSchema)
-      const doc2 = createYjsDocFromEntirety(
+      const _doc2 = createYjsDocFromEntirety(
         StructListSchema,
         exportEntirety(doc1),
       )
@@ -512,29 +512,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")

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,33 +1,38 @@
-// 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()`,
+// `yjs.unwrap()`) 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,
+  unwrap,
+} from "@kyneta/schema"
 import * as Y from "yjs"
 import { ensureContainers } from "./populate.js"
 import {
@@ -127,42 +132,67 @@ 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.
- *
- * @example
- * ```ts
- * import { bindYjs } from "@kyneta/yjs-schema"
- * import { Schema } from "@kyneta/schema"
+ * The Yjs CRDT substrate namespace.
  *
- * const TodoDoc = bindYjs(Schema.doc({
- *   title: Schema.annotated("text"),
- *   items: Schema.list(Schema.struct({
- *     name: Schema.string(),
- *     done: Schema.boolean(),
- *   })),
- * }))
+ * - `yjs.bind(schema)` — collaborative sync (default)
+ * - `yjs.bind(schema, "ephemeral")` — ephemeral/presence broadcast
+ * - `yjs.replica()` — collaborative replication (default)
+ * - `yjs.replica("ephemeral")` — ephemeral replication
+ * - `yjs.unwrap(ref)` — access the underlying Y.Doc
  *
- * const doc = exchange.get("my-todos", TodoDoc)
- * ```
+ * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
+ * Passing `"authoritative"` is a compile error.
  */
-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> & {
+  /** Access the underlying `Y.Doc` backing a ref. */
+  unwrap(ref: object): Y.Doc
+} = {
+  ...createSubstrateNamespace<CrdtStrategy, YjsCaps>({
+    strategies: {
+      collaborative: {
+        factory: ctx => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory,
+      },
+      ephemeral: {
+        factory: ctx => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory,
+      },
+    },
+    defaultStrategy: "collaborative",
+  }),
+
+  unwrap(ref: object): Y.Doc {
+    let substrate: any
+    try {
+      substrate = unwrap(ref)
+    } catch {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. " +
+          "Use a doc created by exchange.get() with a yjs.bind() schema, " +
+          "or by createYjsDoc().",
+      )
+    }
+
+    const doc = substrate[BACKING_DOC]
+    if (
+      !doc ||
+      typeof doc !== "object" ||
+      typeof (doc as any).getMap !== "function" ||
+      typeof (doc as any).clientID !== "number"
+    ) {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. " +
+          "The ref has a substrate but it is not a Yjs substrate. " +
+          "Use a doc created with a yjs.bind() schema or createYjsDoc().",
+      )
+    }
+    return doc as Y.Doc
+  },
 }