@loro-extended/change 5.4.0 → 5.4.2

package/README.md

@@ -37,7 +37,7 @@ const schema = Shape.doc({
   users: Shape.record(
     Shape.plain.struct({
       name: Shape.plain.string(),
-    })
+    }),
   ),
 });
 
@@ -103,7 +103,7 @@ const blogSchema = Shape.doc({
       heading: Shape.text(), // Collaborative headings
       content: Shape.text(), // Collaborative content
       order: Shape.plain.number(), // Plain metadata
-    })
+    }),
   ),
 });
 ```
@@ -141,7 +141,7 @@ const blogSchemaWithDefaults = Shape.doc({
       heading: Shape.text(),
       content: Shape.text(),
       order: Shape.plain.number(),
-    })
+    }),
   ),
 });
 
@@ -228,7 +228,7 @@ import { change } from "@loro-extended/change";
 // Library code - expose only the ref, not the doc
 class StateMachine {
   private doc: TypedDoc<...>;
-  
+
   get states(): TreeRef<StateNodeShape> {
     return this.doc.states;
   }
@@ -239,7 +239,7 @@ function addStates(states: TreeRef<StateNodeShape>) {
   change(states, draft => {
     const idle = draft.createNode();
     idle.data.name.insert(0, "idle");
-    
+
     const running = draft.createNode();
     running.data.name.insert(0, "running");
   });
@@ -251,6 +251,7 @@ addStates(machine.states); // No access to the underlying doc needed!
 ```
 
 This pattern is useful for:
+
 - **Library APIs**: Expose typed refs without leaking document structure
 - **Component isolation**: Pass refs to components that only need partial access
 - **Testing**: Mock or stub individual refs without full document setup
@@ -259,37 +260,37 @@ All ref types support `change()`:
 
 ```typescript
 // ListRef
-change(doc.items, draft => {
+change(doc.items, (draft) => {
   draft.push("item1");
   draft.push("item2");
 });
 
 // TextRef
-change(doc.title, draft => {
+change(doc.title, (draft) => {
   draft.insert(0, "Hello ");
   draft.insert(6, "World");
 });
 
 // CounterRef
-change(doc.count, draft => {
+change(doc.count, (draft) => {
   draft.increment(5);
   draft.decrement(2);
 });
 
 // StructRef
-change(doc.profile, draft => {
+change(doc.profile, (draft) => {
   draft.bio.insert(0, "Hello");
   draft.age.increment(1);
 });
 
 // RecordRef
-change(doc.users, draft => {
+change(doc.users, (draft) => {
   draft.set("alice", { name: "Alice" });
   draft.set("bob", { name: "Bob" });
 });
 
 // TreeRef
-change(doc.tree, draft => {
+change(doc.tree, (draft) => {
   const node = draft.createNode();
   node.data.name.insert(0, "root");
 });
@@ -298,14 +299,14 @@ change(doc.tree, draft => {
 Nested `change()` calls are safe - Loro's commit is idempotent:
 
 ```typescript
-change(doc.items, outer => {
+change(doc.items, (outer) => {
   outer.push("from outer");
-  
+
   // Nested change on a different ref - works correctly
-  change(doc.count, inner => {
+  change(doc.count, (inner) => {
     inner.increment(10);
   });
-  
+
   outer.push("still in outer");
 });
 // All mutations are committed
@@ -336,7 +337,7 @@ const ServerPresenceShape = Shape.plain.struct({
     Shape.plain.struct({
       x: Shape.plain.number(),
       y: Shape.plain.number(),
-    })
+    }),
   ),
   tick: Shape.plain.number(),
 });
@@ -516,7 +517,7 @@ handle.subscribe(
   (titles, prev) => {
     // titles: string[], prev: string[] | undefined
     console.log("Titles changed:", titles);
-  }
+  },
 );
 
 // DSL constructs:
@@ -605,18 +606,18 @@ loro(doc).rawValue; // Unmerged CRDT value
 
 **RecordRef** (Map-like interface)
 
