@kyneta/yjs-schema 1.0.0

package/src/create.ts

@@ -0,0 +1,172 @@
+// create — batteries-included document construction backed by YjsSubstrate.
+//
+// Provides `createYjsDoc` and `createYjsDocFromSnapshot` functions that
+// hide the interpret pipeline and layer composition behind a single call.
+//
+// Internally tracks substrates via a module-scoped WeakMap so that sync
+// primitives (`version`, `exportSnapshot`, `importDelta` in sync.ts)
+// can retrieve the substrate from just a doc ref.
+//
+// `getSubstrate` is exported for use by `sync.ts` but is NOT re-exported
+// from the barrel (`index.ts`). It is an internal cross-module helper.
+//
+// Two forms for `createYjsDoc`:
+//   createYjsDoc(schema, yjsDoc)    — "bring your own doc" (wrap existing)
+//   createYjsDoc(schema)            — create a fresh empty Y.Doc
+
+import { interpret, registerSubstrate } from "@kyneta/schema"
+import { changefeed, readable, writable } from "@kyneta/schema"
+import type { Ref } from "@kyneta/schema"
+import type { Schema as SchemaType } from "@kyneta/schema"
+import type { Substrate, SubstratePayload } from "@kyneta/schema"
+import * as Y from "yjs"
+import { YjsVersion } from "./version.js"
+import { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
+
+// ---------------------------------------------------------------------------
+// Substrate tracking (module-scoped)
+// ---------------------------------------------------------------------------
+
+const substrates = new WeakMap<object, Substrate<YjsVersion>>()
+
+/**
+ * Retrieve the substrate associated with a doc created by `createYjsDoc`
+ * or `createYjsDocFromSnapshot`.
+ *
+ * Exported for `sync.ts` — NOT re-exported from the barrel.
+ *
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ */
+export function getSubstrate(doc: object): Substrate<YjsVersion> {
+  const s = substrates.get(doc)
+  if (!s) {
+    throw new Error(
+      "version/exportSnapshot/importDelta called on an object without a YjsSubstrate. " +
+        "Use a doc created by createYjsDoc() or createYjsDocFromSnapshot().",
+    )
+  }
+  return s
+}
+
+// ---------------------------------------------------------------------------
+// registerDoc — internal helper (interpret + WeakMap registration)
+// ---------------------------------------------------------------------------
+
+function registerDoc(
+  schema: SchemaType,
+  substrate: Substrate<YjsVersion>,
+): any {
+  // The `as any` on the builder avoids TS2589 — interpret's fluent API
+  // produces deeply recursive types when S is the abstract SchemaType.
+  // The public createYjsDoc/createYjsDocFromSnapshot signatures provide
+  // the correct Ref<S> return type via interface call signature patterns.
+  const doc: any = (interpret as any)(schema, substrate.context())
+    .with(readable)
+    .with(writable)
+    .with(changefeed)
+    .done()
+  substrates.set(doc, substrate)
+  // Also register in the general unwrap() registry so that the
+  // yjs() escape hatch can discover the substrate from the ref.
+  registerSubstrate(doc, substrate)
+  return doc
+}
+
+// ---------------------------------------------------------------------------
+// isYDoc — runtime check for Y.Doc
+// ---------------------------------------------------------------------------
+
+function isYDoc(value: unknown): value is Y.Doc {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    "getMap" in value &&
+    "getText" in value &&
+    "getArray" in value &&
+    "transact" in value &&
+    typeof (value as any).transact === "function" &&
+    // Y.Doc has clientID; distinguish from other objects
+    "clientID" in value &&
+    typeof (value as any).clientID === "number"
+  )
+}
+
+// ---------------------------------------------------------------------------
+// createYjsDoc
+// ---------------------------------------------------------------------------
+
+// Interface call signature avoids TS2589 on Ref<S> when S is generic.
+
+/**
+ * Create a live Yjs-backed document.
+ *
+ * **Form 1 — bring your own doc:**
+ * ```ts
+ * const yjsDoc = new Y.Doc()
+ * const doc = createYjsDoc(mySchema, yjsDoc)
+ * ```
+ *
+ * **Form 2 — fresh empty doc:**
+ * ```ts
+ * const doc = createYjsDoc(mySchema)
+ *
+ * // Apply initial content via change():
+ * change(doc, d => {
+ *   d.title.insert(0, "Hello")
+ *   d.items.push({ name: "First item" })
+ * })
+ * ```
+ *
+ * Returns a full-stack `Ref<S>` — callable, navigable, writable,
+ * transactable, and observable. Backed by a `YjsSubstrate` with
+ * CRDT collaboration support.
+ *
+ * The returned ref observes **all** mutations to the underlying Y.Doc,
+ * regardless of source (local kyneta writes, importDelta, external
+ * `Y.applyUpdate()`, external raw Yjs API mutations).
+ *
+ * @param schema - The schema describing the document structure.
+ * @param doc - Optional `Y.Doc` instance to wrap. If omitted, a fresh
+ *   empty Y.Doc is created with containers matching the schema.
+ */
+type CreateYjsDoc = <S extends SchemaType>(
+  schema: S,
+  doc?: Y.Doc,
+) => Ref<S>
+
+export const createYjsDoc: CreateYjsDoc = (schema, doc) => {
+  if (doc !== undefined && isYDoc(doc)) {
+    // Bring your own doc — wrap the existing Y.Doc
+    return registerDoc(schema, createYjsSubstrate(doc, schema))
+  }
+  // Fresh empty doc
+  return registerDoc(schema, yjsSubstrateFactory.create(schema))
+}
+
+// ---------------------------------------------------------------------------
+// createYjsDocFromSnapshot
+// ---------------------------------------------------------------------------
+
+type CreateYjsDocFromSnapshot = <S extends SchemaType>(
+  schema: S,
+  payload: SubstratePayload,
+) => Ref<S>
+
+/**
+ * Reconstruct a live Yjs-backed document from a substrate snapshot payload.
+ *
+ * The payload must have been produced by `exportSnapshot()` on a
+ * compatible document. This is the entry point for SSR hydration
+ * and reconnection past log compaction.
+ *
+ * ```ts
+ * const payload = exportSnapshot(docA)
+ * const docB = createYjsDocFromSnapshot(MySchema, payload)
+ * // docB has the same state as docA at the time of export
+ * ```
+ */
+export const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot = (
+  schema,
+  payload,
+) => registerDoc(schema, yjsSubstrateFactory.fromSnapshot(payload, schema))

