@kyneta/yjs-schema 1.0.0 → 1.2.0

package/src/index.ts

@@ -4,80 +4,61 @@
 // with schema-aware typed reads, writes, versioning, and export/import.
 //
 // Batteries-included API (most users):
-//   createYjsDoc, createYjsDocFromSnapshot, version, exportSnapshot,
-//   exportSince, importDelta, change, subscribe, applyChanges
+//   createYjsDoc, createYjsDocFromEntirety, version, exportEntirety,
+//   exportSince, merge, change, subscribe, applyChanges
 //
 // Low-level primitives (power users):
-//   createYjsSubstrate, yjsSubstrateFactory, yjsStoreReader,
+//   createYjsSubstrate, yjsSubstrateFactory, yjsReader,
 //   resolveYjsType, stepIntoYjs, applyChangeToYjs, eventsToOps, YjsVersion
 
 // ---------------------------------------------------------------------------
 // Batteries-included API — one import, one createYjsDoc call, done
 // ---------------------------------------------------------------------------
 
+// Mutation & observation (re-exported from @kyneta/schema for convenience)
+// Schema definition (re-exported for convenience)
+export {
+  applyChanges,
+  change,
+  Schema,
+  subscribe,
+  subscribeNode,
+} from "@kyneta/schema"
 // Construction
-export { createYjsDoc, createYjsDocFromSnapshot } from "./create.js"
-
+export { createYjsDoc, createYjsDocFromEntirety } from "./create.js"
 // Sync primitives (Yjs-specific)
 export {
+  exportEntirety,
   exportSince,
-  exportSnapshot,
-  importDelta,
+  merge,
   version,
 } from "./sync.js"
 
-// Mutation & observation (re-exported from @kyneta/schema for convenience)
-export { applyChanges, change } from "@kyneta/schema"
-export { subscribe, subscribeNode } from "@kyneta/schema"
-
-// Schema definition (re-exported for convenience)
-export { Schema } from "@kyneta/schema"
-
-// Text annotation convenience — so users don't need LoroSchema just for text()
-import type { AnnotatedSchema } from "@kyneta/schema"
-import { Schema } from "@kyneta/schema"
-
-/**
- * Collaborative text (CRDT). Produces `annotated("text")`.
- *
- * The annotation implies scalar string semantics for reads,
- * but the Yjs substrate provides collaborative editing (insert, delete)
- * via Y.Text.
- *
- * This is a convenience re-export so that `@kyneta/yjs-schema` users
- * don't need to import `LoroSchema` just for `text()`.
- */
-export function text(): AnnotatedSchema<"text", undefined> {
-  return Schema.annotated("text")
-}
-
 // Types (re-exported for convenience)
-export type { Changeset, Op, Ref, SubstratePayload } from "@kyneta/schema"
+export type { Changeset } from "@kyneta/changefeed"
+export type { Op, Ref, SubstratePayload } from "@kyneta/schema"
 
 // ---------------------------------------------------------------------------
 // Low-level primitives — for power users and custom substrate compositions
 // ---------------------------------------------------------------------------
 
