@kyneta/yjs-schema 1.2.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,173 +1,38 @@
-import { Version, Schema, Ref, SubstratePayload, SubstrateNamespace, CrdtStrategy, Path, ChangeBase, Op, Reader, Substrate, ReplicaFactory, SubstrateFactory, Segment } from '@kyneta/schema';
-export { Op, Ref, Schema, SubstratePayload, applyChanges, change, subscribe, subscribeNode } from '@kyneta/schema';
-import * as Y from 'yjs';
 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';
 
 /**
- * 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.
+ * 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)
  */
-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";
-    /**
-     * 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;
+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;
-
 /**
  * The Yjs CRDT substrate namespace.
  *
@@ -175,17 +40,15 @@ declare function merge(doc: object, payload: SubstratePayload, origin?: string):
  * - `yjs.bind(schema, "ephemeral")` — ephemeral/presence broadcast
  * - `yjs.replica()` — collaborative replication (default)
  * - `yjs.replica("ephemeral")` — ephemeral replication
- * - `yjs.unwrap(ref)` — access the underlying Y.Doc
  *
  * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
  * Passing `"authoritative"` is a compile error.
+ *
+ * To access the underlying Y.Doc, use `unwrap(ref)` from `@kyneta/schema`.
  */
 /** The closed set of capability tags that the Yjs substrate supports. */
 type YjsCaps = "text" | "json";
-declare const yjs: SubstrateNamespace<CrdtStrategy, YjsCaps> & {
-    /** Access the underlying `Y.Doc` backing a ref. */
-    unwrap(ref: object): Y.Doc;
-};
+declare const yjs: SubstrateNamespace<CrdtStrategy, YjsCaps, YjsNativeMap>;
 
 /**
  * Apply a kyneta Change to the Yjs shared type tree imperatively.
@@ -260,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.
  *
@@ -310,4 +222,4 @@ declare function stepIntoYjs(current: unknown, segment: Segment): unknown;
  */
 declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
 
-export { type YjsCaps, YjsVersion, applyChangeToYjs, createYjsDoc, createYjsDocFromEntirety, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, merge, resolveYjsType, stepIntoYjs, version, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };
+export { type YjsCaps, type YjsNativeMap, YjsVersion, applyChangeToYjs, createYjsSubstrate, ensureContainers, eventsToOps, resolveYjsType, stepIntoYjs, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };