@kyneta/yjs-schema 1.2.0 → 1.3.1

package/src/index.ts

@@ -3,51 +3,49 @@
 // 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"
-
-// Types (re-exported for convenience)
-export type { Changeset } from "@kyneta/changefeed"
-export type { Op, Ref, SubstratePayload } from "@kyneta/schema"
+} from "@kyneta/schema"
 
 // ---------------------------------------------------------------------------
-// Low-level primitives — for power users and custom substrate compositions
+// Yjs-specific exports
 // ---------------------------------------------------------------------------
 
-// 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"
+// 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
@@ -61,4 +59,4 @@ export {
 // Version
 export { YjsVersion } from "./version.js"
 // Container resolution
-export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"
+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

@@ -200,4 +200,4 @@ function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
   }
 
   return map
-}
+}

package/src/substrate.ts

@@ -22,12 +22,18 @@ import type {
   SubstratePayload,
   WritableContext,
 } from "@kyneta/schema"
-import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema"
+import {
+  BACKING_DOC,
+  buildWritableContext,
+  executeBatch,
+  KIND,
+} from "@kyneta/schema"
 import * as Y from "yjs"
 import { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
 import { ensureContainers } from "./populate.js"
 import { yjsReader } from "./reader.js"
 import { YjsVersion } from "./version.js"
+import { resolveYjsType } from "./yjs-resolve.js"
 
 // ---------------------------------------------------------------------------
 // Origin tag — used to suppress echo from our own transactions
@@ -124,6 +130,17 @@ export function createYjsSubstrate(
     context(): WritableContext {
       if (!cachedCtx) {
         cachedCtx = buildWritableContext(substrate)
+        // Attach nativeResolver — used by interpretImpl to set [NATIVE]
+        // on every ref. The resolver maps schema positions to Yjs shared types.
+        ;(cachedCtx as any).nativeResolver = (
+          nodeSchema: SchemaNode,
+          path: { segments: readonly unknown[] },
+        ) => {
+          if (path.segments.length === 0) return doc
+          if (nodeSchema[KIND] === "scalar" || nodeSchema[KIND] === "sum")
+            return undefined
+          return resolveYjsType(rootMap, schema, path as any)
+        }
       }
       return cachedCtx
     },
@@ -252,9 +269,7 @@ export function createYjsSubstrate(
  */
 export function createYjsReplica(doc: Y.Doc): Replica<YjsVersion> {
   let currentDoc = doc
-  let currentBase: YjsVersion = new YjsVersion(
-    Y.encodeStateVector(new Y.Doc()),
-  )
+  let currentBase: YjsVersion = new YjsVersion(Y.encodeStateVector(new Y.Doc()))
 
   return {
     get [BACKING_DOC]() {

package/src/version.ts

@@ -12,30 +12,14 @@
 // decoded `Map<number, number>` (clientID → clock) maps ourselves.
 
 import type { Version } from "@kyneta/schema"
-import { versionVectorMeet } from "@kyneta/schema"
+import {
+  base64ToUint8Array,
+  uint8ArrayToBase64,
+  versionVectorCompare,
+  versionVectorMeet,
+} from "@kyneta/schema"
 import { decodeStateVector } from "yjs"
 
-// ---------------------------------------------------------------------------
-// Base64 helpers (platform-agnostic, no Node.js Buffer dependency)
-// ---------------------------------------------------------------------------
-
-function uint8ArrayToBase64(bytes: Uint8Array): string {
-  let binary = ""
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]!)
-  }
-  return btoa(binary)
-}
-
-function base64ToUint8Array(base64: string): Uint8Array {
-  const binary = atob(base64)
-  const bytes = new Uint8Array(binary.length)
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i)
-  }
-  return bytes
-}
-
 // ---------------------------------------------------------------------------
 // State vector encoding — manual varint (unsigned LEB128)
 // ---------------------------------------------------------------------------
@@ -105,54 +89,19 @@ export class YjsVersion implements Version {
   /**
    * Compare with another version using version-vector partial order.
    *
-   * Decodes both state vectors via `Y.decodeStateVector()` to get
-   * `Map<number, number>` (clientID → clock), then compares:
+   * Delegates to the shared `versionVectorCompare` utility after decoding
+   * both state vectors via `Y.decodeStateVector()`.
    *
-   * - Collect the union of all client IDs from both maps.
-   * - For each client, compare clocks (missing client = clock 0).
-   * - If all clocks in `this` ≤ `other` and at least one strictly less → `"behind"`
-   * - If all clocks in `this` ≥ `other` and at least one strictly greater → `"ahead"`
-   * - If all clocks equal → `"equal"`
-   * - Otherwise → `"concurrent"`
-   *
-   * Throws if `other` is not a `YjsVersion`.
+   * @throws If `other` is not a `YjsVersion`.
    */
   compare(other: Version): "behind" | "equal" | "ahead" | "concurrent" {
     if (!(other instanceof YjsVersion)) {
       throw new Error("YjsVersion can only be compared with another YjsVersion")
     }
-
-    const thisMap = decodeStateVector(this.sv)
-    const otherMap = decodeStateVector(other.sv)
-
-    // Collect the union of all client IDs
-    const allClients = new Set<number>()
-    for (const id of thisMap.keys()) allClients.add(id)
-    for (const id of otherMap.keys()) allClients.add(id)
-
-    let hasLess = false
-    let hasGreater = false
-
-    for (const clientId of allClients) {
-      const thisClock = thisMap.get(clientId) ?? 0
-      const otherClock = otherMap.get(clientId) ?? 0
-
-      if (thisClock < otherClock) {
-        hasLess = true
-      }
-      if (thisClock > otherClock) {
-        hasGreater = true
-      }
-
-      // Early exit: if we've seen both less and greater, it's concurrent
-      if (hasLess && hasGreater) {
-        return "concurrent"
-      }
-    }
-
-    if (hasLess && !hasGreater) return "behind"
-    if (hasGreater && !hasLess) return "ahead"
-    return "equal"
+    return versionVectorCompare(
+      decodeStateVector(this.sv),
+      decodeStateVector(other.sv),
+    )
   }
 
   /**
@@ -166,9 +115,7 @@ export class YjsVersion implements Version {
    */
   meet(other: Version): YjsVersion {
     if (!(other instanceof YjsVersion)) {
-      throw new Error(
-        "YjsVersion can only be meet'd with another YjsVersion",
-      )
+      throw new Error("YjsVersion can only be meet'd with another YjsVersion")
     }
     const thisMap = decodeStateVector(this.sv)
     const otherMap = decodeStateVector(other.sv)

package/src/yjs-resolve.ts

@@ -15,7 +15,7 @@
 // captures all mutations with correct relative paths.
 
 import type { Path, Schema as SchemaNode, Segment } from "@kyneta/schema"
-import { advanceSchema, KIND } from "@kyneta/schema"
+import { advanceSchema } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------

package/src/create.ts

@@ -1,177 +0,0 @@
-// create — batteries-included document construction backed by YjsSubstrate.
-//
-// Provides `createYjsDoc` and `createYjsDocFromEntirety` 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`, `exportEntirety`, `merge` 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 type {
-  Ref,
-  Schema as SchemaType,
-  Substrate,
-  SubstratePayload,
-} from "@kyneta/schema"
-import {
-  interpret,
-  observation,
-  readable,
-  registerSubstrate,
-  writable,
-} from "@kyneta/schema"
-import type * as Y from "yjs"
-import { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
-import type { YjsVersion } from "./version.js"
-
-// ---------------------------------------------------------------------------
-// Substrate tracking (module-scoped)
-// ---------------------------------------------------------------------------
-
-const substrates = new WeakMap<object, Substrate<YjsVersion>>()
-
-/**
- * Retrieve the substrate associated with a doc created by `createYjsDoc`
- * or `createYjsDocFromEntirety`.
- *
- * Exported for `sync.ts` — NOT re-exported from the barrel.
- *
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
- */
-export function getSubstrate(doc: object): Substrate<YjsVersion> {
-  const s = substrates.get(doc)
-  if (!s) {
-    throw new Error(
-      "version/exportEntirety/merge called on an object without a YjsSubstrate. " +
-        "Use a doc created by createYjsDoc() or createYjsDocFromEntirety().",
-    )
-  }
-  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/createYjsDocFromEntirety 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(observation)
-    .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, merge, 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))
-}
-
-// ---------------------------------------------------------------------------
-// createYjsDocFromEntirety
-// ---------------------------------------------------------------------------
-
-type CreateYjsDocFromEntirety = <S extends SchemaType>(
-  schema: S,
-  payload: SubstratePayload,
-) => Ref<S>
-
-/**
- * Reconstruct a live Yjs-backed document from a substrate entirety payload.
- *
- * The payload must have been produced by `exportEntirety()` on a
- * compatible document. This is the entry point for SSR hydration
- * and reconnection past log compaction.
- *
- * ```ts
- * const payload = exportEntirety(docA)
- * const docB = createYjsDocFromEntirety(MySchema, payload)
- * // docB has the same state as docA at the time of export
- * ```
- */
-export const createYjsDocFromEntirety: CreateYjsDocFromEntirety = (
-  schema,
-  payload,
-) => registerDoc(schema, yjsSubstrateFactory.fromEntirety(payload, schema))

package/src/sync.ts

@@ -1,107 +0,0 @@
-// sync — sync primitives for YjsSubstrate-backed documents.
-//
-// These functions provide version tracking, entirety export, and merge
-// for documents created via `createYjsDoc` or
-// `createYjsDocFromEntirety`. They discover the substrate via the
-// module-scoped WeakMap in `create.ts`.
-//
-// Unlike PlainSubstrate's sync (which returns Op[] for deltas),
-// YjsSubstrate's sync uses binary SubstratePayload for both entireties
-// and deltas — these are Yjs's native state-as-update bytes.
-
-import type { SubstratePayload } from "@kyneta/schema"
-import { getSubstrate } from "./create.js"
-import type { YjsVersion } from "./version.js"
-
-// ---------------------------------------------------------------------------
-// version — current YjsVersion
-// ---------------------------------------------------------------------------
-
-/**
- * Current version as a `YjsVersion` (wrapping a Yjs state vector).
- *
- * Use `.serialize()` to get a text-safe string for embedding in HTML
- * meta tags, URL parameters, etc.
- *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
- */
-export function version(doc: object): YjsVersion {
-  return getSubstrate(doc).version()
-}
-
-// ---------------------------------------------------------------------------
-// exportEntirety — full state for reconstruction
-// ---------------------------------------------------------------------------
-
-/**
- * Export the full substrate entirety — sufficient for a new peer to
- * reconstruct an equivalent document via `createYjsDocFromEntirety()`.
- *
- * Returns a binary `SubstratePayload` (Yjs state-as-update bytes).
- *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
- */
-export function exportEntirety(doc: object): SubstratePayload {
-  return getSubstrate(doc).exportEntirety()
-}
-
-// ---------------------------------------------------------------------------
-// exportSince — delta since a version
-// ---------------------------------------------------------------------------
-
-/**
- * Export a delta payload containing all changes since the given version.
- *
- * Returns a binary `SubstratePayload` (Yjs update bytes), or `null`
- * if the delta cannot be computed.
- *
- * ```ts
- * const v0 = version(docA)
- * change(docA, d => d.title.insert(0, "Hi"))
- * const delta = exportSince(docA, v0)
- * merge(docB, delta!)
- * ```
- *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
- * @param since - The version to diff from.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
- */
-export function exportSince(
-  doc: object,
-  since: YjsVersion,
-): SubstratePayload | null {
-  return getSubstrate(doc).exportSince(since)
-}
-
-// ---------------------------------------------------------------------------
-// merge — apply a delta from another peer
-// ---------------------------------------------------------------------------
-
-/**
- * Import a delta payload into a live document.
- *
- * The payload must have been produced by `exportSince()` or
- * `exportEntirety()` on a compatible document.
- *
- * After import, the changefeed fires for all subscribers — the event
- * bridge handles this automatically.
- *
- * ```ts
- * const delta = exportSince(docA, sinceVersion)
- * merge(docB, delta!, "sync")
- * ```
- *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
- * @param payload - The delta or entirety payload to merge.
- * @param origin - Optional provenance tag for the changeset.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
- */
-export function merge(
-  doc: object,
-  payload: SubstratePayload,
-  origin?: string,
-): void {
-  getSubstrate(doc).merge(payload, origin)
-}