@kyneta/yjs-schema 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Version, Schema, Ref, SubstratePayload, StoreReader, Path, Segment, ChangeBase, Op, Substrate, SubstrateFactory, BoundSchema, AnnotatedSchema } from '@kyneta/schema';
+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';
 import * as Y from 'yjs';
 import { Doc } from 'yjs';
@@ -74,7 +74,7 @@ declare class YjsVersion implements Version {
  * CRDT collaboration support.
  *
  * The returned ref observes **all** mutations to the underlying Y.Doc,
- * regardless of source (local kyneta writes, importDelta, external
+ * regardless of source (local kyneta writes, merge, external
  * `Y.applyUpdate()`, external raw Yjs API mutations).
  *
  * @param schema - The schema describing the document structure.
@@ -83,21 +83,21 @@ declare class YjsVersion implements Version {
  */
 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>;
+type CreateYjsDocFromEntirety = <S extends Schema>(schema: S, payload: SubstratePayload) => Ref<S>;
 /**
- * Reconstruct a live Yjs-backed document from a substrate snapshot payload.
+ * Reconstruct a live Yjs-backed document from a substrate entirety payload.
  *
- * The payload must have been produced by `exportSnapshot()` on a
+ * 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 = exportSnapshot(docA)
- * const docB = createYjsDocFromSnapshot(MySchema, payload)
+ * const payload = exportEntirety(docA)
+ * const docB = createYjsDocFromEntirety(MySchema, payload)
  * // docB has the same state as docA at the time of export
  * ```
  */
-declare const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot;
+declare const createYjsDocFromEntirety: CreateYjsDocFromEntirety;
 
 /**
  * Current version as a `YjsVersion` (wrapping a Yjs state vector).
@@ -105,20 +105,20 @@ declare const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot;
  * 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`.
+ * @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 snapshot — sufficient for a new peer to
- * reconstruct an equivalent document via `createYjsDocFromSnapshot()`.
+ * 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 `createYjsDocFromSnapshot`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-declare function exportSnapshot(doc: object): SubstratePayload;
+declare function exportEntirety(doc: object): SubstratePayload;
 /**
  * Export a delta payload containing all changes since the given version.
  *
@@ -129,78 +129,65 @@ declare function exportSnapshot(doc: object): SubstratePayload;
  * const v0 = version(docA)
  * change(docA, d => d.title.insert(0, "Hi"))
  * const delta = exportSince(docA, v0)
- * importDelta(docB, delta!)
+ * merge(docB, delta!)
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
  * @param since - The version to diff from.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @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
- * `exportSnapshot()` on a compatible document.
+ * `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)
- * importDelta(docB, delta!, "sync")
+ * merge(docB, delta!, "sync")
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @param payload - The delta or snapshot payload to import.
+ * @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` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-declare function importDelta(doc: object, payload: SubstratePayload, origin?: string): void;
+declare function merge(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.
+ * Bind a schema to the Yjs CRDT substrate with causal merge strategy.
  *
- * 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`)
+ * 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.
  *
- * @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.
+ * **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.
  *
- * Left-folds over path segments using `advanceSchema` for pure schema
- * descent and `stepIntoYjs` for Yjs-specific navigation.
+ * @example
+ * ```ts
+ * import { bindYjs } from "@kyneta/yjs-schema"
+ * import { Schema } from "@kyneta/schema"
  *
- * Returns the Yjs shared type or plain value at the terminal position.
- * For an empty path, returns the root map itself.
+ * const TodoDoc = bindYjs(Schema.doc({
+ *   title: Schema.annotated("text"),
+ *   items: Schema.list(Schema.struct({
+ *     name: Schema.string(),
+ *     done: Schema.boolean(),
+ *   })),
+ * }))
  *
- * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
- * @param rootSchema - The root document schema
- * @param path - The path to resolve
+ * const doc = exchange.get("my-todos", TodoDoc)
+ * ```
  */
-declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
+declare function bindYjs<S extends Schema>(schema: S): BoundSchema<S>;
 
 /**
  * Apply a kyneta Change to the Yjs shared type tree imperatively.
@@ -238,14 +225,42 @@ declare function eventsToOps(events: Y.YEvent<any>[]): Op[];
  * 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.
+ * When `conditional` is true, fields that already exist in the root map
+ * are skipped. This is the correct mode after hydration — containers
+ * present from stored state must not be overwritten (each `rootMap.set()`
+ * is a CRDT write that advances the version vector and may conflict
+ * with stored operations).
+ *
+ * When `conditional` is false (default), all fields are created
+ * unconditionally. This is the correct mode for fresh documents.
+ *
+ * **Structural identity:** This function temporarily sets `doc.clientID`
+ * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
+ * then restores the caller's clientID. This produces byte-identical
+ * 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 conditional - If true, skip fields that already exist in the root map.
+ *   Context: jj:smmulzkm (two-phase substrate construction)
+ */
+declare function ensureContainers(doc: Y.Doc, schema: Schema, conditional?: boolean): void;
+
+/**
+ * Creates a Reader 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 ensureContainers(doc: Y.Doc, schema: Schema): void;
+declare function yjsReader(doc: Y.Doc, schema: Schema): Reader;
 
 /**
  * Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
@@ -253,11 +268,11 @@ declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
  * 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.
+ * versioning, and export/merge 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
+ * mutations to the Y.Doc (merges, external local writes) are bridged
  * to the kyneta changefeed. Subscribing to the kyneta doc observes all
  * mutations regardless of source.
  *
@@ -266,49 +281,8 @@ declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
  * @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.
  *
@@ -336,6 +310,34 @@ declare function bindYjs<S extends Schema>(schema: S): BoundSchema<S>;
  */
 declare function yjs(ref: object): Doc;
 
+/**
+ * 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;
+
 /**
  * Collaborative text (CRDT). Produces `annotated("text")`.
  *
@@ -348,4 +350,4 @@ declare function yjs(ref: object): Doc;
  */
 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 };
+export { YjsVersion, applyChangeToYjs, bindYjs, createYjsDoc, createYjsDocFromEntirety, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, merge, resolveYjsType, stepIntoYjs, text, version, yjs, yjsReader, yjsSubstrateFactory };