@loro-extended/change 5.2.0 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-extended/change",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "A schema-driven, type-safe wrapper for Loro CRDT that provides natural JavaScript syntax for collaborative data mutations",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -25,13 +25,14 @@
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.17"
   },
   "peerDependencies": {
     "loro-crdt": "^1.10.3"
   },
   "scripts": {
     "build": "tsup",
+    "test": "verify logic",
     "verify": "verify"
   }
 }

package/src/conversion.ts

@@ -108,17 +108,53 @@ function convertStructInput(
   }
 
   const map = new LoroMap()
-  for (const [k, v] of Object.entries(value)) {
+
+  // Iterate over schema keys to ensure all nested containers are materialized
+  for (const k of Object.keys(shape.shapes)) {
     const nestedSchema = shape.shapes[k]
-    if (nestedSchema) {
+    const v = value[k]
+
+    if (v !== undefined) {
       const convertedValue = convertInputToRef(v, nestedSchema)
       if (isContainer(convertedValue)) {
         map.setContainer(k, convertedValue)
       } else {
         map.set(k, convertedValue)
       }
-    } else {
-      map.set(k, value)
+    } else if (isContainerShape(nestedSchema)) {
+      // If value is missing but it's a container shape, create an empty container
+      // This ensures deterministic container IDs across peers
+      let emptyValue: any
+      if (nestedSchema._type === "struct" || nestedSchema._type === "record") {
+        emptyValue = {}
+      } else if (
+        nestedSchema._type === "list" ||
+        nestedSchema._type === "movableList"
+      ) {
+        emptyValue = []
+      } else if (nestedSchema._type === "text") {
+        emptyValue = ""
+      } else if (nestedSchema._type === "counter") {
+        emptyValue = 0
+      }
+
+      if (emptyValue !== undefined) {
+        const convertedValue = convertInputToRef(emptyValue, nestedSchema)
+        if (isContainer(convertedValue)) {
+          map.setContainer(k, convertedValue)
+        }
+      }
+    }
+  }
+
+  // Also handle keys present in value but not in schema (if any, though for structs this shouldn't happen ideally)
+  // But for backward compatibility or loose typing, we might want to preserve them?
+  // The original code did:
+  // if (nestedSchema) { ... } else { map.set(k, value) }
+  // So it allowed extra keys.
+  for (const [k, v] of Object.entries(value)) {
+    if (!shape.shapes[k]) {
+      map.set(k, v)
     }
   }
 

package/src/functional-helpers.test.ts

@@ -361,6 +361,131 @@ describe("functional helpers", () => {
     })
   })
 
