@kyneta/yjs-schema 1.2.0 → 1.3.1

package/dist/index.js

@@ -2,40 +2,150 @@
 import {
   applyChanges,
   change,
+  createDoc,
+  createRef,
+  exportEntirety,
+  exportSince,
+  merge,
+  NATIVE,
   Schema,
   subscribe,
-  subscribeNode
+  subscribeNode,
+  unwrap,
+  version
 } from "@kyneta/schema";
 
-// src/create.ts
+// src/bind-yjs.ts
 import {
-  interpret,
-  observation,
-  readable,
-  registerSubstrate,
-  writable
+  BACKING_DOC as BACKING_DOC2,
+  createSubstrateNamespace,
+  STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2
 } from "@kyneta/schema";
+import * as Y6 from "yjs";
+
+// src/populate.ts
+import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
+import * as Y from "yjs";
+function ensureContainers(doc, schema, conditional = false) {
+  const rootMap = doc.getMap("root");
+  if (schema[KIND] !== "product") {
+    return;
+  }
+  const savedClientID = doc.clientID;
+  doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
+  try {
+    doc.transact(() => {
+      for (const [key, fieldSchema] of Object.entries(schema.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) {
+  switch (fieldSchema[KIND]) {
+    case "text":
+      rootMap.set(key, new Y.Text());
+      return;
+    case "product":
+      rootMap.set(key, ensureMapContainers(fieldSchema));
+      return;
+    case "sequence":
+      rootMap.set(key, new Y.Array());
+      return;
+    case "map":
+      rootMap.set(key, new Y.Map());
+      return;
+    case "scalar":
+    case "sum": {
+      const zero = Zero.structural(fieldSchema);
+      if (zero !== void 0) {
+        rootMap.set(key, zero);
+      }
+      return;
+    }
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at root field "${key}".`
+      );
+  }
+}
+function ensureMapContainers(schema) {
+  const map = new Y.Map();
+  if (schema[KIND] !== "product") return map;
+  for (const [key, fieldSchema] of Object.entries(
+    schema.fields
+  ).sort(([a], [b]) => a.localeCompare(b))) {
+    switch (fieldSchema[KIND]) {
+      case "text":
+        map.set(key, new Y.Text());
+        break;
+      case "product":
+        map.set(key, ensureMapContainers(fieldSchema));
+        break;
+      case "sequence":
+        map.set(key, new Y.Array());
+        break;
+      case "map":
+        map.set(key, new Y.Map());
+        break;
+      case "scalar":
+      case "sum": {
+        const zero = Zero.structural(fieldSchema);
+        if (zero !== void 0) {
+          map.set(key, zero);
+        }
+        break;
+      }
+      case "counter":
+      case "set":
+      case "tree":
+      case "movable":
+        throw new Error(
+          `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at nested field "${key}".`
+        );
+    }
+  }
+  return map;
+}
 
 // src/substrate.ts
-import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema";
+import {
+  BACKING_DOC,
+  buildWritableContext,
+  executeBatch,
+  KIND as KIND3
+} from "@kyneta/schema";
 import * as Y5 from "yjs";
 
 // src/change-mapping.ts
-import { advanceSchema as advanceSchema2, expandMapOpsToLeaves, KIND as KIND2, RawPath } from "@kyneta/schema";
-import * as Y2 from "yjs";
+import {
+  advanceSchema as advanceSchema2,
+  expandMapOpsToLeaves,
+  KIND as KIND2,
+  RawPath
+} from "@kyneta/schema";
+import * as Y3 from "yjs";
 
 // src/yjs-resolve.ts
 import { advanceSchema } from "@kyneta/schema";
-import * as Y from "yjs";
+import * as Y2 from "yjs";
 function stepIntoYjs(current, segment) {
   const resolved = segment.resolve();
-  if (current instanceof Y.Map) {
+  if (current instanceof Y2.Map) {
     return current.get(resolved);
   }
-  if (current instanceof Y.Array) {
+  if (current instanceof Y2.Array) {
     return current.get(resolved);
   }
-  if (current instanceof Y.Text) {
+  if (current instanceof Y2.Text) {
     throw new Error(`yjs-resolve: cannot step into Y.Text`);
   }
   return void 0;
@@ -83,7 +193,7 @@ function applyChangeToYjs(rootMap, rootSchema, path, change2) {
 }
 function applyTextChange(rootMap, rootSchema, path, change2) {
   const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y2.Text)) {
+  if (!(resolved instanceof Y3.Text)) {
     throw new Error(
       `applyChangeToYjs: TextChange target at path [${pathToString(path)}] is not a Y.Text`
     );
@@ -92,7 +202,7 @@ function applyTextChange(rootMap, rootSchema, path, change2) {
 }
 function applySequenceChange(rootMap, rootSchema, path, change2) {
   const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y2.Array)) {
+  if (!(resolved instanceof Y3.Array)) {
     throw new Error(
       `applyChangeToYjs: SequenceChange target at path [${pathToString(path)}] is not a Y.Array`
     );
@@ -117,7 +227,7 @@ function applySequenceChange(rootMap, rootSchema, path, change2) {
 }
 function applyMapChange(rootMap, rootSchema, path, change2) {
   const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y2.Map)) {
+  if (!(resolved instanceof Y3.Map)) {
     throw new Error(
       `applyChangeToYjs: MapChange target at path [${pathToString(path)}] is not a Y.Map`
     );
@@ -146,11 +256,11 @@ function applyReplaceChange(rootMap, rootSchema, path, change2) {
   const parentPath = path.slice(0, -1);
   const parent = resolveYjsType(rootMap, rootSchema, parentPath);
   const resolved = lastSeg.resolve();
-  if (parent instanceof Y2.Map && lastSeg.role === "key") {
+  if (parent instanceof Y3.Map && lastSeg.role === "key") {
     const targetSchema = resolveSchemaAtPath(rootSchema, path);
     const yjsValue = maybeCreateSharedType(change2.value, targetSchema);
     parent.set(resolved, yjsValue);
-  } else if (parent instanceof Y2.Array && lastSeg.role === "index") {
+  } else if (parent instanceof Y3.Array && lastSeg.role === "index") {
     const targetSchema = resolveSchemaAtPath(rootSchema, path);
     const yjsValue = maybeCreateSharedType(change2.value, targetSchema);
     parent.delete(resolved, 1);
@@ -166,7 +276,7 @@ function maybeCreateSharedType(value, schema) {
   switch (schema[KIND2]) {
     // First-class text → Y.Text
     case "text": {
-      const text = new Y2.Text();
+      const text = new Y3.Text();
       if (typeof value === "string" && value.length > 0) {
         text.insert(0, value);
       }
@@ -180,7 +290,7 @@ function maybeCreateSharedType(value, schema) {
     }
     case "sequence": {
       if (!Array.isArray(value)) return value;
-      const arr = new Y2.Array();
+      const arr = new Y3.Array();
       const itemSchema = schema.item;
       const items = value.map(
         (item) => maybeCreateSharedType(item, itemSchema)
@@ -192,7 +302,7 @@ function maybeCreateSharedType(value, schema) {
       if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) {
         return value;
       }
-      const map = new Y2.Map();
+      const map = new Y3.Map();
       const valueSchema = schema.item;
       for (const [k, v] of Object.entries(value)) {
         map.set(k, maybeCreateSharedType(v, valueSchema));
@@ -213,7 +323,7 @@ function maybeCreateSharedType(value, schema) {
   }
 }
 function createStructuredMap(obj, productSchema) {
-  const map = new Y2.Map();
+  const map = new Y3.Map();
   if (productSchema[KIND2] !== "product") {
     for (const [key, val] of Object.entries(obj)) {
       map.set(key, val);
@@ -231,7 +341,7 @@ function createStructuredMap(obj, productSchema) {
   )) {
     if (key in obj) continue;
     if (fieldSchema[KIND2] === "text") {
-      map.set(key, new Y2.Text());
+      map.set(key, new Y3.Text());
     }
   }
   return map;
@@ -259,13 +369,13 @@ function yjsPathToKynetaPath(yjsPath) {
   return path;
 }
 function eventToChange(event) {
-  if (event.target instanceof Y2.Text) {
+  if (event.target instanceof Y3.Text) {
     return textEventToChange(event);
   }
-  if (event.target instanceof Y2.Array) {
+  if (event.target instanceof Y3.Array) {
     return arrayEventToChange(event);
   }
-  if (event.target instanceof Y2.Map) {
+  if (event.target instanceof Y3.Map) {
     return mapEventToChange(event);
   }
   return null;
@@ -323,9 +433,9 @@ function mapEventToChange(event) {
   };
 }
 function extractEventValue(value) {
-  if (value instanceof Y2.Map) return value.toJSON();
-  if (value instanceof Y2.Array) return value.toJSON();
-  if (value instanceof Y2.Text) return value.toJSON();
+  if (value instanceof Y3.Map) return value.toJSON();
+  if (value instanceof Y3.Array) return value.toJSON();
+  if (value instanceof Y3.Text) return value.toJSON();
   return value;
 }
 function resolveSchemaAtPath(rootSchema, path) {
@@ -356,99 +466,6 @@ function pathToString(path) {
   return path.segments.map((seg) => String(seg.resolve())).join(".");
 }
 
-// src/populate.ts
-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");
-  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(schema.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) {
-  switch (fieldSchema[KIND3]) {
-    case "text":
-      rootMap.set(key, new Y3.Text());
-      return;
-    case "product":
-      rootMap.set(key, ensureMapContainers(fieldSchema));
-      return;
-    case "sequence":
-      rootMap.set(key, new Y3.Array());
-      return;
-    case "map":
-      rootMap.set(key, new Y3.Map());
-      return;
-    case "scalar":
-    case "sum": {
-      const zero = Zero.structural(fieldSchema);
-      if (zero !== void 0) {
-        rootMap.set(key, zero);
-      }
-      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();
-  if (schema[KIND3] !== "product") return map;
-  for (const [key, fieldSchema] of Object.entries(
-    schema.fields
-  ).sort(([a], [b]) => a.localeCompare(b))) {
-    switch (fieldSchema[KIND3]) {
-      case "text":
-        map.set(key, new Y3.Text());
-        break;
-      case "product":
-        map.set(key, ensureMapContainers(fieldSchema));
-        break;
-      case "sequence":
-        map.set(key, new Y3.Array());
-        break;
-      case "map":
-        map.set(key, new Y3.Map());
-        break;
-      case "scalar":
-      case "sum": {
-        const zero = Zero.structural(fieldSchema);
-        if (zero !== void 0) {
-          map.set(key, zero);
-        }
-        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;
-}
-
 // src/reader.ts
 import * as Y4 from "yjs";
 function extractValue(resolved) {
@@ -507,23 +524,13 @@ function yjsReader(doc, schema) {
 }
 
 // src/version.ts
-import { versionVectorMeet } from "@kyneta/schema";
+import {
+  base64ToUint8Array,
+  uint8ArrayToBase64,
+  versionVectorCompare,
+  versionVectorMeet
+} from "@kyneta/schema";
 import { decodeStateVector } from "yjs";
-function uint8ArrayToBase64(bytes) {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-}
-function base64ToUint8Array(base64) {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes;
-}
 function encodeStateVector(map) {
   const bytes = [];
   function writeVarUint(value) {
@@ -557,45 +564,19 @@ var YjsVersion = class _YjsVersion {
   /**
    * 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"`
+   * Delegates to the shared `versionVectorCompare` utility after decoding
+   * both state vectors via `Y.decodeStateVector()`.
    *
-   * Throws if `other` is not a `YjsVersion`.
+   * @throws If `other` is not a `YjsVersion`.
    */
   compare(other) {
     if (!(other instanceof _YjsVersion)) {
       throw new Error("YjsVersion can only be compared with another YjsVersion");
     }
-    const thisMap = decodeStateVector(this.sv);
-    const otherMap = decodeStateVector(other.sv);
-    const allClients = /* @__PURE__ */ new Set();
-    for (const id of thisMap.keys()) allClients.add(id);
-    for (const id of otherMap.keys()) allClients.add(id);
-    let hasLess = false;
-    let hasGreater = false;
-    for (const clientId of allClients) {
-      const thisClock = thisMap.get(clientId) ?? 0;
-      const otherClock = otherMap.get(clientId) ?? 0;
-      if (thisClock < otherClock) {
-        hasLess = true;
-      }
-      if (thisClock > otherClock) {
-        hasGreater = true;
-      }
-      if (hasLess && hasGreater) {
-        return "concurrent";
-      }
-    }
-    if (hasLess && !hasGreater) return "behind";
-    if (hasGreater && !hasLess) return "ahead";
-    return "equal";
+    return versionVectorCompare(
+      decodeStateVector(this.sv),
+      decodeStateVector(other.sv)
+    );
   }
   /**
    * Greatest lower bound (lattice meet) of two Yjs versions.
@@ -608,9 +589,7 @@ var YjsVersion = class _YjsVersion {
    */
   meet(other) {
     if (!(other instanceof _YjsVersion)) {
-      throw new Error(
-        "YjsVersion can only be meet'd with another YjsVersion"
-      );
+      throw new Error("YjsVersion can only be meet'd with another YjsVersion");
     }
     const thisMap = decodeStateVector(this.sv);
     const otherMap = decodeStateVector(other.sv);
@@ -666,6 +645,12 @@ function createYjsSubstrate(doc, schema) {
     context() {
       if (!cachedCtx) {
         cachedCtx = buildWritableContext(substrate);
+        cachedCtx.nativeResolver = (nodeSchema, path) => {
+          if (path.segments.length === 0) return doc;
+          if (nodeSchema[KIND3] === "scalar" || nodeSchema[KIND3] === "sum")
+            return void 0;
+          return resolveYjsType(rootMap, schema, path);
+        };
       }
       return cachedCtx;
     },
@@ -730,9 +715,7 @@ function createYjsSubstrate(doc, schema) {
 }
 function createYjsReplica(doc) {
   let currentDoc = doc;
-  let currentBase = new YjsVersion(
-    Y5.encodeStateVector(new Y5.Doc())
-  );
+  let currentBase = new YjsVersion(Y5.encodeStateVector(new Y5.Doc()));
   return {
     get [BACKING_DOC]() {
       return currentDoc;
@@ -828,57 +811,7 @@ var yjsSubstrateFactory = {
   }
 };
 
-// src/create.ts
-var substrates = /* @__PURE__ */ new WeakMap();
-function getSubstrate(doc) {
-  const s = substrates.get(doc);
-  if (!s) {
-    throw new Error(
-      "version/exportEntirety/merge called on an object without a YjsSubstrate. Use a doc created by createYjsDoc() or createYjsDocFromEntirety()."
-    );
-  }
-  return s;
-}
-function registerDoc(schema, substrate) {
-  const doc = interpret(schema, substrate.context()).with(readable).with(writable).with(observation).done();
-  substrates.set(doc, substrate);
-  registerSubstrate(doc, substrate);
-  return doc;
-}
-function isYDoc(value) {
-  return value !== null && value !== void 0 && typeof value === "object" && "getMap" in value && "getText" in value && "getArray" in value && "transact" in value && typeof value.transact === "function" && // Y.Doc has clientID; distinguish from other objects
-  "clientID" in value && typeof value.clientID === "number";
-}
-var createYjsDoc = (schema, doc) => {
-  if (doc !== void 0 && isYDoc(doc)) {
-    return registerDoc(schema, createYjsSubstrate(doc, schema));
-  }
-  return registerDoc(schema, yjsSubstrateFactory.create(schema));
-};
-var createYjsDocFromEntirety = (schema, payload) => registerDoc(schema, yjsSubstrateFactory.fromEntirety(payload, schema));
-
-// src/sync.ts
-function version(doc) {
-  return getSubstrate(doc).version();
-}
-function exportEntirety(doc) {
-  return getSubstrate(doc).exportEntirety();
-}
-function exportSince(doc, since) {
-  return getSubstrate(doc).exportSince(since);
-}
-function merge(doc, payload, origin) {
-  getSubstrate(doc).merge(payload, origin);
-}
-
 // src/bind-yjs.ts
-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;
   for (let i = 0; i < peerId.length; i++) {
@@ -917,46 +850,28 @@ function createYjsFactory(peerId) {
     }
   };
 }
-var yjs = {
-  ...createSubstrateNamespace({
-    strategies: {
-      collaborative: {
-        factory: (ctx) => createYjsFactory(ctx.peerId),
-        replicaFactory: yjsReplicaFactory
-      },
-      ephemeral: {
-        factory: (ctx) => createYjsFactory(ctx.peerId),
-        replicaFactory: yjsReplicaFactory
-      }
+var yjs = createSubstrateNamespace({
+  strategies: {
+    collaborative: {
+      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()."
-      );
+    ephemeral: {
+      factory: (ctx) => createYjsFactory(ctx.peerId),
+      replicaFactory: yjsReplicaFactory
     }
-    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;
-  }
-};
+  },
+  defaultStrategy: "collaborative"
+});
 export {
+  NATIVE,
   Schema,
   YjsVersion,
   applyChangeToYjs,
   applyChanges,
   change,
-  createYjsDoc,
-  createYjsDocFromEntirety,
+  createDoc,
+  createRef,
   createYjsSubstrate,
   ensureContainers,
   eventsToOps,
@@ -967,6 +882,7 @@ export {
   stepIntoYjs,
   subscribe,
   subscribeNode,
+  unwrap,
   version,
   yjs,
   yjsReader,