Advance RFC #0566 "@cached" to Stage Recommended

[emberjs-rfcs-bot]

Advance #566 to the Recommended Stage

Summary

This pull request is advancing the RFC to the Recommended Stage.

• PR to Accepted Stage: @cached #566
• PR to Ready For Release Stage
• PR to Released Stage

An FCP is required before merging this PR to advance.

Recommended Stage Summary

The "Recommended" stage is the final milestone for an RFC. It provides a signal to the wider community to indicate that a feature has been put through its ecosystem paces and is ready to use.

To reach the "Recommended" stage, the following should be true:

If appropriate, the feature is integrated into the tutorial and the guides prose. API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.

If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.

If the proposal updates or replaces an existing feature, high-quality codemods are available.

If needed, Ember debugging tools as well as popular IDE support have been updated to support the feature.

If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".

Any criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met.

An FCP is required to enter this stage. Multiple RFCs may be moved as a batch into "Recommended" with the same PR.

Checklist to move to Recommended

• Any criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met
• If appropriate, the feature is integrated into the tutorial and the guides prose. API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.
• If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.
• If the proposal updates or replaces an existing feature, high-quality codemods are available
• If needed, Ember debugging tools as well as popular IDE support have been updated to support the feature.
• If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".
• This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP

Criteria for moving to Recommended (required)

• Fully document in Guides
• Skim guides for places that might have related outdated information
• Review tutorial for appropriate places to use it
• Release new @glimmer/tracking npm package for correct types (@kategengler, @wycats) confirmed ember ships with correct types now.

[NullVoxPopuli]

🎉

[NullVoxPopuli]

will we required to not have to have ember-cached-decorator-polyfill for providing types before we can advance this to "recommended"?

@glimmer/tracking does have @cached: https://github.com/glimmerjs/glimmer.js/blob/master/packages/%40glimmer/tracking/src/cached.ts
but it's the v2-beta -- (not present in 1.1.2).

Idk what all is involved with finalizing the v2 of @glimmer/tracking, but if I can help in anyway, lemme know

[wagenet]

This is what I had to do to get types working:

import '@glimmer/tracking';

// We need this until we're on @glimmer/tracking 2.0 since this method only actually
// exists in Ember's special version.
declare module '@glimmer/tracking' {
	/**
	 * @decorator
	 *
	 * Memoizes the result of a getter based on autotracking.
	 *
	 * The `@cached` decorator can be used on native getters to memoize their return
	 * values based on the tracked state they consume while being calculated.
	 *
	 * By default a getter is always re-computed every time it is accessed. On
	 * average this is faster than caching every getter result by default.
	 *
	 * However, there are absolutely cases where getters are expensive, and their
	 * values are used repeatedly, so memoization would be very helpful.
	 * Strategic, opt-in memoization is a useful tool that helps developers
	 * optimize their apps when relevant, without adding extra overhead unless
	 * necessary.
	 *
	 * @example
	 *
	 * ```ts
	 * import { tracked, cached } from '@glimmer/tracking';
	 *
	 * class Person {
	 *   @tracked firstName = 'Jen';
	 *   @tracked lastName = 'Weber';
	 *
	 *   @cached
	 *   get fullName() {
	 *     return `${this.firstName} ${this.lastName}`;
	 *   }
	 * }
	 * ```
	 */
	export let cached: PropertyDecorator;
}

[wagenet]

@mixonic is going to check out the docs here.

[ef4]

The stable types in ember-source might include this without changes to @glimmer/tracking, @NullVoxPopuli is investigating.

That may or may not resolve the types question, and @mixonic is still planning to work on docs.

[NullVoxPopuli]

@cached has "a" type here: https://github.com/NullVoxPopuli/cached-status-2023-09-08/blob/main/app/app.ts#L12

but is without JSDoc.
When doing "go-to-definition", you get

declare module '@ember/-internals/metal/lib/cached' {
  export const cached: PropertyDecorator;
}

which is a little goofy.
But at least it's not an error

It's also the same strategy that @tracked uses to provide types.

declare module '@ember/-internals/metal/lib/tracked' {
 // ...
}

so, I think I can PR copy-pasta some JS Doc to @cached ez
emberjs/ember.js#20543

[ef4]

API docs are solid now.
@cached is findable in the guides via search.
built-in ember types are updated.