Add docs from RFC 556

NullVoxPopuli · NullVoxPopuli · commit e3be65f79b62 · 2022-02-24T16:57:57.000-05:00
diff --git a/packages/@glimmer/tracking/src/cached.ts b/packages/@glimmer/tracking/src/cached.ts
@@ -1,6 +1,63 @@
 import { DEBUG } from '@glimmer/env';
 import { createCache, getValue } from '@glimmer/validator';
 
+/**
+ * @decorator
+ *
+ * The `@cached` decorator can be used on getters in order to cache the return
+ * value of the getter. This is useful when a getter is expensive and used very
+ * often.
+ *
+ *
+ * @example
+ *
+ * in this guest list class, we have the `sortedGuests`
+ * getter that sorts the guests alphabetically:
+ *
+ * ```js
+ * import { tracked } from '@glimmer/tracking';
+ *
+ * class GuestList {
+ *   @tracked guests = ['Zoey', 'Tomster'];
+ *
+ *   get sortedGuests() {
+ *     return this.guests.slice().sort()
+ *   }
+ * }
+ * ```
+ *
+ * Every time `sortedGuests` is accessed, a new array will be created and sorted,
+ * because JavaScript getters do not cache by default. When the guest list is
+ * small, like the one in the example, this is not a problem. However, if the guest
+ * list were to grow very large, it would mean that we would be doing a large
+ * amount of work each time we accessed `sortedGetters`. With `@cached`, we can
+ * cache the value instead:
+ *
+ * ```js
+ * import { tracked, cached } from '@glimmer/tracking';
+ *
+ * class GuestList {
+ *   @tracked guests = ['Zoey', 'Tomster'];
+ *
+ *   @cached
+ *   get sortedGuests() {
+ *     return this.guests.slice().sort()
+ *   }
+ * }
+ * ```
+ *
+ * Now the `sortedGuests` getter will be cached based on _autotracking_. It will
+ * only rerun and create a new sorted array when the `guests` tracked property is
+ * updated.
+ *
+ * In general, you should avoid using `@cached` unless you have confirmed that the
+ * getter you are decorating is computationally expensive. `@cached` adds a small
+ * amount of overhead to the getter, making it more expensive. While this overhead
+ * is small, if `@cached` is overused it can add up to a large impact overall in
+ * your app. Many getters and tracked properties are only accessed once, rendered,
+ * and then never rerendered, so adding `@cached` when it is unnecessary can
+ * negatively impact performance.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const cached: PropertyDecorator = (...args: any[]) => {
   const [target, key, descriptor] = args;
