@kyneta/yjs-schema 1.1.0 → 1.2.0

package/dist/index.js

@@ -9,8 +9,8 @@ import {
 
 // src/create.ts
 import {
-  changefeed,
   interpret,
+  observation,
   readable,
   registerSubstrate,
   writable
@@ -21,7 +21,7 @@ import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema"
 import * as Y5 from "yjs";
 
 // src/change-mapping.ts
-import { advanceSchema as advanceSchema2, expandMapOpsToLeaves, RawPath } from "@kyneta/schema";
+import { advanceSchema as advanceSchema2, expandMapOpsToLeaves, KIND as KIND2, RawPath } from "@kyneta/schema";
 import * as Y2 from "yjs";
 
 // src/yjs-resolve.ts
@@ -43,10 +43,6 @@ function stepIntoYjs(current, segment) {
 function resolveYjsType(rootMap, rootSchema, path) {
   let current = rootMap;
   let schema = rootSchema;
-  let rootProduct = rootSchema;
-  while (rootProduct._kind === "annotated" && rootProduct.schema !== void 0) {
-    rootProduct = rootProduct.schema;
-  }
   for (let i = 0; i < path.length; i++) {
     const seg = path.segments[i];
     const nextSchema = advanceSchema(schema, seg);
@@ -73,11 +69,11 @@ function applyChangeToYjs(rootMap, rootSchema, path, change2) {
       return;
     case "increment":
       throw new Error(
-        `Yjs substrate does not support counter annotations. Use Schema.number() with ReplaceChange instead. Attempted IncrementChange with amount=${change2.amount} at path [${pathToString(path)}].`
+        `Yjs substrate does not support "${change2.type}" changes. Counter requires a CRDT backend that supports counters (e.g. Loro). Attempted IncrementChange with amount=${change2.amount} at path [${pathToString(path)}].`
       );
     case "tree":
       throw new Error(
-        `Yjs substrate does not support tree annotations. Yjs has no native tree type. Attempted TreeChange at path [${pathToString(path)}].`
+        `Yjs substrate does not support "${change2.type}" changes. Tree requires a CRDT backend that supports trees (e.g. Loro). Attempted TreeChange at path [${pathToString(path)}].`
       );
     default:
       throw new Error(
@@ -167,29 +163,25 @@ function applyReplaceChange(rootMap, rootSchema, path, change2) {
 }
 function maybeCreateSharedType(value, schema) {
   if (schema === void 0) return value;
-  const structural = unwrapAnnotations(schema);
-  const tag = schema._kind === "annotated" ? schema.tag : void 0;
-  if (tag === "text") {
-    const text2 = new Y2.Text();
-    if (typeof value === "string" && value.length > 0) {
-      text2.insert(0, value);
+  switch (schema[KIND2]) {
+    // First-class text → Y.Text
+    case "text": {
+      const text = new Y2.Text();
+      if (typeof value === "string" && value.length > 0) {
+        text.insert(0, value);
+      }
+      return text;
     }
-    return text2;
-  }
-  if (tag === "counter" || tag === "movable" || tag === "tree") {
-    throw new Error(`Yjs substrate does not support "${tag}" annotations.`);
-  }
-  switch (structural._kind) {
     case "product": {
       if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) {
         return value;
       }
-      return createStructuredMap(value, structural);
+      return createStructuredMap(value, schema);
     }
     case "sequence": {
       if (!Array.isArray(value)) return value;
       const arr = new Y2.Array();
-      const itemSchema = structural.item;
+      const itemSchema = schema.item;
       const items = value.map(
         (item) => maybeCreateSharedType(item, itemSchema)
       );
@@ -201,20 +193,28 @@ function maybeCreateSharedType(value, schema) {
         return value;
       }
       const map = new Y2.Map();
-      const valueSchema = structural.item;
+      const valueSchema = schema.item;
       for (const [k, v] of Object.entries(value)) {
         map.set(k, maybeCreateSharedType(v, valueSchema));
       }
       return map;
     }
+    // Unsupported first-class CRDT types — should not reach here
+    // (rejected at bind time by caps check)
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${schema[KIND2]}". This should have been caught at bind() time.`
+      );
     default:
       return value;
   }
 }
 function createStructuredMap(obj, productSchema) {
   const map = new Y2.Map();
-  const structural = unwrapAnnotations(productSchema);
-  if (structural._kind !== "product") {
+  if (productSchema[KIND2] !== "product") {
     for (const [key, val] of Object.entries(obj)) {
       map.set(key, val);
     }
@@ -222,22 +222,21 @@ function createStructuredMap(obj, productSchema) {
   }
   for (const [key, val] of Object.entries(obj)) {
     if (val === void 0) continue;
-    const fieldSchema = structural.fields[key];
+    const fieldSchema = productSchema.fields[key];
     const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val;
     map.set(key, yjsVal);
   }
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields
+    productSchema.fields
   )) {
     if (key in obj) continue;
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-    if (tag === "text") {
+    if (fieldSchema[KIND2] === "text") {
       map.set(key, new Y2.Text());
     }
   }
   return map;
 }
-function eventsToOps(events) {
+function eventsToOps(events, schema) {
   const ops = [];
   for (const event of events) {
     const kynetaPath = yjsPathToKynetaPath(event.path);
@@ -246,7 +245,7 @@ function eventsToOps(events) {
       ops.push({ path: kynetaPath, change: change2 });
     }
   }
-  return expandMapOpsToLeaves(ops);
+  return expandMapOpsToLeaves(ops, schema);
 }
 function yjsPathToKynetaPath(yjsPath) {
   let path = RawPath.empty;
@@ -329,13 +328,6 @@ function extractEventValue(value) {
   if (value instanceof Y2.Text) return value.toJSON();
   return value;
 }
-function unwrapAnnotations(schema) {
-  let s = schema;
-  while (s._kind === "annotated" && s.schema !== void 0) {
-    s = s.schema;
-  }
-  return s;
-}
 function resolveSchemaAtPath(rootSchema, path) {
   let schema = rootSchema;
   for (const seg of path.segments) {
@@ -344,16 +336,19 @@ function resolveSchemaAtPath(rootSchema, path) {
   return schema;
 }
 function getItemSchema(schema) {
-  const structural = unwrapAnnotations(schema);
-  return structural._kind === "sequence" ? structural.item : void 0;
+  if (schema[KIND2] === "sequence") return schema.item;
+  if (schema[KIND2] === "movable") return schema.item;
+  return void 0;
 }
 function getFieldSchema(schema, key) {
-  const structural = unwrapAnnotations(schema);
-  if (structural._kind === "product") {
-    return structural.fields[key];
+  if (schema[KIND2] === "product") {
+    return schema.fields[key];
+  }
+  if (schema[KIND2] === "map") {
+    return schema.item;
   }
-  if (structural._kind === "map") {
-    return structural.item;
+  if (schema[KIND2] === "set") {
+    return schema.item;
   }
   return void 0;
 }
@@ -362,22 +357,18 @@ function pathToString(path) {
 }
 
 // src/populate.ts
-import { STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
+import { KIND as KIND3, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
 import * as Y3 from "yjs";
 function ensureContainers(doc, schema, conditional = false) {
   const rootMap = doc.getMap("root");
-  let rootProduct = schema;
-  while (rootProduct._kind === "annotated" && rootProduct.schema !== void 0) {
-    rootProduct = rootProduct.schema;
-  }
-  if (rootProduct._kind !== "product") {
+  if (schema[KIND3] !== "product") {
     return;
   }
   const savedClientID = doc.clientID;
   doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
   try {
     doc.transact(() => {
-      for (const [key, fieldSchema] of Object.entries(rootProduct.fields).sort(
+      for (const [key, fieldSchema] of Object.entries(schema.fields).sort(
         ([a], [b]) => a.localeCompare(b)
       )) {
         if (conditional && rootMap.has(key)) continue;
@@ -389,28 +380,12 @@ function ensureContainers(doc, schema, conditional = false) {
   }
 }
 function ensureRootField(rootMap, key, fieldSchema) {
-  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-  switch (tag) {
+  switch (fieldSchema[KIND3]) {
     case "text":
       rootMap.set(key, new Y3.Text());
       return;
-    case "counter":
-      throw new Error(
-        `Yjs substrate does not support counter annotations. Use Schema.number() with ReplaceChange instead. Encountered counter annotation at root field "${key}".`
-      );
-    case "movable":
-      throw new Error(
-        `Yjs substrate does not support movable list annotations. Yjs has no native movable list type. Encountered movable annotation at root field "${key}".`
-      );
-    case "tree":
-      throw new Error(
-        `Yjs substrate does not support tree annotations. Yjs has no native tree type. Encountered tree annotation at root field "${key}".`
-      );
-  }
-  const structural = unwrapAnnotations2(fieldSchema);
-  switch (structural._kind) {
     case "product":
-      rootMap.set(key, ensureMapContainers(structural));
+      rootMap.set(key, ensureMapContainers(fieldSchema));
       return;
     case "sequence":
       rootMap.set(key, new Y3.Array());
@@ -426,22 +401,25 @@ function ensureRootField(rootMap, key, fieldSchema) {
       }
       return;
     }
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${fieldSchema[KIND3]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at root field "${key}".`
+      );
   }
 }
 function ensureMapContainers(schema) {
   const map = new Y3.Map();
-  const structural = unwrapAnnotations2(schema);
-  if (structural._kind !== "product") return map;
+  if (schema[KIND3] !== "product") return map;
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields
+    schema.fields
   ).sort(([a], [b]) => a.localeCompare(b))) {
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-    if (tag === "text") {
-      map.set(key, new Y3.Text());
-      continue;
-    }
-    const fs = unwrapAnnotations2(fieldSchema);
-    switch (fs._kind) {
+    switch (fieldSchema[KIND3]) {
+      case "text":
+        map.set(key, new Y3.Text());
+        break;
       case "product":
         map.set(key, ensureMapContainers(fieldSchema));
         break;
@@ -459,17 +437,17 @@ function ensureMapContainers(schema) {
         }
         break;
       }
+      case "counter":
+      case "set":
+      case "tree":
+      case "movable":
+        throw new Error(
+          `Yjs substrate does not support [KIND]="${fieldSchema[KIND3]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at nested field "${key}".`
+        );
     }
   }
   return map;
 }
-function unwrapAnnotations2(schema) {
-  let s = schema;
-  while (s._kind === "annotated" && s.schema !== void 0) {
-    s = s.schema;
-  }
-  return s;
-}
 
 // src/reader.ts
 import * as Y4 from "yjs";
@@ -529,6 +507,7 @@ function yjsReader(doc, schema) {
 }
 
 // src/version.ts
+import { versionVectorMeet } from "@kyneta/schema";
 import { decodeStateVector } from "yjs";
 function uint8ArrayToBase64(bytes) {
   let binary = "";
@@ -545,6 +524,22 @@ function base64ToUint8Array(base64) {
   }
   return bytes;
 }
+function encodeStateVector(map) {
+  const bytes = [];
+  function writeVarUint(value) {
+    while (value > 127) {
+      bytes.push(value & 127 | 128);
+      value >>>= 7;
+    }
+    bytes.push(value & 127);
+  }
+  writeVarUint(map.size);
+  for (const [clientId, clock] of map) {
+    writeVarUint(clientId);
+    writeVarUint(clock);
+  }
+  return new Uint8Array(bytes);
+}
 var YjsVersion = class _YjsVersion {
   sv;
   constructor(sv) {
@@ -602,6 +597,26 @@ var YjsVersion = class _YjsVersion {
     if (hasGreater && !hasLess) return "ahead";
     return "equal";
   }
+  /**
+   * 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) {
+    if (!(other instanceof _YjsVersion)) {
+      throw new Error(
+        "YjsVersion can only be meet'd with another YjsVersion"
+      );
+    }
+    const thisMap = decodeStateVector(this.sv);
+    const otherMap = decodeStateVector(other.sv);
+    const result = versionVectorMeet(thisMap, otherMap);
+    return new _YjsVersion(encodeStateVector(result));
+  }
   /**
    * Parse a serialized YjsVersion string back into a YjsVersion.
    *
@@ -633,7 +648,7 @@ function createYjsSubstrate(doc, schema) {
         pendingChanges.push({ path, change: change2 });
       }
     },
-    onFlush(origin) {
+    onFlush(_origin) {
       if (!inOurTransaction && pendingChanges.length > 0) {
         inOurTransaction = true;
         try {
@@ -657,6 +672,14 @@ function createYjsSubstrate(doc, schema) {
     version() {
       return new YjsVersion(Y5.encodeStateVector(doc));
     },
+    baseVersion() {
+      return new YjsVersion(new Uint8Array([0]));
+    },
+    advance(_to) {
+      throw new Error(
+        "advance() on a live Yjs substrate is not yet supported. Use advance() on a YjsReplica instead."
+      );
+    },
     exportEntirety() {
       return {
         kind: "entirety",
@@ -690,7 +713,7 @@ function createYjsSubstrate(doc, schema) {
     if (transaction.origin === KYNETA_ORIGIN) {
       return;
     }
-    const ops = eventsToOps(events);
+    const ops = eventsToOps(events, schema);
     if (ops.length === 0) {
       return;
     }
@@ -706,21 +729,46 @@ function createYjsSubstrate(doc, schema) {
   return substrate;
 }
 function createYjsReplica(doc) {
+  let currentDoc = doc;
+  let currentBase = new YjsVersion(
+    Y5.encodeStateVector(new Y5.Doc())
+  );
   return {
-    [BACKING_DOC]: doc,
+    get [BACKING_DOC]() {
+      return currentDoc;
+    },
     version() {
-      return new YjsVersion(Y5.encodeStateVector(doc));
+      return new YjsVersion(Y5.encodeStateVector(currentDoc));
+    },
+    baseVersion() {
+      return currentBase;
+    },
+    advance(to) {
+      const baseCmp = currentBase.compare(to);
+      if (baseCmp === "ahead") {
+        throw new Error("advance(): target is behind base version");
+      }
+      const currentCmp = to.compare(this.version());
+      if (currentCmp === "ahead") {
+        throw new Error("advance(): target is ahead of current version");
+      }
+      if (currentCmp !== "equal") return;
+      const update = Y5.encodeStateAsUpdate(currentDoc);
+      const newDoc = new Y5.Doc();
+      Y5.applyUpdate(newDoc, update);
+      currentDoc = newDoc;
+      currentBase = new YjsVersion(Y5.encodeStateVector(currentDoc));
     },
     exportEntirety() {
       return {
         kind: "entirety",
         encoding: "binary",
-        data: Y5.encodeStateAsUpdate(doc)
+        data: Y5.encodeStateAsUpdate(currentDoc)
       };
     },
     exportSince(since) {
       try {
-        const bytes = Y5.encodeStateAsUpdate(doc, since.sv);
+        const bytes = Y5.encodeStateAsUpdate(currentDoc, since.sv);
         return { kind: "since", encoding: "binary", data: bytes };
       } catch {
         return null;
@@ -732,7 +780,7 @@ function createYjsReplica(doc) {
           "YjsReplica.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
         );
       }
-      Y5.applyUpdate(doc, payload.data);
+      Y5.applyUpdate(currentDoc, payload.data);
     }
   };
 }
@@ -792,7 +840,7 @@ function getSubstrate(doc) {
   return s;
 }
 function registerDoc(schema, substrate) {
-  const doc = interpret(schema, substrate.context()).with(readable).with(writable).with(changefeed).done();
+  const doc = interpret(schema, substrate.context()).with(readable).with(writable).with(observation).done();
   substrates.set(doc, substrate);
   registerSubstrate(doc, substrate);
   return doc;
@@ -823,11 +871,13 @@ function merge(doc, payload, origin) {
   getSubstrate(doc).merge(payload, origin);
 }
 
-// src/index.ts
-import { Schema as Schema2 } from "@kyneta/schema";
-
 // src/bind-yjs.ts
-import { BACKING_DOC as BACKING_DOC2, bind, STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2 } from "@kyneta/schema";
+import {
+  BACKING_DOC as BACKING_DOC2,
+  createSubstrateNamespace,
+  STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2,
+  unwrap
+} from "@kyneta/schema";
 import * as Y6 from "yjs";
 function hashPeerId(peerId) {
   let hash = 2166136261;
@@ -867,44 +917,43 @@ function createYjsFactory(peerId) {
     }
   };
 }
-function bindYjs(schema) {
-  return bind({
-    schema,
-    factory: (ctx) => createYjsFactory(ctx.peerId),
-    strategy: "causal"
-  });
-}
-
-// src/yjs-escape.ts
-import { BACKING_DOC as BACKING_DOC3, unwrap } from "@kyneta/schema";
-function yjs(ref) {
-  let substrate;
-  try {
-    substrate = unwrap(ref);
-  } catch {
-    throw new Error(
-      "yjs() requires a ref backed by a Yjs substrate. Use a doc created by exchange.get() with a bindYjs() schema, or by createYjsDoc()."
-    );
-  }
-  const doc = substrate[BACKING_DOC3];
-  if (!doc || typeof doc !== "object" || typeof doc.getMap !== "function" || typeof doc.clientID !== "number") {
-    throw new Error(
-      "yjs() requires a ref backed by a Yjs substrate. The ref has a substrate but it is not a Yjs substrate. Use a doc created with a bindYjs() schema or createYjsDoc()."
-    );
+var yjs = {
+  ...createSubstrateNamespace({
+    strategies: {
+      collaborative: {
+        factory: (ctx) => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory
+      },
+      ephemeral: {
+        factory: (ctx) => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory
+      }
+    },
+    defaultStrategy: "collaborative"
+  }),
+  unwrap(ref) {
+    let substrate;
+    try {
+      substrate = unwrap(ref);
+    } catch {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. Use a doc created by exchange.get() with a yjs.bind() schema, or by createYjsDoc()."
+      );
+    }
+    const doc = substrate[BACKING_DOC2];
+    if (!doc || typeof doc !== "object" || typeof doc.getMap !== "function" || typeof doc.clientID !== "number") {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. The ref has a substrate but it is not a Yjs substrate. Use a doc created with a yjs.bind() schema or createYjsDoc()."
+      );
+    }
+    return doc;
   }
-  return doc;
-}
-
-// src/index.ts
-function text() {
-  return Schema2.annotated("text");
-}
+};
 export {
   Schema,
   YjsVersion,
   applyChangeToYjs,
   applyChanges,
-  bindYjs,
   change,
   createYjsDoc,
   createYjsDocFromEntirety,
@@ -918,10 +967,10 @@ export {
   stepIntoYjs,
   subscribe,
   subscribeNode,
-  text,
   version,
   yjs,
   yjsReader,
+  yjsReplicaFactory,
   yjsSubstrateFactory
 };
 //# sourceMappingURL=index.js.map