@voidhash/mimic 1.0.0-beta.14 → 1.0.0-beta.16

package/src/client/ClientDocument.ts

@@ -558,6 +558,9 @@ export const make = <
       ops: tx.ops,
       pendingCount: _pending.length + 1,
       isConnected: transport.isConnected(),
+      activeDraftCount: _drafts.size,
+      activeDraftIds: Array.from(_drafts.keys()),
+      callStack: new Error().stack?.split("\n").slice(1, 6).join("\n"),
     });
 
     const pending: PendingTransaction = {
@@ -1002,6 +1005,9 @@ export const make = <
         isConnected: transport.isConnected(),
         isReady: _initState.type === "ready",
         pendingCount: _pending.length,
+        activeDraftCount: _drafts.size,
+        activeDraftIds: Array.from(_drafts.keys()),
+        callStack: new Error().stack?.split("\n").slice(1, 6).join("\n"),
       });
 
       // Allow transactions even when disconnected - they will be queued
@@ -1176,6 +1182,13 @@ export const make = <
         id: draftId,
 
         update: (fn: (root: Primitive.InferProxy<TSchema>) => void): void => {
+          debugLog("draft.update: starting", {
+            draftId,
+            consumed,
+            currentOpsCount: draftState.ops.size,
+            pendingCount: _pending.length,
+          });
+
           if (consumed) {
             throw new InvalidStateError("Draft has already been committed or discarded.");
           }
@@ -1213,7 +1226,12 @@ export const make = <
             }
           }
 
-          debugLog("draft.update", { draftId, newOpsCount: tx.ops.length, totalOps: draftState.ops.size });
+          debugLog("draft.update: complete", {
+            draftId,
+            newOpsCount: tx.ops.length,
+            totalOps: draftState.ops.size,
+            note: "Ops stored in draft - NOT sent to server",
+          });
 
           // Recompute optimistic state to reflect draft changes
           recomputeOptimisticState();
