@loro-extended/change 5.3.0 → 5.4.0

package/README.md

@@ -605,15 +605,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()` |                                |
-| `size`               |                                |
-| `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**
 
@@ -906,6 +909,40 @@ draft.metadata.values();
 const value = draft.metadata.get("key");
 ```
 
+### Record Bulk Update Operations
+
+Records support bulk update methods for efficient batch operations:
+
+```typescript
+// Replace entire contents - keys not in the new object are removed
+draft.players.replace({
+  alice: { name: "Alice", score: 100 },
+  bob: { name: "Bob", score: 50 },
+});
+// Result: only alice and bob exist, any previous entries are removed
+
+// Merge values - existing keys not in the new object are kept
+draft.scores.merge({
+  alice: 150, // updates alice
+  charlie: 25, // adds charlie
+});
+// Result: alice=150, bob=50 (unchanged), charlie=25
+
+// Clear all entries
+draft.history.clear();
+// Result: empty record
+```
+
+**Method semantics:**
+
+| 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.
+
 ### Tree Operations
 
 Trees are hierarchical structures where each node has typed metadata. Perfect for state machines, file systems, org charts, and nested data.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PeerID, LoroDoc, Container, LoroTreeNode, TreeID, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroTree, LoroCounter, Value } from 'loro-crdt';
+import { PeerID, LoroDoc, Container, LoroTreeNode, TreeID, LoroEventBatch, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroTree, LoroCounter, Value, ContainerID, Diff } from 'loro-crdt';
 
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 /**
@@ -256,6 +256,8 @@ declare const INTERNAL_SYMBOL: unique symbol;
 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;
@@ -275,11 +277,19 @@ declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape>
     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 */
+    /** 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 */
@@ -302,6 +312,8 @@ declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape>
     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;
 }
@@ -480,6 +492,20 @@ declare class RecordRefInternals<NestedShape extends ContainerOrValueShape> exte
     set(key: string, value: any): void;
     /** Delete a key */
     delete(key: string): void;
+    /**
+     * Replace entire contents with new values.
+     * Keys not in `values` are removed.
+     */
+    replace(values: Record<string, any>): void;
+    /**
+     * Merge values into record.
+     * Existing keys not in `values` are kept.
+     */
+    merge(values: Record<string, any>): void;
+    /**
+     * Remove all entries from the record.
+     */
+    clear(): void;
     /** Absorb mutated plain values back into Loro containers */
     absorbPlainValues(): void;
     /** Create the loro namespace for record */
@@ -501,8 +527,59 @@ declare class RecordRef<NestedShape extends ContainerOrValueShape> extends Typed
     setContainer<C extends Container>(key: string, container: C): C;
     has(key: string): boolean;
     keys(): string[];
-    values(): any[];
+    /**
+     * Returns an array of all values in the record.
+     * For container-valued records, returns properly typed refs.
+     */
+    values(): InferMutableType<NestedShape>[];
+    /**
+     * Returns an array of [key, value] pairs.
+     * For container-valued records, values are properly typed refs.
+     */
+    entries(): [string, InferMutableType<NestedShape>][];
     get size(): number;
+    /**
+     * Replace entire contents with new values.
+     * Keys not in `values` are removed.
+     *
+     * @example
+     * ```typescript
+     * doc.change(draft => {
+     *   draft.players.replace({
+     *     alice: { score: 100 },
+     *     bob: { score: 50 }
+     *   })
+     * })
+     * ```
+     */
+    replace(values: Record<string, Infer<NestedShape>>): void;
+    /**
+     * Merge values into record.
+     * Existing keys not in `values` are kept.
+     *
+     * @example
+     * ```typescript
+     * doc.change(draft => {
+     *   // Adds charlie, updates alice, keeps bob unchanged
+     *   draft.players.merge({
+     *     alice: { score: 150 },
+     *     charlie: { score: 25 }
+     *   })
+     * })
+     * ```
+     */
+    merge(values: Record<string, Infer<NestedShape>>): void;
+    /**
+     * Remove all entries from the record.
+     *
+     * @example
+     * ```typescript
+     * doc.change(draft => {
+     *   draft.players.clear()
+     * })
+     * ```
+     */
+    clear(): void;
     toJSON(): Record<string, Infer<NestedShape>>;
 }
 
@@ -667,6 +744,8 @@ declare class TreeNodeRefInternals<DataShape extends StructContainerShape> imple
     getOrCreateDataRef(): StructRef<DataShape["shapes"]>;
     /** Absorb mutated plain values back into Loro containers */
     absorbPlainValues(): void;
+    /** Force materialization of the container and its nested containers */
+    materialize(): void;
     /** Get the loro namespace (cached) */
     getLoroNamespace(): LoroTreeNodeRef;
     /** Create the loro namespace for tree node */
@@ -930,7 +1009,7 @@ 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;
 }
 /**
  * loro() return type for ListRef and MovableListRef.
@@ -1159,10 +1238,6 @@ interface MovableListContainerShape<NestedShape extends ContainerOrValueShape =
     readonly _type: "movableList";
     readonly shape: NestedShape;
 }
-/**
- * @deprecated Use StructContainerShape instead. MapContainerShape is an alias for backward compatibility.
- */
-type MapContainerShape<NestedShapes extends Record<string, ContainerOrValueShape> = Record<string, ContainerOrValueShape>> = StructContainerShape<NestedShapes>;
 /**
  * Container shape for objects with fixed keys (structs).
  * This is the preferred way to define fixed-key objects.
@@ -1243,10 +1318,6 @@ interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array, Uint8Array>
     readonly _type: "value";
     readonly valueType: "uint8array";
 }
-/**
- * @deprecated Use StructValueShape instead. ObjectValueShape is an alias for backward compatibility.
- */
-type ObjectValueShape<T extends Record<string, ValueShape> = Record<string, ValueShape>> = StructValueShape<T>;
 /**
  * Value shape for objects with fixed keys (structs).
  * This is the preferred way to define fixed-key plain value objects.
@@ -1600,6 +1671,39 @@ declare function getLoroContainer<NestedShapes extends Record<string, ContainerO
 declare function getLoroContainer<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>): LoroTree;
 declare function getLoroContainer<DataShape extends StructContainerShape>(ref: TreeRefInterface<DataShape>): LoroTree;
 declare function getLoroContainer<Shape extends ContainerShape>(ref: TypedRef<Shape>): ShapeToContainer<Shape>;
+/**
+ * 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 });
+ * ```
+ */
+declare function fork<Shape extends DocShape>(doc: TypedDoc<Shape>, options?: {
+    preservePeerId?: boolean;
+}): TypedDoc<Shape>;
 /**
  * Creates a new TypedDoc at a specified version (frontiers).
  * The forked doc will only contain history before the specified frontiers.
@@ -1627,6 +1731,52 @@ declare function getLoroContainer<Shape extends ContainerShape>(ref: TypedRef<Sh
  * ```
  */
 declare function forkAt<Shape extends DocShape>(doc: TypedDoc<Shape>, frontiers: Frontiers): TypedDoc<Shape>;
