Add computed.shallow annotation

.changeset/smooth-glasses-search.md

@@ -0,0 +1,5 @@
+---
+"mobx": minor
+---
+
+Add computed.shallow annotation

docs/computeds.md

@@ -151,6 +151,14 @@ class Dimension {
 
 </details>
 
+<details id="computed-shallow"><summary>{🚀} **Tip:** `computed.shallow` for comparing output shallowly <a href="#computed-shallow" class="tip-anchor"></a></summary>
+
+If the output of a computed value that is a collection with all items identical to the collection from previous computation doesn't need to notify observers, `computed.shallow` can be used. It will do size check and reference equality check for each item, rather than a reference equality check of the collection, before notifying observers.
+
+In practice, `computed.shalow` is useful only in limited situations. Only use it if changes in the underlying observables can still lead to the same contents in the collection, for example, if we were filtering a list of rectangles by whether they are in a given area, the rectangles included might stay the same even though the area changes.
+
+</details>
+
 <details id="computed-struct"><summary>{🚀} **Tip:** `computed.struct` for comparing output structurally <a href="#computed-struct" class="tip-anchor"></a></summary>
 
 If the output of a computed value that is structurally equivalent to the previous computation doesn't need to notify observers, `computed.struct` can be used. It will make a structural comparison first, rather than a reference equality check, before notifying observers. For example:

docs/observable-state.md

@@ -297,6 +297,7 @@ Note that it is possible to pass `{ proxy: false }` as an option to `observable`
 | `action`                                   | Mark a method as an action that will modify the state. Check out [actions](actions.md) for more details. Non-writable.                                                                                                                                                                                                                            |
 | `action.bound`                             | Like action, but will also bind the action to the instance so that `this` will always be set. Non-writable.                                                                                                                                                                                                                                       |
 | `computed`                                 | Can be used on a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) to declare it as a derived value that can be cached. Check out [computeds](computeds.md) for more details.                                                                                                                             |
+| `computed.shallow`                         | Like `computed`, but for collections. After recomputing, if the contents of the collection are equal to the previous result, no observers will be notified.                                                                                                                                                                                       |
 | `computed.struct`                          | Like `computed`, except that if after recomputing the result is structurally equal to the previous result, no observers will be notified.                                                                                                                                                                                                         |
 | `true`                                     | Infer the best annotation. Check out [makeAutoObservable](#makeautoobservable) for more details.                                                                                                                                                                                                                                                  |
 | `false`                                    | Explicitly do not annotate this property.                                                                                                                                                                                                                                                                                                         |

packages/mobx/__tests__/v5/base/typescript-decorators.ts

@@ -207,7 +207,33 @@ test("computed setter should succeed", () => {
     t.equal(b.propX, 8)
 })
 
-test("typescript: parameterized computed decorator", () => {
+test("@computed.shallow (TS)", () => {
+    class TestClass {
+        @observable.struct x = { a: 3 }
+        @observable.struct y = { b: 4 }
+        @computed.shallow
+        get array() {
+            return [this.x, this.y]
+        }
+        constructor() {
+            makeObservable(this)
+        }
+    }
+
+    const t1 = new TestClass()
+    const changes: string[] = []
+    const d = autorun(() => changes.push(JSON.stringify(t1.array)))
+
+    t1.x = { a: 5 } // change
+    t.equal(changes.length, 2)
+    t1.x.a = 6 // no change
+    t.equal(changes.length, 2)
+    d()
+
+    t.deepEqual(changes, ['[{"a":3},{"b":4}]', '[{"a":5},{"b":4}]'])
+})
+
+test("@computed.struct (TS)", () => {
     class TestClass {
         @observable x = 3
         @observable y = 3

packages/mobx/src/api/computed.ts

@@ -17,6 +17,7 @@ import {
 import type { ClassGetterDecorator } from "../types/decorator_fills"
 
 export const COMPUTED = "computed"
+export const COMPUTED_SHALLOW = "computed.shallow"
 export const COMPUTED_STRUCT = "computed.struct"
 
 export interface IComputedFactory extends Annotation, PropertyDecorator, ClassGetterDecorator {
@@ -25,10 +26,14 @@ export interface IComputedFactory extends Annotation, PropertyDecorator, ClassGe
     // computed(fn, opts)
     <T>(func: () => T, options?: IComputedValueOptions<T>): IComputedValue<T>
 
+    shallow: Annotation & PropertyDecorator & ClassGetterDecorator
     struct: Annotation & PropertyDecorator & ClassGetterDecorator
 }
 
 const computedAnnotation = createComputedAnnotation(COMPUTED)
+const computedShallowAnnotation = createComputedAnnotation(COMPUTED_SHALLOW, {
+    equals: comparer.shallow
+})
 const computedStructAnnotation = createComputedAnnotation(COMPUTED_STRUCT, {
     equals: comparer.structural
 })
@@ -71,4 +76,5 @@ export const computed: IComputedFactory = function computed(arg1, arg2) {
 
 Object.assign(computed, computedAnnotation)
 
+computed.shallow = createDecoratorAnnotation(computedShallowAnnotation)
 computed.struct = createDecoratorAnnotation(computedStructAnnotation)