babel / babel/website

Clarify documentation on Caching

Open
#1,827 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
777
Forks
1.4k
Avg merge
16h 45m
Merged PRs (30d)
3

Description

The new babel.config.js allows (seemingly requires) you to set up caching. I think the [documentation on caching](https://babeljs.io/docs/en/config-files#apicache) is a little unclear in a couple of spots:

> Any time the using callback returns a value other than the one that was expected...

What is meant by "expected?"

Also, the `.invalidate` explanation seems to have been copied from the `.using` section but not updated. I would like to rewrite it, but I'm a bit confused about how `invalidate` works as well... does it invalidate the cache if it encounters a value different from the immediately previous value? Is it based on a boolean? Will it only invalidate a value that had been used with `.using`? In that case, how do you use them together?

Finally, the suggestion to use a boolean with `.using` raises a question -- this will create a cache for values of `true` and `false`. Thus it seems like once you have used both these values there is no way to invalidate the cache (without adding a `.invalidate` or something). I think this should either be specified if my understanding is correct or clarified if it's incorrect.

I think that the error output if you don't set up caching for `babel` is clearer, at least for `.using`:

> `If this function returns a value different from a previously-encountered value`...

Contributor guide

No contributing guide indexed for this repository

Research direction

Read the linked caching documentation and inspect babel.config.js to understand the .using and .invalidate APIs. Compare their explanations with the quoted error output, then clarify what “expected” means, how invalidation relates to previous values and .using, and whether boolean caching can be invalidated; done when the documentation answers each question accurately.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.