Document the caching of autotracked properties #1474
Conversation
|
Hi, @YoranBrondsema. I appreciate your looking into the current state for caching getters. I didn't know about I thought that the code examples were clear and illustrated the effect of caching well. I think we can shorten the surrounding texts a little (we can come back to this suggestion later). Potential problemRight now, I'm unable to implement your example as a component in a new Ember 3.19 app. When I introduced the import statement for the polyfill, I got the error, I believe it's the problem reported in ember-polyfills/ember-cache-primitive-polyfill#3. I reached out to @pzuraq on Discord to see if the fix is something that we can anticipate soon. If not, I wonder if the Guides today should show the polyfill solution, or if we can present a native JS solution instead (if this is simple to do). Please let us know what you think. Thank you! 🙂 |
|
@ijlee2 Thanks for your prompt reply. I have to be honest with you, I didn't even try I suggest we await @pzuraq's input and I imagine it'll work when ember-polyfills/ember-cache-primitive-polyfill#3 is resolved. |
|
Thanks for understanding. I also think it's a good idea to wait for the issue to be resolved. I think Chris and others are more aware of the issue since yesterday so I'm hopeful that it will be resolved soon. |
|
I believe this API should be released in 3.20, so we can probably remove the text about using the polyfill and land this guide once it is available. We should be able to confirm with the current beta. |
YoranBrondsema
force-pushed
the
document-caching
branch
from
08f68dd
to
a897caf
Compare
|
Cool, I removed the mention of the polyfill. Right now, it refers to the RFC. Once it lands, I imagine it should refer to the doc in the API docs (https://api.emberjs.com/) instead? |
|
@YoranBrondsema Apologies for a late reply. For v3.15-3.19 Guides, I think I'd prefer that we present a working solution for caching getters, something that developers can use now. We would continue to use your full name example to demo the solution. When the API is officially a part of Ember (say, it's v3.20 as an example), we can link to the API docs for more information, yep! (Or to the RFC if the API docs are yet to be updated.) Discussion items: What are your thoughts on my preference for presenting a working solution? Besides using If you know of a solution, can you update your full name example to show us how? |
Actually, the internals are available in 3.20 but the feature itself is not exposed there just yet. Needs feature flagging and whatnot (so likely 3.22 at the earliest for usage without the polyfill). |
|
Thanks for all your feedback. A quick summary to make it easier: 3.20 to 3.22? --> mention polyfillFrom 3.20 to whenever the feature is available without a feature flag (possibly 3.22), we should mention that the polyfill ember-cache-primitive-polyfill is required. 3.15 to 3.19 --> also mention polyfill?The doc for ember-cache-primitive-polyfill mentions that it's compatible with Ember 3.13 and up. So I imagine we can use the same guide for 3.15 all the way to 3.22? Or is anything that opposes the use of the caching polyfill for 3.15 to 3.19? Release of feature and beyond --> remove mention of polyfillWe remove the mention of the polyfill when the caching feature is available in Ember.js without a feature flag. Release of @cached RFC --> replace primitive caching API with
|
|
FYI - The |
|
@YoranBrondsema Thanks for creating a suggested path forward. I think your plan is sound and suggesting the polyfill for 3.15-3.19 works. (The import issue doesn't seem to have been addressed yet. However, I don't want that to be a blocker for your PR.) If I understood Robert's last comment correctly, it seems we can enable a feature flag starting 3.20? If so, I think we can document the use of the flag instead of the polyfill (from 3.20 until release of feature). Let me try out the feature flag after work today. |
Sorry I wasn't very clear, the feature flag is enabled by default and will be included in ember-source >= 3.22.0-beta.1 when that is released (~ 3 or 4 weeks from now). For Ember itself, you cannot enable feature flags on any release other than a canary build (this ensures that experimental / unstable features do not sneak into any tagged releases) which means you can't use the caching primitives in Ember until 3.22+. So basically for 3.13 through 3.21, we should mention / use the polyfill; for 3.22+ we should remove mention of the polyfill and use the native API directly. |
|
@rwjblue Thanks for clarifying! @YoranBrondsema May I review your current changes once more later today and make suggestions? Afterwards, you can apply the suggestions (feel free to suggest something else) and backport the text from |
| This works fine in most cases. But sometimes you want a bit more control over | ||
| the recomputation, for instance if the computation that happens in the getter | ||
| is very expensive. In that case, you want to cache the value in between calls | ||
| when the dependencies haven't changed. You want to recompute only if one of the | ||
| dependencies has been modified. |
There was a problem hiding this comment.
| This works fine in most cases. But sometimes you want a bit more control over | |
| the recomputation, for instance if the computation that happens in the getter | |
| is very expensive. In that case, you want to cache the value in between calls | |
| when the dependencies haven't changed. You want to recompute only if one of the | |
| dependencies has been modified. | |
| From the value of `count`, we see that `aspectRatio` was calculated 3 times. | |
| Recomputing is fine in most cases. If the computation that happens in the getter | |
| is very expensive, however, you will want to cache the value and retrieve it when | |
| the dependencies haven't changed. You want to recompute only if a dependency | |
| has been updated. |
There was a problem hiding this comment.
Hi, @YoranBrondsema. I reread the paragraphs and code examples that you had written. They provided a great starting point so I appreciate your work and patience in getting this PR through. 🧡
For each paragraph, I made a suggestion that I think would be concise and easy to understand for someone who is new to caching getters or using Ember's cache API. You are welcome to apply the suggestions as they are, or leave a comment to ask questions or to suggest an alternative text.
For code, I do need us to show an example that doesn't involve first and last names, to help address an active issue (#1480). I think the Photo class and calculating the aspect ratio (some math to stand for an expensive computation) would make a good example. Will this be okay with you?
As a reminder, once you make changes to the autotracking-in-depth.md file in the release folder, please backport the changes to:
v3.15.0v3.16.0v3.17.0v3.18.0v3.19.0
Let us know if you have questions or need help with writing.
| console.log(person.fullName); // Jennifer Weber | ||
| console.log(count); // 2; | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| From the value of `count`, we see that, this time, `aspectRatio` was calculated only twice. |
YoranBrondsema
force-pushed
the
document-caching
branch
from
a897caf
to
14de3ca
Compare
I agree with your changes, nice.
Yes! I updated the text following your suggestions. Once I get your OK, I'll:
I think we'll be good to go after these two steps. |
|
@YoranBrondsema Thanks for reviewing my suggestions and updating the texts. I think they read great and we're ready to backport them to 3.15-3.19! |
YoranBrondsema
force-pushed
the
document-caching
branch
from
14de3ca
to
52035ac
Compare
|
OK should be good now @ijlee2. |
There was a problem hiding this comment.
Thanks! I think the PR can be merged now.
I may want to think about the subsection title more. (Is it better to say caching getters or caching tracked properties? Is there no difference?)
The Autotracking In-Depth section will need to be updated soon with more content (show how to update arrays and objects), so I think we can address this subsection's title at a later time.
Addresses emberjs/ember.js#19030.