docs: clarify that patches are not optimal. Solves #648

immerjs · Oct 20, 2020 · 41673f4 · 41673f4
1 parent c0e6749
commit 41673f4
Show file tree

Hide file tree

Showing 2 changed files with 3 additions and 0 deletions.
diff --git a/docs/patches.md b/docs/patches.md
@@ -112,6 +112,8 @@ The generated patches are similar (but not the same) to the [RFC-6902 JSON patch
 ]
 ```
 
+⚠ Note: The set of patches generated by Immer should be correct, that is, applying them to an equal base object should result in the same end state. However Immer does not guarantee the generated set of patches will be optimal, that is, the minimum set of patches possible. It depends often on the use case what is considered 'optimal', and generating the optimal set of patches is potentielly computationally very expensive. So in cases you might want to post process the generated patches, or compress them as explained below.
+
 ### `produceWithPatches`
 
 <details>

diff --git a/docs/pitfalls.md b/docs/pitfalls.md
@@ -16,6 +16,7 @@ title: Pitfalls
 1. You will need to enable your own classes to work properly with Immer. For docs on the topic, check out the section on [working with complex objects](https://immerjs.github.io/immer/docs/complex-objects).
 1. For arrays, only numeric properties and the `length` property can be mutated. Custom properties are not preserved on arrays.
 1. Note that data that comes from the closure, and not from the base state, will never be drafted, even when the data has become part of the new draft:
+1. The set of patches generated by Immer should be correct, that is, applying them to an equal base object should result in the same end state. However Immer does not guarantee the generated set of patches will be optimal, that is, the minimum set of patches possible.
 
 ```javascript
 function onReceiveTodo(todo) {