package/src/index.ts

@@ -0,0 +1,83 @@
+// @kyneta/yjs-schema — Yjs CRDT substrate for @kyneta/schema.
+//
+// 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, createYjsDocFromSnapshot, version, exportSnapshot,
+//   exportSince, importDelta, change, subscribe, applyChanges
+//
+// Low-level primitives (power users):
+//   createYjsSubstrate, yjsSubstrateFactory, yjsStoreReader,
+//   resolveYjsType, stepIntoYjs, applyChangeToYjs, eventsToOps, YjsVersion
+
+// ---------------------------------------------------------------------------
+// Batteries-included API — one import, one createYjsDoc call, done
+// ---------------------------------------------------------------------------
+
+// Construction
+export { createYjsDoc, createYjsDocFromSnapshot } from "./create.js"
+
+// Sync primitives (Yjs-specific)
+export {
+  exportSince,
+  exportSnapshot,
+  importDelta,
+  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"
+
+// ---------------------------------------------------------------------------
+// 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"
+
+// Change mapping
+export { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
+
+// Container creation
+export { ensureContainers } from "./populate.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"

package/src/populate.ts

@@ -0,0 +1,208 @@
+// populate — Yjs container creation from schema structure.
+//
+// Ensures that the correct Yjs shared types (Y.Text, Y.Array, Y.Map)
+// exist in a Y.Doc's root map to match the schema structure, and that
+// scalar/sum fields are initialized with Zero.structural defaults.
+//
+// This is NOT seed data — it's structural completeness, matching what
+// PlainSubstrate does when it initializes its store with Zero.structural.
+// The Yjs store reader expects to find values at every schema path;
+// without this, unset scalars would return undefined instead of their
+// type-correct zero ("", 0, false).
+//
+// Root container strategy: All schema fields are children of a single
+// root `Y.Map` obtained via `doc.getMap("root")`. This root map holds
+// 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 * as Y from "yjs"
+
+// ---------------------------------------------------------------------------
+// ensureContainers — top-level entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ *
+ * No values are written — the containers are empty after this call.
+ * Initial content should be applied via `change()` after substrate
+ * construction.
+ *
+ * @param doc - The Y.Doc to prepare
+ * @param schema - The root document schema (typically annotated("doc", product))
+ */
+export function ensureContainers(doc: Y.Doc, schema: SchemaNode): void {
+  const rootMap = doc.getMap("root")
+
+  let rootProduct = schema
+  while (
+    rootProduct._kind === "annotated" &&
+    rootProduct.schema !== undefined
+  ) {
+    rootProduct = rootProduct.schema
+  }
+
+  if (rootProduct._kind !== "product") {
+    return
+  }
+
+  doc.transact(() => {
+    for (const [key, fieldSchema] of Object.entries(rootProduct.fields)) {
+      ensureRootField(rootMap, key, fieldSchema as SchemaNode)
+    }
+  })
+}
+
+// ---------------------------------------------------------------------------
+// ensureRootField — create a single root-level container
+// ---------------------------------------------------------------------------
+
+/**
+ * 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)
+ */
+function ensureRootField(
+  rootMap: Y.Map<unknown>,
+  key: string,
+  fieldSchema: SchemaNode,
+): void {
+  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
+
+  switch (tag) {
+    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))
+      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
+      // need structural zero defaults so the store reader returns
+      // type-correct values (e.g. "" not undefined for strings).
+      const zero = Zero.structural(fieldSchema)
+      if (zero !== undefined) {
+        rootMap.set(key, zero)
+      }
+      return
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ensureMapContainers — recursively create nested Y.Map structure
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an empty Y.Map with nested shared type children matching
+ * the product schema's field structure.
+ *
+ * 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.
+ */
+function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
+  const map = new Y.Map()
+  const structural = unwrapAnnotations(schema)
+
+  if (structural._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)
+
+    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)
+        if (zero !== undefined) {
+          map.set(key, zero)
+        }
+        break
+      }
+    }
+  }
+
+  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

