Add an original function

__tests__/flow/flow.js.flow

@@ -1,5 +1,5 @@
 // @flow
-import produce, {setAutoFreeze, setUseProxies, produce as produce2, applyPatches, Patch} from "../../src/immer"
+import produce, {setAutoFreeze, setUseProxies, produce as produce2, applyPatches, Patch, original} from "../../src/immer"
 
 setAutoFreeze(true)
 setUseProxies(true)
@@ -93,4 +93,26 @@ produce({x: 3}, [])
         p = patches
     })
     applyPatches({}, p)
+}
+
+{
+    produce({x: 3}, draftState => {
+        let a = original(draftState)
+        if (a) {
+            a.x
+            // $ExpectError
+            a.y
+        }
+    })
+}
+
+{
+    produce([1], draftState => {
+        const a = original(draftState);
+        if (a) {
+            const b: number = a[0];
+            // $ExpectError
+            const c: string = a[0];
+        }
+    })
 }

__tests__/flow/ts.ts

@@ -1,4 +1,4 @@
-import produce, {setAutoFreeze, setUseProxies} from "../../src/immer"
+import produce, {setAutoFreeze, setUseProxies, original} from "../../src/immer"
 
 setAutoFreeze(true)
 setUseProxies(true)
@@ -77,3 +77,22 @@ produce({x: 3}, [])
             ? produce<any, any>(handlers[type])(state, payload)
             : state
 }
+
+produce({x: 3, z: {}}, draftState => {
+    const a = draftState;
+
+    if (a) {
+        a.x
+        // $ExpectError
+        a.y
+    }
+})
+
+produce([1], draftState => {
+    const a = original(draftState);
+    if (a) {
+        // $ExpectError
+        const b: string = a[0];
+        const c: number = a[0];
+    }
+})

__tests__/original.js

@@ -0,0 +1,49 @@
+"use strict"
+import produce, {original, setUseProxies} from "../src/immer"
+
+describe("original", () => {
+    const baseState = {
+        a: [],
+        b: {}
+    }
+
+    it("should return the original from the draft", () => {
+        setUseProxies(true)
+
+        produce(baseState, draftState => {
+            expect(original(draftState)).toBe(baseState)
+            expect(original(draftState.a)).toBe(baseState.a)
+            expect(original(draftState.b)).toBe(baseState.b)
+        })
+
+        setUseProxies(false)
+
+        produce(baseState, draftState => {
+            expect(original(draftState)).toBe(baseState)
+            expect(original(draftState.a)).toBe(baseState.a)
+            expect(original(draftState.b)).toBe(baseState.b)
+        })
+    })
+
+    it("should return the original from the proxy", () => {
+        produce(baseState, draftState => {
+            expect(original(draftState)).toBe(baseState)
+            expect(original(draftState.a)).toBe(baseState.a)
+            expect(original(draftState.b)).toBe(baseState.b)
+        })
+    })
+
+    it("should return undefined for new values on the draft", () => {
+        produce(baseState, draftState => {
+            draftState.c = {}
+            draftState.d = 3
+            expect(original(draftState.c)).toBeUndefined()
+            expect(original(draftState.d)).toBeUndefined()
+        })
+    })
+
+    it("should return undefined for an object that is not proxied", () => {
+        expect(original({})).toBeUndefined()
+        expect(original(3)).toBeUndefined()
+    })
+})

readme.md

@@ -351,6 +351,17 @@ const userReducer = produce((draft, action) => {
 })
 ```
 
+## Extracting the original object from a proxied instance
+
+Immer exposes a named export `original` that will get the original object from the proxied instance inside `produce` (or return `undefined` for unproxied values). A good example of when this can be useful is when searching for nodes in a tree-like state using strict equality.
+
+```js
+const baseState = { users: [{ name: "Richie" }] };
+const nextState = produce(baseState, draftState => {
+    original(draftState.users) // is === baseState.users
+})
+```
+
 ## Using `this`
 
 The recipe will be always invoked with the `draft` as `this` context.

src/common.js

@@ -56,6 +56,13 @@ export function freeze(value) {
     return value
 }
 
+export function original(value) {
+    if (value && value[PROXY_STATE]) {
+        return value[PROXY_STATE].base
+    }
+    // otherwise return undefined
+}
+
 const assign =
     Object.assign ||
     function assign(target, value) {

src/immer.d.ts

@@ -109,4 +109,6 @@ export function setAutoFreeze(autoFreeze: boolean): void
  */
 export function setUseProxies(useProxies: boolean): void
 
-export function applyPatches<S>(state: S, patches: Patch[]): S
+export function applyPatches<S>(state: S, patches: Patch[]): S
+
+export function original<T>(value: T): T | void

src/immer.js

@@ -1,4 +1,4 @@
-export {setAutoFreeze, setUseProxies} from "./common"
+export {setAutoFreeze, setUseProxies, original} from "./common"
 
 import {applyPatches as applyPatchesImpl} from "./patches"
 import {isProxyable, getUseProxies} from "./common"

src/immer.js.flow

@@ -83,4 +83,6 @@ declare export function setAutoFreeze(autoFreeze: boolean): void
  */
 declare export function setUseProxies(useProxies: boolean): void
 
-declare export function applyPatches<S>(state: S, patches: Patch[]): S
+declare export function applyPatches<S>(state: S, patches: Patch[]): S
+
+declare export function original<S>(value: S): ?S