@kyneta/yjs-schema 1.1.0 → 1.3.0

package/src/change-mapping.ts

@@ -29,7 +29,12 @@ import type {
   TextChange,
   TextInstruction,
 } from "@kyneta/schema"
-import { advanceSchema, expandMapOpsToLeaves, RawPath } from "@kyneta/schema"
+import {
+  advanceSchema,
+  expandMapOpsToLeaves,
+  KIND,
+  RawPath,
+} from "@kyneta/schema"
 import * as Y from "yjs"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -74,15 +79,15 @@ export function applyChangeToYjs(
 
     case "increment":
       throw new Error(
-        "Yjs substrate does not support counter annotations. " +
-          "Use Schema.number() with ReplaceChange instead. " +
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Counter requires a CRDT backend that supports counters (e.g. Loro). ` +
           `Attempted IncrementChange with amount=${(change as IncrementChange).amount} at path [${pathToString(path)}].`,
       )
 
     case "tree":
       throw new Error(
-        "Yjs substrate does not support tree annotations. " +
-          "Yjs has no native tree type. " +
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Tree requires a CRDT backend that supports trees (e.g. Loro). ` +
           `Attempted TreeChange at path [${pathToString(path)}].`,
       )
 
@@ -250,24 +255,16 @@ function maybeCreateSharedType(
 ): unknown {
   if (schema === undefined) return value
 
-  const structural = unwrapAnnotations(schema)
-  const tag = schema._kind === "annotated" ? schema.tag : undefined
-
-  // Annotated text → Y.Text
-  if (tag === "text") {
-    const text = new Y.Text()
-    if (typeof value === "string" && value.length > 0) {
-      text.insert(0, value)
+  switch (schema[KIND]) {
+    // First-class text → Y.Text
+    case "text": {
+      const text = new Y.Text()
+      if (typeof value === "string" && value.length > 0) {
+        text.insert(0, value)
+      }
+      return text
     }
-    return text
-  }
 
-  // Annotated counter/movable/tree → should not reach here (thrown earlier)
-  if (tag === "counter" || tag === "movable" || tag === "tree") {
-    throw new Error(`Yjs substrate does not support "${tag}" annotations.`)
-  }
-
-  switch (structural._kind) {
     case "product": {
       if (
         value === null ||
@@ -277,13 +274,13 @@ function maybeCreateSharedType(
       ) {
         return value
       }
-      return createStructuredMap(value as Record<string, unknown>, structural)
+      return createStructuredMap(value as Record<string, unknown>, schema)
     }
 
     case "sequence": {
       if (!Array.isArray(value)) return value
       const arr = new Y.Array()
-      const itemSchema = structural.item
+      const itemSchema = schema.item
       const items = (value as unknown[]).map(item =>
         maybeCreateSharedType(item, itemSchema),
       )
@@ -301,15 +298,26 @@ function maybeCreateSharedType(
         return value
       }
       const map = new Y.Map()
-      const valueSchema = structural.item
+      const valueSchema = schema.item
       for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
         map.set(k, maybeCreateSharedType(v, valueSchema))
       }
       return map
     }
 
+    // Unsupported first-class CRDT types — should not reach here
+    // (rejected at bind time by caps check)
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${schema[KIND]}". ` +
+          `This should have been caught at bind() time.`,
+      )
+
     default:
-      // Scalar, sum, or other — return as plain value
+      // Scalar, sum — return as plain value
       return value
   }
 }
@@ -326,9 +334,8 @@ function createStructuredMap(
   productSchema: SchemaNode,
 ): Y.Map<any> {
   const map = new Y.Map()
-  const structural = unwrapAnnotations(productSchema)
 
-  if (structural._kind !== "product") {
+  if (productSchema[KIND] !== "product") {
     // Fallback: set all values as plain
     for (const [key, val] of Object.entries(obj)) {
       map.set(key, val)
@@ -339,25 +346,22 @@ function createStructuredMap(
   // Process fields present in the value object
   for (const [key, val] of Object.entries(obj)) {
     if (val === undefined) continue
-    const fieldSchema = structural.fields[key]
+    const fieldSchema = productSchema.fields[key]
     const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val
     map.set(key, yjsVal)
   }
 
-  // Create shared types for annotated fields declared in the schema
+  // Create shared types for first-class CRDT fields declared in the schema
   // but missing from the value object. This ensures Yjs containers
   // exist for later mutation (e.g. .insert() on a text field inside
   // a struct inside a record/list).
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields as Record<string, SchemaNode>,
+    productSchema.fields as Record<string, SchemaNode>,
   )) {
     if (key in obj) continue // already processed above
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-    if (tag === "text") {
+    if (fieldSchema[KIND] === "text") {
       map.set(key, new Y.Text())
     }
-    // Other annotated container types (counter, movable, tree) are
-    // unsupported in Yjs and will throw if used elsewhere.
   }
 
   return map
@@ -380,7 +384,7 @@ function createStructuredMap(
  *
  * @param events - The events from the `observeDeep` callback
  */
-export function eventsToOps(events: Y.YEvent<any>[]): Op[] {
+export function eventsToOps(events: Y.YEvent<any>[], schema: SchemaNode): Op[] {
   const ops: Op[] = []
 
   for (const event of events) {
@@ -391,7 +395,7 @@ export function eventsToOps(events: Y.YEvent<any>[]): Op[] {
     }
   }
 
-  return expandMapOpsToLeaves(ops)
+  return expandMapOpsToLeaves(ops, schema)
 }
 
 // ---------------------------------------------------------------------------
@@ -541,17 +545,6 @@ function extractEventValue(value: unknown): unknown {
 // Schema 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
-}
-
 /**
  * Resolve the schema at a given path by walking through advanceSchema.
  */
@@ -567,8 +560,9 @@ function resolveSchemaAtPath(rootSchema: SchemaNode, path: Path): SchemaNode {
  * Get the item schema from a sequence schema, if available.
  */
 function getItemSchema(schema: SchemaNode): SchemaNode | undefined {
-  const structural = unwrapAnnotations(schema)
-  return structural._kind === "sequence" ? structural.item : undefined
+  if (schema[KIND] === "sequence") return schema.item
+  if (schema[KIND] === "movable") return schema.item
+  return undefined
 }
 
 /**
@@ -578,12 +572,14 @@ function getFieldSchema(
   schema: SchemaNode,
   key: string,
 ): SchemaNode | undefined {
-  const structural = unwrapAnnotations(schema)
-  if (structural._kind === "product") {
-    return structural.fields[key]
+  if (schema[KIND] === "product") {
+    return schema.fields[key]
+  }
+  if (schema[KIND] === "map") {
+    return schema.item
   }
-  if (structural._kind === "map") {
-    return structural.item
+  if (schema[KIND] === "set") {
+    return schema.item
   }
   return undefined
 }

package/src/index.ts

@@ -3,75 +3,60 @@
 // Provides a Substrate<YjsVersion> implementation that wraps a Y.Doc
 // with schema-aware typed reads, writes, versioning, and export/import.
 //
-// Batteries-included API (most users):
-//   createYjsDoc, createYjsDocFromEntirety, version, exportEntirety,
-//   exportSince, merge, change, subscribe, applyChanges
-//
-// Low-level primitives (power users):
-//   createYjsSubstrate, yjsSubstrateFactory, yjsReader,
-//   resolveYjsType, stepIntoYjs, applyChangeToYjs, eventsToOps, YjsVersion
+// The single entry point is `createDoc(yjs.bind(schema))`. For the
+// batteries-included API, import from this package. For the composable
+// toolkit, import from `@kyneta/schema` directly.
 
 // ---------------------------------------------------------------------------
-// Batteries-included API — one import, one createYjsDoc call, done
+// Generic API (re-exported from @kyneta/schema for convenience)
 // ---------------------------------------------------------------------------
 
+// Types (re-exported for convenience)
+export type { Changeset } from "@kyneta/changefeed"
+export type { DocRef, Op, Ref, SubstratePayload } from "@kyneta/schema"
+// Construction
 // Mutation & observation (re-exported from @kyneta/schema for convenience)
 // Schema definition (re-exported for convenience)
+// Native escape hatch
+// Sync primitives (generic — work for any substrate)
 export {
   applyChanges,
   change,
-  Schema,
-  subscribe,
-  subscribeNode,
-} from "@kyneta/schema"
-// Construction
-export { createYjsDoc, createYjsDocFromEntirety } from "./create.js"
-// Sync primitives (Yjs-specific)
-export {
+  createDoc,
+  createRef,
   exportEntirety,
   exportSince,
   merge,
+  NATIVE,
+  Schema,
+  subscribe,
+  subscribeNode,
+  unwrap,
   version,
-} from "./sync.js"
-
-// 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"
+} from "@kyneta/schema"
 
 // ---------------------------------------------------------------------------
-// Low-level primitives — for power users and custom substrate compositions
+// Yjs-specific exports
 // ---------------------------------------------------------------------------
 
-// Bind — convenience wrapper for Yjs CRDT substrate
-export { bindYjs } from "./bind-yjs.js"
+export type { YjsCaps } from "./bind-yjs.js"
+// Namespace
+export { yjs } from "./bind-yjs.js"
 // Change mapping
 export { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
+// NativeMap — the Yjs functor
+export type { YjsNativeMap } from "./native-map.js"
 // Container creation
 export { ensureContainers } from "./populate.js"
 // Reader
 export { yjsReader } from "./reader.js"
 // Substrate
-export { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
+export {
+  createYjsSubstrate,
+  yjsReplicaFactory,
+  yjsSubstrateFactory,
+} from "./substrate.js"
 // Version
 export { YjsVersion } from "./version.js"
-// Escape hatch — access the underlying Y.Doc from a ref
-export { yjs } from "./yjs-escape.js"
 // Container resolution
 export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"

package/src/native-map.ts

@@ -0,0 +1,37 @@
+// native-map — Yjs NativeMap functor.
+//
+// Maps schema kinds to Yjs shared types. Used as the `N`
+// type parameter in `SchemaRef<S, M, N>` for Yjs-backed documents.
+
+import type { NativeMap } from "@kyneta/schema"
+import type * as Y from "yjs"
+
+/**
+ * NativeMap for the Yjs CRDT substrate.
+ *
+ * Maps each schema kind to the corresponding Yjs shared type:
+ * - `root → Y.Doc` (the document itself)
+ * - `text → Y.Text`
+ * - `counter → undefined` (Yjs has no counter type)
+ * - `list → Y.Array<unknown>`
+ * - `movableList → undefined` (Yjs has no movable list)
+ * - `struct → Y.Map<unknown>` (Yjs uses maps for struct fields)
+ * - `map → Y.Map<unknown>`
+ * - `tree → undefined` (Yjs has no tree type)
+ * - `set → undefined` (not yet supported)
+ * - `scalar → undefined` (no container; stored in parent map)
+ * - `sum → undefined` (no container; stored in parent map)
+ */
+export interface YjsNativeMap extends NativeMap {
+  readonly root: Y.Doc
+  readonly text: Y.Text
+  readonly counter: undefined
+  readonly list: Y.Array<unknown>
+  readonly movableList: undefined
+  readonly struct: Y.Map<unknown>
+  readonly map: Y.Map<unknown>
+  readonly tree: undefined
+  readonly set: undefined
+  readonly scalar: undefined
+  readonly sum: undefined
+}

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 { STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
+import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -26,9 +26,9 @@ 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.
  *
  * When `conditional` is true, fields that already exist in the root map
  * are skipped. This is the correct mode after hydration — containers
@@ -45,7 +45,7 @@ import * as Y from "yjs"
  * 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)
  */
@@ -56,15 +56,7 @@ export function ensureContainers(
 ): 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
   }
 
@@ -75,7 +67,7 @@ export function ensureContainers(
 
   try {
     doc.transact(() => {
-      for (const [key, fieldSchema] of Object.entries(rootProduct.fields).sort(
+      for (const [key, fieldSchema] of Object.entries(schema.fields).sort(
         ([a], [b]) => a.localeCompare(b),
       )) {
         if (conditional && rootMap.has(key)) continue
@@ -95,62 +87,36 @@ export function ensureContainers(
 /**
  * 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
@@ -162,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}".`,
+      )
   }
 }
 
@@ -175,37 +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>,
+    schema.fields as Record<string, SchemaNode>,
   ).sort(([a], [b]) => a.localeCompare(b))) {
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-    if (tag === "text") {
-      map.set(key, new Y.Text())
-      continue
-    }
-
-    const fs = unwrapAnnotations(fieldSchema)
+    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)
@@ -214,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
-}