@@ -0,0 +1,123 @@
+// store-reader — YjsStoreReader implementation.
+//
+// Implements StoreReader 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.
+//
+// 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 * as Y from "yjs"
+import { resolveYjsType } from "./yjs-resolve.js"
+
+// ---------------------------------------------------------------------------
+// Value extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a plain value from a Yjs shared type or return a plain value as-is.
+ *
+ * - Y.Text → `.toJSON()` (string)
+ * - Y.Map → `.toJSON()` (plain object snapshot — for product/map reads)
+ * - Y.Array → `.toJSON()` (plain array snapshot)
+ * - Plain values (string, number, boolean, null) → returned as-is
+ */
+function extractValue(resolved: unknown): unknown {
+  if (resolved instanceof Y.Text) {
+    return resolved.toJSON()
+  }
+  if (resolved instanceof Y.Map) {
+    return resolved.toJSON()
+  }
+  if (resolved instanceof Y.Array) {
+    return resolved.toJSON()
+  }
+  // Plain scalar value (string, number, boolean, null, etc.)
+  return resolved
+}
+
+// ---------------------------------------------------------------------------
+// yjsStoreReader
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a StoreReader that navigates the Yjs shared type tree live,
+ * using the schema as a type witness to determine navigation at each
+ * path segment.
+ *
+ * The reader is a live view — mutations to the underlying Y.Doc
+ * (via `doc.transact()`, or `Y.applyUpdate()`) are immediately
+ * visible through the reader.
+ *
+ * Internally obtains the root map via `doc.getMap("root")`.
+ *
+ * @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 {
+  const rootMap = doc.getMap("root")
+
+  return {
+    read(path: Path): unknown {
+      if (path.length === 0) {
+        // Root read — return the full root map as JSON
+        return rootMap.toJSON()
+      }
+      const resolved = resolveYjsType(rootMap, schema, path)
+      return extractValue(resolved)
+    },
+
+    arrayLength(path: Path): number {
+      const resolved = resolveYjsType(rootMap, schema, path)
+      if (resolved instanceof Y.Array) {
+        return resolved.length
+      }
+      // Graceful fallback for plain array values
+      if (Array.isArray(resolved)) {
+        return resolved.length
+      }
+      return 0
+    },
+
+    keys(path: Path): string[] {
+      const resolved = resolveYjsType(rootMap, schema, path)
+      if (resolved instanceof Y.Map) {
+        return Array.from(resolved.keys())
+      }
+      // Graceful fallback for plain object values
+      if (
+        resolved !== null &&
+        resolved !== undefined &&
+        typeof resolved === "object" &&
+        !Array.isArray(resolved)
+      ) {
+        return Object.keys(resolved as Record<string, unknown>)
+      }
+      return []
+    },
+
+    hasKey(path: Path, key: string): boolean {
+      const resolved = resolveYjsType(rootMap, schema, path)
+      if (resolved instanceof Y.Map) {
+        return resolved.has(key)
+      }
+      // Graceful fallback for plain object values
+      if (
+        resolved !== null &&
+        resolved !== undefined &&
+        typeof resolved === "object" &&
+        !Array.isArray(resolved)
+      ) {
+        return key in (resolved as Record<string, unknown>)
+      }
+      return false
+    },
+  }
+}