@kyneta/yjs-schema 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# @kyneta/yjs-schema
+
+Yjs CRDT substrate for `@kyneta/schema` — collaborative data types with typed refs.
+
+Wraps a `Y.Doc` with schema-aware typed reads, writes, versioning, and export/import through the standard `Substrate<YjsVersion>` interface. Adding a Yjs substrate proves the schema algebra's portability beyond Loro and opens the door to the entire Yjs ecosystem (y-websocket, y-indexeddb, y-webrtc, Hocuspocus, Liveblocks, etc.).
+
+## Quick Start
+
+```ts
+import {
+  createYjsDoc,
+  change,
+  subscribe,
+  Schema,
+  text,
+  version,
+  exportSnapshot,
+  exportSince,
+  importDelta,
+} from "@kyneta/yjs-schema"
+
+// Define a schema
+const TodoDoc = Schema.doc({
+  title: text(),
+  items: Schema.list(
+    Schema.struct({
+      name: Schema.string(),
+      done: Schema.boolean(),
+    }),
+  ),
+})
+
+// Create a document with optional seed values
+const doc = createYjsDoc(TodoDoc, {
+  title: "My Todos",
+  items: [{ name: "Buy milk", done: false }],
+})
+
+// Read
+doc.title()           // "My Todos"
+doc.items.length      // 1
+
+// Write
+change(doc, (d) => {
+  d.title.insert(9, " (v2)")
+  d.items.push({ name: "Walk dog", done: false })
+})
+
+// Observe
+subscribe(doc, (changeset) => {
+  console.log("Changed:", changeset.ops.length, "ops")
+})
+```
+
+## Schema Types Supported
+
+| Schema type | Yjs backing type | Notes |
+|---|---|---|
+| `text()` | `Y.Text` | Character-level collaborative editing |
+| `Schema.struct({...})` | `Y.Map` | Fixed-key product type |
+| `Schema.list(item)` | `Y.Array` | Ordered sequence |
+| `Schema.record(item)` | `Y.Map` | Dynamic-key map |
+| `Schema.string()` | Plain value | Stored in parent `Y.Map` |
+| `Schema.number()` | Plain value | Stored in parent `Y.Map` |
+| `Schema.boolean()` | Plain value | Stored in parent `Y.Map` |
+
+### Unsupported
+
+- **`Schema.annotated("counter")`** — Yjs has no native counter type. Use `Schema.number()` with `ReplaceChange` instead. Attempting to use a counter annotation will throw at construction time.
+- **`Schema.annotated("movable")`** — Yjs has no native movable list. Will throw at construction time.
+- **`Schema.annotated("tree")`** — Yjs has no native tree type. Will throw at construction time.
+
+## Sync
+
+```ts
+import {
+  createYjsDoc,
+  createYjsDocFromSnapshot,
+  version,
+  exportSnapshot,
+  exportSince,
+  importDelta,
+  change,
+} from "@kyneta/yjs-schema"
+
+// Peer A creates a doc
+const docA = createYjsDoc(MySchema, { title: "Draft" })
+
+// Peer B bootstraps from a full snapshot
+const snapshot = exportSnapshot(docA)
+const docB = createYjsDocFromSnapshot(MySchema, snapshot)
+
+// After mutations on A, sync incrementally
+const vBefore = version(docB)
+change(docA, (d) => d.title.insert(5, " v2"))
+
+const delta = exportSince(docA, vBefore)
+importDelta(docB, delta!)
+// docB.title() === "Draft v2"
+```
+
+## Exchange Integration
+
+```ts
+import { bindYjs } from "@kyneta/yjs-schema"
+import { Schema, text } from "@kyneta/yjs-schema"
+
+const TodoDoc = bindYjs(Schema.doc({
+  title: text(),
+  items: Schema.list(Schema.struct({
+    name: Schema.string(),
+    done: Schema.boolean(),
+  })),
+}))
+
+// Use with @kyneta/exchange
+const doc = exchange.get("my-todos", TodoDoc)
+```
+
+`bindYjs` produces a `BoundSchema` with `strategy: "causal"`, which the exchange uses for bidirectional CRDT sync.
+
+## Escape Hatch
+
+Access the underlying `Y.Doc` for direct Yjs API usage:
+
+```ts
+import { yjs } from "@kyneta/yjs-schema"
+
+const doc = createYjsDoc(MySchema)
+const yjsDoc = yjs(doc)
+
+// Use with Yjs ecosystem
+// y-websocket, y-indexeddb, y-webrtc, Hocuspocus, etc.
+yjsDoc.getMap("root").toJSON()  // raw state
+yjsDoc.clientID                  // client ID
+```
+
+## Yjs Ecosystem Compatibility
+
+Because `yjs(doc)` returns a standard `Y.Doc`, the entire Yjs provider ecosystem works out of the box:
+
+- **y-websocket** — WebSocket sync
+- **y-indexeddb** — Local persistence
+- **y-webrtc** — Peer-to-peer sync
+- **Hocuspocus** — Scalable Yjs server
+- **Liveblocks** — Managed collaboration infrastructure
+- **y-prosemirror** / **y-codemirror** — Rich text editor bindings
+
+## API Reference
+
+### Batteries-included (most users)
+
+| Export | Description |
+|---|---|
+| `createYjsDoc(schema, docOrSeed?)` | Create a live Yjs-backed document |
+| `createYjsDocFromSnapshot(schema, payload)` | Reconstruct from snapshot |
+| `version(doc)` | Current `YjsVersion` |
+| `exportSnapshot(doc)` | Full state as `SubstratePayload` |
+| `exportSince(doc, since)` | Delta since version |
+| `importDelta(doc, payload, origin?)` | Apply delta from peer |
+| `change(doc, fn)` | Transactional mutation |
+| `subscribe(doc, callback)` | Observe changes |
+| `bindYjs(schema)` | Bind schema for exchange use |
+| `yjs(ref)` | Escape hatch → `Y.Doc` |
+| `text()` | `Schema.annotated("text")` convenience |
+
+### Low-level primitives (power users)
+
+| Export | Description |
+|---|---|
+| `YjsVersion` | Version class wrapping Yjs state vectors |
+| `yjsStoreReader(doc, schema)` | Live `StoreReader` over Yjs types |
+| `resolveYjsType(rootMap, schema, path)` | Path resolution |
+| `applyChangeToYjs(rootMap, schema, path, change)` | kyneta → Yjs |
+| `eventsToOps(events)` | Yjs → kyneta |
+| `populateRoot(doc, schema, seed)` | Root container population |
+| `createYjsSubstrate(doc, schema)` | Low-level substrate construction |
+| `yjsSubstrateFactory` | `SubstrateFactory<YjsVersion>` |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+import { Version, Schema, Ref, SubstratePayload, StoreReader, Path, Segment, ChangeBase, Op, Substrate, SubstrateFactory, BoundSchema, AnnotatedSchema } from '@kyneta/schema';
+export { Changeset, Op, Ref, Schema, SubstratePayload, applyChanges, change, subscribe, subscribeNode } from '@kyneta/schema';
+import * as Y from 'yjs';
+import { Doc } from 'yjs';
+
+/**
+ * A Version wrapping a Yjs state vector.
+ *
+ * State vectors track the complete peer state — which operations from
+ * each client have been observed. This is the right abstraction for sync
+ * diffing: `exportSince(version)` uses the state vector to compute the
+ * minimal update payload via `Y.encodeStateAsUpdate(doc, sv)`.
+ *
+ * `serialize()` encodes to base64 for text-safe embedding.
+ * `compare()` decodes both state vectors and performs standard
+ * version-vector partial-order comparison over the client-clock maps.
+ */
+declare class YjsVersion implements Version {
+    readonly sv: Uint8Array;
+    constructor(sv: Uint8Array);
+    /**
+     * Serialize the state vector to a base64 string.
+     *
+     * The encoding is: raw state vector bytes → base64.
+     * This is text-safe for embedding in HTML meta tags, URL parameters, etc.
+     */
+    serialize(): string;
+    /**
+     * 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:
+     *
+     * - 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`.
+     */
+    compare(other: Version): "behind" | "equal" | "ahead" | "concurrent";
+    /**
+     * Parse a serialized YjsVersion string back into a YjsVersion.
+     *
+     * The inverse of `serialize()`: base64 → `Uint8Array`.
+     */
+    static parse(serialized: string): YjsVersion;
+}
+
+/**
+ * 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 Schema>(schema: S, doc?: Y.Doc) => Ref<S>;
+declare const createYjsDoc: CreateYjsDoc;
+type CreateYjsDocFromSnapshot = <S extends Schema>(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
+ * ```
+ */
+declare const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot;
+
+/**
+ * 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 `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ */
+declare function version(doc: object): YjsVersion;
+/**
+ * Export the full substrate snapshot — sufficient for a new peer to
+ * reconstruct an equivalent document via `createYjsDocFromSnapshot()`.
+ *
+ * Returns a binary `SubstratePayload` (Yjs state-as-update bytes).
+ *
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ */
+declare function exportSnapshot(doc: object): SubstratePayload;
+/**
+ * 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)
+ * importDelta(docB, delta!)
+ * ```
+ *
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @param since - The version to diff from.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ */
+declare function exportSince(doc: object, since: YjsVersion): SubstratePayload | null;
+/**
+ * Import a delta payload into a live document.
+ *
+ * The payload must have been produced by `exportSince()` or
+ * `exportSnapshot()` on a compatible document.
+ *
+ * After import, the changefeed fires for all subscribers — the event
+ * bridge handles this automatically.
+ *
+ * ```ts
+ * const delta = exportSince(docA, sinceVersion)
+ * importDelta(docB, delta!, "sync")
+ * ```
+ *
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @param payload - The delta or snapshot payload to import.
+ * @param origin - Optional provenance tag for the changeset.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ */
+declare function importDelta(doc: object, payload: SubstratePayload, origin?: string): void;
+
+/**
+ * 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.
+ */
+declare function yjsStoreReader(doc: Y.Doc, schema: Schema): StoreReader;
+
+/**
+ * Navigate one step deeper into the Yjs shared type tree.
+ *
+ * Uses `instanceof` for runtime type discrimination:
+ * - `Y.Map` → `.get(key)`
+ * - `Y.Array` → `.get(index)`
+ * - `Y.Text` → terminal (cannot step further)
+ * - Plain value → terminal (return `undefined`)
+ *
+ * @param current - The current position (a Yjs shared type or plain value)
+ * @param segment - The path segment to follow
+ */
+declare function stepIntoYjs(current: unknown, segment: Segment): unknown;
+/**
+ * Resolve a Yjs shared type (or plain value) at the given path.
+ *
+ * Left-folds over path segments using `advanceSchema` for pure schema
+ * descent and `stepIntoYjs` for Yjs-specific navigation.
+ *
+ * Returns the Yjs shared type or plain value at the terminal position.
+ * For an empty path, returns the root map itself.
+ *
+ * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
+ * @param rootSchema - The root document schema
+ * @param path - The path to resolve
+ */
+declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
+
+/**
+ * Apply a kyneta Change to the Yjs shared type tree imperatively.
+ *
+ * Resolves the target shared type at `path`, then applies the change
+ * via the appropriate Yjs API. Must be called within a `doc.transact()`
+ * for atomicity and correct event batching.
+ *
+ * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
+ * @param rootSchema - The root document schema
+ * @param path - The path to the target
+ * @param change - The kyneta Change to apply
+ */
+declare function applyChangeToYjs(rootMap: Y.Map<any>, rootSchema: Schema, path: Path, change: ChangeBase): void;
+/**
+ * Convert `observeDeep` events into kyneta `Op[]` for changefeed delivery.
+ *
+ * Each `Y.YEvent` in the array maps to one Op with:
+ * - `path`: derived from `event.path` (relative to the observed root Y.Map)
+ * - `change`: derived from the event's delta/keys based on target type
+ *
+ * `event.path` in `observeDeep` is relative to the observed shared type.
+ * Since we observe `rootMap` (the single root Y.Map), paths map directly
+ * to kyneta `PathSegment[]`.
+ *
+ * @param events - The events from the `observeDeep` callback
+ */
+declare function eventsToOps(events: Y.YEvent<any>[]): Op[];
+
+/**
+ * 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))
+ */
+declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
+
+/**
+ * Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
+ *
+ * This is the "bring your own doc" entry point. The user creates and
+ * manages the Y.Doc (possibly via a Yjs provider); this function wraps
+ * it with a schema-aware overlay providing typed reads, writes,
+ * versioning, and export/import through the standard Substrate interface.
+ *
+ * **Event bridge contract:** A persistent `observeDeep` handler is
+ * registered on the root Y.Map at construction time. All non-kyneta
+ * mutations to the Y.Doc (imports, external local writes) are bridged
+ * to the kyneta changefeed. Subscribing to the kyneta doc observes all
+ * mutations regardless of source.
+ *
+ * @param doc - The Y.Doc to wrap. The substrate does NOT own the doc;
+ *   the caller is responsible for its lifecycle.
+ * @param schema - The root schema for the document.
+ */
+declare function createYjsSubstrate(doc: Y.Doc, schema: Schema): Substrate<YjsVersion>;
+/**
+ * Factory for constructing Yjs-backed substrates.
+ *
+ * - `create(schema)` — creates a fresh Y.Doc with empty containers
+ *   matching the schema structure. No seed data — initial content
+ *   should be applied via `change()` after construction.
+ * - `fromSnapshot(payload, schema)` — creates a Y.Doc from a snapshot
+ *   payload, returns a substrate.
+ * - `parseVersion(serialized)` — deserializes a YjsVersion.
+ */
+declare const yjsSubstrateFactory: SubstrateFactory<YjsVersion>;
+
+/**
+ * Bind a schema to the Yjs CRDT substrate with causal merge strategy.
+ *
+ * This is the recommended way to declare a Yjs-backed document type.
+ * The factory builder injects a deterministic numeric Yjs clientID derived
+ * from the exchange's string peerId, ensuring consistent change attribution
+ * across all documents and sessions.
+ *
+ * **Unsupported annotations:** Yjs has no native counter, movable list,
+ * or tree types. Schemas passed to `bindYjs` must not contain
+ * `Schema.annotated("counter")`, `Schema.annotated("movable")`, or
+ * `Schema.annotated("tree")`. These will throw at construction time.
+ *
+ * @example
+ * ```ts
+ * import { bindYjs } from "@kyneta/yjs-schema"
+ * import { Schema } from "@kyneta/schema"
+ *
+ * const TodoDoc = bindYjs(Schema.doc({
+ *   title: Schema.annotated("text"),
+ *   items: Schema.list(Schema.struct({
+ *     name: Schema.string(),
+ *     done: Schema.boolean(),
+ *   })),
+ * }))
+ *
+ * const doc = exchange.get("my-todos", TodoDoc)
+ * ```
+ */
+declare function bindYjs<S extends Schema>(schema: S): BoundSchema<S>;
+
+/**
+ * Returns the `Y.Doc` backing the given ref.
+ *
+ * This is the Yjs-specific escape hatch for accessing substrate-level
+ * capabilities: raw Yjs API, y-prosemirror/y-codemirror bindings,
+ * undo manager, awareness protocol, Yjs providers (y-websocket,
+ * y-indexeddb, y-webrtc, Hocuspocus, Liveblocks), etc.
+ *
+ * Currently supports root document refs only. Child-level resolution
+ * (e.g. `yjs(doc.title)` → `Y.Text`) is future work.
+ *
+ * @param ref - A root document ref backed by a Yjs substrate
+ * @returns The `Y.Doc` backing the ref
+ * @throws If the ref is not backed by a Yjs substrate
+ *
+ * @example
+ * ```ts
+ * import { yjs } from "@kyneta/yjs-schema"
+ *
+ * const doc = exchange.get("my-doc", TodoDoc)
+ * const yjsDoc = yjs(doc)
+ * console.log(yjsDoc.getMap("root").toJSON())  // raw state
+ * console.log(yjsDoc.clientID)                  // client ID
+ * ```
+ */
+declare function yjs(ref: object): Doc;
+
+/**
+ * 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()`.
+ */
+declare function text(): AnnotatedSchema<"text", undefined>;
+
+export { YjsVersion, applyChangeToYjs, bindYjs, createYjsDoc, createYjsDocFromSnapshot, createYjsSubstrate, ensureContainers, eventsToOps, exportSince, exportSnapshot, importDelta, resolveYjsType, stepIntoYjs, text, version, yjs, yjsStoreReader, yjsSubstrateFactory };