docs: v1.5.0 changelog

Author: zxch3n

pages/changelog/v1.5.0.mdx

@@ -0,0 +1,113 @@
+---
+version: "v1.5.0"
+title: "release v1.5.0"
+date: 2025/04/04
+---
+
+## New
+
+### 1. New Hooks
+
+`doc.subscribePreCommit(listener)` - Modify commit options before processing:
+
+This hook is particularly useful because doc.commit() is often invoked implicitly in various methods such as doc.import, doc.export, doc.checkout, and doc.exportJsonUpdates. Without this hook, users attempting to add custom messages to each commit might miss these implicit commit triggers.
+
+```ts
+const doc = new LoroDoc();
+doc.setPeerId(0);
+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:
+
+```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;
+    }),
+  };
+  hash.update(JSON.stringify(change));
+  const sha256Hash = hash.digest("hex");
+  e.modifier.setMessage(sha256Hash);
+});
+
+doc.getList("list").insert(0, 100);
+doc.commit();
+
+expect(doc.getChangeAt({ peer: "0", counter: 0 }).message).toBe(
+  "2af99cf93869173984bcf6b1ce5412610b0413d027a5511a8f720a02a4432853",
+);
+```
+
+`doc.subscribeFirstCommitFromPeer(listener)` - Triggers on first peer interaction:
+
+This hook provides an ideal point to associate peer information (such as author identity) with the document.
+
+```ts
+const doc = new LoroDoc();
+doc.setPeerId(0);
+doc.subscribeFirstCommitFromPeer((e) => {
+  doc.getMap("users").set(e.peer, "user-" + e.peer);
+});
+doc.getList("list").insert(0, 100);
+doc.commit();
+expect(doc.getMap("users").get("0")).toBe("user-0");
+```
+
+### 2. EphemeralStore
+
+EphemeralStore is a better alternative to Awareness for ephemeral states:
+
+Awareness is commonly used as a state-based CRDT for handling ephemeral states in real-time collaboration scenarios, such as cursor positions and application component highlights. As application complexity grows, Awareness may be set in multiple places, from cursor positions to user presence. However, the current version of Awareness doesn't support partial state updates, which means even minor mouse movements require synchronizing the entire Awareness state.
+
+```ts
+awareness.setLocalState({
+  ...awareness.getLocalState(),
+  x: 167,
+});
+```
+Since Awareness is primarily used in real-time collaboration scenarios where consistency requirements are relatively low, we can make it more flexible. We've introduced EphemeralStore as an alternative to Awareness. Think of it as a simple key-value store that uses timestamp-based last-write-wins for conflict resolution. You can choose the appropriate granularity for your key-value pairs based on your application's needs, and only modified key-value pairs are synchronized.
+
+
+```ts
+import {
+    EphemeralStore,
+    EphemeralListener,
+    EphemeralStoreEvent,
+} from "loro-crdt";
+
+const store = new EphemeralStore();
+// Set ephemeral data
+store.set("loro-prosemirror", {
+    anchor: ...,
+    focus: ...,
+    user: "Alice"
+});
+store.set("online-users", ["Alice", "Bob"]);
+
+expect(storeB.get("online-users")).toEqual(["Alice", "Bob"]);
+// Encode only the data for `loro-prosemirror`
+const encoded = store.encode("loro-prosemirror")
+
+store.subscribe((e: EphemeralStoreEvent) => {
+    // Listen to changes from `local`, `remote`, or `timeout` events
+});
+```
+
+## Fix
+
+- Fixed text styling at end "\n" character
+- Added JSON support for current transaction operations