loro-crdt 1.2.7 → 1.3.0

package/base64/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,
@@ -627,6 +648,8 @@ export interface LoroEventBatch {
      */
     currentTarget?: ContainerID;
     events: LoroEvent[];
+    from: Frontiers;
+    to: Frontiers;
 }
 
 /**
@@ -793,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>;
@@ -1469,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;
@@ -1653,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.
@@ -1689,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:
 *
@@ -2014,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");
@@ -2195,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;
@@ -2488,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");
@@ -3365,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