[Documentation]: Missing documentation for @jest/create-cache-key-function

[Maximaximum]

🚀 Feature Proposal

The @jest/create-cache-key-function package has no documentation. Even though the https://jestjs.io/docs/next/code-transformation page says that transformer authors should use it to create cache keys, there's no information on how the function should be actually used. The source code doesn't contain any documentation comments neither. It would be great to have some examples.

Motivation

It's currently unclear how to use the @jest/create-cache-key-function package. It's also unclear what the getCacheKey() function on a transformer should return.

Personally, I just ended up using this code:

getCacheKey() {
  return (Math.random() * 10000000).toString();
}

which is surely an awful idea.

Example

No response

Pitch

The official Jest documentation (https://jestjs.io/docs/next/code-transformation) recommends using @jest/create-cache-key-function, but there's no information at all on HOW to use it.

[SimenB]

PR very much welcome! Example usage is here: https://github.com/facebook/react-native/blob/61e1b6f86cf98d8a74eeb9353143fe0c624fe6e6/jest/preprocessor.js#L186-L190

What is essentially does is hash the file to be transformed, pluss the content of the file(s) passed to easily invalidate if any of the files changes.

It's also unclear what the getCacheKey() function on a transformer should return.

It should return a string (usually a hash, but that doesn't really matter) that changes if the file to transform would transform into a different result. E.g. different options or (more likely) changed content of the file. Might also include version of whatever tool you use to transform (like babel etc.). Essentially - if running code transform without caching would return a different result from transform, getCacheKey should change.

Original PR might help: #10587

[shahinghasemi]

What's the benefit of getGlobalCacheKey? I assume this is to handle the case when a test's dependency changes, therefore, invalidates the cache key for that test.
For example let's say we have a test file called test.ts which requires another package like sum.ts now if sum.ts changes, then the previous cache key for this test file should be invalidated in favor of the sum changes. Am I right?
If so, how files and values parameters in getGlobalCacheKey function should be passed in getCacheKey context? Should we scan the whole file system first? I couldn't find a practical example.

[SimenB]

It's to handle if files outside of your tests (such as babel config or version) change (which are "global", instead of related directly to the file under transformation). getCacheKeyFunction returns a function which incorporates that hash into the hash for the specific file.

I couldn't find a practical example.

I linked to react native which uses it in the comment above yours

[SimenB]

https://github.com/facebook/jest/releases/tag/v28.0.0-alpha.6

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.