@kyneta/yjs-schema 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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 { 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';
-import { Doc } from 'yjs';
+export { Changeset } from '@kyneta/changefeed';
 
 /**
  * A Version wrapping a Yjs state vector.
@@ -41,6 +41,16 @@ declare class YjsVersion implements Version {
      * 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.
      *
@@ -159,35 +169,23 @@ declare function exportSince(doc: object, since: YjsVersion): SubstratePayload |
 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.
+ * The Yjs CRDT substrate namespace.
  *
- * **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.
+ * - `yjs.bind(schema)` — collaborative sync (default)
+ * - `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
  *
- * @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)
- * ```
+ * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
+ * Passing `"authoritative"` is a compile error.
  */
-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> & {
+    /** Access the underlying `Y.Doc` backing a ref. */
+    unwrap(ref: object): Y.Doc;
+};
 
 /**
  * Apply a kyneta Change to the Yjs shared type tree imperatively.
@@ -215,15 +213,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 +238,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)
  */
@@ -281,35 +279,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 +310,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, YjsVersion, applyChangeToYjs, createYjsDoc, createYjsDocFromEntirety, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, merge, resolveYjsType, stepIntoYjs, version, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };