loro-crdt 1.2.0 → 1.2.2

package/nodejs/loro_wasm.d.ts

@@ -155,6 +155,36 @@ interface LoroDoc {
      * ```
      */
     subscribeLocalUpdates(f: (bytes: Uint8Array) => void): () => void
+    /**
+     * Convert the document to a JSON value with a custom replacer function.
+     * 
+     * This method works similarly to `JSON.stringify`'s replacer parameter.
+     * The replacer function is called for each value in the document and can transform
+     * how values are serialized to JSON.
+     * 
+     * @param replacer - A function that takes a key and value, and returns how that value
+     *                  should be serialized. Similar to JSON.stringify's replacer. 
+     *                  If return undefined, the value will be skipped.
+     * @returns The JSON representation of the document after applying the replacer function.
+     * 
+     * @example
+     * ```ts
+     * const doc = new LoroDoc();
+     * const text = doc.getText("text");
+     * text.insert(0, "Hello");
+     * text.mark(0, 2, {bold: true});
+     * 
+     * // Use delta to represent text
+     * const json = doc.toJsonWithReplacer((key, value) => {
+     *   if (value instanceof LoroText) {
+     *     return value.toDelta();
+     *   } 
+     * 
+     *   return value;
+     * });
+     * ```
+     */
+    toJsonWithReplacer(replacer: (key: string | index, value: Value | Container) => Value | Container | undefined): Value;
 }
 
 /**
@@ -231,7 +261,8 @@ export type Value =
   | null
   | { [key: string]: Value }
   | Uint8Array
-  | Value[];
+  | Value[]
+  | undefined;
 
 export type UndoConfig = {
     mergeInterval?: number,
@@ -343,6 +374,15 @@ interface LoroList {
     getCursor(pos: number, side?: Side): Cursor | undefined;
 }
 
+export type TreeNodeShallowValue = {
+    id: TreeID,
+    parent: TreeID | undefined,
+    index: number,
+    fractionalIndex: string,
+    meta: ContainerID,
+    children: TreeNodeShallowValue[],
+}
+
 export type TreeNodeValue = {
     id: TreeID,
     parent: TreeID | undefined,
@@ -1320,6 +1360,11 @@ export class LoroCounter {
   getAttached(): LoroTree | undefined;
 /**
 * Get the value of the counter.
+* @returns {number}
+*/
+  getShallowValue(): number;
+/**
+* Get the value of the counter.
 */
   readonly value: number;
 }
@@ -1863,7 +1908,30 @@ export class LoroDoc {
 */
   import(update_or_snapshot: Uint8Array): ImportStatus;
 /**
-* Import a batch of updates.
+* Import a batch of updates and snapshots.
+*
+* It's more efficient than importing updates one by one.
+*
+* @deprecated Use `importBatch` instead.
+*
+* @example
+* ```ts
+* import { LoroDoc } from "loro-crdt";
+*
+* const doc = new LoroDoc();
+* const text = doc.getText("text");
+* text.insert(0, "Hello");
+* const updates = doc.export({ mode: "update" });
+* const snapshot = doc.export({ mode: "snapshot" });
+* const doc2 = new LoroDoc();
+* doc2.importBatch([snapshot, updates]);
+* ```
+* @param {Uint8Array[]} data
+* @returns {ImportStatus}
+*/
+  importUpdateBatch(data: Uint8Array[]): ImportStatus;
+/**
+* Import a batch of updates or snapshots.
 *
 * It's more efficient than importing updates one by one.
 *
@@ -1877,15 +1945,18 @@ export class LoroDoc {
 * const updates = doc.export({ mode: "update" });
 * const snapshot = doc.export({ mode: "snapshot" });
 * const doc2 = new LoroDoc();
-* doc2.importUpdateBatch([snapshot, updates]);
+* doc2.importBatch([snapshot, updates]);
 * ```
-* @param {Array<any>} data
+* @param {Uint8Array[]} data
 * @returns {ImportStatus}
 */
-  importUpdateBatch(data: Array<any>): ImportStatus;
+  importBatch(data: Uint8Array[]): ImportStatus;
 /**
 * Get the shallow json format of the document state.
 *
+* Unlike `toJSON()` which recursively resolves all containers to their values,
+* `getShallowValue()` returns container IDs as strings for any nested containers.
+*
 * @example
 * ```ts
 * import { LoroDoc } from "loro-crdt";
@@ -1895,20 +1966,28 @@ export class LoroDoc {
 * const tree = doc.getTree("tree");
 * const map = doc.getMap("map");
 * const shallowValue = doc.getShallowValue();
-* /*
-* {"list": ..., "tree": ..., "map": ...}
-*  *\/
 * console.log(shallowValue);
+* // {
+* //   list: 'cid:root-list:List',
+* //   tree: 'cid:root-tree:Tree',
+* //   map: 'cid:root-map:Map'
+* // }
+*
+* // It points to the same container as `list`
+* const listB = doc.getContainerById(shallowValue.list);
 * ```
-* @returns {any}
+* @returns {Record<string, ContainerID>}
 */
-  getShallowValue(): any;
+  getShallowValue(): Record<string, ContainerID>;
 /**
 * Get the json format of the entire document state.
 *
+* Unlike `getShallowValue()` which returns container IDs as strings,
+* `toJSON()` recursively resolves all containers to their actual values.
+*
 * @example
 * ```ts
-* import { LoroDoc, LoroText, LoroMap } from "loro-crdt";
+* import { LoroDoc, LoroText } from "loro-crdt";
 *
 * const doc = new LoroDoc();
 * const list = doc.getList("list");
@@ -1917,10 +1996,8 @@ export class LoroDoc {
 * text.insert(0, "Hello");
 * const map = list.insertContainer(1, new LoroMap());
 * map.set("foo", "bar");
-* /*
-* {"list": ["Hello", {"foo": "bar"}]}
-*  *\/
 * console.log(doc.toJSON());
+* // {"list": ["Hello", {"foo": "bar"}]}
 * ```
 * @returns {any}
 */
@@ -2181,6 +2258,26 @@ export class LoroList {
 */
   isDeleted(): boolean;
 /**
+* Get the shallow value of the list.
+*
+* Unlike `toJSON()` which recursively resolves all containers to their values,
+* `getShallowValue()` returns container IDs as strings for any nested containers.
+*
+* ```js
+* const doc = new LoroDoc();
+* doc.setPeerId("1");
+* const list = doc.getList("list");
+* list.insert(0, 1);
+* list.insert(1, "two");
+* const subList = list.insertContainer(2, new LoroList());
+* subList.insert(0, "sub");
+* list.getShallowValue(); // [1, "two", "cid:2@1:List"]
+* list.toJSON(); // [1, "two", ["sub"]]
+* ```
+* @returns {Value[]}
+*/
+  getShallowValue(): Value[];
+/**
 * Get the id of this container.
 */
   readonly id: ContainerID;
@@ -2342,6 +2439,34 @@ export class LoroMap {
 */
   isDeleted(): boolean;
 /**
+* Get the shallow value of the map.
+*
+* Unlike `toJSON()` which recursively resolves all containers to their values,
+* `getShallowValue()` returns container IDs as strings for any nested containers.
+*
+* @example
+* ```ts
+* import { LoroDoc } from "loro-crdt";
+*
+* const doc = new LoroDoc();
+* doc.setPeerId("1");
+* const map = doc.getMap("map");
+* map.set("key", "value");
+* const subText = map.setContainer("text", new LoroText());
+* subText.insert(0, "Hello");
+*
+* // Get shallow value - nested containers are represented by their IDs
+* console.log(map.getShallowValue());
+* // Output: { key: "value", text: "cid:1@1:Text" }
+*
+* // Get full value with nested containers resolved by `toJSON()`
+* console.log(map.toJSON());
+* // Output: { key: "value", text: "Hello" }
+* ```
+* @returns {Record<string, Value>}
+*/
+  getShallowValue(): Record<string, Value>;
+/**
 * The container id of this handler.
 */
   readonly id: ContainerID;
@@ -2485,6 +2610,26 @@ export class LoroMovableList {
 */
   isDeleted(): boolean;
 /**
+* Get the shallow value of the movable list.
+*
+* Unlike `toJSON()` which recursively resolves all containers to their values,
+* `getShallowValue()` returns container IDs as strings for any nested containers.
+*
+* ```js
+* const doc = new LoroDoc();
+* doc.setPeerId("1");
+* const list = doc.getMovableList("list");
+* list.insert(0, 1);
+* list.insert(1, "two");
+* const subList = list.insertContainer(2, new LoroList());
+* subList.insert(0, "sub");
+* list.getShallowValue(); // [1, "two", "cid:2@1:List"]
+* list.toJSON(); // [1, "two", ["sub"]]
+* ```
+* @returns {Value[]}
+*/
+  getShallowValue(): Value[];
+/**
 * Get the id of this container.
 */
   readonly id: ContainerID;
@@ -2542,9 +2687,9 @@ export class LoroText {
 * text.insert(0, "Hello");
 * text.iter((str) => (console.log(str), true));
 * ```
-* @param {Function} callback
+* @param {(string) => boolean} callback
 */
-  iter(callback: Function): void;
+  iter(callback: (string) => boolean): void;
 /**
 * Insert the string at the given index (utf-16 index).
 *
@@ -2800,6 +2945,11 @@ export class LoroText {
 */
   isDeleted(): boolean;
 /**
+* Get the shallow value of the text. This equals to `text.toString()`.
+* @returns {string}
+*/
+  getShallowValue(): string;
+/**
 * Get the container id of the text.
 */
   readonly id: ContainerID;
@@ -2972,6 +3122,48 @@ export class LoroTree {
 */
   isDeleted(): boolean;
 /**
+* Get the shallow value of the tree.
+*
+* Unlike `toJSON()` which recursively resolves nested containers to their values,
+* `getShallowValue()` returns container IDs as strings for any nested containers.
+*
+* @example
+* ```ts
+* const doc = new LoroDoc();
+* doc.setPeerId("1");
+* const tree = doc.getTree("tree");
+* const root = tree.createNode();
+* root.data.set("name", "root");
+* const text = root.data.setContainer("content", new LoroText());
+* text.insert(0, "Hello");
+*
+* console.log(tree.getShallowValue());
+* // [{
+* //   id: "0@1",
+* //   parent: null,
+* //   index: 0,
+* //   fractional_index: "80",
+* //   meta: "cid:0@1:Map",
+* //   children: []
+* // }]
+*
+* console.log(tree.toJSON());
+* // [{
+* //   id: "0@1",
+* //   parent: null,
+* //   index: 0,
+* //   fractional_index: "80",
+* //   meta: {
+* //     name: "root",
+* //     content: "Hello"
+* //   },
+* //   children: []
+* // }]
+* ```
+* @returns {TreeNodeShallowValue[]}
+*/
+  getShallowValue(): TreeNodeShallowValue[];
+/**
 * Get the id of the container.
 */
   readonly id: ContainerID;

package/nodejs/loro_wasm.js

@@ -858,6 +858,14 @@ class LoroCounter {
         const ret = wasm.lorocounter_getAttached(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+    * Get the value of the counter.
+    * @returns {number}
+    */
+    getShallowValue() {
+        const ret = wasm.lorocounter_getShallowValue(this.__wbg_ptr);
+        return ret;
+    }
 }
 module.exports.LoroCounter = LoroCounter;
 
@@ -1985,10 +1993,12 @@ class LoroDoc {
         }
     }
     /**
-    * Import a batch of updates.
+    * Import a batch of updates and snapshots.
     *
     * It's more efficient than importing updates one by one.
     *
+    * @deprecated Use `importBatch` instead.
+    *
     * @example
     * ```ts
     * import { LoroDoc } from "loro-crdt";
@@ -1999,9 +2009,9 @@ class LoroDoc {
     * const updates = doc.export({ mode: "update" });
     * const snapshot = doc.export({ mode: "snapshot" });
     * const doc2 = new LoroDoc();
-    * doc2.importUpdateBatch([snapshot, updates]);
+    * doc2.importBatch([snapshot, updates]);
     * ```
-    * @param {Array<any>} data
+    * @param {Uint8Array[]} data
     * @returns {ImportStatus}
     */
     importUpdateBatch(data) {
@@ -2020,8 +2030,46 @@ class LoroDoc {
         }
     }
     /**
+    * Import a batch of updates or snapshots.
+    *
+    * It's more efficient than importing updates one by one.
+    *
+    * @example
+    * ```ts
+    * import { LoroDoc } from "loro-crdt";
+    *
+    * const doc = new LoroDoc();
+    * const text = doc.getText("text");
+    * text.insert(0, "Hello");
+    * const updates = doc.export({ mode: "update" });
+    * const snapshot = doc.export({ mode: "snapshot" });
+    * const doc2 = new LoroDoc();
+    * doc2.importBatch([snapshot, updates]);
+    * ```
+    * @param {Uint8Array[]} data
+    * @returns {ImportStatus}
+    */
+    importBatch(data) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.lorodoc_importBatch(retptr, this.__wbg_ptr, addHeapObject(data));
+            var r0 = getInt32Memory0()[retptr / 4 + 0];
+            var r1 = getInt32Memory0()[retptr / 4 + 1];
+            var r2 = getInt32Memory0()[retptr / 4 + 2];
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
     * Get the shallow json format of the document state.
     *
+    * Unlike `toJSON()` which recursively resolves all containers to their values,
+    * `getShallowValue()` returns container IDs as strings for any nested containers.
+    *
     * @example
     * ```ts
     * import { LoroDoc } from "loro-crdt";
@@ -2031,12 +2079,17 @@ class LoroDoc {
     * const tree = doc.getTree("tree");
     * const map = doc.getMap("map");
     * const shallowValue = doc.getShallowValue();
-    * /*
-    * {"list": ..., "tree": ..., "map": ...}
-    *  *\/
     * console.log(shallowValue);
+    * // {
+    * //   list: 'cid:root-list:List',
+    * //   tree: 'cid:root-tree:Tree',
+    * //   map: 'cid:root-map:Map'
+    * // }
+    *
+    * // It points to the same container as `list`
+    * const listB = doc.getContainerById(shallowValue.list);
     * ```
-    * @returns {any}
+    * @returns {Record<string, ContainerID>}
     */
     getShallowValue() {
         try {
@@ -2056,9 +2109,12 @@ class LoroDoc {
     /**
     * Get the json format of the entire document state.
     *
+    * Unlike `getShallowValue()` which returns container IDs as strings,
+    * `toJSON()` recursively resolves all containers to their actual values.
+    *
     * @example
     * ```ts
-    * import { LoroDoc, LoroText, LoroMap } from "loro-crdt";
+    * import { LoroDoc, LoroText } from "loro-crdt";
     *
     * const doc = new LoroDoc();
     * const list = doc.getList("list");
@@ -2067,10 +2123,8 @@ class LoroDoc {
     * text.insert(0, "Hello");
     * const map = list.insertContainer(1, new LoroMap());
     * map.set("foo", "bar");
-    * /*
-    * {"list": ["Hello", {"foo": "bar"}]}
-    *  *\/
     * console.log(doc.toJSON());
+    * // {"list": ["Hello", {"foo": "bar"}]}
     * ```
     * @returns {any}
     */
@@ -2826,6 +2880,29 @@ class LoroList {
         const ret = wasm.lorolist_isDeleted(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+    * Get the shallow value of the list.
+    *
+    * Unlike `toJSON()` which recursively resolves all containers to their values,
+    * `getShallowValue()` returns container IDs as strings for any nested containers.
+    *
+    * ```js
+    * const doc = new LoroDoc();
+    * doc.setPeerId("1");
+    * const list = doc.getList("list");
+    * list.insert(0, 1);
+    * list.insert(1, "two");
+    * const subList = list.insertContainer(2, new LoroList());
+    * subList.insert(0, "sub");
+    * list.getShallowValue(); // [1, "two", "cid:2@1:List"]
+    * list.toJSON(); // [1, "two", ["sub"]]
+    * ```
+    * @returns {Value[]}
+    */
+    getShallowValue() {
+        const ret = wasm.lorolist_getShallowValue(this.__wbg_ptr);
+        return takeObject(ret);
+    }
 }
 module.exports.LoroList = LoroList;
 
@@ -3277,6 +3354,37 @@ class LoroMap {
         const ret = wasm.loromap_isDeleted(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+    * Get the shallow value of the map.
+    *
+    * Unlike `toJSON()` which recursively resolves all containers to their values,
+    * `getShallowValue()` returns container IDs as strings for any nested containers.
+    *
+    * @example
+    * ```ts
+    * import { LoroDoc } from "loro-crdt";
+    *
+    * const doc = new LoroDoc();
+    * doc.setPeerId("1");
+    * const map = doc.getMap("map");
+    * map.set("key", "value");
+    * const subText = map.setContainer("text", new LoroText());
+    * subText.insert(0, "Hello");
+    *
+    * // Get shallow value - nested containers are represented by their IDs
+    * console.log(map.getShallowValue());
+    * // Output: { key: "value", text: "cid:1@1:Text" }
+    *
+    * // Get full value with nested containers resolved by `toJSON()`
+    * console.log(map.toJSON());
+    * // Output: { key: "value", text: "Hello" }
+    * ```
+    * @returns {Record<string, Value>}
+    */
+    getShallowValue() {
+        const ret = wasm.loromap_getShallowValue(this.__wbg_ptr);
+        return takeObject(ret);
+    }
 }
 module.exports.LoroMap = LoroMap;
 
@@ -3785,6 +3893,29 @@ class LoroMovableList {
         const ret = wasm.loromovablelist_isDeleted(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+    * Get the shallow value of the movable list.
+    *
+    * Unlike `toJSON()` which recursively resolves all containers to their values,
+    * `getShallowValue()` returns container IDs as strings for any nested containers.
+    *
+    * ```js
+    * const doc = new LoroDoc();
+    * doc.setPeerId("1");
+    * const list = doc.getMovableList("list");
+    * list.insert(0, 1);
+    * list.insert(1, "two");
+    * const subList = list.insertContainer(2, new LoroList());
+    * subList.insert(0, "sub");
+    * list.getShallowValue(); // [1, "two", "cid:2@1:List"]
+    * list.toJSON(); // [1, "two", ["sub"]]
+    * ```
+    * @returns {Value[]}
+    */
+    getShallowValue() {
+        const ret = wasm.loromovablelist_getShallowValue(this.__wbg_ptr);
+        return takeObject(ret);
+    }
 }
 module.exports.LoroMovableList = LoroMovableList;
 
@@ -3854,13 +3985,19 @@ class LoroText {
     * text.insert(0, "Hello");
     * text.iter((str) => (console.log(str), true));
     * ```
-    * @param {Function} callback
+    * @param {(string) => boolean} callback
     */
     iter(callback) {
         try {
-            wasm.lorotext_iter(this.__wbg_ptr, addBorrowedObject(callback));
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.lorotext_iter(retptr, this.__wbg_ptr, addHeapObject(callback));
+            var r0 = getInt32Memory0()[retptr / 4 + 0];
+            var r1 = getInt32Memory0()[retptr / 4 + 1];
+            if (r1) {
+                throw takeObject(r0);
+            }
         } finally {
-            heap[stack_pointer++] = undefined;
+            wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
     /**
@@ -4435,6 +4572,26 @@ class LoroText {
         const ret = wasm.lorotext_isDeleted(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+    * Get the shallow value of the text. This equals to `text.toString()`.
+    * @returns {string}
+    */
+    getShallowValue() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.lorotext_getShallowValue(retptr, this.__wbg_ptr);
+            var r0 = getInt32Memory0()[retptr / 4 + 0];
+            var r1 = getInt32Memory0()[retptr / 4 + 1];
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export_5(deferred1_0, deferred1_1, 1);
+        }
+    }
 }
 module.exports.LoroText = LoroText;
 
@@ -4883,6 +5040,51 @@ class LoroTree {
         const ret = wasm.lorotree_isDeleted(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+    * Get the shallow value of the tree.
+    *
+    * Unlike `toJSON()` which recursively resolves nested containers to their values,
+    * `getShallowValue()` returns container IDs as strings for any nested containers.
+    *
+    * @example
+    * ```ts
+    * const doc = new LoroDoc();
+    * doc.setPeerId("1");
+    * const tree = doc.getTree("tree");
+    * const root = tree.createNode();
+    * root.data.set("name", "root");
+    * const text = root.data.setContainer("content", new LoroText());
+    * text.insert(0, "Hello");
+    *
+    * console.log(tree.getShallowValue());
+    * // [{
+    * //   id: "0@1",
+    * //   parent: null,
+    * //   index: 0,
+    * //   fractional_index: "80",
+    * //   meta: "cid:0@1:Map",
+    * //   children: []
+    * // }]
+    *
+    * console.log(tree.toJSON());
+    * // [{
+    * //   id: "0@1",
+    * //   parent: null,
+    * //   index: 0,
+    * //   fractional_index: "80",
+    * //   meta: {
+    * //     name: "root",
+    * //     content: "Hello"
+    * //   },
+    * //   children: []
+    * // }]
+    * ```
+    * @returns {TreeNodeShallowValue[]}
+    */
+    getShallowValue() {
+        const ret = wasm.lorotree_getShallowValue(this.__wbg_ptr);
+        return takeObject(ret);
+    }
 }
 module.exports.LoroTree = LoroTree;