docs(async): Rework async education #1176

TwistedMinda · 2022-05-21T16:36:28Z

I need to re-read myself a few times more but I guess the main idea is here.
I would also like to test if the loadable API could be used inside actions to also explain how preloading can be done without Suspense.

Anyways, what do you think?

EDIT: What did I do to break the prettier check? :/

vercel · 2022-05-21T16:36:33Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
jotai	✅ Ready (Inspect)	Visit Preview	May 31, 2022 at 0:44AM (UTC)

codesandbox-ci · 2022-05-21T16:37:24Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 5d3d203:

Sandbox	Source
React	Configuration
React Typescript	Configuration
React Browserify	Configuration
React Snowpack	Configuration
Next.js	Configuration
Next.js with custom Babel config	Configuration
React with custom Babel config	Configuration

dai-shi · 2022-05-21T22:24:45Z

Thanks for the suggestion.

One request: I want to limit the discussion in "BASICS" to the core module jotai. If we need to talk about loadable from jotai/utils, "GUIDES" is a better place. How about moving "Async" section to the first item of "GUIDES"?

What did I do to break the prettier check? :/

yarn run prettier will fix it. I recently added it, which had once included and been broken for a while. There are pros and cons, but appreciate for understanding.

dai-shi · 2022-05-21T22:28:39Z

docs/basics/async.mdx

