Add onChange hook

src/draft.ts

@@ -162,7 +162,7 @@ const proxyHandler: ProxyHandler<ProxyDraft> = {
     )
       return true;
     ensureShallowCopy(target);
-    markChanged(target);
+    markChanged(target, key, { kind: 'set', prev: current, next: value });
     if (has(target.original, key) && isEqual(value, target.original[key])) {
       // !case: handle the case of assigning the original non-draftable value to a draft
       target.assignedMap!.delete(key);
@@ -203,10 +203,11 @@ const proxyHandler: ProxyHandler<ProxyDraft> = {
     if (target.type === DraftType.Array) {
       return proxyHandler.set!.call(this, target, key, undefined, target.proxy);
     }
-    if (peek(target.original, key) !== undefined || key in target.original) {
+    const prev = peek(target.original, key);
+    if (prev !== undefined || key in target.original) {
       // !case: delete an existing key
       ensureShallowCopy(target);
-      markChanged(target);
+      markChanged(target, key, { kind: 'delete', prev });
       target.assignedMap!.set(key, false);
     } else {
       target.assignedMap = target.assignedMap ?? new Map();

src/interface.ts

@@ -109,6 +109,19 @@ export interface ApplyMutableOptions {
   mutable?: boolean;
 }
 
+export interface ChangeInput {
+  kind: 'set' | 'delete' | 'map.set' | 'map.delete' | 'map.clear' | 'set.add' | 'set.delete' | 'set.clear';
+  prev?: any;
+  next?: any;
+  value?: any;
+  existed?: boolean;
+}
+
+export interface ChangeEvent extends ChangeInput {
+  key?: any;
+  path: (string | number)[];
+}
+
 export interface Options<O extends PatchesOptions, F extends boolean> {
   /**
    * In strict mode, Forbid accessing non-draftable values and forbid returning a non-draft value.
@@ -127,6 +140,10 @@ export interface Options<O extends PatchesOptions, F extends boolean> {
    * And it can also return a shallow copy function(AutoFreeze and Patches should both be disabled).
    */
   mark?: Mark<O, F>;
+  /**
+   * onChange callback. When set, caller can be aware of each change as it happens.
+   */
+  onChange?: (event: ChangeEvent) => void;
 }
 
 export interface ExternalOptions<O extends PatchesOptions, F extends boolean> {
@@ -147,6 +164,10 @@ export interface ExternalOptions<O extends PatchesOptions, F extends boolean> {
    * And it can also return a shallow copy function(AutoFreeze and Patches should both be disabled).
    */
   mark?: Mark<O, F>[] | Mark<O, F>;
+  /**
+   * onChange callback. When set, caller can be aware of each change as it happens.
+   */
+  onChange?: (event: ChangeEvent) => void;
 }
 
 // Exclude `symbol`

src/makeCreator.ts

@@ -148,6 +148,7 @@ export const makeCreator: MakeCreator = (arg) => {
       mark,
       strict,
       enablePatches,
+      onChange: options.onChange,
     };
     if (
       !isDraftable(state, _options) &&

src/map.ts

@@ -23,9 +23,10 @@ export const mapHandler = {
   set(key: any, value: any) {
     const target = getProxyDraft(this)!;
     const source = latest(target);
-    if (!source.has(key) || !isEqual(source.get(key), value)) {
+    const prev = source.get(key);
+    if (!source.has(key) || !isEqual(prev, value)) {
       ensureShallowCopy(target);
-      markChanged(target);
+      markChanged(target, key, { kind:'map.set', prev, next: value });
       target.assignedMap!.set(key, true);
       target.copy.set(key, value);
       markFinalization(target, key, value, generatePatches);
@@ -37,8 +38,9 @@ export const mapHandler = {
       return false;
     }
     const target = getProxyDraft(this)!;
+    const prev = latest(target).get(key);
     ensureShallowCopy(target);
-    markChanged(target);
+    markChanged(target, key, { kind:'map.delete', prev });
     if (target.original.has(key)) {
       target.assignedMap!.set(key, false);
     } else {
@@ -51,7 +53,7 @@ export const mapHandler = {
     const target = getProxyDraft(this)!;
     if (!this.size) return;
     ensureShallowCopy(target);
-    markChanged(target);
+    markChanged(target, undefined, { kind:'map.clear' });
     target.assignedMap = new Map();
     for (const [key] of target.original) {
       target.assignedMap.set(key, false);

src/set.ts

@@ -75,41 +75,47 @@ export const setHandler = {
     const target = getProxyDraft(this)!;
     if (!this.has(value)) {
       ensureShallowCopy(target);
-      markChanged(target);
+      markChanged(target, undefined, { kind:'set.add', value });
       target.assignedMap!.set(value, true);
       target.setMap!.set(value, value);
       markFinalization(target, value, value, generatePatches);
     }
     return this;
   },
   delete(value: any): boolean {
-    if (!this.has(value)) {
+    const existed = this.has(value);
+    if (!existed) {
       return false;
     }
     const target = getProxyDraft(this)!;
     ensureShallowCopy(target);
-    markChanged(target);
+    markChanged(target, undefined, { kind:'set.delete', value, existed });
     const valueProxyDraft = getProxyDraft(value)!;
+    let ok: boolean;
     if (valueProxyDraft && target.setMap!.has(valueProxyDraft.original)) {
       // delete drafted
       target.assignedMap!.set(valueProxyDraft.original, false);
-      return target.setMap!.delete(valueProxyDraft.original);
+      ok = target.setMap!.delete(valueProxyDraft.original);
     }
-    if (!valueProxyDraft && target.setMap!.has(value)) {
-      // non-draftable values
-      target.assignedMap!.set(value, false);
-    } else {
-      // reassigned
-      target.assignedMap!.delete(value);
+    else {
+      if (!valueProxyDraft && target.setMap!.has(value)) {
+        // non-draftable values
+        target.assignedMap!.set(value, false);
+      }
+      else {
+        // reassigned
+        target.assignedMap!.delete(value);
+      }
+      // delete reassigned or non-draftable values
+      ok = target.setMap!.delete(value);
     }
-    // delete reassigned or non-draftable values
-    return target.setMap!.delete(value);
+    return ok;
   },
   clear() {
     if (!this.size) return;
     const target = getProxyDraft(this)!;
     ensureShallowCopy(target);
-    markChanged(target);
+    markChanged(target, undefined, { kind:'set.clear' });
     for (const value of target.original) {
       target.assignedMap!.set(value, false);
     }

src/utils/mark.ts

@@ -1,11 +1,40 @@
-import { ProxyDraft } from '../interface';
+import { ProxyDraft, ChangeInput } from '../interface';
 
-export function markChanged(proxyDraft: ProxyDraft) {
+export function markChanged(proxyDraft: ProxyDraft, key?: string | number | symbol, operation?: ChangeInput) {
   proxyDraft.assignedMap = proxyDraft.assignedMap ?? new Map();
   if (!proxyDraft.operated) {
     proxyDraft.operated = true;
     if (proxyDraft.parent) {
       markChanged(proxyDraft.parent);
     }
   }
+
+  // Emit operation hook if provided
+  if (operation && proxyDraft.options.onChange) {
+    try {
+      // Build path from root to this node
+      const path: (string | number)[] = [];
+      let current: ProxyDraft | null = proxyDraft;
+
+      while (current && current.parent) {
+        if (current.key !== undefined) {
+          path.unshift(current.key as string | number);
+        }
+        current = current.parent;
+      }
+
+      // Add the current key if provided
+      if (key !== undefined) {
+        path.push(key as string | number);
+      }
+
+      proxyDraft.options.onChange({
+        ...operation,
+        path,
+        key,
+      });
+    } catch (e) {
+      // Be conservative: never throw from hooks
+    }
+  }
 }