feat!: make events synchronous by using [email protected] (#39)

* feat: use [email protected] to support synchronous api

* docs: simplify by making things sync

Author: zxch3n

README.md

@@ -59,8 +59,7 @@ const mirror = new Mirror({
 });
 
 // Update the state (immutable update)
-// Note: setState is async; await it in non-React code
-await mirror.setState((s) => ({
+mirror.setState((s) => ({
     ...s,
     todos: [
         ...s.todos,
@@ -72,7 +71,7 @@ await mirror.setState((s) => ({
 }));
 
 // Or: draft-style updates (mutate a draft)
-await mirror.setState((state) => {
+mirror.setState((state) => {
     state.todos.push({
         text: "Learn Loro Mirror",
         completed: false,
@@ -362,7 +361,7 @@ const mySchema = schema({ outline: schema.LoroTree(node) });
     - **`inferOptions`**: `{ defaultLoroText?: boolean; defaultMovableList?: boolean }` – influence container-type inference when inserting containers from plain values.
 
 - `getState(): State`: Returns the current in-memory state view.
-- `setState(updater, options?)`: Update state and sync to Loro. Returns a Promise.
+- `setState(updater, options?)`: Update state and sync to Loro. Runs synchronously.
     - **`updater`**: either a partial object to shallow-merge or a function that may mutate a draft (Immer-style) or return a new state object.
     - **`options`**: `{ tags?: string | string[] }` – arbitrary tags attached to this update; delivered to subscribers in metadata.
 - `subscribe(callback): () => void`: Subscribe to state changes. `callback` receives `(state, metadata)` where `metadata` includes:
@@ -412,8 +411,8 @@ const unsubscribe = mirror.subscribe((state, { direction, tags }) => {
     }
 });
 
-// Update with draft mutation + tags (await for deterministic ordering)
-await mirror.setState(
+// Update with draft mutation + tags
+mirror.setState(
     (s) => {
         s.todos.push({
             text: "Write docs",

api.md

@@ -36,8 +36,8 @@
 
  - Methods
    - `getState(): InferType<S>` — returns the current mirror state (immutable snapshot)
-   - `setState(updater, options?): Promise<void>`
-     - Promise-returning; await in non-React code for ordering/errors.
+  - `setState(updater, options?): void`
+    - Synchronous; the state, validation, and subscriber notifications all finish before `setState` returns.
      - `updater` supports both styles:
        - Mutate a draft: `(draft: InferType<S>) => void`
        - Return a new object: `(prev: Readonly<InferInputType<S>>) => InferInputType<S>`
@@ -75,7 +75,7 @@
 
  const mirror = new Mirror({ doc: new LoroDoc(), schema: appSchema });
 
- await mirror.setState((s) => {
+ mirror.setState((s) => {
      s.settings.title = "Docs";
      s.todos.push({ id: "1", text: "Ship" });
  });
@@ -219,7 +219,7 @@
 
  - Lists: always provide an `idSelector` if items have stable IDs — enables minimal add/update/move/delete instead of positional churn. Prefer `LoroMovableList` when reorder operations are common.
 - `$cid` for IDs: Every `LoroMap` includes a stable `$cid` you can use as a React `key` or as a `LoroList` item selector: `(item) => item.$cid`.
- - `setState` styles: choose your favorite — draft mutation or returning a new object. Both are supported and return a Promise. Await in non-React code when you need ordering or to catch validation errors.
+- `setState` styles: choose your favorite — draft mutation or returning a new object. Both run synchronously, so follow-up logic can safely read the updated state immediately.
  - Tagging updates: pass `{ tags: ["analytics", "user"] }` to `setState` and inspect `metadata.tags` in subscribers.
  - Trees: you can create/move/delete nodes in state (Mirror emits precise `tree-create/move/delete`). Node `data` is a normal Loro map — nested containers (text, list, map) update incrementally.
  - Initial state: providing `initialState` hints shapes and defaults in memory, but does not write into the LoroDoc until a real change occurs.

package.json

@@ -22,9 +22,6 @@
     "license": "MIT",
     "devDependencies": {
         "@types/node": "^18.0.0",
-        "@typescript-eslint/eslint-plugin": "^5.0.0",
-        "@typescript-eslint/parser": "^5.0.0",
-        "eslint": "^8.0.0",
         "oxlint": "^1.12.0",
         "oxlint-tsgolint": "^0.0.4",
         "typescript": "^4.7.0",

packages/core/README.md

@@ -32,17 +32,16 @@ const store = new Mirror({ doc, schema: appSchema });
 // Read state
 const state = store.getState();
 
-// Update (return a new state)
-// setState is async; await it in non-React code
-await store.setState({
+// Update (return a new state) — synchronous; the next line sees the new state.
+store.setState({
     ...state,
     settings: { ...state.settings, darkMode: true },
     todos: [...state.todos, { text: "Add milk" }],
     notes: "Hello, team!",
 });
 
 // Or mutate a draft (Immer-style)
-await store.setState((s) => {
+store.setState((s) => {
     s.todos.push({ text: "Ship" });
     s.settings.title = "Project";
 });
@@ -82,7 +81,7 @@ Trees are advanced usage; see Advanced: Trees at the end.
     - inferOptions: `{ defaultLoroText?: boolean; defaultMovableList?: boolean }` for container inference when schema is missing
 - Methods:
     - getState(): Current state
-    - setState(updater | partial, options?): Mutate a draft or return a new object. Returns a Promise and should be `await`ed in non-React code when you need the update applied before the next line.
+    - setState(updater | partial, options?): Mutate a draft or return a new object. Runs synchronously so downstream logic can immediately read the latest state.
         - options: `{ tags?: string | string[] }` (surfaces in subscriber metadata)
     - subscribe((state, metadata) => void): Subscribe; returns unsubscribe
         - metadata: `{ direction: FROM_LORO | TO_LORO; tags?: string[] }`
@@ -134,7 +133,7 @@ const node = schema.LoroMap({ name: schema.String({ required: true }) });
 const s = schema({ tree: schema.LoroTree(node) });
 const mirror = new Mirror({ doc: new LoroDoc(), schema: s });
 
-await mirror.setState((st) => {
+mirror.setState((st) => {
     st.tree.push({ data: { name: "root" }, children: [] });
 });
 ```

packages/core/package.json

@@ -24,7 +24,6 @@
         "build": "tsc -p .",
         "test": "vitest run",
         "test:watch": "vitest",
-        "lint": "eslint src --ext .ts,.tsx",
         "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
     },
     "keywords": [
@@ -41,7 +40,7 @@
         "immer": "^10.0.3"
     },
     "peerDependencies": {
-        "loro-crdt": "^1.7.1"
+        "loro-crdt": "^1.8.0"
     },
     "devDependencies": {
         "@types/node": "^20.10.5",

packages/core/src/core/loroEventApply.test.ts

@@ -3,18 +3,13 @@ import { describe, it, expect } from "vitest";
 import { LoroDoc, LoroText, LoroList, LoroMap, LoroCounter } from "loro-crdt";
 import { applyEventBatchToState } from "./loroEventApply";
 
-const commitAndAssert = async (
-    doc: LoroDoc,
-    getState: () => unknown,
-) => {
+const commitAndAssert = (doc: LoroDoc, getState: () => unknown) => {
     doc.commit();
-    // allow microtask queue to flush if needed
-    await Promise.resolve();
     expect(getState()).toEqual(doc.toJSON());
 };
 
 describe("applyEventBatchToState (inline)", () => {
-    it("syncs map primitives", async () => {
+    it("syncs map primitives", () => {
         const doc = new LoroDoc();
         let state: Record<string, unknown> = {};
         const unsub = doc.subscribe((b) => {
@@ -25,13 +20,13 @@ describe("applyEventBatchToState (inline)", () => {
 
         const m = doc.getMap("m");
         m.set("a", 1);
-        await commitAndAssert(doc, () => state);
+        commitAndAssert(doc, () => state);
 
         m.set("b", 2);
-        await commitAndAssert(doc, () => state);
+        commitAndAssert(doc, () => state);
 
         m.delete("a");
-        await commitAndAssert(doc, () => state);
+        commitAndAssert(doc, () => state);
 
         unsub();
     });
@@ -600,7 +595,9 @@ describe("applyEventBatchToState (inline)", () => {
         };
 
         const textOp = () => {
-            const t = chance(0.5) ? texts[rand(texts.length)] : nestedTexts[rand(nestedTexts.length)] || texts[0];
+            const t = chance(0.5)
+                ? texts[rand(texts.length)]
+                : nestedTexts[rand(nestedTexts.length)] || texts[0];
             if (t.isDeleted()) {
                 return;
             }
@@ -715,7 +712,7 @@ function normalize(i: Record<string, unknown>): Record<string, unknown> {
             }
         } else if (typeof v === "number") {
             if (v === 0) {
-                delete s[k]
+                delete s[k];
             }
         } else if (typeof v === "string") {
             if (v === "") {

packages/core/src/core/mirror.ts

@@ -1689,45 +1689,41 @@ export class Mirror<S extends SchemaType> {
     /**
      * Update state and propagate changes to Loro.
      *
-     * NOTE: You should await this method
-     *
      * - If `updater` is an object, it will shallow-merge into the current state.
      * - If `updater` is a function, it may EITHER:
      *   - mutate a draft (Immer-style), OR
      *   - return a brand new immutable state object.
      *
      * This supports both immutable and mutative update styles without surprises.
      */
-    async setState(
+    setState(
         updater: (state: Readonly<InferInputType<S>>) => InferInputType<S>,
         options?: SetStateOptions,
-    ): Promise<void>;
-    async setState(
+    ): void;
+    setState(
         updater: (state: InferType<S>) => void,
         options?: SetStateOptions,
-    ): Promise<void>;
-    async setState(
+    ): void;
+    setState(
         updater: Partial<InferInputType<S>>,
         options?: SetStateOptions,
-    ): Promise<void>;
-    async setState(
+    ): void;
+    setState(
         updater:
             | ((state: InferType<S>) => InferType<S> | InferInputType<S> | void)
             | ((state: Readonly<InferInputType<S>>) => InferInputType<S>)
             | Partial<InferInputType<S>>,
         options?: SetStateOptions,
-    ): Promise<void> {
+    ): void {
         if (this.syncing) return; // Prevent recursive updates
-        // Wait for the existing Loro event to be handled
-        await Promise.resolve();
         // Calculate new state; support mutative or return-based updater via Immer
         const newState =
             typeof updater === "function"
                 ? produce<InferType<S>>(this.state, (draft) => {
                       const res = (
-                          updater as (state: InferType<S>) =>
-                              | InferType<S>
-                              | void
+                          updater as (
+                              state: InferType<S>,
+                          ) => InferType<S> | void
                       )(draft as InferType<S>);
                       if (res && res !== (draft as unknown)) {
                           // Return a replacement so Immer finalizes it
@@ -1741,7 +1737,7 @@ export class Mirror<S extends SchemaType> {
                   ) as InferType<S>);
 
         // Validate state if needed
-        // TODO: REVIEW We don't need to validate the state that are already reviewed
+        // TODO: We don't need to validate the state that are already reviewed
         if (this.options.validateUpdates) {
             const validation =
                 this.schema && validateSchema(this.schema, newState);

packages/core/tests/cid.test.ts

@@ -266,17 +266,17 @@ describe("$cid: state injection and write ignoring (always-on for LoroMap)", ()
         expect(after).toBe(before);
     });
 
-    it("TO_LORO + consistency check: changing $cid throws divergence error", async () => {
+    it("TO_LORO + consistency check: changing $cid throws divergence error", () => {
         const doc = new LoroDoc();
         const s = schema({ m: schema.LoroMap({ label: schema.String() }) });
         const m = new Mirror({ doc, schema: s, checkStateConsistency: true });
 
-        await expect(
+        expect(() => {
             m.setState((draft: any) => {
                 draft.m.label = "ok";
                 draft.m[CID_KEY] = "tamper"; // should be ignored to Loro and trigger consistency error
-            }),
-        ).rejects.toThrow();
+            });
+        }).toThrow();
     });
 
     it("list items: $cid values exist and are unique per item", async () => {

packages/core/tests/mirror-movable-list.test.ts

@@ -13,7 +13,7 @@ const waitForSync = async () => {
 };
 
 describe("MovableList", () => {
-    async function initTestMirror() {
+    function initTestMirror() {
         const doc = new LoroDoc();
         doc.setPeerId(1);
         const schema_ = schema({
@@ -31,7 +31,7 @@ describe("MovableList", () => {
             schema: schema_,
         });
 
-        await mirror.setState({
+        mirror.setState({
             list: [
                 {
                     id: "1",
@@ -40,8 +40,6 @@ describe("MovableList", () => {
             ],
         });
 
-        await waitForSync();
-
         return { mirror, doc };
     }
 
@@ -536,16 +534,16 @@ describe("MovableList", () => {
         } as any);
     });
 
-    it("movable list throws on duplicate ids in new state", async () => {
-        const { mirror } = await initTestMirror();
-        await expect(
+    it("movable list throws on duplicate ids in new state", () => {
+        const { mirror } = initTestMirror();
+        expect(() => {
             mirror.setState({
                 list: [
                     { id: "X", text: "1" },
                     { id: "X", text: "2" },
                 ],
-            }),
-        ).rejects.toThrow();
+            });
+        }).toThrow();
     });
 
     it("movable list fuzz: large shuffles preserve container ids and text", async () => {

packages/core/tests/mirror-tree.test.ts

@@ -974,27 +974,27 @@ describe("LoroTree integration", () => {
         // sanity: ensure format looks like `${number}@${peer}`
         expect(nodeIds.every((id: string) => /@/.test(id))).toBe(true);
     });
-    it("TO_LORO: invalid tree value (non-array) throws validation error", async () => {
+    it("TO_LORO: invalid tree value (non-array) throws validation error", () => {
         const doc = new LoroDoc();
         const s = schema({
             tree: schema.LoroTree(schema.LoroMap({ title: schema.String() })),
         });
         const m = new Mirror({ doc, schema: s });
 
-        await expect(
+        expect(() => {
             m.setState({
                 tree: { id: "", data: { title: "X" } },
-            } as any),
-        ).rejects.toThrow();
+            } as any);
+        }).toThrow();
     });
-    it("TO_LORO: invalid node shape (children not array) throws", async () => {
+    it("TO_LORO: invalid node shape (children not array) throws", () => {
         const doc = new LoroDoc();
         const s = schema({
             tree: schema.LoroTree(schema.LoroMap({ title: schema.String() })),
         });
         const m = new Mirror({ doc, schema: s });
 
-        await expect(
+        expect(() => {
             m.setState({
                 tree: [
                     {
@@ -1003,8 +1003,8 @@ describe("LoroTree integration", () => {
                         children: "oops",
                     },
                 ],
-            } as any),
-        ).rejects.toThrow();
+            } as any);
+        }).toThrow();
     });
 
     // Nested tree container inside a map