+  describe("loro(ref).subscribe() for imported (remote) changes", () => {
+    it("should fire TextRef subscription when changes are imported", () => {
+      // Create two documents - simulating two clients
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      // Set up subscription on doc2's title ref
+      const callback = vi.fn()
+      const unsubscribe = loro(doc2.title).subscribe(callback)
+
+      // Make changes on doc1
+      doc1.title.insert(0, "Hello from doc1")
+      loro(doc1).doc.commit()
+
+      // Export from doc1 and import into doc2 (simulating sync)
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      // The subscription should have fired
+      expect(callback).toHaveBeenCalled()
+
+      // And the value should be updated
+      expect(doc2.title.toString()).toBe("Hello from doc1")
+
+      unsubscribe()
+    })
+
+    it("should fire CounterRef subscription when changes are imported", () => {
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      const callback = vi.fn()
+      const unsubscribe = loro(doc2.count).subscribe(callback)
+
+      doc1.count.increment(42)
+      loro(doc1).doc.commit()
+
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      expect(callback).toHaveBeenCalled()
+      expect(doc2.count.value).toBe(42)
+
+      unsubscribe()
+    })
+
+    it("should fire ListRef subscription when changes are imported", () => {
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      const callback = vi.fn()
+      const unsubscribe = loro(doc2.items).subscribe(callback)
+
+      doc1.items.push("item1")
+      doc1.items.push("item2")
+      loro(doc1).doc.commit()
+
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      expect(callback).toHaveBeenCalled()
+      expect(doc2.items.toJSON()).toEqual(["item1", "item2"])
+
+      unsubscribe()
+    })
+
+    it("should fire doc-level subscription when changes are imported", () => {
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      const callback = vi.fn()
+      const unsubscribe = loro(doc2).doc.subscribe(callback)
+
+      doc1.title.insert(0, "Hello")
+      loro(doc1).doc.commit()
+
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      expect(callback).toHaveBeenCalled()
+
+      unsubscribe()
+    })
+
+    it("should NOT fire subscription for containers that were not changed", () => {
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      // Subscribe to count, but only change title
+      const countCallback = vi.fn()
+      const unsubscribe = loro(doc2.count).subscribe(countCallback)
+
+      doc1.title.insert(0, "Hello")
+      loro(doc1).doc.commit()
+
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      // Count subscription should NOT have fired since count wasn't changed
+      expect(countCallback).not.toHaveBeenCalled()
+
+      unsubscribe()
+    })
+
+    it("should provide updated value in subscription callback", () => {
+      const doc1 = createTypedDoc(fullSchema)
+      const doc2 = createTypedDoc(fullSchema)
+
+      let capturedValue: string | undefined
+      const unsubscribe = loro(doc2.title).subscribe(() => {
+        capturedValue = doc2.title.toString()
+      })
+
+      doc1.title.insert(0, "Remote text")
+      loro(doc1).doc.commit()
+
+      const snapshot = loro(doc1).doc.export({ mode: "snapshot" })
+      loro(doc2).doc.import(snapshot)
+
+      expect(capturedValue).toBe("Remote text")
+
+      unsubscribe()
+    })
+  })
+
   describe("getLoroDoc() on refs", () => {
     it("should return LoroDoc from TextRef", () => {
       const doc = createTypedDoc(fullSchema)

package/src/functional-helpers.ts

@@ -1,11 +1,11 @@
-import type {
-  LoroCounter,
+import {
+  type LoroCounter,
   LoroDoc,
-  LoroList,
-  LoroMap,
-  LoroMovableList,
-  LoroText,
-  LoroTree,
+  type LoroList,
+  type LoroMap,
+  type LoroMovableList,
+  type LoroText,
+  type LoroTree,
 } from "loro-crdt"
 import { loro } from "./loro.js"
 import type {
@@ -274,6 +274,52 @@ export function getLoroContainer(
   return loro(ref as any).container
 }
 
+/**
+ * Creates a new TypedDoc as a fork of the current document.
+ * The forked doc contains all history up to the current version.
+ * The forked doc has a different PeerID from the original by default.
+ *
+ * For raw LoroDoc access, use: `loro(doc).doc.fork()`
+ *
+ * @param doc - The TypedDoc to fork
+ * @param options - Optional settings
+ * @param options.preservePeerId - If true, copies the original doc's peer ID to the fork
+ * @returns A new TypedDoc with the same schema at the current version
+ *
+ * @example
+ * ```typescript
+ * import { fork, loro } from "@loro-extended/change"
+ *
+ * const doc = createTypedDoc(schema);
+ * doc.title.update("Hello");
+ *
+ * // Fork the document
+ * const forkedDoc = fork(doc);
+ * forkedDoc.title.update("World");
+ *
+ * console.log(doc.title.toString()); // "Hello"
+ * console.log(forkedDoc.title.toString()); // "World"
+ *
+ * // Fork with same peer ID (for World/Worldview pattern)
+ * const worldview = fork(world, { preservePeerId: true });
+ * ```
+ */
+export function fork<Shape extends DocShape>(
+  doc: TypedDoc<Shape>,
+  options?: { preservePeerId?: boolean },
+): TypedDoc<Shape> {
+  const loroDoc = loro(doc).doc
+  const forkedLoroDoc = loroDoc.fork()
+  const shape = loro(doc).docShape as Shape
+
+  // Optionally preserve the peer ID (useful for World/Worldview pattern)
+  if (options?.preservePeerId) {
+    forkedLoroDoc.setPeerId(loroDoc.peerId)
+  }
+
+  return createTypedDoc(shape, forkedLoroDoc)
+}
+
 /**
  * Creates a new TypedDoc at a specified version (frontiers).
  * The forked doc will only contain history before the specified frontiers.
@@ -309,3 +355,71 @@ export function forkAt<Shape extends DocShape>(
   const shape = loro(doc).docShape as Shape
   return createTypedDoc(shape, forkedLoroDoc)
 }
+
+/**
+ * Creates a new TypedDoc at a specified version using a shallow snapshot.
+ * Unlike `forkAt`, this creates a "garbage-collected" snapshot that only
+ * contains the current state and history since the specified frontiers.
+ *
+ * This is more memory-efficient than `forkAt` for documents with long history,
+ * especially useful for the fork-and-merge pattern in LEA where we only need:
+ * 1. Read current state
+ * 2. Apply changes
+ * 3. Export delta and merge back
+ *
+ * The shallow fork has a different PeerID from the original by default.
+ * Use `preservePeerId: true` to copy the original's peer ID (useful for
+ * fork-and-merge patterns where you want consistent frontier progression).
+ *
+ * @param doc - The TypedDoc to fork
+ * @param frontiers - The version to fork at (obtained from `loro(doc).doc.frontiers()`)
+ * @param options - Optional settings
+ * @param options.preservePeerId - If true, copies the original doc's peer ID to the fork
+ * @returns A new TypedDoc with the same schema at the specified version (shallow)
+ *
+ * @example
+ * ```typescript
+ * import { shallowForkAt, loro } from "@loro-extended/change"
+ *
+ * const doc = createTypedDoc(schema);
+ * doc.title.update("Hello");
+ * const frontiers = loro(doc).doc.frontiers();
+ *
+ * // Create a shallow fork (memory-efficient)
+ * const shallowDoc = shallowForkAt(doc, frontiers, { preservePeerId: true });
+ *
+ * // Modify the shallow doc
+ * shallowDoc.title.update("World");
+ *
+ * // Merge changes back
+ * const update = loro(shallowDoc).doc.export({
+ *   mode: "update",
+ *   from: loro(doc).doc.version()
+ * });
+ * loro(doc).doc.import(update);
+ * ```
+ */
+export function shallowForkAt<Shape extends DocShape>(
+  doc: TypedDoc<Shape>,
+  frontiers: Frontiers,
+  options?: { preservePeerId?: boolean },
+): TypedDoc<Shape> {
+  const loroDoc = loro(doc).doc
+  const shape = loro(doc).docShape as Shape
+
+  // Export a shallow snapshot at the specified frontiers
+  const shallowBytes = loroDoc.export({
+    mode: "shallow-snapshot",
+    frontiers,
+  })
+
+  // Create a new LoroDoc from the shallow snapshot
+  const shallowLoroDoc = LoroDoc.fromSnapshot(shallowBytes)
+
+  // Optionally preserve the peer ID for consistent frontier progression
+  if (options?.preservePeerId) {
+    shallowLoroDoc.setPeerId(loroDoc.peerId)
+  }
+
+  return createTypedDoc(shape, shallowLoroDoc)
+}

package/src/index.ts

@@ -4,13 +4,17 @@ export {
   derivePlaceholder,
   deriveShapePlaceholder,
 } from "./derive-placeholder.js"
+
 // Functional helpers (recommended API)
 export {
   change,
+  fork,
   forkAt,
   getLoroContainer,
   getLoroDoc,
+  shallowForkAt,
 } from "./functional-helpers.js"
+
 // The loro() escape hatch for CRDT internals
 export {
   LORO_SYMBOL,
@@ -23,6 +27,7 @@ export {
   type LoroTypedDocRef,
   loro,
 } from "./loro.js"
+
 export { mergeValue, overlayPlaceholder } from "./overlay.js"
 // Path selector DSL exports
 export { createPathBuilder } from "./path-builder.js"
@@ -35,43 +40,42 @@ export type {
   PathSelector,
 } from "./path-selector.js"
 export { createPlaceholderProxy } from "./placeholder-proxy.js"
+export { replayDiff } from "./replay-diff.js"
+// Shape utilities
+// Container shapes
+// Value shapes
 export type {
-  // Escape hatch shapes for untyped integration
   AnyContainerShape,
   AnyValueShape,
   ArrayValueShape,
   ContainerOrValueShape,
   ContainerShape,
   ContainerType as RootContainerType,
-  // Container shapes
   CounterContainerShape,
-  // Discriminated union for tagged unions
+  // Tagged union
   DiscriminatedUnionValueShape,
-  // Schema node types
   DocShape,
   ListContainerShape,
-  /** @deprecated Use StructContainerShape instead */
-  MapContainerShape,
   MovableListContainerShape,
-  /** @deprecated Use StructValueShape instead */
-  ObjectValueShape,
+  NumberValueShape,
   RecordContainerShape,
   RecordValueShape,
+  StringValueShape,
   StructContainerShape,
   StructValueShape,
   TextContainerShape,
   TreeContainerShape,
-  // Tree-related types
   TreeNodeJSON,
   TreeRefInterface,
+  // Union of two or more plain value types
   UnionValueShape,
-  // Value shapes
   ValueShape,
   // WithNullable type for shapes that support .nullable()
   WithNullable,
   // WithPlaceholder type for shapes that support .placeholder()
   WithPlaceholder,
 } from "./shape.js"
+
 // Schema and type exports
 export { Shape } from "./shape.js"
 export type { Frontiers, TypedDoc } from "./typed-doc.js"

package/src/loro.ts

@@ -28,6 +28,7 @@ import type {
   Container,
   LoroCounter,
   LoroDoc,
+  LoroEventBatch,
   LoroList,
   LoroMap,
   LoroMovableList,
@@ -85,7 +86,7 @@ export interface LoroRefBase {
    * @param callback - Function called when the container changes
    * @returns Subscription that can be used to unsubscribe
    */
-  subscribe(callback: (event: unknown) => void): Subscription
+  subscribe(callback: (event: LoroEventBatch) => void): Subscription
 }
 
 /**