-// Version
-export { YjsVersion } from "./version.js"
-
-// Store reader
-export { yjsStoreReader } from "./store-reader.js"
-
-// Container resolution
-export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"
-
+// Namespace — the yjs substrate namespace (replaces standalone escape hatch;
+// the old `yjs(ref)` call is now `yjs.unwrap(ref)`)
+export { yjs } from "./bind-yjs.js"
+export type { YjsCaps } from "./bind-yjs.js"
 // Change mapping
 export { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
-
 // Container creation
 export { ensureContainers } from "./populate.js"
-
+// Reader
+export { yjsReader } from "./reader.js"
 // Substrate
-export { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
-
-// Bind — convenience wrapper for Yjs CRDT substrate
-export { bindYjs } from "./bind-yjs.js"
-
-// Escape hatch — access the underlying Y.Doc from a ref
-export { yjs } from "./yjs-escape.js"
+export {
+  createYjsSubstrate,
+  yjsReplicaFactory,
+  yjsSubstrateFactory,
+} from "./substrate.js"
+// Version
+export { YjsVersion } from "./version.js"
+// Container resolution
+export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"

package/src/populate.ts

@@ -15,7 +15,7 @@
 // shared types (Y.Text, Y.Array, Y.Map) and plain value slots uniformly.
 
 import type { Schema as SchemaNode } from "@kyneta/schema"
-import { Zero } from "@kyneta/schema"
+import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -26,37 +26,58 @@ import * as Y from "yjs"
  * Ensure that a Y.Doc's root map contains the correct Yjs shared types
  * matching the schema structure.
  *
- * Obtains the root map via `doc.getMap("root")`, unwraps the root product
- * schema, and creates empty containers for each field within a single
- * `doc.transact()` call for atomicity.
+ * Obtains the root map via `doc.getMap("root")`, reads the root product
+ * schema's fields, and creates empty containers for each field within a
+ * single `doc.transact()` call for atomicity.
  *
- * No values are written — the containers are empty after this call.
- * Initial content should be applied via `change()` after substrate
- * construction.
+ * When `conditional` is true, fields that already exist in the root map
+ * are skipped. This is the correct mode after hydration — containers
+ * present from stored state must not be overwritten (each `rootMap.set()`
+ * is a CRDT write that advances the version vector and may conflict
+ * with stored operations).
+ *
+ * When `conditional` is false (default), all fields are created
+ * unconditionally. This is the correct mode for fresh documents.
+ *
+ * **Structural identity:** This function temporarily sets `doc.clientID`
+ * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
+ * then restores the caller's clientID. This produces byte-identical
+ * structural ops across all peers, enabling Yjs deduplication on merge.
  *
  * @param doc - The Y.Doc to prepare
- * @param schema - The root document schema (typically annotated("doc", product))
+ * @param schema - The root document schema (a ProductSchema)
+ * @param conditional - If true, skip fields that already exist in the root map.
+ *   Context: jj:smmulzkm (two-phase substrate construction)
  */
-export function ensureContainers(doc: Y.Doc, schema: SchemaNode): void {
+export function ensureContainers(
+  doc: Y.Doc,
+  schema: SchemaNode,
+  conditional = false,
+): void {
   const rootMap = doc.getMap("root")
 
-  let rootProduct = schema
-  while (
-    rootProduct._kind === "annotated" &&
-    rootProduct.schema !== undefined
-  ) {
-    rootProduct = rootProduct.schema
-  }
-
-  if (rootProduct._kind !== "product") {
+  if (schema[KIND] !== "product") {
     return
   }
 
-  doc.transact(() => {
-    for (const [key, fieldSchema] of Object.entries(rootProduct.fields)) {
-      ensureRootField(rootMap, key, fieldSchema as SchemaNode)
-    }
-  })
+  // Switch to structural identity for deterministic container creation.
+  // All peers produce byte-identical structural ops at clientID 0.
+  const savedClientID = doc.clientID
+  doc.clientID = STRUCTURAL_YJS_CLIENT_ID
+
+  try {
+    doc.transact(() => {
+      for (const [key, fieldSchema] of Object.entries(schema.fields).sort(
+        ([a], [b]) => a.localeCompare(b),
+      )) {
+        if (conditional && rootMap.has(key)) continue
+        ensureRootField(rootMap, key, fieldSchema as SchemaNode)
+      }
+    })
+  } finally {
+    // Restore the caller's identity for application writes.
+    doc.clientID = savedClientID
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -66,62 +87,36 @@ export function ensureContainers(doc: Y.Doc, schema: SchemaNode): void {
 /**
  * Ensure a root-level Yjs shared type exists for a schema field.
  *
- * Dispatches based on the schema annotation tag and structural kind:
- * - `annotated("text")` → empty Y.Text
- * - `annotated("counter")` → throws (unsupported in Yjs)
- * - `annotated("movable")` → throws (unsupported in Yjs)
- * - `annotated("tree")` → throws (unsupported in Yjs)
- * - `product` → empty Y.Map (recursive for nested products)
- * - `sequence` → empty Y.Array
- * - `map` → empty Y.Map
- * - `scalar`/`sum` → no-op (plain values don't need containers)
+ * Dispatches on `[KIND]`:
+ * - `"text"` → empty Y.Text
+ * - `"product"` → empty Y.Map (recursive for nested products)
+ * - `"sequence"` → empty Y.Array
+ * - `"map"` → empty Y.Map
+ * - `"scalar"` / `"sum"` → Zero.structural default
+ * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
  */
 function ensureRootField(
   rootMap: Y.Map<unknown>,
   key: string,
   fieldSchema: SchemaNode,
 ): void {
-  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-  switch (tag) {
+  switch (fieldSchema[KIND]) {
     case "text":
       rootMap.set(key, new Y.Text())
       return
 
-    case "counter":
-      throw new Error(
-        `Yjs substrate does not support counter annotations. ` +
-          `Use Schema.number() with ReplaceChange instead. ` +
-          `Encountered counter annotation at root field "${key}".`,
-      )
-
-    case "movable":
-      throw new Error(
-        `Yjs substrate does not support movable list annotations. ` +
-          `Yjs has no native movable list type. ` +
-          `Encountered movable annotation at root field "${key}".`,
-      )
-
-    case "tree":
-      throw new Error(
-        `Yjs substrate does not support tree annotations. ` +
-          `Yjs has no native tree type. ` +
-          `Encountered tree annotation at root field "${key}".`,
-      )
-  }
-
-  const structural = unwrapAnnotations(fieldSchema)
-
-  switch (structural._kind) {
     case "product":
-      rootMap.set(key, ensureMapContainers(structural))
+      rootMap.set(key, ensureMapContainers(fieldSchema))
       return
+
     case "sequence":
       rootMap.set(key, new Y.Array())
       return
+
     case "map":
       rootMap.set(key, new Y.Map())
       return
+
     case "scalar":
     case "sum": {
       // Plain values don't need shared type containers, but they DO
@@ -133,6 +128,16 @@ function ensureRootField(
       }
       return
     }
+
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". ` +
+          `Supported kinds: text, product, sequence, map, scalar, sum. ` +
+          `Encountered unsupported kind at root field "${key}".`,
+      )
   }
 }
 
@@ -146,38 +151,33 @@ function ensureRootField(
  *
  * Only creates containers for fields that require Yjs shared types
  * (text → Y.Text, product → Y.Map, sequence → Y.Array, map → Y.Map).
- * Scalar and sum fields are left empty — they'll be written as plain
- * values via change() when needed.
+ * Scalar and sum fields are set to their structural zero defaults.
  */
 function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
   const map = new Y.Map()
-  const structural = unwrapAnnotations(schema)
 
-  if (structural._kind !== "product") return map
+  if (schema[KIND] !== "product") return map
 
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields as Record<string, SchemaNode>,
-  )) {
-    const tag =
-      fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-    if (tag === "text") {
-      map.set(key, new Y.Text())
-      continue
-    }
-
-    const fs = unwrapAnnotations(fieldSchema)
+    schema.fields as Record<string, SchemaNode>,
+  ).sort(([a], [b]) => a.localeCompare(b))) {
+    switch (fieldSchema[KIND]) {
+      case "text":
+        map.set(key, new Y.Text())
+        break
 
-    switch (fs._kind) {
       case "product":
         map.set(key, ensureMapContainers(fieldSchema))
         break
+
       case "sequence":
         map.set(key, new Y.Array())
         break
+
       case "map":
         map.set(key, new Y.Map())
         break
+
       case "scalar":
       case "sum": {
         const zero = Zero.structural(fieldSchema)
@@ -186,23 +186,18 @@ function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
         }
         break
       }
+
+      case "counter":
+      case "set":
+      case "tree":
+      case "movable":
+        throw new Error(
+          `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". ` +
+            `Supported kinds: text, product, sequence, map, scalar, sum. ` +
+            `Encountered unsupported kind at nested field "${key}".`,
+        )
     }
   }
 
   return map
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Unwrap annotation wrappers to reach the structural schema node.
- */
-function unwrapAnnotations(schema: SchemaNode): SchemaNode {
-  let s = schema
-  while (s._kind === "annotated" && s.schema !== undefined) {
-    s = s.schema
-  }
-  return s
 }

package/src/{store-reader.ts → reader.ts}

@@ -1,6 +1,6 @@
-// store-reader — YjsStoreReader implementation.
+// store-reader — YjsReader implementation.
 //
-// Implements StoreReader via schema-guided live navigation of the
+// Implements Reader via schema-guided live navigation of the
 // Yjs shared type tree. Each read operation resolves the shared type
 // at the given path using resolveYjsType, then extracts the
 // appropriate value based on `instanceof` discrimination.
@@ -8,9 +8,7 @@
 // Y.Text → .toJSON() (string), Y.Map → .toJSON() (plain object),
 // Y.Array → .toJSON() (plain array), plain values → as-is.
 
-import type { StoreReader } from "@kyneta/schema"
-import type { Path } from "@kyneta/schema"
-import type { Schema as SchemaNode } from "@kyneta/schema"
+import type { Path, Reader, Schema as SchemaNode } from "@kyneta/schema"
 import * as Y from "yjs"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -41,11 +39,11 @@ function extractValue(resolved: unknown): unknown {
 }
 
 // ---------------------------------------------------------------------------
-// yjsStoreReader
+// yjsReader
 // ---------------------------------------------------------------------------
 
 /**
- * Creates a StoreReader that navigates the Yjs shared type tree live,
+ * Creates a Reader that navigates the Yjs shared type tree live,
  * using the schema as a type witness to determine navigation at each
  * path segment.
  *
@@ -58,10 +56,7 @@ function extractValue(resolved: unknown): unknown {
  * @param doc - The Y.Doc to read from.
  * @param schema - The root schema for the document.
  */
-export function yjsStoreReader(
-  doc: Y.Doc,
-  schema: SchemaNode,
-): StoreReader {
+export function yjsReader(doc: Y.Doc, schema: SchemaNode): Reader {
   const rootMap = doc.getMap("root")
 
   return {
@@ -120,4 +115,4 @@ export function yjsStoreReader(
       return false
     },
   }
-}
+}