-| Direct Access                    | Only via `loro()`              |
-| -------------------------------- | ------------------------------ |
-| `get(key)`                       | `setContainer(key, container)` |
-| `set(key, value)`                | `subscribe(callback)`          |
-| `delete(key)`                    | `doc`                          |
-| `has(key)`                       | `container`                    |
-| `keys()`, `values()`, `entries()`|                                |
-| `size`                           |                                |
-| `replace(values)`                |                                |
-| `merge(values)`                  |                                |
-| `clear()`                        |                                |
-| `toJSON()`                       |                                |
+| Direct Access                     | Only via `loro()`              |
+| --------------------------------- | ------------------------------ |
+| `get(key)`                        | `setContainer(key, container)` |
+| `set(key, value)`                 | `subscribe(callback)`          |
+| `delete(key)`                     | `doc`                          |
+| `has(key)`                        | `container`                    |
+| `keys()`, `values()`, `entries()` |                                |
+| `size`                            |                                |
+| `replace(values)`                 |                                |
+| `merge(values)`                   |                                |
+| `clear()`                         |                                |
+| `toJSON()`                        |                                |
 
 **TextRef**
 
@@ -668,6 +669,25 @@ function TextEditor({ textRef }: { textRef: TextRef }) {
 }
 ```
 
+### Subscribing to Document Transitions
+
+Use `getTransition()` to build `{ before, after }` TypedDocs from a
+subscription event using the diff overlay (no checkout or fork required):
+
+```typescript
+import { getTransition, loro } from "@loro-extended/change";
+
+const unsubscribe = loro(doc).subscribe((event) => {
+  if (event.by === "checkout") return;
+
+  const { before, after } = getTransition(doc, event);
+
+  if (!before.users.has("alice") && after.users.has("alice")) {
+    console.log("Alice just joined");
+  }
+});
+```
+
 ### Schema Builders
 
 #### `Shape.doc(shape)`
@@ -935,11 +955,11 @@ draft.history.clear();
 
 **Method semantics:**
 
-| Method             | Adds new | Updates existing | Removes absent |
-| ------------------ | -------- | ---------------- | -------------- |
-| `replace(values)`  | ✅       | ✅               | ✅             |
-| `merge(values)`    | ✅       | ✅               | ❌             |
-| `clear()`          | ❌       | ❌               | ✅ (all)       |
+| Method            | Adds new | Updates existing | Removes absent |
+| ----------------- | -------- | ---------------- | -------------- |
+| `replace(values)` | ✅       | ✅               | ✅             |
+| `merge(values)`   | ✅       | ✅               | ❌             |
+| `clear()`         | ❌       | ❌               | ✅ (all)       |
 
 These methods batch all operations into a single commit, avoiding multiple subscription notifications.
 
@@ -957,7 +977,7 @@ const StateNodeDataShape = Shape.struct({
       name: Shape.plain.string(),
       rego: Shape.plain.string(),
       description: Shape.plain.string().nullable(),
-    })
+    }),
   ),
 });
 
@@ -1099,7 +1119,7 @@ const todoSchema = Shape.doc({
       id: Shape.plain.string(),
       text: Shape.plain.string(),
       done: Shape.plain.boolean(),
-    })
+    }),
   ),
 });
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PeerID, LoroDoc, Container, LoroTreeNode, TreeID, LoroEventBatch, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroTree, LoroCounter, Value, ContainerID, Diff } from 'loro-crdt';
+import { LoroDoc, ContainerID, Diff, PeerID, Container, LoroTreeNode, TreeID, LoroEventBatch, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroTree, LoroCounter, Value } from 'loro-crdt';
 
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 /**
@@ -105,6 +105,114 @@ type JsonPatchTestOperation = {
 type JsonPatchOperation = JsonPatchAddOperation | JsonPatchRemoveOperation | JsonPatchReplaceOperation | JsonPatchMoveOperation | JsonPatchCopyOperation | JsonPatchTestOperation;
 type JsonPatch = JsonPatchOperation[];
 
+/**
+ * Symbol for internal methods that should not be enumerable or accessible to users.
+ * Used to hide implementation details like absorbPlainValues(), getTypedRefParams(), etc.
+ *
+ * This achieves Success Criteria #7 from loro-api-refactor.md:
+ * "Internal methods hidden - Via Symbol, not enumerable"
+ */
+declare const INTERNAL_SYMBOL: unique symbol;
+/**
+ * Minimal interface for refs that only need absorbPlainValues.
+ * Used by TreeNodeRef which doesn't extend TypedRef.
+ */
+interface RefInternalsBase {
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+    /** Force materialization of the container and its nested containers */
+    materialize(): void;
+}
+type DiffOverlay$1 = ReadonlyMap<ContainerID, Diff>;
+type TypedRefParams<Shape extends DocShape | ContainerShape> = {
+    shape: Shape;
+    placeholder?: Infer<Shape>;
+    getContainer: () => ShapeToContainer<Shape>;
+    autoCommit?: boolean;
+    batchedMutation?: boolean;
+    getDoc: () => LoroDoc;
+    overlay?: DiffOverlay$1;
+};
+/**
+ * Abstract base class for all ref internal implementations.
+ * Contains shared logic that was previously in TypedRef.createBaseInternals().
+ *
+ * Subclasses implement specific behavior for each ref type.
+ */
+declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape> implements RefInternalsBase {
+    protected readonly params: TypedRefParams<Shape>;
+    protected cachedContainer: ShapeToContainer<Shape> | undefined;
+    protected loroNamespace: LoroRefBase | undefined;
+    private _suppressAutoCommit;
+    constructor(params: TypedRefParams<Shape>);
+    /** Get the underlying Loro container (cached) */
+    getContainer(): ShapeToContainer<Shape>;
+    /** Commit changes if autoCommit is enabled and not suppressed */
+    commitIfAuto(): void;
+    /**
+     * Temporarily suppress auto-commit during batch operations.
+     * Used by assignPlainValueToTypedRef() to batch multiple property assignments.
+     */
+    setSuppressAutoCommit(suppress: boolean): void;
+    /** Check if auto-commit is currently suppressed */
+    isSuppressAutoCommit(): boolean;
+    /** Get the shape for this ref */
+    getShape(): Shape;
+    /** Get the placeholder value */
+    getPlaceholder(): Infer<Shape> | undefined;
+    /** Check if autoCommit is enabled */
+    getAutoCommit(): boolean;
+    /** Check if in batched mutation mode */
+    getBatchedMutation(): boolean;
+    /** Get the LoroDoc */
+    getDoc(): LoroDoc;
+    /** Get the diff overlay map (if provided) */
+    getOverlay(): DiffOverlay$1 | undefined;
+    /**
+     * Get the TypedRefParams needed to recreate this ref.
+     * Used by change() to create draft refs with modified params.
+     *
+     * Returns a new params object with the same shape, placeholder, getContainer, and getDoc,
+     * but allows overriding autoCommit and batchedMutation for draft creation.
+     */
+    getTypedRefParams(): TypedRefParams<Shape>;
+    /** Get the loro namespace (cached) */
+    getLoroNamespace(): LoroRefBase;
+    /** Absorb mutated plain values back into Loro containers - subclasses override */
+    abstract absorbPlainValues(): void;
+    /** Force materialization of the container and its nested containers */
+    materialize(): void;
+    /** Create the loro() namespace object - subclasses override for specific types */
+    protected createLoroNamespace(): LoroRefBase;
+}
+/**
+ * Base class for all typed refs.
+ *
+ * All internal methods are accessed via [INTERNAL_SYMBOL] to prevent
+ * namespace collisions with user data properties.
+ *
+ * Uses the Facade + Implementation pattern:
+ * - TypedRef is the thin public facade
+ * - BaseRefInternals subclasses contain all implementation logic
+ */
+declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
+    /**
+     * Internal implementation accessed via Symbol.
+     * Subclasses must set this to their specific internals class instance.
+     */
+    abstract [INTERNAL_SYMBOL]: BaseRefInternals<Shape>;
+    /**
+     * Serializes the ref to a plain JSON-compatible value.
+     * Returns the plain type inferred from the shape.
+     */
+    abstract toJSON(): Infer<Shape>;
+    /**
+     * Access the loro() namespace via the well-known symbol.
+     * This is used by the loro() function to access CRDT internals.
+     */
+    get [LORO_SYMBOL](): LoroRefBase;
+}
+
 /** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
 
 /**
@@ -143,6 +251,10 @@ type Frontiers = {
     peer: PeerID;
     counter: number;
 }[];
+type CreateTypedDocOptions = {
+    doc?: LoroDoc;
+    overlay?: DiffOverlay$1;
+};
 type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
     /**
      * The primary method of mutating typed documents.
@@ -208,7 +320,7 @@ type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
  * Returns a proxied document where schema properties are accessed directly.
  *
  * @param shape - The document schema (with optional .placeholder() values)
- * @param existingDoc - Optional existing LoroDoc to wrap
+ * @param options - Optional existing LoroDoc or diff overlay
  * @returns A proxied TypedDoc with direct schema access
  *
  * @example
@@ -239,111 +351,7 @@ type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
  * loro(doc).subscribe(callback);
  * ```
  */
-declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
-
-/**
- * Symbol for internal methods that should not be enumerable or accessible to users.
- * Used to hide implementation details like absorbPlainValues(), getTypedRefParams(), etc.
- *
- * This achieves Success Criteria #7 from loro-api-refactor.md:
- * "Internal methods hidden - Via Symbol, not enumerable"
- */
-declare const INTERNAL_SYMBOL: unique symbol;
-/**
- * Minimal interface for refs that only need absorbPlainValues.
- * Used by TreeNodeRef which doesn't extend TypedRef.
- */
-interface RefInternalsBase {
-    /** Absorb mutated plain values back into Loro containers */
-    absorbPlainValues(): void;
-    /** Force materialization of the container and its nested containers */
-    materialize(): void;
-}
-type TypedRefParams<Shape extends DocShape | ContainerShape> = {
-    shape: Shape;
-    placeholder?: Infer<Shape>;
-    getContainer: () => ShapeToContainer<Shape>;
-    autoCommit?: boolean;
-    batchedMutation?: boolean;
-    getDoc: () => LoroDoc;
-};
-/**
- * Abstract base class for all ref internal implementations.
- * Contains shared logic that was previously in TypedRef.createBaseInternals().
- *
- * Subclasses implement specific behavior for each ref type.
- */
-declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape> implements RefInternalsBase {
-    protected readonly params: TypedRefParams<Shape>;
-    protected cachedContainer: ShapeToContainer<Shape> | undefined;
-    protected loroNamespace: LoroRefBase | undefined;
-    private _suppressAutoCommit;
-    constructor(params: TypedRefParams<Shape>);
-    /** Get the underlying Loro container (cached) */
-    getContainer(): ShapeToContainer<Shape>;
-    /** Commit changes if autoCommit is enabled and not suppressed */
-    commitIfAuto(): void;
-    /**
-     * Temporarily suppress auto-commit during batch operations.
-     * Used by assignPlainValueToTypedRef() to batch multiple property assignments.
-     */
-    setSuppressAutoCommit(suppress: boolean): void;
-    /** Check if auto-commit is currently suppressed */
-    isSuppressAutoCommit(): boolean;
-    /** Get the shape for this ref */
-    getShape(): Shape;
-    /** Get the placeholder value */
-    getPlaceholder(): Infer<Shape> | undefined;
-    /** Check if autoCommit is enabled */
-    getAutoCommit(): boolean;
-    /** Check if in batched mutation mode */
-    getBatchedMutation(): boolean;
-    /** Get the LoroDoc */
-    getDoc(): LoroDoc;
-    /**
-     * Get the TypedRefParams needed to recreate this ref.
-     * Used by change() to create draft refs with modified params.
-     *
-     * Returns a new params object with the same shape, placeholder, getContainer, and getDoc,
-     * but allows overriding autoCommit and batchedMutation for draft creation.
-     */
-    getTypedRefParams(): TypedRefParams<Shape>;
-    /** Get the loro namespace (cached) */
-    getLoroNamespace(): LoroRefBase;
-    /** Absorb mutated plain values back into Loro containers - subclasses override */
-    abstract absorbPlainValues(): void;
-    /** Force materialization of the container and its nested containers */
-    materialize(): void;
-    /** Create the loro() namespace object - subclasses override for specific types */
-    protected createLoroNamespace(): LoroRefBase;
-}
-/**
- * Base class for all typed refs.
- *
- * All internal methods are accessed via [INTERNAL_SYMBOL] to prevent
- * namespace collisions with user data properties.
- *
- * Uses the Facade + Implementation pattern:
- * - TypedRef is the thin public facade
- * - BaseRefInternals subclasses contain all implementation logic
- */
-declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
-    /**
-     * Internal implementation accessed via Symbol.
-     * Subclasses must set this to their specific internals class instance.
-     */
-    abstract [INTERNAL_SYMBOL]: BaseRefInternals<Shape>;
-    /**
-     * Serializes the ref to a plain JSON-compatible value.
-     * Returns the plain type inferred from the shape.
-     */
-    abstract toJSON(): Infer<Shape>;
-    /**
-     * Access the loro() namespace via the well-known symbol.
-     * This is used by the loro() function to access CRDT internals.
-     */
-    get [LORO_SYMBOL](): LoroRefBase;
-}
+declare function createTypedDoc<Shape extends DocShape>(shape: Shape, options?: CreateTypedDocOptions): TypedDoc<Shape>;
 
 /**
  * Internal implementation for CounterRef.
@@ -386,6 +394,8 @@ declare class CounterRef extends TypedRef<CounterContainerShape> {
  */
 declare class ListRefBaseInternals<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends BaseRefInternals<any> {
     private itemCache;
+    private overlayListCache?;
+    getOverlayList(): Item[] | undefined;
     /** Get typed ref params for creating child refs at an index */
     getChildTypedRefParams(index: number, shape: ContainerShape): TypedRefParams<ContainerShape>;
     /** Get item for predicate functions (returns plain value) */
@@ -1383,7 +1393,7 @@ interface AnyValueShape extends Shape<Value, Value, undefined> {
     readonly _type: "value";
     readonly valueType: "any";
 }
-type ValueShape = AnyValueShape | StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | StructValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
+type ValueShape = AnyValueShape | ArrayValueShape | BooleanValueShape | DiscriminatedUnionValueShape | NullValueShape | NumberValueShape | RecordValueShape | StringValueShape | StructValueShape | Uint8ArrayValueShape | UndefinedValueShape | UnionValueShape;
 type ContainerOrValueShape = ContainerShape | ValueShape;
 interface Shape<Plain, Mutable, Placeholder = Plain> {
     readonly _type: string;
@@ -1561,6 +1571,9 @@ declare function derivePlaceholder<T extends DocShape>(schema: T): InferPlacehol
  */
 declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
 
+type DiffOverlay = ReadonlyMap<ContainerID, Diff>;
+declare function createDiffOverlay(doc: LoroDoc, batch: LoroEventBatch): DiffOverlay;
+
 /**
  * The primary method of mutating typed documents and refs.
  * Batches multiple mutations into a single transaction.
@@ -1777,6 +1790,16 @@ declare function forkAt<Shape extends DocShape>(doc: TypedDoc<Shape>, frontiers:
 declare function shallowForkAt<Shape extends DocShape>(doc: TypedDoc<Shape>, frontiers: Frontiers, options?: {
     preservePeerId?: boolean;
 }): TypedDoc<Shape>;
+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.
+ */
+declare function getTransition<Shape extends DocShape>(doc: TypedDoc<Shape>, event: LoroEventBatch): Transition<Shape>;
 
 /**
  * Overlays CRDT state with placeholder defaults
@@ -1930,4 +1953,4 @@ declare function replayDiff(doc: LoroDoc, diff: [ContainerID, Diff][]): void;
  */
 declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, CounterRef, type DiscriminatedUnionValueShape, type DocShape, type Frontiers, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, LORO_SYMBOL, type ListContainerShape, ListRef, type LoroCounterRef, type LoroListRef, type LoroMapRef, type LoroRefBase, type LoroTextRef, type LoroTreeRef, type LoroTypedDocRef, type MovableListContainerShape, MovableListRef, type Mutable, type NumberValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, RecordRef, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StringValueShape, type StructContainerShape, type StructRef, type StructValueShape, type TextContainerShape, TextRef, type TreeContainerShape, type TreeNodeJSON, TreeNodeRef, TreeRef, type TreeRefInterface, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, fork, forkAt, getLoroContainer, getLoroDoc, hasWildcard, loro, mergeValue, overlayPlaceholder, replayDiff, shallowForkAt, validatePlaceholder };
+export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type BooleanValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, CounterRef, type DiffOverlay$1 as DiffOverlay, type DiscriminatedUnionValueShape, type DocShape, type Frontiers, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, LORO_SYMBOL, type ListContainerShape, ListRef, type LoroCounterRef, type LoroListRef, type LoroMapRef, type LoroRefBase, type LoroTextRef, type LoroTreeRef, type LoroTypedDocRef, type MovableListContainerShape, MovableListRef, type Mutable, type NullValueShape, type NumberValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, RecordRef, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StringValueShape, type StructContainerShape, type StructRef, type StructValueShape, type TextContainerShape, TextRef, type Transition, type TreeContainerShape, type TreeNodeJSON, TreeNodeRef, TreeRef, type TreeRefInterface, type TypedDoc, type Uint8ArrayValueShape, type UndefinedValueShape, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createDiffOverlay, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, fork, forkAt, getLoroContainer, getLoroDoc, getTransition, hasWildcard, loro, mergeValue, overlayPlaceholder, replayDiff, shallowForkAt, validatePlaceholder };