@loro-extended/change 5.3.0 → 5.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-extended/change",
-  "version": "5.3.0",
+  "version": "5.4.1",
   "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/change.test.ts

@@ -2248,7 +2248,7 @@ describe("Edge Cases and Error Handling", () => {
       // Note: authorColor is NOT set - this should fall back to placeholder default
 
       // Wrap with TypedDoc
-      const typedDoc = createTypedDoc(DocSchema, loroDoc)
+      const typedDoc = createTypedDoc(DocSchema, { doc: loroDoc })
 
       // This should not throw "placeholder required"
       expect(() => {

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/diff-overlay.test.ts

@@ -0,0 +1,95 @@
+import type { LoroEventBatch } from "loro-crdt"
+import { describe, expect, it } from "vitest"
+import { createDiffOverlay } from "./diff-overlay.js"
+import { createTypedDoc, loro, Shape } from "./index.js"
+
+describe("diff overlay", () => {
+  it("should read before values via overlay without checkout", () => {
+    const schema = Shape.doc({
+      counter: Shape.counter(),
+      info: Shape.struct({
+        name: Shape.plain.string(),
+        count: Shape.plain.number(),
+      }),
+      list: Shape.list(Shape.plain.number()),
+      text: Shape.text(),
+    })
+
+    const doc = createTypedDoc(schema)
+    const loroDoc = loro(doc).doc
+
+    doc.counter.increment(10)
+    doc.info.name = "Alice"
+    doc.info.count = 1
+    doc.list.push(1)
+    doc.text.insert(0, "hello")
+    loroDoc.commit()
+
+    const transitions: Array<{
+      before: {
+        counter: number
+        name: string
+        count: number
+        list: number[]
+        text: string
+      }
+      after: {
+        counter: number
+        name: string
+        count: number
+        list: number[]
+        text: string
+      }
+    }> = []
+
+    loroDoc.subscribe(event => {
+      const batch = event as LoroEventBatch
+      if (batch.by === "checkout") return
+
+      const overlay = createDiffOverlay(loroDoc, batch)
+      const beforeDoc = createTypedDoc(schema, { doc: loroDoc, overlay })
+      const afterDoc = createTypedDoc(schema, { doc: loroDoc })
+
+      transitions.push({
+        before: {
+          counter: beforeDoc.counter.value,
+          name: beforeDoc.info.name,
+          count: beforeDoc.info.count,
+          list: beforeDoc.list.toArray(),
+          text: beforeDoc.text.toString(),
+        },
+        after: {
+          counter: afterDoc.counter.value,
+          name: afterDoc.info.name,
+          count: afterDoc.info.count,
+          list: afterDoc.list.toArray(),
+          text: afterDoc.text.toString(),
+        },
+      })
+    })
+
+    doc.change(draft => {
+      draft.counter.increment(5)
+      draft.info.name = "Bob"
+      draft.info.count = 2
+      draft.list.push(2)
+      draft.text.update("hello world")
+    })
+
+    expect(transitions).toHaveLength(1)
+    expect(transitions[0].before).toEqual({
+      counter: 10,
+      name: "Alice",
+      count: 1,
+      list: [1],
+      text: "hello",
+    })
+    expect(transitions[0].after).toEqual({
+      counter: 15,
+      name: "Bob",
+      count: 2,
+      list: [1, 2],
+      text: "hello world",
+    })
+  })
+})

package/src/diff-overlay.ts

@@ -0,0 +1,10 @@
+import type { ContainerID, Diff, LoroDoc, LoroEventBatch } from "loro-crdt"
+
+export type DiffOverlay = ReadonlyMap<ContainerID, Diff>
+
+export function createDiffOverlay(
+  doc: LoroDoc,
+  batch: LoroEventBatch,
+): DiffOverlay {
+  return new Map(doc.diff(batch.to, batch.from, false))
+}

package/src/discriminated-union-tojson.test.ts

@@ -64,7 +64,7 @@ describe("Record with Map entries - placeholder required bug", () => {
     // Note: authorColor is NOT set - this should fall back to placeholder
 
     // Now wrap it with TypedDoc
-    const typedDoc = createTypedDoc(AiStateSchema, loroDoc)
+    const typedDoc = createTypedDoc(AiStateSchema, { doc: loroDoc })
 
     // This should not throw "placeholder required"
     // BUG: Currently throws because the nested MapRef has placeholder: undefined
@@ -107,7 +107,7 @@ describe("Record with Map entries - placeholder required bug", () => {
     // Only set peerId - other fields are missing
     studentMap.set("peerId", "peer-456")
 
-    const typedDoc = createTypedDoc(AiStateSchema, loroDoc)
+    const typedDoc = createTypedDoc(AiStateSchema, { doc: loroDoc })
 
     // This should not throw - missing fields should use placeholder defaults
     expect(() => {

package/src/fork-at.test.ts

@@ -197,7 +197,7 @@ describe("forkAt", () => {
       expect(rawForkedDoc.toJSON()).toEqual({ text: "Hello" })
 
       // Can wrap it manually if needed
-      const typedForkedDoc = createTypedDoc(schema, rawForkedDoc)
+      const typedForkedDoc = createTypedDoc(schema, { doc: rawForkedDoc })
       expect(typedForkedDoc.text.toString()).toBe("Hello")
     })
   })

package/src/functional-helpers.test.ts

@@ -1,3 +1,4 @@
+import type { LoroEventBatch } from "loro-crdt"
 import {
   LoroCounter,
   LoroList,
@@ -7,7 +8,12 @@ import {
   LoroTree,
 } from "loro-crdt"
 import { describe, expect, it, vi } from "vitest"
-import { change, getLoroContainer, getLoroDoc } from "./functional-helpers.js"
+import {
+  change,
+  getLoroContainer,
+  getLoroDoc,
+  getTransition,
+} from "./functional-helpers.js"
 import { loro } from "./loro.js"
 import { Shape } from "./shape.js"
 import { createTypedDoc } from "./typed-doc.js"
@@ -486,6 +492,49 @@ describe("functional helpers", () => {
     })
   })
 
+  describe("getTransition()", () => {
+    it("should return before/after using reverse diff overlay", () => {
+      const doc = createTypedDoc(schema)
+
+      const transitions: Array<{ beforeCount: number; afterCount: number }> = []
+      const unsubscribe = loro(doc).subscribe(event => {
+        const { before, after } = getTransition(doc, event)
+        transitions.push({
+          beforeCount: before.count.value,
+          afterCount: after.count.value,
+        })
+      })
+
+      doc.count.increment(2)
+      loro(doc).doc.commit()
+
+      expect(transitions).toEqual([{ beforeCount: 0, afterCount: 2 }])
+      unsubscribe()
+    })
+
+    it("should throw on checkout events", () => {
+      const doc = createTypedDoc(schema)
+      const frontiers = loro(doc).doc.frontiers()
+
+      doc.count.increment(1)
+      loro(doc).doc.commit()
+
+      let checkoutEvent: LoroEventBatch | undefined
+      const unsubscribe = loro(doc).subscribe(event => {
+        checkoutEvent = event
+      })
+
+      loro(doc).doc.checkout(frontiers)
+
+      expect(checkoutEvent).toBeDefined()
+      expect(() => getTransition(doc, checkoutEvent as LoroEventBatch)).toThrow(
+        "getTransition does not support checkout events",
+      )
+
+      unsubscribe()
+    })
+  })
+
   describe("getLoroDoc() on refs", () => {
     it("should return LoroDoc from TextRef", () => {
       const doc = createTypedDoc(fullSchema)

package/src/functional-helpers.ts

@@ -1,12 +1,14 @@
-import type {
-  LoroCounter,
+import {
+  type LoroCounter,
   LoroDoc,
-  LoroList,
-  LoroMap,
-  LoroMovableList,
-  LoroText,
-  LoroTree,
+  type LoroEventBatch,
+  type LoroList,
+  type LoroMap,
+  type LoroMovableList,
+  type LoroText,
+  type LoroTree,
 } from "loro-crdt"
+import { createDiffOverlay } from "./diff-overlay.js"
 import { loro } from "./loro.js"
 import type {
   ContainerOrValueShape,
@@ -274,6 +276,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, { doc: forkedLoroDoc })
+}
+
 /**
  * Creates a new TypedDoc at a specified version (frontiers).
  * The forked doc will only contain history before the specified frontiers.
@@ -307,5 +355,101 @@ export function forkAt<Shape extends DocShape>(
   const loroDoc = loro(doc).doc
   const forkedLoroDoc = loroDoc.forkAt(frontiers)
   const shape = loro(doc).docShape as Shape
-  return createTypedDoc(shape, forkedLoroDoc)
+  return createTypedDoc(shape, { doc: 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, { doc: shallowLoroDoc })
+}
+
+export type Transition<Shape extends DocShape> = {
+  before: TypedDoc<Shape>
+  after: TypedDoc<Shape>
+}
+
+/**
+ * Build a `{ before, after }` transition from a TypedDoc and a Loro event batch.
+ * Uses a reverse diff overlay to compute the "before" view without checkout.
+ * Throws on checkout events to avoid time-travel transitions.
+ */
+export function getTransition<Shape extends DocShape>(
+  doc: TypedDoc<Shape>,
+  event: LoroEventBatch,
+): Transition<Shape> {
+  if (event.by === "checkout") {
+    throw new Error("getTransition does not support checkout events")
+  }
+
+  const loroDoc = getLoroDoc(doc)
+  const shape = loro(doc).docShape as Shape
+  const overlay = createDiffOverlay(loroDoc, event)
+
+  return {
+    before: createTypedDoc(shape, { doc: loroDoc, overlay }),
+    after: createTypedDoc(shape, { doc: loroDoc }),
+  }
 }

package/src/index.ts

@@ -4,12 +4,18 @@ export {
   derivePlaceholder,
   deriveShapePlaceholder,
 } from "./derive-placeholder.js"
+// Diff overlay--make the TypedDoc return values as if a diff is applied
+export { createDiffOverlay } from "./diff-overlay.js"
+export type { Transition } from "./functional-helpers.js"
 // Functional helpers (recommended API)
 export {
   change,
+  fork,
   forkAt,
   getLoroContainer,
   getLoroDoc,
+  getTransition,
+  shallowForkAt,
 } from "./functional-helpers.js"
 // The loro() escape hatch for CRDT internals
 export {
@@ -23,68 +29,89 @@ export {
   type LoroTypedDocRef,
   loro,
 } from "./loro.js"
+// Regular placeholder overlay
 export { mergeValue, overlayPlaceholder } from "./overlay.js"
+
 // Path selector DSL exports
 export { createPathBuilder } from "./path-builder.js"
+
 export { compileToJsonPath, hasWildcard } from "./path-compiler.js"
+
 export { evaluatePath, evaluatePathOnValue } from "./path-evaluator.js"
+
 export type {
   PathBuilder,
   PathNode,
   PathSegment,
   PathSelector,
 } from "./path-selector.js"
+
 export { createPlaceholderProxy } from "./placeholder-proxy.js"
+
+export { replayDiff } from "./replay-diff.js"
+// Doc shapes
+// Container shapes
+// Value shapes
+// Shape utilities
 export type {
-  // Escape hatch shapes for untyped integration
   AnyContainerShape,
   AnyValueShape,
   ArrayValueShape,
+  BooleanValueShape,
+  // A shape type representing any container-type or value-type shape (excludes DocShape)
   ContainerOrValueShape,
+  // A shape type representing any container-type shape
   ContainerShape,
   ContainerType as RootContainerType,
-  // Container shapes
   CounterContainerShape,
-  // Discriminated union for tagged unions
+  // Tagged union of two or more plain value types
   DiscriminatedUnionValueShape,
-  // Schema node types
   DocShape,
   ListContainerShape,
-  /** @deprecated Use StructContainerShape instead */
-  MapContainerShape,
   MovableListContainerShape,
-  /** @deprecated Use StructValueShape instead */
-  ObjectValueShape,
+  NullValueShape,
+  NumberValueShape,
   RecordContainerShape,
   RecordValueShape,
+  StringValueShape,
   StructContainerShape,
   StructValueShape,
   TextContainerShape,
   TreeContainerShape,
-  // Tree-related types
   TreeNodeJSON,
   TreeRefInterface,
+  Uint8ArrayValueShape,
+  UndefinedValueShape,
+  // Union of two or more plain value types
   UnionValueShape,
-  // Value shapes
+  // A shape type representing any value-type shape
   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"
+
 export { createTypedDoc } from "./typed-doc.js"
+
 // Typed ref types - for specifying types with the loro() function
-export type { CounterRef } from "./typed-refs/counter-ref.js"
-export type { ListRef } from "./typed-refs/list-ref.js"
-export type { MovableListRef } from "./typed-refs/movable-list-ref.js"
-export type { RecordRef } from "./typed-refs/record-ref.js"
-export type { StructRef } from "./typed-refs/struct-ref.js"
-export type { TextRef } from "./typed-refs/text-ref.js"
-export type { TreeNodeRef } from "./typed-refs/tree-node-ref.js"
-export type { TreeRef } from "./typed-refs/tree-ref.js"
+export type {
+  CounterRef,
+  DiffOverlay,
+  ListRef,
+  MovableListRef,
+  RecordRef,
+  StructRef,
+  TextRef,
+  TreeNodeRef,
+  TreeRef,
+} from "./typed-refs/index.js"
+
 export type {
   // Type inference - Infer<T> is the recommended unified helper
   Infer,
@@ -94,5 +121,6 @@ export type {
   InferRaw,
   Mutable,
 } from "./types.js"
+
 // Utility exports
 export { validatePlaceholder } from "./validation.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
 }
 
 /**