@@ -1221,6 +1239,12 @@ export const make = <
         },
 
         commit: (): void => {
+          debugLog("draft.commit: starting", {
+            draftId,
+            consumed,
+            opsCount: draftState.ops.size,
+          });
+
           if (consumed) {
             throw new InvalidStateError("Draft has already been committed or discarded.");
           }
@@ -1229,7 +1253,11 @@ export const make = <
           const ops = Array.from(draftState.ops.values());
           _drafts.delete(draftId);
 
-          debugLog("draft.commit", { draftId, opsCount: ops.length });
+          debugLog("draft.commit: submitting", {
+            draftId,
+            opsCount: ops.length,
+            note: ops.length > 0 ? "Will call submitTransaction" : "Empty draft - no transaction",
+          });
 
           if (ops.length > 0) {
             const tx = Transaction.make(ops);
@@ -1243,6 +1271,12 @@ export const make = <
         },
 
         discard: (): void => {
+          debugLog("draft.discard: starting", {
+            draftId,
+            consumed,
+            opsCount: draftState.ops.size,
+          });
+
           if (consumed) {
             throw new InvalidStateError("Draft has already been committed or discarded.");
           }
@@ -1250,7 +1284,10 @@ export const make = <
 
           _drafts.delete(draftId);
 
-          debugLog("draft.discard", { draftId });
+          debugLog("draft.discard: complete", {
+            draftId,
+            note: "Draft discarded - no transaction sent to server",
+          });
 
           recomputeOptimisticState();
           notifyDraftChange();

package/src/primitives/Struct.ts

@@ -6,7 +6,7 @@ import * as ProxyEnvironment from "../ProxyEnvironment";
 import * as Transform from "../Transform";
 import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator, InferState, InferProxy, InferSnapshot, NeedsValue, InferUpdateInput, InferSetInput } from "../Primitive";
 import { ValidationError } from "../Primitive";
-import { runValidators, applyDefaults } from "./shared";
+import { runValidators, applyDefaults, primitiveAllowsNullValue } from "./shared";
 
 // =============================================================================
 // Struct Set Input Types
@@ -89,6 +89,13 @@ export type MakeOptional<T extends AnyPrimitive> = T extends Primitive<infer S,
   ? Primitive<S, P, false, H, SI, UI>
   : T;
 
+/**
+ * Transforms a primitive type to make it optional and strip its default (TRequired = false, THasDefault = false).
+ */
+export type MakeOptionalNoDefault<T extends AnyPrimitive> = T extends Primitive<infer S, infer P, any, any, infer SI, infer UI>
+  ? Primitive<S, P, false, false, SI, UI>
+  : T;
+
 /**
  * Maps each field in a struct to its optional version.
  * All fields become optional (TRequired = false).
@@ -97,6 +104,14 @@ export type PartialFields<TFields extends Record<string, AnyPrimitive>> = {
   [K in keyof TFields]: MakeOptional<TFields[K]>;
 };
 
+/**
+ * Maps each field in a struct to its optional version with defaults stripped.
+ * All fields become optional (TRequired = false) and lose their defaults (THasDefault = false).
+ */
+export type PartialFieldsNoDefault<TFields extends Record<string, AnyPrimitive>> = {
+  [K in keyof TFields]: MakeOptionalNoDefault<TFields[K]>;
+};
+
 /**
  * Maps a schema definition to its proxy type.
  * Provides nested field access + get()/set()/toSnapshot() methods for the whole struct.
@@ -142,6 +157,13 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TRequ
       apply: (payload) => payload,
       deduplicable: true,
     }),
+    unset: OperationDefinition.make({
+      kind: "struct.unset" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+      deduplicable: true,
+    }),
   };
 
   constructor(schema: StructPrimitiveSchema<TFields>) {
@@ -191,13 +213,23 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TRequ
     });
   }
 
-  /** Make all properties of this struct optional (TRequired = false for all fields) */
-  partial(): StructPrimitive<PartialFields<TFields>, TRequired, THasDefault> {
+  /** Make all properties of this struct optional (TRequired = false for all fields), optionally stripping defaults */
+  partial(options: { stripDefaults: true }): StructPrimitive<PartialFieldsNoDefault<TFields>, TRequired, THasDefault>;
+  partial(options?: { stripDefaults?: boolean }): StructPrimitive<PartialFields<TFields>, TRequired, THasDefault>;
+  partial(options?: { stripDefaults?: boolean }): StructPrimitive<PartialFields<TFields>, TRequired, THasDefault> | StructPrimitive<PartialFieldsNoDefault<TFields>, TRequired, THasDefault> {
+    const stripDefaults = options?.stripDefaults;
     const partialFields: Record<string, AnyPrimitive> = {};
     for (const key in this._schema.fields) {
       const field = this._schema.fields[key]!;
-      // Create a new field that is not required (optional)
-      partialFields[key] = this._makeFieldOptional(field);
+      partialFields[key] = this._makeFieldOptional(field, stripDefaults);
+    }
+    if (stripDefaults) {
+      return new StructPrimitive<PartialFieldsNoDefault<TFields>, TRequired, THasDefault>({
+        required: this._schema.required,
+        defaultValue: undefined,
+        fields: partialFields as PartialFieldsNoDefault<TFields>,
+        validators: [],
+      });
     }
     return new StructPrimitive<PartialFields<TFields>, TRequired, THasDefault>({
       required: this._schema.required,
@@ -207,18 +239,89 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TRequ
     });
   }
 
-  private _makeFieldOptional(field: AnyPrimitive): AnyPrimitive {
-    // Create a new primitive with required: false
-    // We access the _schema property if available, otherwise return as-is
-    const fieldAny = field as any;
-    if (fieldAny._schema && typeof fieldAny._schema === "object") {
-      const Constructor = field.constructor as new (schema: any) => AnyPrimitive;
+  private _makeFieldOptional(field: AnyPrimitive, stripDefaults?: boolean): AnyPrimitive {
+    const maybeStripped = stripDefaults ? this._stripDefaultsRecursively(field) : field;
+
+    // Create a new field with required: false, preserving its shape.
+    const fieldWithSchema = maybeStripped as { _schema?: Record<string, unknown> };
+    if (fieldWithSchema._schema && typeof fieldWithSchema._schema === "object") {
+      const Constructor = maybeStripped.constructor as new (schema: unknown) => AnyPrimitive;
       return new Constructor({
-        ...fieldAny._schema,
+        ...fieldWithSchema._schema,
         required: false,
       });
     }
-    return field;
+    return maybeStripped;
+  }
+
+  /**
+   * Recursively strips defaults from a primitive and nested child primitives.
+   * This is used by partial({ stripDefaults: true }) so omitted fields resolve to undefined.
+   */
+  private _stripDefaultsRecursively(field: AnyPrimitive): AnyPrimitive {
+    const fieldWithSchema = field as { _schema?: Record<string, unknown> };
+    if (!fieldWithSchema._schema || typeof fieldWithSchema._schema !== "object") {
+      return field;
+    }
+
+    const nextSchema: Record<string, unknown> = { ...fieldWithSchema._schema };
+
+    // Struct fields
+    if (
+      nextSchema["fields"] &&
+      typeof nextSchema["fields"] === "object" &&
+      !Array.isArray(nextSchema["fields"])
+    ) {
+      const nextFields: Record<string, AnyPrimitive> = {};
+      for (const key in nextSchema["fields"] as Record<string, AnyPrimitive>) {
+        const nestedField = (nextSchema["fields"] as Record<string, AnyPrimitive>)[key]!;
+        nextFields[key] = this._stripDefaultsRecursively(nestedField);
+      }
+      nextSchema["fields"] = nextFields;
+    }
+
+    // Array element primitive
+    if (nextSchema["element"] && typeof nextSchema["element"] === "object") {
+      nextSchema["element"] = this._stripDefaultsRecursively(nextSchema["element"] as AnyPrimitive);
+    }
+
+    // Either variants (array) / Union variants (record)
+    if (Array.isArray(nextSchema["variants"])) {
+      nextSchema["variants"] = (nextSchema["variants"] as readonly AnyPrimitive[]).map((variant) =>
+        this._stripDefaultsRecursively(variant)
+      );
+    } else if (nextSchema["variants"] && typeof nextSchema["variants"] === "object") {
+      const nextVariants: Record<string, AnyPrimitive> = {};
+      for (const key in nextSchema["variants"] as Record<string, AnyPrimitive>) {
+        const nestedVariant = (nextSchema["variants"] as Record<string, AnyPrimitive>)[key]!;
+        nextVariants[key] = this._stripDefaultsRecursively(nestedVariant);
+      }
+      nextSchema["variants"] = nextVariants;
+    }
+
+    // Tree root node primitive
+    if (nextSchema["root"] && typeof nextSchema["root"] === "object") {
+      nextSchema["root"] = this._stripDefaultsRecursively(nextSchema["root"] as AnyPrimitive);
+    }
+
+    // Clear known default carriers across primitives.
+    if ("defaultValue" in nextSchema) {
+      nextSchema["defaultValue"] = undefined;
+    }
+    if ("defaultInput" in nextSchema) {
+      nextSchema["defaultInput"] = undefined;
+    }
+
+    const Constructor = field.constructor as new (schema: unknown) => AnyPrimitive;
+    return new Constructor(nextSchema);
+  }
+
+  private _isRequiredWithoutDefault(field: AnyPrimitive): boolean {
+    const fieldDefault = field._internal.getInitialState();
+    return (
+      (field as { _schema?: { required?: boolean } })._schema?.required === true &&
+      fieldDefault === undefined
+    );
   }
 
   readonly _internal: PrimitiveInternal<InferStructState<TFields>, StructProxy<TFields, TRequired, THasDefault>> = {
@@ -270,12 +373,24 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TRequ
           for (const key in value) {
             if (Object.prototype.hasOwnProperty.call(value, key)) {
               const fieldValue = value[key as keyof TFields];
-              if (fieldValue === undefined) continue; // Skip undefined values
-
               const fieldPrimitive = fields[key as keyof TFields];
               if (!fieldPrimitive) continue; // Skip unknown fields
 
               const fieldPath = operationPath.append(key);
+
+              const shouldUnset =
+                fieldValue === undefined ||
+                (fieldValue === null && !primitiveAllowsNullValue(fieldPrimitive));
+              if (shouldUnset) {
+                if (this._isRequiredWithoutDefault(fieldPrimitive)) {
+                  throw new ValidationError(`Field "${key}" is required and cannot be null or undefined`);
+                }
+                env.addOperation(
+                  Operation.fromDefinition(fieldPath, this._opDefinitions.unset, null)
+                );
+                continue;
+              }
+
               const fieldProxy = fieldPrimitive._internal.createProxy(env, fieldPath);
 
               // Check if this is a nested struct and value is a plain object (partial update)
@@ -368,24 +483,32 @@ export class StructPrimitive<TFields extends Record<string, AnyPrimitive>, TRequ
         }
 
         const fieldPrimitive = this._schema.fields[fieldName]!;
-        const remainingPath = path.shift();
-        const fieldOperation = {
-          ...operation,
-          path: remainingPath,
-        };
-
         // Get the current field state
         const currentState = state ?? ({} as InferStructState<TFields>);
-        const currentFieldState = currentState[fieldName] as InferState<typeof fieldPrimitive> | undefined;
+        if (operation.kind === "struct.unset" && tokens.length === 1) {
+          if (this._isRequiredWithoutDefault(fieldPrimitive)) {
+            throw new ValidationError(`Field "${globalThis.String(fieldName)}" is required and cannot be removed`);
+          }
+          const mutableState = { ...currentState } as Record<string, unknown>;
+          delete mutableState[globalThis.String(fieldName)];
+          newState = mutableState as InferStructState<TFields>;
+        } else {
+          const remainingPath = path.shift();
+          const fieldOperation = {
+            ...operation,
+            path: remainingPath,
+          };
+          const currentFieldState = currentState[fieldName] as InferState<typeof fieldPrimitive> | undefined;
 
-        // Apply the operation to the field
-        const newFieldState = fieldPrimitive._internal.applyOperation(currentFieldState, fieldOperation);
+          // Apply the operation to the field
+          const newFieldState = fieldPrimitive._internal.applyOperation(currentFieldState, fieldOperation);
 
-        // Build updated state
-        newState = {
-          ...currentState,
-          [fieldName]: newFieldState,
-        };
+          // Build updated state
+          newState = {
+            ...currentState,
+            [fieldName]: newFieldState,
+          };
+        }
       }
 
       // Run validators on the new state
@@ -501,4 +624,3 @@ export const Struct = <TFields extends Record<string, AnyPrimitive>>(
   fields: TFields
 ): StructPrimitive<TFields, false, false> =>
   new StructPrimitive({ required: false, defaultValue: undefined, fields, validators: [] });
-

package/src/primitives/shared.ts

@@ -171,6 +171,31 @@ 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.
+ */
+type PrimitiveWithLiteral = AnyPrimitive & {
+  readonly _tag: "LiteralPrimitive";
+  readonly literal: unknown;
+};
+
+const isLiteralPrimitive = (primitive: AnyPrimitive): primitive is PrimitiveWithLiteral =>
+  primitive._tag === "LiteralPrimitive" && "literal" in primitive;
+
+export function primitiveAllowsNullValue(primitive: AnyPrimitive): boolean {
+  if (isLiteralPrimitive(primitive)) {
+    return primitive.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 +239,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 +340,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);
+    });
   });
 });