+/**
+ * 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);
+ * ```
+ */
+declare function shallowForkAt<Shape extends DocShape>(doc: TypedDoc<Shape>, frontiers: Frontiers, options?: {
+    preservePeerId?: boolean;
+}): TypedDoc<Shape>;
 
 /**
  * Overlays CRDT state with placeholder defaults
@@ -1763,10 +1913,21 @@ declare function evaluatePathOnValue(value: unknown, segments: PathSegment[]): u
  */
 declare function createPlaceholderProxy<T extends object>(target: T): T;
 
+/**
+ * Replay a diff as local operations on a document.
+ *
+ * Unlike doc.import() which creates import events, this creates LOCAL events
+ * that are captured by subscribeLocalUpdates() and UndoManager.
+ *
+ * @param doc - The target document to apply changes to
+ * @param diff - The diff from doc.diff(from, to, false)
+ */
+declare function replayDiff(doc: LoroDoc, diff: [ContainerID, Diff][]): void;
+
 /**
  * Validates placeholder against schema structure without using Zod
  * Combines the functionality of createPlaceholderValidator and createValueValidator
  */
 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 MapContainerShape, type MovableListContainerShape, MovableListRef, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, RecordRef, type RecordValueShape, type ContainerType as RootContainerType, Shape, 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, forkAt, getLoroContainer, getLoroDoc, hasWildcard, loro, mergeValue, overlayPlaceholder, validatePlaceholder };
+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 };