loro-crdt 1.2.6 → 1.3.0

package/nodejs/loro_wasm.d.ts

@@ -172,7 +172,7 @@ interface LoroDoc {
      * const doc = new LoroDoc();
      * const text = doc.getText("text");
      * text.insert(0, "Hello");
-     * text.mark(0, 2, {bold: true});
+     * text.mark({ start: 0, end: 2 }, "bold", true);
      * 
      * // Use delta to represent text
      * const json = doc.toJsonWithReplacer((key, value) => {
@@ -264,6 +264,27 @@ export type Value =
   | Value[]
   | undefined;
 
+export type IdSpan = {
+    peer: PeerID,
+    counter: number,
+    length: number,
+}
+
+export type VersionVectorDiff = {
+    /**
+     * The spans that the `from` side needs to retreat to reach the `to` side
+     *
+     * These spans are included in the `from`, but not in the `to`
+     */
+    retreat: IdSpan[],
+    /**
+     * The spans that the `from` side needs to forward to reach the `to` side
+     *
+     * These spans are included in the `to`, but not in the `from`
+     */
+    forward: IdSpan[],
+}
+
 export type UndoConfig = {
     mergeInterval?: number,
     maxUndoSteps?: number,
@@ -397,11 +418,6 @@ export type TreeNodeJSON<T> = Omit<TreeNodeValue, 'meta' | 'children'> & {
     children: TreeNodeJSON<T>[],
 }
 
-interface LoroTree{
-    toArray(): TreeNodeValue[];
-    getNodes(options?: { withDeleted?: boolean } ): LoroTreeNode[];
-}
-
 interface LoroMovableList {
     /**
      * Get the cursor position at the given pos.
@@ -632,6 +648,8 @@ export interface LoroEventBatch {
      */
     currentTarget?: ContainerID;
     events: LoroEvent[];
+    from: Frontiers;
+    to: Frontiers;
 }
 
 /**
@@ -798,9 +816,19 @@ interface LoroDoc<T extends Record<string, Container> = Record<string, Container
      *
      * @param start - The start version vector.
      * @param end - The end version vector.
+     * @param withPeerCompression - Whether to compress the peer IDs in the updates. Defaults to true. If you want to process the operations in application code, set this to false.
      * @returns The updates in the given range.
      */
-    exportJsonUpdates(start?: VersionVector, end?: VersionVector): JsonSchema;
+    exportJsonUpdates(start?: VersionVector, end?: VersionVector, withPeerCompression?: boolean): JsonSchema;
+    /**
+     * Export the readable [`Change`]s in the given [`IdSpan`].
+     *
+     * The peers are not compressed in the returned changes.
+     *
+     * @param idSpan - The id span to export.
+     * @returns The changes in the given id span.
+     */
+    exportJsonInIdSpan(idSpan: IdSpan): JsonChange[];
 }
 interface LoroList<T = unknown> {
     new(): LoroList<T>;
@@ -1129,6 +1157,8 @@ interface LoroTree<T extends Record<string, unknown> = Record<string, unknown>>
      */
     getNodeByID(target: TreeID): LoroTreeNode<T>;
     subscribe(listener: Listener): Subscription;
+    toArray(): TreeNodeValue[];
+    getNodes(options?: { withDeleted?: boolean } ): LoroTreeNode<T>[];
 }
 interface LoroTreeNode<T extends Record<string, unknown> = Record<string, unknown>> {
     /**
@@ -1156,7 +1186,36 @@ interface LoroTreeNode<T extends Record<string, unknown> = Record<string, unknow
      * ```
      */
     createNode(index?: number): LoroTreeNode<T>;
+    /**
+     * Move this tree node to be a child of the parent.
+     * If the parent is undefined, this node will be a root node.
+     *
+     * If the index is not provided, the node will be appended to the end.
+     *
+     * It's not allowed that the target is an ancestor of the parent.
+     *
+     * @example
+     * ```ts
+     * const doc = new LoroDoc();
+     * const tree = doc.getTree("tree");
+     * const root = tree.createNode();
+     * const node = root.createNode();
+     * const node2 = node.createNode();
+     * node2.move(undefined, 0);
+     * // node2   root
+     * //          |
+     * //         node
+     *
+     * ```
+     */
     move(parent?: LoroTreeNode<T>, index?: number): void;
+    /**
+     * Get the parent node of this node.
+     *
+     * - The parent of the root node is `undefined`.
+     * - The object returned is a new js object each time because it need to cross
+     *   the WASM boundary.
+     */
     parent(): LoroTreeNode<T> | undefined;
     /**
      * Get the children of this node.
@@ -1443,9 +1502,12 @@ export class LoroDoc {
 */
   setRecordTimestamp(auto_record: boolean): void;
 /**
-* If two continuous local changes are within the interval, they will be merged into one change.
+* If two continuous local changes are within (<=) the interval(**in seconds**), they will be merged into one change.
+*
+* The default value is 1_000 seconds.
 *
-* The default value is 1_000_000, the default unit is seconds.
+* By default, we record timestamps in seconds for each change. So if the merge interval is 1, and changes A and B
+* have timestamps of 3 and 4 respectively, then they will be merged into one change
 * @param {number} interval
 */
   setChangeMergeInterval(interval: number): void;
@@ -1627,6 +1689,54 @@ export class LoroDoc {
 */
   travelChangeAncestors(ids: ({ peer: PeerID, counter: number })[], f: (change: Change) => boolean): void;
 /**
+* Find the op id spans that between the `from` version and the `to` version.
+*
+* You can combine it with `exportJsonInIdSpan` to get the changes between two versions.
+*
+* You can use it to travel all the changes from `from` to `to`. `from` and `to` are frontiers,
+* and they can be concurrent to each other. You can use it to find all the changes related to an event:
+*
+* @example
+* ```ts
+* import { LoroDoc } from "loro-crdt";
+*
+* const docA = new LoroDoc();
+* docA.setPeerId("1");
+* const docB = new LoroDoc();
+*
+* docA.getText("text").update("Hello");
+* docA.commit();
+* const snapshot = docA.export({ mode: "snapshot" });
+* let done = false;
+* docB.subscribe(e => {
+*   const spans = docB.findIdSpansBetween(e.from, e.to);
+*   const changes = docB.exportJsonInIdSpan(spans.forward[0]);
+*   console.log(changes);
+*   // [{
+*   //   id: "0@1",
+*   //   timestamp: expect.any(Number),
+*   //   deps: [],
+*   //   lamport: 0,
+*   //   msg: undefined,
+*   //   ops: [{
+*   //     container: "cid:root-text:Text",
+*   //     counter: 0,
+*   //     content: {
+*   //       type: "insert",
+*   //       pos: 0,
+*   //       text: "Hello"
+*   //     }
+*   //   }]
+*   // }]
+* });
+* docB.import(snapshot);
+* ```
+* @param {({ peer: PeerID, counter: number })[]} from
+* @param {({ peer: PeerID, counter: number })[]} to
+* @returns {VersionVectorDiff}
+*/
+  findIdSpansBetween(from: ({ peer: PeerID, counter: number })[], to: ({ peer: PeerID, counter: number })[]): VersionVectorDiff;
+/**
 * Checkout the `DocState` to a specific version.
 *
 * > The document becomes detached during a `checkout` operation.
@@ -1663,12 +1773,14 @@ export class LoroDoc {
 */
   setPeerId(peer_id: number | bigint | `${number}`): void;
 /**
-* Commit the cumulative auto committed transaction.
+* Commit the cumulative auto-committed transaction.
 *
 * You can specify the `origin`, `timestamp`, and `message` of the commit.
 *
 * - The `origin` is used to mark the event
 * - The `message` works like a git commit message, which will be recorded and synced to peers
+* - The `timestamp` is the number of seconds that have elapsed since 00:00:00 UTC on January 1, 1970.
+*   It defaults to `Date.now() / 1000` when timestamp recording is enabled
 *
 * The events will be emitted after a transaction is committed. A transaction is committed when:
 *
@@ -1988,7 +2100,7 @@ export class LoroDoc {
 *
 * @example
 * ```ts
-* import { LoroDoc, LoroText } from "loro-crdt";
+* import { LoroDoc, LoroText, LoroMap } from "loro-crdt";
 *
 * const doc = new LoroDoc();
 * const list = doc.getList("list");
@@ -2169,6 +2281,40 @@ export class LoroDoc {
 */
   getChangedContainersIn(id: { peer: PeerID, counter: number }, len: number): (ContainerID)[];
 /**
+* Revert the document to the given frontiers.
+*
+* The doc will not become detached when using this method. Instead, it will generate a series
+* of operations to revert the document to the given version.
+*
+* @example
+* ```ts
+* const doc = new LoroDoc();
+* doc.setPeerId("1");
+* const text = doc.getText("text");
+* text.insert(0, "Hello");
+* doc.commit();
+* doc.revertTo([{ peer: "1", counter: 1 }]);
+* expect(doc.getText("text").toString()).toBe("He");
+* ```
+* @param {({ peer: PeerID, counter: number })[]} frontiers
+*/
+  revertTo(frontiers: ({ peer: PeerID, counter: number })[]): void;
+/**
+* Apply a diff batch to the document
+* @param {Record<ContainerID, Diff>} diff
+*/
+  applyDiff(diff: Record<ContainerID, Diff>): void;
+/**
+* Calculate the differences between two frontiers
+*
+* The entries in the returned object are sorted by causal order: the creation of a child container will be
+* presented before its use.
+* @param {({ peer: PeerID, counter: number })[]} from
+* @param {({ peer: PeerID, counter: number })[]} to
+* @returns {Record<ContainerID, Diff>}
+*/
+  diff(from: ({ peer: PeerID, counter: number })[], to: ({ peer: PeerID, counter: number })[]): Record<ContainerID, Diff>;
+/**
 * Peer ID of the current writer.
 */
   readonly peerId: bigint;
@@ -2462,7 +2608,7 @@ export class LoroMap {
 *
 * @example
 * ```ts
-* import { LoroDoc } from "loro-crdt";
+* import { LoroDoc, LoroText } from "loro-crdt";
 *
 * const doc = new LoroDoc();
 * doc.setPeerId("1");
@@ -3194,31 +3340,6 @@ export class LoroTreeNode {
 */
   __getClassname(): string;
 /**
-* Move this tree node to be a child of the parent.
-* If the parent is undefined, this node will be a root node.
-*
-* If the index is not provided, the node will be appended to the end.
-*
-* It's not allowed that the target is an ancestor of the parent.
-*
-* @example
-* ```ts
-* const doc = new LoroDoc();
-* const tree = doc.getTree("tree");
-* const root = tree.createNode();
-* const node = root.createNode();
-* const node2 = node.createNode();
-* node2.move(undefined, 0);
-* // node2   root
-* //          |
-* //         node
-*
-* ```
-* @param {LoroTreeNode | undefined} parent
-* @param {number | undefined} [index]
-*/
-  move(parent: LoroTreeNode | undefined, index?: number): void;
-/**
 * Move the tree node to be after the target node.
 *
 * @example
@@ -3271,15 +3392,6 @@ export class LoroTreeNode {
 */
   fractionalIndex(): string | undefined;
 /**
-* Get the parent node of this node.
-*
-* - The parent of the root node is `undefined`.
-* - The object returned is a new js object each time because it need to cross
-*   the WASM boundary.
-* @returns {LoroTreeNode | undefined}
-*/
-  parent(): LoroTreeNode | undefined;
-/**
 * Check if the node is deleted.
 * @returns {boolean}
 */
@@ -3373,6 +3485,7 @@ export class UndoManager {
   setMaxUndoSteps(steps: number): void;
 /**
 * Set the merge interval (in ms).
+*
 * If the interval is set to 0, the undo steps will not be merged.
 * Otherwise, the undo steps will be merged if the interval between the two steps is less than the given interval.
 * @param {number} interval