@kyneta/yjs-schema 1.1.0 → 1.3.0

package/README.md

@@ -20,7 +20,7 @@ import {
 } from "@kyneta/yjs-schema"
 
 // Define a schema
-const TodoDoc = Schema.doc({
+const TodoDoc = Schema.struct({
   title: text(),
   items: Schema.list(
     Schema.struct({
@@ -105,7 +105,7 @@ importDelta(docB, delta!)
 import { bindYjs } from "@kyneta/yjs-schema"
 import { Schema, text } from "@kyneta/yjs-schema"
 
-const TodoDoc = bindYjs(Schema.doc({
+const TodoDoc = bindYjs(Schema.struct({
   title: text(),
   items: Schema.list(Schema.struct({
     name: Schema.string(),
@@ -179,4 +179,4 @@ Because `yjs(doc)` returns a standard `Y.Doc`, the entire Yjs provider ecosystem
 
 ## License
 
-MIT
+MIT

package/dist/index.d.ts

@@ -1,193 +1,54 @@
-import { Version, Schema, Ref, SubstratePayload, BoundSchema, Path, ChangeBase, Op, Reader, Substrate, SubstrateFactory, Segment, AnnotatedSchema } from '@kyneta/schema';
-export { Changeset, Op, Ref, Schema, SubstratePayload, applyChanges, change, subscribe, subscribeNode } from '@kyneta/schema';
+export { Changeset } from '@kyneta/changefeed';
+import { NativeMap, SubstrateNamespace, CrdtStrategy, Schema, Path, ChangeBase, Op, Reader, Version, Substrate, ReplicaFactory, SubstrateFactory, Segment } from '@kyneta/schema';
+export { DocRef, NATIVE, Op, Ref, Schema, SubstratePayload, applyChanges, change, createDoc, createRef, exportEntirety, exportSince, merge, subscribe, subscribeNode, unwrap, version } 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;
+ * 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)
+ */
+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;
 }
 
 /**
- * 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 Schema>(schema: S, doc?: Y.Doc) => Ref<S>;
-declare const createYjsDoc: CreateYjsDoc;
-type CreateYjsDocFromEntirety = <S extends Schema>(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
- * ```
- */
-declare const createYjsDocFromEntirety: CreateYjsDocFromEntirety;
-
-/**
- * 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`.
- */
-declare function version(doc: object): YjsVersion;
-/**
- * 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`.
- */
-declare function exportEntirety(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)
- * 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`.
- */
-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
- * `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`.
- */
-declare function merge(doc: object, payload: SubstratePayload, origin?: string): void;
-
-/**
- * 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.
+ * The Yjs CRDT substrate namespace.
  *
- * @example
- * ```ts
- * import { bindYjs } from "@kyneta/yjs-schema"
- * import { Schema } from "@kyneta/schema"
+ * - `yjs.bind(schema)` — collaborative sync (default)
+ * - `yjs.bind(schema, "ephemeral")` — ephemeral/presence broadcast
+ * - `yjs.replica()` — collaborative replication (default)
+ * - `yjs.replica("ephemeral")` — ephemeral replication
  *
- * const TodoDoc = bindYjs(Schema.doc({
- *   title: Schema.annotated("text"),
- *   items: Schema.list(Schema.struct({
- *     name: Schema.string(),
- *     done: Schema.boolean(),
- *   })),
- * }))
+ * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
+ * Passing `"authoritative"` is a compile error.
  *
- * const doc = exchange.get("my-todos", TodoDoc)
- * ```
+ * To access the underlying Y.Doc, use `unwrap(ref)` from `@kyneta/schema`.
  */
-declare function bindYjs<S extends Schema>(schema: S): BoundSchema<S>;
+/** The closed set of capability tags that the Yjs substrate supports. */
+type YjsCaps = "text" | "json";
+declare const yjs: SubstrateNamespace<CrdtStrategy, YjsCaps, YjsNativeMap>;
 
 /**
  * Apply a kyneta Change to the Yjs shared type tree imperatively.
@@ -215,15 +76,15 @@ declare function applyChangeToYjs(rootMap: Y.Map<any>, rootSchema: Schema, path:
  *
  * @param events - The events from the `observeDeep` callback
  */
-declare function eventsToOps(events: Y.YEvent<any>[]): Op[];
+declare function eventsToOps(events: Y.YEvent<any>[], schema: Schema): 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.
+ * 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
@@ -240,7 +101,7 @@ declare function eventsToOps(events: Y.YEvent<any>[]): Op[];
  * 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)
  */
@@ -262,6 +123,55 @@ declare function ensureContainers(doc: Y.Doc, schema: Schema, conditional?: bool
  */
 declare function yjsReader(doc: Y.Doc, schema: Schema): Reader;
 
+/**
+ * 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.
+     *
+     * Delegates to the shared `versionVectorCompare` utility after decoding
+     * both state vectors via `Y.decodeStateVector()`.
+     *
+     * @throws If `other` is not a `YjsVersion`.
+     */
+    compare(other: Version): "behind" | "equal" | "ahead" | "concurrent";
+    /**
+     * Greatest lower bound (lattice meet) of two Yjs versions.
+     *
+     * Decodes both state vectors, computes the component-wise minimum
+     * via the shared `versionVectorMeet` utility, and encodes the result
+     * back to a Yjs state vector.
+     *
+     * @throws If `other` is not a `YjsVersion`.
+     */
+    meet(other: Version): YjsVersion;
+    /**
+     * Parse a serialized YjsVersion string back into a YjsVersion.
+     *
+     * The inverse of `serialize()`: base64 → `Uint8Array`.
+     */
+    static parse(serialized: string): YjsVersion;
+}
+
 /**
  * Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
  *
@@ -281,35 +191,9 @@ declare function yjsReader(doc: Y.Doc, schema: Schema): Reader;
  * @param schema - The root schema for the document.
  */
 declare function createYjsSubstrate(doc: Y.Doc, schema: Schema): Substrate<YjsVersion>;
+declare const yjsReplicaFactory: ReplicaFactory<YjsVersion>;
 declare const yjsSubstrateFactory: SubstrateFactory<YjsVersion>;
 
-/**
- * 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;
-
 /**
  * Navigate one step deeper into the Yjs shared type tree.
  *
@@ -338,16 +222,4 @@ declare function stepIntoYjs(current: unknown, segment: Segment): unknown;
  */
 declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
 
-/**
- * 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, createYjsDocFromEntirety, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, merge, resolveYjsType, stepIntoYjs, text, version, yjs, yjsReader, yjsSubstrateFactory };
+export { type YjsCaps, type YjsNativeMap, YjsVersion, applyChangeToYjs, createYjsSubstrate, ensureContainers, eventsToOps, resolveYjsType, stepIntoYjs, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };