@kyneta/yjs-schema 1.1.0 → 1.3.0

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() }))
@@ -16,34 +16,33 @@
 //   3. Reading back: doc.profiles() should return { [key]: { name, bio } }
 //   4. Sync: two peers should converge after exchanging deltas
 
-import { describe, expect, it } from "vitest"
 import {
   change,
-  createYjsDoc,
-  createYjsDocFromEntirety,
+  createDoc,
   exportEntirety,
   exportSince,
   merge,
   Schema,
   subscribe,
-  text,
   version,
-} from "../index.js"
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
+import { yjs } from "../bind-yjs.js"
 
 // ===========================================================================
 // 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,22 +51,30 @@ 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(),
     }),
   ),
 })
 
+// ===========================================================================
+// Bound schemas
+// ===========================================================================
+
+const BoundProfile = yjs.bind(ProfileSchema)
+const BoundPlainRecord = yjs.bind(PlainRecordSchema)
+const BoundListProfile = yjs.bind(ListProfileSchema)
+
 // ===========================================================================
 // Baseline: record-of-struct (plain, no text)
 // ===========================================================================
 
 describe("record-of-struct (plain baseline)", () => {
   it("set a record entry and read it back", () => {
-    const doc = createYjsDoc(PlainRecordSchema)
+    const doc = createDoc(BoundPlainRecord)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", age: 30 })
@@ -80,7 +87,7 @@ describe("record-of-struct (plain baseline)", () => {
   })
 
   it("set multiple entries and read all back", () => {
-    const doc = createYjsDoc(PlainRecordSchema)
+    const doc = createDoc(BoundPlainRecord)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", age: 30 })
@@ -95,7 +102,7 @@ describe("record-of-struct (plain baseline)", () => {
   })
 
   it("navigate into a record entry via .at()", () => {
-    const doc = createYjsDoc(PlainRecordSchema)
+    const doc = createDoc(BoundPlainRecord)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", age: 30 })
@@ -108,14 +115,14 @@ describe("record-of-struct (plain baseline)", () => {
   })
 
   it("syncs record-of-struct between two peers via snapshot", () => {
-    const docA = createYjsDoc(PlainRecordSchema)
+    const docA = createDoc(BoundPlainRecord)
 
     change(docA, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", age: 30 })
     })
 
     const snapshot = exportEntirety(docA)
-    const docB = createYjsDocFromEntirety(PlainRecordSchema, snapshot)
+    const docB = createDoc(BoundPlainRecord, snapshot)
 
     expect(docB.profiles()).toEqual({
       alice: { displayName: "Alice", age: 30 },
@@ -123,17 +130,14 @@ describe("record-of-struct (plain baseline)", () => {
   })
 
   it("syncs record-of-struct between two peers via delta", () => {
-    const docA = createYjsDoc(PlainRecordSchema)
+    const docA = createDoc(BoundPlainRecord)
 
     change(docA, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", age: 30 })
     })
 
     // Establish docB from snapshot (avoids Yjs clientID collision)
-    const docB = createYjsDocFromEntirety(
-      PlainRecordSchema,
-      exportEntirety(docA),
-    )
+    const docB = createDoc(BoundPlainRecord, exportEntirety(docA))
 
     const v0 = version(docB)
 
@@ -158,7 +162,7 @@ describe("record-of-struct (plain baseline)", () => {
 
 describe("text-inside-struct-inside-record", () => {
   it("set a record entry with text field omitted and read it back", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -171,7 +175,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("set a record entry with text field provided and read it back", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", bio: "Hello world" })
@@ -184,7 +188,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("navigate into a record entry and read the text", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -197,7 +201,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("insert text into a text field inside a record entry (field omitted at creation)", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -211,7 +215,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("insert text into a text field inside a record entry (field provided at creation)", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice", bio: "Initial" })
@@ -225,7 +229,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("set multiple entries and edit text independently", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -242,7 +246,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("subscribe fires on text edit inside record entry", () => {
-    const doc = createYjsDoc(ProfileSchema)
+    const doc = createDoc(BoundProfile)
 
     change(doc, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -261,7 +265,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("syncs text-inside-record via snapshot", () => {
-    const docA = createYjsDoc(ProfileSchema)
+    const docA = createDoc(BoundProfile)
 
     change(docA, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -271,7 +275,7 @@ describe("text-inside-struct-inside-record", () => {
     })
 
     const snapshot = exportEntirety(docA)
-    const docB = createYjsDocFromEntirety(ProfileSchema, snapshot)
+    const docB = createDoc(BoundProfile, snapshot)
 
     expect(docB.profiles()).toEqual({
       alice: { displayName: "Alice", bio: "Collaborative bio" },
@@ -282,7 +286,7 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("syncs text-inside-record via delta", () => {
-    const docA = createYjsDoc(ProfileSchema)
+    const docA = createDoc(BoundProfile)
 
     change(docA, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
@@ -291,7 +295,7 @@ describe("text-inside-struct-inside-record", () => {
     // Establish docB from snapshot (consistent with Yjs test patterns —
     // two independently-created Y.Docs may share a clientID, causing
     // silent update drops)
-    const docB = createYjsDocFromEntirety(ProfileSchema, exportEntirety(docA))
+    const docB = createDoc(BoundProfile, exportEntirety(docA))
     const v0 = version(docB)
 
     change(docA, (d: any) => {
@@ -314,13 +318,13 @@ describe("text-inside-struct-inside-record", () => {
   })
 
   it("concurrent text edits inside record entries converge", () => {
-    const docA = createYjsDoc(ProfileSchema)
+    const docA = createDoc(BoundProfile)
 
     // Sync initial state: A creates the entry, B starts from snapshot
     change(docA, (d: any) => {
       d.profiles.set("alice", { displayName: "Alice" })
     })
-    const docB = createYjsDocFromEntirety(ProfileSchema, exportEntirety(docA))
+    const docB = createDoc(BoundProfile, exportEntirety(docA))
 
     // Both peers edit concurrently
     const vA = version(docA)
@@ -354,7 +358,7 @@ describe("text-inside-struct-inside-record", () => {
 
 describe("text-inside-struct-inside-list", () => {
   it("push a struct with text field omitted and read it back", () => {
-    const doc = createYjsDoc(ListProfileSchema)
+    const doc = createDoc(BoundListProfile)
 
     change(doc, (d: any) => {
       d.players.push({ name: "Alice" })
@@ -366,7 +370,7 @@ describe("text-inside-struct-inside-list", () => {
   })
 
   it("push a struct with text field provided and read it back", () => {
-    const doc = createYjsDoc(ListProfileSchema)
+    const doc = createDoc(BoundListProfile)
 
     change(doc, (d: any) => {
       d.players.push({ name: "Alice", bio: "Hi there" })
@@ -378,7 +382,7 @@ describe("text-inside-struct-inside-list", () => {
   })
 
   it("insert text into a text field inside a list item (field omitted at creation)", () => {
-    const doc = createYjsDoc(ListProfileSchema)
+    const doc = createDoc(BoundListProfile)
 
     change(doc, (d: any) => {
       d.players.push({ name: "Alice" })
@@ -392,7 +396,7 @@ describe("text-inside-struct-inside-list", () => {
   })
 
   it("multiple list items with independent text fields", () => {
-    const doc = createYjsDoc(ListProfileSchema)
+    const doc = createDoc(BoundListProfile)
 
     change(doc, (d: any) => {
       d.players.push({ name: "Alice" })
@@ -409,17 +413,14 @@ describe("text-inside-struct-inside-list", () => {
   })
 
   it("syncs list-of-struct-with-text via delta", () => {
-    const docA = createYjsDoc(ListProfileSchema)
+    const docA = createDoc(BoundListProfile)
 
     change(docA, (d: any) => {
       d.players.push({ name: "Alice" })
     })
 
     // Establish docB from snapshot (avoids Yjs clientID collision)
-    const docB = createYjsDocFromEntirety(
-      ListProfileSchema,
-      exportEntirety(docA),
-    )
+    const docB = createDoc(BoundListProfile, exportEntirety(docA))
     const v0 = version(docB)
 
     change(docA, (d: any) => {

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" })