@@ -80,6 +110,57 @@ const Component = () => {

 > There's no way to know as of now if an atom suspends because of `read` or `write`.


We can remove this. It's a note for pre-1.4. write will not suspend. Exception: if you write a promise object, it will suspend, but "you know it".

@dai-shi That part was so misleading me that I didn't even dare to touch it.
So you confirm me that:

cont [_, setNum] = useAtom(writeAsync) is never gonna suspend

only the below will

cont [_, setNum] = useAtom(writeAsync) is never gonna suspend React.useEffect(() => { setTimeout(() => { setNum() }, 1000) // This triggers the suspend }, [])

Are we good?

if you write a promise object, it will suspend, but "you know it".

I'm not sure I understood that part

How about moving "Async" section to the first item of "GUIDES"?

Arf I feel bad about it. I would have really liked for people to consider it basics. But I feel your pain of attacking utils straight in the basics... In that case, I would propose a re-order of the menu to put Async in top of the scene.

What do you think?
Just a proposition, we can fallback to just moving Async if you want, for now ;)

BASICS - Concepts - Primitives API - Core - Utils GUIDES - Async - Resettable <== Too simply to be a guide, should only be an util/recipe, no? - Persistence - Atoms in atom - Composing atoms EXPERIENCE - TypeScript - Debugging - Devtools - Babel - Testing - Core Internals BRIDGES - Next.js - React Native - Vite SHOWCASE: - Comparison - Showcase

@dai-shi I'm not sure how to document the loadable util correctly, tho.
Is there anything more that I should be aware of, more of the simple usage:

const loadableAtom = loadable(asyncAtom) // Does not need to be wrapped by a <React.Suspense> element const Component = () => { const value = useAtom(loadableAtom) }

I added it as last util, in my last commit, if you may review that part too ;)

cont [_, setNum] = useAtom(writeAsync) is never gonna suspend React.useEffect(() => { setTimeout(() => { setNum() }, 1000) // This triggers the suspend }, [])

It will not trigger suspend.

@dai-shi Yeah, my bad! It's only gonna suspend read() calls. Gonna clean that up

Pinpickle

@TwistedMinda I wanted to say thanks for the docs that I never got to writing for the past 6 months! I added a little nit, but it being documented is far better than the situation we're in at the moment.

Pinpickle · 2022-05-23T09:40:16Z

docs/utils/loadable.mdx

+title: loadable
+---
+
+For some reason, you may not want to profit from the React's `Suspense` core handling of jotai, and prevent your app from suspending when using async atoms.


This comes off as a little negative to me ("not want to profit"), I think there are lots of valid use-cases for loadable.

You could say something like

If you don't want async atoms to suspend or throw to an error boundary (for example, for finer-grained control of loading and error logic), you can use the loadable util. It returns a value with one of three states: loading, hasData and hasError.

@Pinpickle Sounds way better!

dai-shi · 2022-05-23T13:56:28Z

Arf I feel bad about it. I would have really liked for people to consider it basics.

If you want to keep async section in basics, I would require that to be only about jotai, so no loadable. We can still more about async in guides. I actually like it better.

dai-shi · 2022-05-23T13:57:11Z

Just a proposition, we can fallback to just moving Async if you want, for now ;)

I want @sandren 's comment on it.

TwistedMinda · 2022-05-23T15:01:33Z

@dai-shi

If you want to keep async section in basics, I would require that to be only about jotai, so no loadable. We can still more about async in guides. I actually like it better.

Hm I feel stuck now. Cutting the async guide in half seems like a bad idea to me.
I prefer your solution of moving it to Guides in total, if I had to choose

If you want to cut in 2 parts, what would you approach in each?

dai-shi · 2022-05-24T00:00:02Z

If you want to cut in 2 parts, what would you approach in each?

BASICS: only about atom(async(get) => ...) and the fact that we need <Suspense> higher in the tree, but within <Provider>.
GUIDES: async write, loadable, promise as value, infinite pending

I don't mean I'm very confident on this. So, I'd like to hear your opinions. But, I strongly feel we should have "BASICS" to explain only about jotai, no jotai/utils. If it's too confusing, "BASICS" can be only about "sync".

TwistedMinda · 2022-05-25T16:38:48Z

@dai-shi Well even after meditating I still strongly believe we shouldn't cut the Async part, as its the "most-complicated" and should not be confusing in any way!

So I moved it to guides as you recommended. But really had to move away the show-case that was preventing a good transition of basics to the first guide. A demo is not a basic, right? I moved it at the end in a Demo sub-section.

Did you review the content of the async page? Do you think it's ok for now?
I'm not experienced with async atoms enough to documentate them better, so maybe just a polish and we can let someone take over?
I actually only use the simple patterns :p

dai-shi · 2022-05-26T14:38:06Z

So I moved it to guides as you recommended.

Fair enough. I'll think about it once again.

Did you review the content of the async page?

Sorry, not yet. Please give me some time as this is such an important change/improvement.

sandren · 2022-05-26T19:39:45Z

@dai-shi I think moving the async doc to 'guides' is a good idea as it allows us to cover more than what is available in Jotai core. 🙂

dai-shi

Thanks for working on this! Looks very good. Added some comments.

docs/guides/persistence.mdx

dai-shi · 2022-05-28T06:14:25Z

readme.md

+- Demo
+ - [Comparison](./docs/basics/comparison.mdx)
+ - [Showcase](./docs/basics/showcase.mdx)


@sandren what do you think about moving them down here?
I expected many people are interested in "comparison" and "showcase" before diving into detailed docs.

@dai-shi We can move the Demo Sub-section to the top of basics, I wouldn't mind at all, like the entry point

In this PR, let's move them between Basics and Guides.
@sandren will probably re-organize anyway in follow-up PRs.

done: 5d3d203

docs/guides/async.mdx

Co-authored-by: Daishi Kato <[email protected]>

dai-shi

Let's merge this. Thanks so much for your contribution!

TwistedMinda added 5 commits May 21, 2022 03:14

fix typo

65e5b1e

rework async part

676921c

Merge branch 'main' into docs/educate-async

e0bba5d

added introduction

e0cb50f

common preload for async read

dce8477

vercel bot deployed to Preview May 21, 2022 16:37 View deployment

re-read #1

ece17fd

vercel bot deployed to Preview May 21, 2022 16:42 View deployment

dai-shi reviewed May 21, 2022

View reviewed changes

prettier & remove async old statement

3b88de3

vercel bot deployed to Preview May 22, 2022 12:30 View deployment

added loadable utils

533ca9c

vercel bot deployed to Preview May 22, 2022 12:44 View deployment

re-ran prettier

53ae1c3

vercel bot deployed to Preview May 22, 2022 12:45 View deployment

cleaned loadable

ac9ad48

vercel bot deployed to Preview May 22, 2022 12:51 View deployment

Pinpickle reviewed May 23, 2022

View reviewed changes

improve loadable intro

09b3c99

vercel bot deployed to Preview May 23, 2022 10:00 View deployment

quick update

97aa90e

vercel bot deployed to Preview May 23, 2022 10:07 View deployment

fixed write async atoms suspend timing

eabd5a7

vercel bot deployed to Preview May 23, 2022 17:15 View deployment

moved async

0fab1c7

vercel bot deployed to Preview May 25, 2022 16:32 View deployment

dai-shi reviewed May 28, 2022

View reviewed changes

TwistedMinda and others added 2 commits May 28, 2022 13:34

Update docs/guides/persistence.mdx

212ccda

Co-authored-by: Daishi Kato <[email protected]>

Update docs/guides/async.mdx

01eba22

Co-authored-by: Daishi Kato <[email protected]>

vercel bot deployed to Preview May 28, 2022 11:36 View deployment

simplify Suspense

9497f09

vercel bot deployed to Preview May 28, 2022 11:42 View deployment

Update docs/guides/async.mdx

73428bc

Co-authored-by: Daishi Kato <[email protected]>

vercel bot deployed to Preview May 28, 2022 12:12 View deployment

revert readme

5d3d203

vercel bot deployed to Preview May 31, 2022 00:44 View deployment

dai-shi approved these changes May 31, 2022

View reviewed changes

dai-shi merged commit 3a09955 into pmndrs:main May 31, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(async): Rework async education #1176

docs(async): Rework async education #1176

TwistedMinda commented May 21, 2022 •

edited

Loading

vercel bot commented May 21, 2022 •

edited

Loading

codesandbox-ci bot commented May 21, 2022 •

edited

Loading

dai-shi commented May 21, 2022

dai-shi May 21, 2022

TwistedMinda May 22, 2022

TwistedMinda May 22, 2022 •

edited

Loading

dai-shi May 23, 2022

TwistedMinda May 23, 2022

Pinpickle left a comment

Pinpickle May 23, 2022 •

edited

Loading

TwistedMinda May 23, 2022

dai-shi commented May 23, 2022

dai-shi commented May 23, 2022

TwistedMinda commented May 23, 2022 •

edited

Loading

dai-shi commented May 24, 2022

TwistedMinda commented May 25, 2022

dai-shi commented May 26, 2022

sandren commented May 26, 2022

dai-shi left a comment

dai-shi May 28, 2022

TwistedMinda May 28, 2022 •

edited

Loading

dai-shi May 28, 2022

dai-shi May 31, 2022

dai-shi left a comment •

edited

Loading

		@@ -80,6 +110,57 @@ const Component = () => {

		> There's no way to know as of now if an atom suspends because of `read` or `write`.

docs(async): Rework async education #1176

docs(async): Rework async education #1176

Conversation

TwistedMinda commented May 21, 2022 • edited Loading

vercel bot commented May 21, 2022 • edited Loading

codesandbox-ci bot commented May 21, 2022 • edited Loading

dai-shi commented May 21, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TwistedMinda May 22, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pinpickle left a comment

Choose a reason for hiding this comment

Pinpickle May 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dai-shi commented May 23, 2022

dai-shi commented May 23, 2022

TwistedMinda commented May 23, 2022 • edited Loading

dai-shi commented May 24, 2022

TwistedMinda commented May 25, 2022

dai-shi commented May 26, 2022

sandren commented May 26, 2022

dai-shi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TwistedMinda May 28, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dai-shi left a comment • edited Loading

Choose a reason for hiding this comment

TwistedMinda commented May 21, 2022 •

edited

Loading

vercel bot commented May 21, 2022 •

edited

Loading

codesandbox-ci bot commented May 21, 2022 •

edited

Loading

TwistedMinda May 22, 2022 •

edited

Loading

Pinpickle May 23, 2022 •

edited

Loading

TwistedMinda commented May 23, 2022 •

edited

Loading

TwistedMinda May 28, 2022 •

edited

Loading

dai-shi left a comment •

edited

Loading