loro-crdt 1.4.5 → 1.5.0

package/base64/loro_wasm.d.ts

@@ -161,6 +161,126 @@ interface LoroDoc {
      */
     subscribeLocalUpdates(f: (bytes: Uint8Array) => void): () => void
 
+    /**
+     * Subscribe to the first commit from a peer. Operations performed on the `LoroDoc` within this callback
+     * will be merged into the current commit.
+     *
+     * This is useful for managing the relationship between `PeerID` and user information.
+     * For example, you could store user names in a `LoroMap` using `PeerID` as the key and the `UserID` as the value.
+     *
+     * @param f - A callback function that receives a peer id.
+     *
+     * @example
+     * ```ts
+     * const doc = new LoroDoc();
+     * doc.setPeerId(0);
+     * const p = [];
+     * doc.subscribeFirstCommitFromPeer((peer) => {
+     *   p.push(peer);
+     *   doc.getMap("map").set(e.peer, "user-" + e.peer);
+     * });
+     * doc.getList("list").insert(0, 100);
+     * doc.commit();
+     * doc.getList("list").insert(0, 200);
+     * doc.commit();
+     * doc.setPeerId(1);
+     * doc.getList("list").insert(0, 300);
+     * doc.commit();
+     * expect(p).toEqual(["0", "1"]);
+     * expect(doc.getMap("map").get("0")).toBe("user-0");
+     * ```
+     **/
+    subscribeFirstCommitFromPeer(f: (e: { peer: PeerID }) => void): () => void
+
+    /**
+     * Subscribe to the pre-commit event.
+     *
+     * The callback will be called when the changes are committed but not yet applied to the OpLog.
+     * You can modify the commit message and timestamp in the callback by `ChangeModifier`.
+     *
+     * @example
+     * ```ts
+     * const doc = new LoroDoc();
+     * doc.subscribePreCommit((e) => {
+     *   e.modifier.setMessage("test").setTimestamp(Date.now());
+     * });
+     * doc.getList("list").insert(0, 100);
+     * doc.commit();
+     * expect(doc.getChangeAt({ peer: "0", counter: 0 }).message).toBe("test");
+     * ```
+     * 
+     * ### Advanced Example: Creating a Merkle DAG
+     * 
+     * By combining `doc.subscribePreCommit` with `doc.exportJsonInIdSpan`, you can implement advanced features like representing Loro's editing history as a Merkle DAG:
+     * 
+     * ```ts
+     * const doc = new LoroDoc();
+     * doc.setPeerId(0);
+     * doc.subscribePreCommit((e) => {
+     *   const changes = doc.exportJsonInIdSpan(e.changeMeta)
+     *   expect(changes).toHaveLength(1);
+     *   const hash = crypto.createHash('sha256');
+     *   const change = {
+     *     ...changes[0],
+     *     deps: changes[0].deps.map(d => {
+     *       const depChange = doc.getChangeAt(idStrToId(d))
+     *       return depChange.message;
+     *     })
+     *   }
+     *   console.log(change); // The output is shown below
+     *   hash.update(JSON.stringify(change));
+     *   const sha256Hash = hash.digest('hex');
+     *   e.modifier.setMessage(sha256Hash);
+     * });
+     * 
+     * doc.getList("list").insert(0, 100);
+     * doc.commit();
+     * // Change 0
+     * // {
+     * //   id: '0@0',
+     * //   timestamp: 0,
+     * //   deps: [],
+     * //   lamport: 0,
+     * //   msg: undefined,
+     * //   ops: [
+     * //     {
+     * //       container: 'cid:root-list:List',
+     * //       content: { type: 'insert', pos: 0, value: [100] },
+     * //       counter: 0
+     * //     }
+     * //   ]
+     * // }
+     * 
+     * 
+     * doc.getList("list").insert(0, 200);
+     * doc.commit();
+     * // Change 1
+     * // {
+     * //   id: '1@0',
+     * //   timestamp: 0,
+     * //   deps: [
+     * //     '2af99cf93869173984bcf6b1ce5412610b0413d027a5511a8f720a02a4432853'
+     * //   ],
+     * //   lamport: 1,
+     * //   msg: undefined,
+     * //   ops: [
+     * //     {
+     * //       container: 'cid:root-list:List',
+     * //       content: { type: 'insert', pos: 0, value: [200] },
+     * //       counter: 1
+     * //     }
+     * //   ]
+     * // }
+     * 
+     * expect(doc.getChangeAt({ peer: "0", counter: 0 }).message).toBe("2af99cf93869173984bcf6b1ce5412610b0413d027a5511a8f720a02a4432853");
+     * expect(doc.getChangeAt({ peer: "0", counter: 1 }).message).toBe("aedbb442c554ecf59090e0e8339df1d8febf647f25cc37c67be0c6e27071d37f");
+     * ```
+     * 
+     * @param f - A callback function that receives a pre commit event.
+     * 
+     **/
+    subscribePreCommit(f: (e: { changeMeta: Change, origin: string, modifier: ChangeModifier }) => void): () => void
+
     /**
      * Convert the document to a JSON value with a custom replacer function.
      *
@@ -759,7 +879,6 @@ export type AwarenessListener = (
     origin: "local" | "timeout" | "remote" | string,
 ) => void;
 
-
 interface Listener {
     (event: LoroEventBatch): void;
 }
@@ -856,10 +975,15 @@ interface LoroDoc<T extends Record<string, Container> = Record<string, Container
      */
     exportJsonUpdates(start?: VersionVector, end?: VersionVector, withPeerCompression?: boolean): JsonSchema;
     /**
-     * Export the readable [`Change`]s in the given [`IdSpan`].
+     * Exports changes within the specified ID span to JSON schema format.
      *
-     * The peers are not compressed in the returned changes.
+     * The JSON schema format produced by this method is identical to the one generated by `export_json_updates`.
+     * It ensures deterministic output, making it ideal for hash calculations and integrity checks.
      *
+     * This method can also export pending changes from the uncommitted transaction that have not yet been applied to the OpLog.
+     * 
+     * This method will NOT trigger a new commit implicitly.
+     * 
      * @param idSpan - The id span to export.
      * @returns The changes in the given id span.
      */
@@ -1274,6 +1398,25 @@ interface AwarenessWasm<T extends Value = Value> {
     removeOutdated(): PeerID[];
 }
 
+type EphemeralListener = (event: EphemeralStoreEvent) => void;
+type EphemeralLocalListener = (bytes: Uint8Array) => void;
+
+interface EphemeralStoreWasm<T extends Value = Value> {
+    set(key: string, value: T): void;
+    get(key: string): T | undefined;
+    getAllStates(): Record<string, T>;
+    removeOutdated();
+    subscribeLocalUpdates(f: EphemeralLocalListener): () => void;
+    subscribe(f: EphemeralListener): () => void;
+}
+
+interface EphemeralStoreEvent {
+    by: "local" | "import" | "timeout";
+    added: string[];
+    updated: string[];
+    removed: string[];
+}
+
 
 
 /**
@@ -1349,6 +1492,21 @@ export class AwarenessWasm {
   peers(): (PeerID)[];
 }
 /**
+*/
+export class ChangeModifier {
+  free(): void;
+/**
+* @param {string} message
+* @returns {ChangeModifier}
+*/
+  setMessage(message: string): ChangeModifier;
+/**
+* @param {number} timestamp
+* @returns {ChangeModifier}
+*/
+  setTimestamp(timestamp: number): ChangeModifier;
+}
+/**
 * Cursor is a stable position representation in the doc.
 * When expressing the position of a cursor, using "index" can be unstable
 * because the cursor's position may change due to other deletions and insertions,
@@ -1418,6 +1576,63 @@ export class Cursor {
   kind(): any;
 }
 /**
+*/
+export class EphemeralStoreWasm {
+  free(): void;
+/**
+* Creates a new `EphemeralStore` instance.
+*
+* The `timeout` parameter specifies the duration in milliseconds.
+* A state of a peer is considered outdated, if the last update of the state of the peer
+* is older than the `timeout`.
+* @param {number} timeout
+*/
+  constructor(timeout: number);
+/**
+* @param {string} key
+* @param {any} value
+*/
+  set(key: string, value: any): void;
+/**
+* @param {string} key
+*/
+  delete(key: string): void;
+/**
+* @param {string} key
+* @returns {any}
+*/
+  get(key: string): any;
+/**
+* @returns {any}
+*/
+  getAllStates(): any;
+/**
+* @param {string} key
+* @returns {Uint8Array}
+*/
+  encode(key: string): Uint8Array;
+/**
+* @returns {Uint8Array}
+*/
+  encodeAll(): Uint8Array;
+/**
+* @param {Uint8Array} data
+*/
+  apply(data: Uint8Array): void;
+/**
+*/
+  removeOutdated(): void;
+/**
+* If the state is empty.
+* @returns {boolean}
+*/
+  isEmpty(): boolean;
+/**
+* @returns {(string)[]}
+*/
+  keys(): (string)[];
+}
+/**
 * The handler of a counter container.
 */
 export class LoroCounter {
@@ -2443,6 +2658,27 @@ export class LoroDoc {
 */
   applyDiff(diff: [ContainerID, Diff|JsonDiff][]): void;
 /**
+* Get the pending operations from the current transaction in JSON format
+*
+* This method returns a JSON representation of operations that have been applied
+* but not yet committed in the current transaction.
+*
+* It will use the same data format as `doc.exportJsonUpdates()`
+*
+* @example
+* ```ts
+* const doc = new LoroDoc();
+* const text = doc.getText("text");
+* text.insert(0, "Hello");
+* // Get pending ops before commit
+* const pendingOps = doc.getPendingOpsFromCurrentTxnAsJson();
+* doc.commit();
+* const emptyOps = doc.getPendingOpsFromCurrentTxnAsJson(); // this is undefined
+* ```
+* @returns {JsonSchema | undefined}
+*/
+  getUncommittedOpsAsJson(): JsonSchema | undefined;
+/**
 * Peer ID of the current writer.
 */
   readonly peerId: bigint;
@@ -3104,8 +3340,6 @@ export class LoroText {
 *
 * You can use it to create a highlight, make a range of text bold, or add a link to a range of text.
 *
-* Note: this is not suitable for unmergeable annotations like comments.
-*
 * @example
 * ```ts
 * import { LoroDoc } from "loro-crdt";