Updated docs. Also fixes #445

__tests__/frozen.js

@@ -149,6 +149,9 @@ function runTests(name, useProxies) {
 			expect(() => res.delete("b")).toThrow(
 				"This object has been frozen and should not be mutated"
 			)
+
+			// In draft, still editable
+			expect(produce(res, d => void d.set("a", 2))).not.toBe(res)
 		})
 
 		it("will freeze sets", () => {
@@ -165,6 +168,9 @@ function runTests(name, useProxies) {
 			expect(() => base.clear()).toThrow(
 				"This object has been frozen and should not be mutated"
 			)
+
+			// In draft, still editable
+			expect(produce(res, d => void d.add(2))).not.toBe(res)
 		})
 	})
 }

docs/api.md

@@ -20,6 +20,7 @@ title: API overview
 | `original` | Given a draft object (doesn't have to be a tree root), returns the the original object at the same path in the original state tree, if present | [Original](original.md) |
 | `Patch` | Exposed TypeScript type, describes the shape of an (inverse) patch object | [Patches](patches.md) |
 | `produce` | The core API of Immer, also exposed as the `default` export | [Produce](produce.md) |
+| `produceWithPatches` | Works the same as `produce`, but instead of just returning the produced object, it returns a tuple, consisting of `[result, patches, inversePatches]`. | [Patches](patches.md) |
 | `setAutoFreeze` | Enables / disables automatic freezing of the trees produces. By default enabled in development builds | [Freezing](freezing.md) |
 | `setUseProxies` | Can be used to disable or force the use of `Proxy` objects. Useful when filing bug reports. |  |
 

docs/complex-objects.md

@@ -5,7 +5,7 @@ title: Working with classes
 
 <div id="codefund"><!-- fallback content --></div>
 
-Plain objects and arrays are always drafted by Immer.
+Plain objects, arrays, `Map`s and `Set`s are always drafted by Immer.
 
 Every other object must use the `immerable` symbol to mark itself as compatible with Immer. When one of these objects is mutated within a producer, its prototype is preserved between copies.
 
@@ -27,36 +27,4 @@ For arrays, only numeric properties and the `length` property can be mutated. Cu
 
 When working with `Date` objects, you should always create a new `Date` instance instead of mutating an existing `Date` object.
 
-Built-in classes like `Map` and `Set` are not yet supported (they might be if there is popular demand). As a workaround, you should clone them before mutating them in a producer:
-
-```js
-const state = {
-	set: new Set(),
-	map: new Map()
-}
-const nextState = produce(state, draft => {
-	// Don't use any Set methods, as that mutates the instance!
-	draft.set.add("foo") // ❌
-
-	// 1. Instead, clone the set (just once)
-	const newSet = new Set(draft.set) // ✅
-
-	// 2. Mutate the clone (just in this producer)
-	newSet.add("foo")
-
-	// 3. Update the draft with the new set
-	draft.set = newSet
-
-	// Similarly, don't use any Map methods.
-	draft.map.set("foo", "bar") // ❌
-
-	// 1. Instead, clone the map (just once)
-	const newMap = new Map(draft.map) // ✅
-
-	// 2. Mutate it
-	newMap.set("foo", "bar")
-
-	// 3. Update the draft
-	draft.map = newMap
-})
-```
+Maps and Sets that are produced by Immer will be made artificially immutable. This means that they will throw an exception when trying mutative methods like `set`, `clear` etc. outside a producer.

docs/faq.md

@@ -20,7 +20,7 @@ A: Yes
 
 ## Q: I can't rely on Proxies being present on my target environments. Can I use Immer?
 
-A: Yes
+A: Yes [details](http://localhost:3000/immer/docs/installation#immer-on-older-javascript-environments)
 
 ## Q: Can I typecheck my data structures when using Immer?
 
@@ -30,6 +30,10 @@ A: Yes
 
 A: Yes
 
+## Q: Can I use Maps and Sets?
+
+A: Yes
+
 ## Q: Is it fast?
 
 A: Yes

docs/introduction.md

@@ -54,7 +54,7 @@ Head to the [next section](produce) to further dive into `produce`.
 
 ## Benefits
 
-- Immutability with normal JavaScript objects and arrays. No new APIs to learn!
+- Immutability with normal JavaScript objects, arrays, Sets and Maps. No new APIs to learn!
 - Strongly typed, no string based paths selectors etc.
 - Structural sharing out of the box
 - Object freezing out of the box

docs/performance.md

@@ -27,7 +27,7 @@ Here is a [simple benchmark](https://github.com/immerjs/immer/blob/master/__perf
 
 Something that isn't reflected in the numbers above, but in reality, Immer is sometimes significantly _faster_ than a hand written reducer. The reason for that is that Immer will detect "no-op" state changes, and return the original state if nothing actually changed, which can avoid a lot of re-renderings for example. Cases are known where simply applying immer solved critical performance issues.
 
-These tests were executed on Node 10.15.1. Use `yarn test:perf` to reproduce them locally.
+These tests were executed on Node 10.16.3. Use `yarn test:perf` to reproduce them locally.
 
 ![performance.png](/immer/img/performance.png)