@kyneta/yjs-schema 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,14 +1,27 @@
+// src/index.ts
+import {
+  applyChanges,
+  change,
+  Schema,
+  subscribe,
+  subscribeNode
+} from "@kyneta/schema";
+
 // src/create.ts
-import { interpret, registerSubstrate } from "@kyneta/schema";
-import { changefeed, readable, writable } from "@kyneta/schema";
+import {
+  changefeed,
+  interpret,
+  readable,
+  registerSubstrate,
+  writable
+} from "@kyneta/schema";
 
 // src/substrate.ts
-import { buildWritableContext, executeBatch } from "@kyneta/schema";
+import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema";
 import * as Y5 from "yjs";
 
 // src/change-mapping.ts
-import { advanceSchema as advanceSchema2, expandMapOpsToLeaves } from "@kyneta/schema";
-import { RawPath } from "@kyneta/schema";
+import { advanceSchema as advanceSchema2, expandMapOpsToLeaves, RawPath } from "@kyneta/schema";
 import * as Y2 from "yjs";
 
 // src/yjs-resolve.ts
@@ -23,9 +36,7 @@ function stepIntoYjs(current, segment) {
     return current.get(resolved);
   }
   if (current instanceof Y.Text) {
-    throw new Error(
-      `yjs-resolve: cannot step into Y.Text`
-    );
+    throw new Error(`yjs-resolve: cannot step into Y.Text`);
   }
   return void 0;
 }
@@ -166,19 +177,14 @@ function maybeCreateSharedType(value, schema) {
     return text2;
   }
   if (tag === "counter" || tag === "movable" || tag === "tree") {
-    throw new Error(
-      `Yjs substrate does not support "${tag}" annotations.`
-    );
+    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, structural);
     }
     case "sequence": {
       if (!Array.isArray(value)) return value;
@@ -196,9 +202,7 @@ function maybeCreateSharedType(value, schema) {
       }
       const map = new Y2.Map();
       const valueSchema = structural.item;
-      for (const [k, v] of Object.entries(
-        value
-      )) {
+      for (const [k, v] of Object.entries(value)) {
         map.set(k, maybeCreateSharedType(v, valueSchema));
       }
       return map;
@@ -302,18 +306,16 @@ function mapEventToChange(event) {
   let hasSet = false;
   let hasDelete = false;
   const target = event.target;
-  event.changes.keys.forEach(
-    (change2, key) => {
-      if (change2.action === "add" || change2.action === "update") {
-        const value = target.get(key);
-        set[key] = extractEventValue(value);
-        hasSet = true;
-      } else if (change2.action === "delete") {
-        deleteKeys.push(key);
-        hasDelete = true;
-      }
+  event.changes.keys.forEach((change2, key) => {
+    if (change2.action === "add" || change2.action === "update") {
+      const value = target.get(key);
+      set[key] = extractEventValue(value);
+      hasSet = true;
+    } else if (change2.action === "delete") {
+      deleteKeys.push(key);
+      hasDelete = true;
     }
-  );
+  });
   if (!hasSet && !hasDelete) return null;
   return {
     type: "map",
@@ -360,9 +362,9 @@ function pathToString(path) {
 }
 
 // src/populate.ts
-import { Zero } from "@kyneta/schema";
+import { STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
 import * as Y3 from "yjs";
-function ensureContainers(doc, schema) {
+function ensureContainers(doc, schema, conditional = false) {
   const rootMap = doc.getMap("root");
   let rootProduct = schema;
   while (rootProduct._kind === "annotated" && rootProduct.schema !== void 0) {
@@ -371,11 +373,20 @@ function ensureContainers(doc, schema) {
   if (rootProduct._kind !== "product") {
     return;
   }
-  doc.transact(() => {
-    for (const [key, fieldSchema] of Object.entries(rootProduct.fields)) {
-      ensureRootField(rootMap, key, fieldSchema);
-    }
-  });
+  const savedClientID = doc.clientID;
+  doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
+  try {
+    doc.transact(() => {
+      for (const [key, fieldSchema] of Object.entries(rootProduct.fields).sort(
+        ([a], [b]) => a.localeCompare(b)
+      )) {
+        if (conditional && rootMap.has(key)) continue;
+        ensureRootField(rootMap, key, fieldSchema);
+      }
+    });
+  } finally {
+    doc.clientID = savedClientID;
+  }
 }
 function ensureRootField(rootMap, key, fieldSchema) {
   const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
@@ -423,7 +434,7 @@ function ensureMapContainers(schema) {
   if (structural._kind !== "product") return map;
   for (const [key, fieldSchema] of Object.entries(
     structural.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());
@@ -460,7 +471,7 @@ function unwrapAnnotations2(schema) {
   return s;
 }
 
-// src/store-reader.ts
+// src/reader.ts
 import * as Y4 from "yjs";
 function extractValue(resolved) {
   if (resolved instanceof Y4.Text) {
@@ -474,7 +485,7 @@ function extractValue(resolved) {
   }
   return resolved;
 }
-function yjsStoreReader(doc, schema) {
+function yjsReader(doc, schema) {
   const rootMap = doc.getMap("root");
   return {
     read(path) {
@@ -565,9 +576,7 @@ var YjsVersion = class _YjsVersion {
    */
   compare(other) {
     if (!(other instanceof _YjsVersion)) {
-      throw new Error(
-        "YjsVersion can only be compared with another YjsVersion"
-      );
+      throw new Error("YjsVersion can only be compared with another YjsVersion");
     }
     const thisMap = decodeStateVector(this.sv);
     const otherMap = decodeStateVector(other.sv);
@@ -607,41 +616,18 @@ var YjsVersion = class _YjsVersion {
   }
 };
 
-// src/yjs-escape.ts
-import { unwrap } from "@kyneta/schema";
-var substrateToYjsDoc = /* @__PURE__ */ new WeakMap();
-function registerYjsSubstrate(substrate, doc) {
-  substrateToYjsDoc.set(substrate, doc);
-}
-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 = substrateToYjsDoc.get(substrate);
-  if (!doc) {
-    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()."
-    );
-  }
-  return doc;
-}
-
 // src/substrate.ts
 var KYNETA_ORIGIN = "kyneta-prepare";
 function createYjsSubstrate(doc, schema) {
   const pendingChanges = [];
   let inOurTransaction = false;
-  let pendingImportOrigin;
+  let pendingMergeOrigin;
   let cachedCtx;
   const rootMap = doc.getMap("root");
-  const reader = yjsStoreReader(doc, schema);
+  const reader = yjsReader(doc, schema);
   const substrate = {
-    store: reader,
+    [BACKING_DOC]: doc,
+    reader,
     prepare(path, change2) {
       if (!inOurTransaction) {
         pendingChanges.push({ path, change: change2 });
@@ -671,8 +657,9 @@ function createYjsSubstrate(doc, schema) {
     version() {
       return new YjsVersion(Y5.encodeStateVector(doc));
     },
-    exportSnapshot() {
+    exportEntirety() {
       return {
+        kind: "entirety",
         encoding: "binary",
         data: Y5.encodeStateAsUpdate(doc)
       };
@@ -680,22 +667,22 @@ function createYjsSubstrate(doc, schema) {
     exportSince(since) {
       try {
         const bytes = Y5.encodeStateAsUpdate(doc, since.sv);
-        return { encoding: "binary", data: bytes };
+        return { kind: "since", encoding: "binary", data: bytes };
       } catch {
         return null;
       }
     },
-    importDelta(payload, origin) {
+    merge(payload, origin) {
       if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
         throw new Error(
-          "YjsSubstrate.importDelta only supports binary-encoded payloads"
+          "YjsSubstrate.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
         );
       }
-      pendingImportOrigin = origin;
+      pendingMergeOrigin = origin;
       try {
         Y5.applyUpdate(doc, payload.data, origin ?? "remote");
       } finally {
-        pendingImportOrigin = void 0;
+        pendingMergeOrigin = void 0;
       }
     }
   };
@@ -707,7 +694,7 @@ function createYjsSubstrate(doc, schema) {
     if (ops.length === 0) {
       return;
     }
-    const origin = pendingImportOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
+    const origin = pendingMergeOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
     const ctx = substrate.context();
     inOurTransaction = true;
     try {
@@ -716,25 +703,78 @@ function createYjsSubstrate(doc, schema) {
       inOurTransaction = false;
     }
   });
-  registerYjsSubstrate(substrate, doc);
   return substrate;
 }
-var yjsSubstrateFactory = {
-  create(schema) {
-    const doc = new Y5.Doc();
-    ensureContainers(doc, schema);
-    return createYjsSubstrate(doc, schema);
+function createYjsReplica(doc) {
+  return {
+    [BACKING_DOC]: doc,
+    version() {
+      return new YjsVersion(Y5.encodeStateVector(doc));
+    },
+    exportEntirety() {
+      return {
+        kind: "entirety",
+        encoding: "binary",
+        data: Y5.encodeStateAsUpdate(doc)
+      };
+    },
+    exportSince(since) {
+      try {
+        const bytes = Y5.encodeStateAsUpdate(doc, since.sv);
+        return { kind: "since", encoding: "binary", data: bytes };
+      } catch {
+        return null;
+      }
+    },
+    merge(payload, _origin) {
+      if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
+        throw new Error(
+          "YjsReplica.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
+        );
+      }
+      Y5.applyUpdate(doc, payload.data);
+    }
+  };
+}
+var yjsReplicaFactory = {
+  replicaType: ["yjs", 1, 0],
+  createEmpty() {
+    return createYjsReplica(new Y5.Doc());
   },
-  fromSnapshot(payload, schema) {
+  fromEntirety(payload) {
     if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
       throw new Error(
-        "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads"
+        "YjsReplicaFactory.fromEntirety only supports binary-encoded payloads"
       );
     }
     const doc = new Y5.Doc();
     Y5.applyUpdate(doc, payload.data);
+    return createYjsReplica(doc);
+  },
+  parseVersion(serialized) {
+    return YjsVersion.parse(serialized);
+  }
+};
+var yjsSubstrateFactory = {
+  replica: yjsReplicaFactory,
+  createReplica() {
+    return createYjsReplica(new Y5.Doc());
+  },
+  upgrade(replica, schema) {
+    const doc = replica[BACKING_DOC];
+    ensureContainers(doc, schema, true);
     return createYjsSubstrate(doc, schema);
   },
+  create(schema) {
+    const doc = new Y5.Doc();
+    ensureContainers(doc, schema);
+    return createYjsSubstrate(doc, schema);
+  },
+  fromEntirety(payload, schema) {
+    const replica = this.createReplica();
+    replica.merge(payload);
+    return this.upgrade(replica, schema);
+  },
   parseVersion(serialized) {
     return YjsVersion.parse(serialized);
   }
@@ -746,7 +786,7 @@ function getSubstrate(doc) {
   const s = substrates.get(doc);
   if (!s) {
     throw new Error(
-      "version/exportSnapshot/importDelta called on an object without a YjsSubstrate. Use a doc created by createYjsDoc() or createYjsDocFromSnapshot()."
+      "version/exportEntirety/merge called on an object without a YjsSubstrate. Use a doc created by createYjsDoc() or createYjsDocFromEntirety()."
     );
   }
   return s;
@@ -767,30 +807,27 @@ var createYjsDoc = (schema, doc) => {
   }
   return registerDoc(schema, yjsSubstrateFactory.create(schema));
 };
-var createYjsDocFromSnapshot = (schema, payload) => registerDoc(schema, yjsSubstrateFactory.fromSnapshot(payload, schema));
+var createYjsDocFromEntirety = (schema, payload) => registerDoc(schema, yjsSubstrateFactory.fromEntirety(payload, schema));
 
 // src/sync.ts
 function version(doc) {
   return getSubstrate(doc).version();
 }
-function exportSnapshot(doc) {
-  return getSubstrate(doc).exportSnapshot();
+function exportEntirety(doc) {
+  return getSubstrate(doc).exportEntirety();
 }
 function exportSince(doc, since) {
   return getSubstrate(doc).exportSince(since);
 }
-function importDelta(doc, payload, origin) {
-  getSubstrate(doc).importDelta(payload, origin);
+function merge(doc, payload, origin) {
+  getSubstrate(doc).merge(payload, origin);
 }
 
 // src/index.ts
-import { applyChanges, change } from "@kyneta/schema";
-import { subscribe, subscribeNode } from "@kyneta/schema";
-import { Schema } from "@kyneta/schema";
 import { Schema as Schema2 } from "@kyneta/schema";
 
 // src/bind-yjs.ts
-import { bind } from "@kyneta/schema";
+import { BACKING_DOC as BACKING_DOC2, bind, STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2 } from "@kyneta/schema";
 import * as Y6 from "yjs";
 function hashPeerId(peerId) {
   let hash = 2166136261;
@@ -798,28 +835,33 @@ function hashPeerId(peerId) {
     hash ^= peerId.charCodeAt(i);
     hash = Math.imul(hash, 16777619);
   }
-  return hash >>> 0;
+  const result = hash >>> 0;
+  return result === STRUCTURAL_YJS_CLIENT_ID2 ? 1 : result;
 }
 function createYjsFactory(peerId) {
   const numericClientId = hashPeerId(peerId);
   return {
-    create(schema) {
-      const doc = new Y6.Doc();
+    replica: yjsReplicaFactory,
+    createReplica() {
+      return createYjsReplica(new Y6.Doc());
+    },
+    upgrade(replica, schema) {
+      const doc = replica[BACKING_DOC2];
       doc.clientID = numericClientId;
-      ensureContainers(doc, schema);
+      ensureContainers(doc, schema, true);
       return createYjsSubstrate(doc, schema);
     },
-    fromSnapshot(payload, schema) {
-      if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
-        throw new Error(
-          "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads"
-        );
-      }
+    create(schema) {
       const doc = new Y6.Doc();
       doc.clientID = numericClientId;
-      Y6.applyUpdate(doc, payload.data);
+      ensureContainers(doc, schema);
       return createYjsSubstrate(doc, schema);
     },
+    fromEntirety(payload, schema) {
+      const replica = this.createReplica();
+      replica.merge(payload);
+      return this.upgrade(replica, schema);
+    },
     parseVersion(serialized) {
       return YjsVersion.parse(serialized);
     }
@@ -833,6 +875,26 @@ function bindYjs(schema) {
   });
 }
 
+// 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()."
+    );
+  }
+  return doc;
+}
+
 // src/index.ts
 function text() {
   return Schema2.annotated("text");
@@ -845,13 +907,13 @@ export {
   bindYjs,
   change,
   createYjsDoc,
-  createYjsDocFromSnapshot,
+  createYjsDocFromEntirety,
   createYjsSubstrate,
   ensureContainers,
   eventsToOps,
+  exportEntirety,
   exportSince,
-  exportSnapshot,
-  importDelta,
+  merge,
   resolveYjsType,
   stepIntoYjs,
   subscribe,
@@ -859,7 +921,7 @@ export {
   text,
   version,
   yjs,
-  yjsStoreReader,
+  yjsReader,
   yjsSubstrateFactory
 };
 //# sourceMappingURL=index.js.map