@voidhash/mimic 1.0.0-beta.13 → 1.0.0-beta.15

package/src/primitives/shared.ts

@@ -171,6 +171,23 @@ export function runValidators<T>(value: T, validators: readonly { validate: (val
   }
 }
 
+/**
+ * Returns true if a primitive can represent null as a meaningful value.
+ * This is used to avoid pruning explicit null values for null-capable scalar unions.
+ */
+export function primitiveAllowsNullValue(primitive: AnyPrimitive): boolean {
+  if (primitive._tag === "LiteralPrimitive") {
+    return (primitive as { literal: unknown }).literal === null;
+  }
+
+  if (primitive._tag === "EitherPrimitive") {
+    const variants = (primitive as { _schema?: { variants?: readonly AnyPrimitive[] } })._schema?.variants;
+    return Array.isArray(variants) && variants.some((variant) => primitiveAllowsNullValue(variant));
+  }
+
+  return false;
+}
+
 /**
  * Checks if an operation is compatible with the given operation definitions.
  * @param operation - The operation to check.
@@ -214,20 +231,50 @@ export function applyDefaults<T extends AnyPrimitive>(
     
     // Layer the provided values on top of initial state
     const result: Record<string, unknown> = { ...structInitialState, ...value };
+    const inputObject =
+      typeof value === "object" && value !== null
+        ? (value as Record<string, unknown>)
+        : undefined;
     
     for (const key in structPrimitive.fields) {
       const fieldPrimitive = structPrimitive.fields[key]!;
+      const hasExplicitKey = inputObject !== undefined && Object.prototype.hasOwnProperty.call(inputObject, key);
+      const explicitValue = hasExplicitKey ? inputObject[key] : undefined;
+      const fieldDefault = fieldPrimitive._internal.getInitialState();
+      const isRequiredWithoutDefault =
+        (fieldPrimitive as { _schema?: { required?: boolean } })._schema?.required === true &&
+        fieldDefault === undefined;
+
+      // Explicit undefined values always prune optional keys.
+      // Explicit null values prune optional keys unless null is a valid semantic value for this field.
+      // Required fields without defaults reject nullish values.
+      const shouldPruneExplicitNullish =
+        hasExplicitKey &&
+        (
+          explicitValue === undefined ||
+          (explicitValue === null && !primitiveAllowsNullValue(fieldPrimitive))
+        );
+      if (shouldPruneExplicitNullish) {
+        if (isRequiredWithoutDefault) {
+          throw new ValidationError(`Field "${key}" is required and cannot be null or undefined`);
+        }
+        delete result[key];
+        continue;
+      }
       
-      if (result[key] === undefined) {
+      if (!hasExplicitKey && result[key] === undefined) {
         // Field still not provided after merging - try individual field default
-        const fieldDefault = fieldPrimitive._internal.getInitialState();
         if (fieldDefault !== undefined) {
           result[key] = fieldDefault;
         }
-      } else if (typeof result[key] === "object" && result[key] !== null) {
+      } else if (
+        hasExplicitKey &&
+        typeof explicitValue === "object" &&
+        explicitValue !== null
+      ) {
         // Recursively apply defaults to nested structs and unions
         if (fieldPrimitive._tag === "StructPrimitive" || fieldPrimitive._tag === "UnionPrimitive") {
-          result[key] = applyDefaults(fieldPrimitive, result[key] as Partial<InferState<typeof fieldPrimitive>>);
+          result[key] = applyDefaults(fieldPrimitive, explicitValue as Partial<InferState<typeof fieldPrimitive>>);
         }
       }
     }
@@ -285,4 +332,3 @@ export function applyDefaults<T extends AnyPrimitive>(
   // For other primitives, return the value as-is
   return value as InferState<T>;
 }
-

package/tests/client/ClientDocument.test.ts

@@ -1878,5 +1878,104 @@ describe("ClientDocument Presence", () => {
 
       expect(transport.sentTransactions.length).toBe(0);
     });
+
+    it("should NEVER send transactions to server during draft.update() - explicit verification", async () => {
+      const initialState: TestState = { title: "Hello", count: 0, items: [] };
+      const client = ClientDocument.make({ schema: TestSchema, transport, initialState });
+      await client.connect();
+
+      // Track when transport.send is called
+      const sendCalls: Transaction.Transaction[] = [];
+      const originalSend = transport.send;
+      transport.send = (tx) => {
+        sendCalls.push(tx);
+        originalSend.call(transport, tx);
+      };
+
+      const draft = client.createDraft();
+
+      // Perform multiple updates
+      draft.update((root) => root.title.set("Update 1"));
+      expect(sendCalls.length).toBe(0);
+
+      draft.update((root) => root.count.set(10));
+      expect(sendCalls.length).toBe(0);
+
+      draft.update((root) => root.title.set("Update 2"));
+      expect(sendCalls.length).toBe(0);
+
+      draft.update((root) => {
+        root.title.set("Update 3");
+        root.count.set(20);
+      });
+      expect(sendCalls.length).toBe(0);
+
+      // Verify optimistic state is updated
+      expect(client.get()?.title).toBe("Update 3");
+      expect(client.get()?.count).toBe(20);
+
+      // Still no transactions sent
+      expect(sendCalls.length).toBe(0);
+      expect(transport.sentTransactions.length).toBe(0);
+
+      // Only after commit should transaction be sent
+      draft.commit();
+      expect(sendCalls.length).toBe(1);
+      expect(transport.sentTransactions.length).toBe(1);
+    });
+
+    it("should never call transport.send during draft lifecycle until commit", async () => {
+      const initialState: TestState = { title: "Hello", count: 0, items: [] };
+      const client = ClientDocument.make({ schema: TestSchema, transport, initialState });
+      await client.connect();
+
+      // Create a spy to track exact moments of transport.send calls
+      const sendTimestamps: { time: number; action: string }[] = [];
+      const originalSend = transport.send;
+      transport.send = (tx) => {
+        sendTimestamps.push({ time: Date.now(), action: "send" });
+        originalSend.call(transport, tx);
+      };
+
+      // Draft operations should NOT trigger send
+      const draft = client.createDraft();
+      expect(sendTimestamps.length).toBe(0);
+
+      draft.update((root) => root.title.set("Draft"));
+      expect(sendTimestamps.length).toBe(0);
+
+      // Regular transaction SHOULD trigger send
+      client.transaction((root) => root.count.set(5));
+      expect(sendTimestamps.length).toBe(1);
+
+      // More draft updates should NOT trigger send
+      draft.update((root) => root.title.set("Draft 2"));
+      expect(sendTimestamps.length).toBe(1);
+
+      // Commit SHOULD trigger send
+      draft.commit();
+      expect(sendTimestamps.length).toBe(2);
+    });
+
+    it("should not send transactions when draft is discarded", async () => {
+      const initialState: TestState = { title: "Hello", count: 0, items: [] };
+      const client = ClientDocument.make({ schema: TestSchema, transport, initialState });
+      await client.connect();
+
+      const draft = client.createDraft();
+      draft.update((root) => root.title.set("Will be discarded"));
+      draft.update((root) => root.count.set(999));
+
+      expect(transport.sentTransactions.length).toBe(0);
+
+      draft.discard();
+
+      // Still no transactions should be sent
+      expect(transport.sentTransactions.length).toBe(0);
+
+      // State should revert
+      expect(client.get()?.title).toBe("Hello");
+      expect(client.get()?.count).toBe(0);
+    });
   });
 });

package/tests/primitives/Struct.test.ts

@@ -4,6 +4,9 @@ import * as ProxyEnvironment from "../../src/ProxyEnvironment";
 import * as OperationPath from "../../src/OperationPath";
 import * as Operation from "../../src/Operation";
 
+const hasOwn = (value: unknown, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
 describe("StructPrimitive", () => {
   describe("proxy", () => {
     it("nested field access returns field primitive proxy", () => {
@@ -83,7 +86,8 @@ describe("StructPrimitive", () => {
 
       expect(operations).toHaveLength(1);
       expect(operations[0]!.kind).toBe("struct.set");
-      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30, email: undefined });
+      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30 });
+      expect(hasOwn(operations[0]!.payload, "email")).toBe(false);
     });
 
     it("set() only requires fields that are required and without defaults", () => {
@@ -103,7 +107,48 @@ describe("StructPrimitive", () => {
 
       expect(operations).toHaveLength(1);
       expect(operations[0]!.kind).toBe("struct.set");
-      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30, email: undefined });
+      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30 });
+      expect(hasOwn(operations[0]!.payload, "email")).toBe(false);
+    });
+
+    it("set() prunes optional keys explicitly set to undefined", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      proxy.set({ name: "Alice", email: undefined });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.set");
+      expect(operations[0]!.payload).toEqual({ name: "Alice" });
+      expect(hasOwn(operations[0]!.payload, "email")).toBe(false);
+    });
+
+    it("set() prunes optional keys explicitly set to null", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      (proxy as any).set({ name: "Alice", email: null });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.set");
+      expect(operations[0]!.payload).toEqual({ name: "Alice" });
+      expect(hasOwn(operations[0]!.payload, "email")).toBe(false);
     });
 
     it("multiple field sets generate separate operations", () => {
@@ -388,7 +433,7 @@ describe("StructPrimitive", () => {
       expect(operations.map((op) => op.payload)).toContain("Doe");
     });
 
-    it("update() skips undefined values", () => {
+    it("update() emits struct.unset for undefined optional values", () => {
       const operations: Operation.Operation<any, any, any>[] = [];
       const env = ProxyEnvironment.make((op) => {
         operations.push(op);
@@ -403,8 +448,100 @@ describe("StructPrimitive", () => {
 
       proxy.update({ name: "John", email: undefined });
 
+      expect(operations).toHaveLength(2);
+      const nameOp = operations.find((op) => op.path.toTokens().join("/") === "name");
+      const unsetOp = operations.find((op) => op.path.toTokens().join("/") === "email");
+      expect(nameOp!.kind).toBe("string.set");
+      expect(nameOp!.payload).toBe("John");
+      expect(unsetOp!.kind).toBe("struct.unset");
+    });
+
+    it("update() removes existing optional key for undefined value", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+      let state: Primitive.InferState<typeof structPrimitive> | undefined = {
+        name: "John",
+        email: "john@example.com",
+      };
+
+      const env = ProxyEnvironment.make({
+        onOperation: (op) => {
+          operations.push(op);
+          state = structPrimitive._internal.applyOperation(state, op);
+        },
+        getState: () => state,
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      proxy.update({ email: undefined });
+
       expect(operations).toHaveLength(1);
-      expect(operations[0]!.payload).toBe("John");
+      expect(operations[0]!.kind).toBe("struct.unset");
+      expect(state).toEqual({ name: "John" });
+      expect(hasOwn(state, "email")).toBe(false);
+    });
+
+    it("update() removes existing optional key for null value", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+      let state: Primitive.InferState<typeof structPrimitive> | undefined = {
+        name: "John",
+        email: "john@example.com",
+      };
+
+      const env = ProxyEnvironment.make({
+        onOperation: (op) => {
+          operations.push(op);
+          state = structPrimitive._internal.applyOperation(state, op);
+        },
+        getState: () => state,
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      (proxy as any).update({ email: null });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.unset");
+      expect(state).toEqual({ name: "John" });
+      expect(hasOwn(state, "email")).toBe(false);
+    });
+
+    it("update() throws for undefined on required fields without defaults", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      expect(() => proxy.update({ name: undefined as never })).toThrow(Primitive.ValidationError);
+      expect(operations).toHaveLength(0);
+    });
+
+    it("update() throws for null on required fields without defaults", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      expect(() => (proxy as any).update({ name: null })).toThrow(Primitive.ValidationError);
+      expect(operations).toHaveLength(0);
     });
 
     it("update() recursively updates nested structs", () => {

package/tests/primitives/Tree.test.ts

@@ -4,6 +4,9 @@ import * as ProxyEnvironment from "../../src/ProxyEnvironment";
 import * as OperationPath from "../../src/OperationPath";
 import * as Operation from "../../src/Operation";
 
+const hasOwn = (value: unknown, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
 describe("TreePrimitive", () => {
   // Define node types using the new TreeNode API
   const FileNode = Primitive.TreeNode("file", {
@@ -609,6 +612,108 @@ describe("TreePrimitive", () => {
       expect(operations[0]!.kind).toBe("number.set");
       expect(operations[0]!.path.toTokens()).toEqual(["file1", "size"]);
     });
+
+    it("update() removes optional node data key when value is undefined", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.node("file1")!.as(FileNode).update({ size: undefined });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.unset");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "size"]);
+
+      const file1 = proxy.get().find((n) => n.id === "file1")!;
+      expect(file1.data).toEqual({ name: "File1" });
+      expect(hasOwn(file1.data, "size")).toBe(false);
+    });
+
+    it("updateAt() removes optional node data key when value is null", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      (proxy as any).updateAt("file1", FileNode, { size: null });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.unset");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "size"]);
+
+      const file1 = proxy.get().find((n) => n.id === "file1")!;
+      expect(file1.data).toEqual({ name: "File1" });
+      expect(hasOwn(file1.data, "size")).toBe(false);
+    });
+
+    it("throws when required node data field is updated with undefined", () => {
+      const StrictFileNode = Primitive.TreeNode("strict-file", {
+        data: Primitive.Struct({
+          name: Primitive.String().required(),
+          note: Primitive.String(),
+        }),
+        children: [] as const,
+      });
+      const StrictFolderNode = Primitive.TreeNode("strict-folder", {
+        data: Primitive.Struct({ label: Primitive.String() }),
+        children: [StrictFileNode] as const,
+      });
+      const strictTree = Primitive.Tree({ root: StrictFolderNode });
+      const initialState: Primitive.TreeState<typeof StrictFolderNode> = [
+        { id: "root", type: "strict-folder", parentId: null, pos: "a0", data: { label: "Root" } },
+        { id: "file1", type: "strict-file", parentId: "root", pos: "a0", data: { name: "File1", note: "keep" } },
+      ];
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make({
+        onOperation: (op) => {
+          operations.push(op);
+        },
+        getState: () => initialState,
+      });
+      const proxy = strictTree._internal.createProxy(env, OperationPath.make(""));
+
+      expect(() => proxy.node("file1")!.as(StrictFileNode).update({ name: undefined as never })).toThrow(
+        Primitive.ValidationError
+      );
+      expect(operations).toHaveLength(0);
+    });
+
+    it("throws when required node data field is updated with null", () => {
+      const StrictFileNode = Primitive.TreeNode("strict-file", {
+        data: Primitive.Struct({
+          name: Primitive.String().required(),
+          note: Primitive.String(),
+        }),
+        children: [] as const,
+      });
+      const StrictFolderNode = Primitive.TreeNode("strict-folder", {
+        data: Primitive.Struct({ label: Primitive.String() }),
+        children: [StrictFileNode] as const,
+      });
+      const strictTree = Primitive.Tree({ root: StrictFolderNode });
+      const initialState: Primitive.TreeState<typeof StrictFolderNode> = [
+        { id: "root", type: "strict-folder", parentId: null, pos: "a0", data: { label: "Root" } },
+        { id: "file1", type: "strict-file", parentId: "root", pos: "a0", data: { name: "File1", note: "keep" } },
+      ];
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make({
+        onOperation: (op) => {
+          operations.push(op);
+        },
+        getState: () => initialState,
+      });
+      const proxy = strictTree._internal.createProxy(env, OperationPath.make(""));
+
+      expect(() => (proxy as any).updateAt("file1", StrictFileNode, { name: null })).toThrow(
+        Primitive.ValidationError
+      );
+      expect(operations).toHaveLength(0);
+    });
   });
 
   describe("proxy - insert with defaults", () => {
@@ -922,6 +1027,44 @@ describe("TreePrimitive - nested input for set() and default()", () => {
       const fileNode = payload.find(n => n.type === "file");
       expect((fileNode!.data as any).size).toBe(0); // Default value
     });
+
+    it("prunes optional keys explicitly set to undefined in nested input", () => {
+      const { env, operations } = createEnvWithState();
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.set({
+        type: "folder",
+        name: "Root",
+        children: [
+          { type: "file", name: "file.txt", size: undefined, children: [] },
+        ],
+      });
+
+      const payload = operations[0]!.payload as Primitive.TreeState<typeof FolderNode>;
+      const fileNode = payload.find(n => n.type === "file");
+      expect(fileNode).toBeDefined();
+      expect(fileNode!.data).toEqual({ name: "file.txt" });
+      expect(hasOwn(fileNode!.data, "size")).toBe(false);
+    });
+
+    it("prunes optional keys explicitly set to null in nested input", () => {
+      const { env, operations } = createEnvWithState();
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      (proxy as any).set({
+        type: "folder",
+        name: "Root",
+        children: [
+          { type: "file", name: "file.txt", size: null, children: [] },
+        ],
+      });
+
+      const payload = operations[0]!.payload as Primitive.TreeState<typeof FolderNode>;
+      const fileNode = payload.find(n => n.type === "file");
+      expect(fileNode).toBeDefined();
+      expect(fileNode!.data).toEqual({ name: "file.txt" });
+      expect(hasOwn(fileNode!.data, "size")).toBe(false);
+    });
   });
 
   describe("default() with nested input", () => {