docs: Fixed incorrect docs regarding synchronous fallback for unimple…

[Mike-Dax]

…mented async transform

Summary

This particular line in the docs is backwards, this PR corrects it. Synchronous code can be run in an async context, but async code can't be run synchronously.

Test plan

This is a docs only change.

[facebook-github-bot]

Hi @Mike-Dax!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[mrazauskas]

The line in question sound clumsy and could be improved, but in general it seems to be correct. The point is that it speaks about transformation, not execution.

In other words, asynchronous transformation (for modules loaded through import or import()) will be handled by transformers that implement processAsync method or, if it is not found, would fall back to process method; in contrary synchronous transformation (for modules loaded through require()) requires process method to be implemented and will not work asynchronously.

Do I miss something?

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[Mike-Dax]

The line in question sound clumsy and could be improved, but in general it seems to be correct.

I think the particular sentence I have a problem with isn't strictly correct.

"Since async transformation can happen synchronously without issue..."

This first part of the sentence is not correct. If processAsync is implemented but the transformation is from a require call, synchronously, the processAsync transformation can't be used.

"...it's possible for the async case to "fall back" to the sync variant, but not vice versa."

And this second half of the sentence is correct, and contradicts the first.

The point is that it speaks about transformation, not execution.

I don't think there's a difference to the 'sidedness' of the function colouring problem that is being spoken about in this passage. In either case, process can be used as either the primary call or a fallback, but processAsync can only be used in an async context.

I think most people will read this page in the mindset of implementing a transform, so being consistent with that language is important. I've had another go at wording it, do you think that's a bit clearer?

[mrazauskas]

I like your version better. Only one detail:

synchronous transpilation cannot use the asynchronous processAsync call if process is unimplemented.

Isn’t it that synchronous transpilation cannot use processAsync at all?

[Mike-Dax]

Ah yes you're correct - I've updated that in the latest commit.

[mrazauskas]

Looks good.

Could you make the same also in versioned docs (https://github.com/facebook/jest/tree/main/website/versioned_docs), please?

Seems like only 28.x and 29.x are applicable in this case.

[Mike-Dax]

Sure thing, done in the latest commit.

[mrazauskas]

👍

[SimenB]

thanks!

[github-actions]

This pull request 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.