Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fixed incorrect docs regarding synchronous fallback for unimple… #14056

Merged
merged 6 commits into from
Apr 9, 2023

Conversation

Mike-Dax
Copy link
Contributor

@Mike-Dax Mike-Dax commented Apr 5, 2023

…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
Copy link
Contributor

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 cla@meta.com. Thanks!

@facebook-github-bot
Copy link
Contributor

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
Copy link
Contributor

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

1 similar comment
@facebook-github-bot
Copy link
Contributor

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

@mrazauskas
Copy link
Contributor

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
Copy link
Contributor

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

2 similar comments
@facebook-github-bot
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor Author

Mike-Dax commented Apr 6, 2023

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
Copy link
Contributor

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
Copy link
Contributor Author

Mike-Dax commented Apr 7, 2023

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

@mrazauskas
Copy link
Contributor

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
Copy link
Contributor Author

Mike-Dax commented Apr 8, 2023

Sure thing, done in the latest commit.

@mrazauskas
Copy link
Contributor

👍

Copy link
Member

@SimenB SimenB left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks!

@SimenB SimenB merged commit 88cd2cf into jestjs:main Apr 9, 2023
@github-actions
Copy link

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.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators May 10, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants