fix(core): prevent divergence with null map values (#18)

* fix(core): prevent divergence with null map values

- diff: treat null as a present value when detecting added keys; guard container insertions with actual value type; fall back to value-based inference when schema/
type mismatches occur and warn to avoid divergence.
- mirror: gate consistency check by checkStateConsistency (not debug); include raw doc.toJSON() in divergence log for easier debugging.
- state: add checkStateConsistency option to createStore and plumb through to Mirror.
- test(core): add null-in-map consistency tests and stabilize existing state tests with explicit commits.
- chore(deps): bump loro-crdt to ^1.7.0 across core/react/jotai and update lockfile.

* chore: fix lint issues

Author: zxch3n

IMPLEMENTATION_PLAN.md

@@ -36,4 +36,4 @@
         "@types/node": "^20.10.5",
         "typescript": "^5.3.3"
     }
-}
+}

packages/core/package.json

@@ -1011,15 +1011,31 @@ export function diffMap<S extends ObjectLike>(
         if (childSchema && childSchema.type === "ignore") {
             continue;
         }
-        const containerType =
+
+        // Determine container type with schema-first, but respect actual value.
+        // If schema suggests a container but the provided value doesn't match it,
+        // log a warning and fall back to inferring from the value to avoid divergence.
+        let containerType =
             childSchema?.getContainerType() ??
             tryInferContainerType(newItem, inferOptions);
+        if (
+            childSchema?.getContainerType() &&
+            containerType &&
+            !isValueOfContainerType(containerType, newItem)
+        ) {
+            console.warn(
+                `Schema mismatch on key "${key}": expected ${childSchema.getContainerType()} but got value ${JSON.stringify(
+                    newItem,
+                )}. Falling back to value-based inference to avoid divergence.`,
+            );
+            containerType = tryInferContainerType(newItem, inferOptions);
+        }
 
         // Added new key: detect by property presence, not truthiness.
         // Using `!oldItem` breaks for valid falsy values like "" or null.
         if (!(key in oldStateObj)) {
             // Inserted a new container
-            if (containerType) {
+            if (containerType && isValueOfContainerType(containerType, newItem)) {
                 changes.push({
                     container: containerId,
                     key,

packages/core/src/core/diff.ts

@@ -9,7 +9,6 @@ import {
     TreeID,
 } from "loro-crdt";
 import { isTreeID } from "./utils";
-import { CID_KEY } from "../constants";
 
 // Plain JSON-like value held in Mirror state (no `any`)
 type JSONPrimitive = string | number | boolean | null | undefined;

packages/core/src/core/loroEventApply.ts

@@ -302,6 +302,19 @@ export class Mirror<S extends SchemaType> {
 
         // Subscribe to the root doc for global updates
         this.subscriptions.push(this.doc.subscribe(this.handleLoroEvent));
+
+        // If the caller provided an initial state, apply it via setState so
+        // Loro is seeded consistently using the regular diff/apply pipeline.
+        if (this.options.initialState && Object.keys(this.options.initialState).length > 0) {
+            // Shallow apply the provided initial state
+            const prevCheck = this.options.checkStateConsistency;
+            this.options.checkStateConsistency = false;
+            try {
+                this.setState(this.options.initialState as Partial<InferType<S>>);
+            } finally {
+                this.options.checkStateConsistency = prevCheck;
+            }
+        }
     }
 
     /**
@@ -350,7 +363,7 @@ export class Mirror<S extends SchemaType> {
             }
         }
 
-        // Build initial state snapshot
+        // Build initial state snapshot from the current document
         const currentDocState = this.buildRootStateSnapshot();
         const newState = produce<InferType<S>>((draft) => {
             Object.assign(draft, currentDocState);
@@ -1805,12 +1818,10 @@ export class Mirror<S extends SchemaType> {
                 containerType === "List" ||
                 containerType === "MovableList"
             ) {
-                const l = container as unknown as LoroList | LoroMovableList;
-                if (l.length === 0) continue;
+                // Always include lists, even if empty, to match Mirror's state shape
                 root[key] = this.containerToStateJson(container);
             } else if (containerType === "Text") {
-                const t = container as LoroText;
-                if ((t.toJSON() as string) === "") continue;
+                // Always include text, even if empty, to match Mirror's state shape
                 root[key] = this.containerToStateJson(container);
             } else if (containerType === "Tree") {
                 const arr = this.containerToStateJson(container) as any[];

packages/core/src/core/mirror.ts

@@ -42,6 +42,8 @@ export interface CreateStoreOptions<S extends SchemaType> {
      * @default false
      */
     debug?: boolean;
+
+    checkStateConsistency?: boolean;
 }
 
 /**
@@ -89,6 +91,7 @@ export function createStore<S extends SchemaType>(
         validateUpdates: options.validateUpdates,
         throwOnValidationError: options.throwOnValidationError ?? true,
         debug: options.debug,
+        checkStateConsistency: options.checkStateConsistency,
     });
 
     return {
@@ -108,14 +111,12 @@ export function createStore<S extends SchemaType>(
 export function createReducer<
     S extends SchemaType,
     A extends Record<string, unknown>,
->(
-    actionHandlers: {
-        [K in keyof A]: (
-            state: import("immer").Draft<InferType<S>>,
-            payload: A[K],
-        ) => void;
-    },
-) {
+>(actionHandlers: {
+    [K in keyof A]: (
+        state: import("immer").Draft<InferType<S>>,
+        payload: A[K],
+    ) => void;
+}) {
     return (store: Store<S>) => {
         // Return a dispatch function that takes an action and payload
         return <K extends keyof A>(actionType: K, payload: A[K]) => {
@@ -125,11 +126,12 @@ export function createReducer<
             }
 
             store.setState((state) =>
-                produce<InferType<S>>(state, (
-                    draft: import("immer").Draft<InferType<S>>,
-                ) => {
-                    handler(draft, payload);
-                }),
+                produce<InferType<S>>(
+                    state,
+                    (draft: import("immer").Draft<InferType<S>>) => {
+                        handler(draft, payload);
+                    },
+                ),
             );
         };
     };

packages/core/src/core/state.ts

@@ -7,7 +7,7 @@ exports[`MovableList > movable list handles basic sets 1`] = `
       "deps": [],
       "id": "0@0",
       "lamport": 0,
-      "msg": undefined,
+      "msg": null,
       "ops": [
         {
           "container": "cid:root-list:MovableList",

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

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { LoroDoc, LoroMap, LoroList } from "loro-crdt";
+import { Mirror, schema, toNormalizedJson } from "../../src";
+
+describe("setState consistency with null fields in LoroMap", () => {
+    it("does not diverge when a loro-map field contains null and checkStateConsistency is enabled", async () => {
+        const withSchema = schema({
+            m: schema.LoroMap({
+                nested: schema.LoroMap({}),
+            }),
+        });
+
+        const doc = new LoroDoc();
+        const m = doc.getMap("m");
+        // Pre-populate a null field inside a loro map
+        m.set("nested", null);
+        doc.commit();
+        await Promise.resolve();
+
+        const mirror = new Mirror({
+            schema: withSchema,
+            doc,
+            // rely on doc state; just enable consistency check
+            checkStateConsistency: true,
+        });
+
+        // Sanity: mirror picks up the null from doc
+        expect(mirror.getState()).toEqual(toNormalizedJson(doc));
+        console.log(JSON.stringify(doc.toJSON(), null, 2));
+
+        // Update another field (unrelated) to force a diff run
+        expect(() => {
+            mirror.setState((s) => {
+                // write a new primitive field alongside nested
+                (s as any).m["other"] = 1;
+            });
+        }).not.toThrow();
+
+        // State remains in sync with doc
+        expect(mirror.getState()).toEqual(toNormalizedJson(doc));
+        // And the original null is preserved
+        expect((mirror.getState() as any).m.nested).toBeNull();
+    });
+
+    it("remains stable when the null lives deeper (list -> map) and we no-op setState", async () => {
+        const withSchema = schema({
+            root: schema.LoroMap({
+                list: schema.LoroList(
+                    schema.LoroMap({ child: schema.LoroMap({}) }),
+                ),
+            }),
+        });
+
+        const doc = new LoroDoc();
+        const root = doc.getMap("root");
+        // Attach a new list container under the root map, not the root-level list
+        // to avoid introducing an unexpected top-level key for validation.
+        const list = root.setContainer("list", new LoroList());
+        const item = list.pushContainer(new LoroMap());
+        // child is a loro-map by schema, but currently null in the doc JSON
+        item.set("child", null);
+
+        const mirror = new Mirror({
+            schema: withSchema,
+            doc,
+            checkStateConsistency: true,
+        });
+
+        // No-op update should not throw or change representation
+        expect(() => {
+            mirror.setState((s) => s);
+        }).not.toThrow();
+        expect(mirror.getState()).toEqual(toNormalizedJson(doc));
+        expect((mirror.getState() as any).root.list[0].child).toBeNull();
+    });
+});