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

doc: update atom-effect docs #2188

Merged
merged 1 commit into from
Oct 16, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions docs/integrations/effect.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ type EffectFn = (
function atomEffect(effectFn: EffectFn): Atom<void>
```

**effectFn** (required): A function or async function for listening to state updates with `get` and writing state updates with `set`. The `effectFn` is useful for creating side effects that interact with other Jotai atoms. You can cleanup these side effects by returning a cleanup function.
**effectFn** (required): A function for listening to state updates with `get` and writing state updates with `set`. The `effectFn` is useful for creating side effects that interact with other Jotai atoms. You can cleanup these side effects by returning a cleanup function.

## Usage

Expand Down Expand Up @@ -218,7 +218,7 @@ Aside from mount events, the effect runs when any of its dependencies change val
<summary>Example</summary>

```js
const asyncEffect = atomEffect((get, set) => {
atomEffect((get, set) => {
// updates whenever `anAtom` changes value but not when `anotherAtom` changes value
get(anAtom)
setTimeout(() => {
Expand All @@ -232,12 +232,14 @@ Aside from mount events, the effect runs when any of its dependencies change val
- **Async:**
For effects that return a promise, all atoms accessed with `get` prior to the returned promise resolving are added to the atom's internal dependency map. Atoms that have been watched after the promise has resolved, for instance in a `setTimeout`, are not included in the dependency map.

⚠️ Use [caution](https://github.com/jotaijs/jotai-effect/discussions/10) when using async effects
Copy link
Member

Choose a reason for hiding this comment

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

My suggestion is to drop async, but let's merge this PR for now.


<!-- prettier-ignore -->
<details style="cursor: pointer; user-select: none;">
<summary>Example</summary>

```js
const asyncEffect = atomEffect(async (get, set) => {
atomEffect(async (get, set) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
// updates whenever `anAtom` changes value but not when `anotherAtom` changes value
get(anAtom)
Expand All @@ -257,7 +259,7 @@ Aside from mount events, the effect runs when any of its dependencies change val
<summary>Example</summary>

```js
const asyncEffect = atomEffect((get, set) => {
atomEffect((get, set) => {
// runs once on atom mount
// does not update when `idAtom` changes
const unsubscribe = subscribe((value) => {
Expand All @@ -282,7 +284,7 @@ Aside from mount events, the effect runs when any of its dependencies change val
```js
const isEnabledAtom = atom(true)

const asyncEffect = atomEffect((get, set) => {
atomEffect((get, set) => {
// if `isEnabledAtom` is true, runs when `isEnabledAtom` or `anAtom` changes value
// otherwise runs when `isEnabledAtom` or `anotherAtom` changes value
if (get(isEnabledAtom)) {
Expand Down Expand Up @@ -316,9 +318,11 @@ atomEffects are more appropriate for modeling logic in atoms.
They are scoped to the store context rather than the component.
This guarantees that a single effect will be used regardless of how many calls they have.

The same guarantee can be achieved with the useEffect hook if you ensure that the useEffect has only actioning one call.
The same guarantee can be achieved with the useEffect hook if you ensure that the useEffect has only one actioning call.

atomEffects are distinguished from useEffect in a few other ways. The can directly react to atom state changes, are resistent to infinite loops, and can be mounted conditionally.

#### Conclusion
#### It's up to you

Both useEffect and atomEffect have their own advantages and applications. Your project’s specific needs and your comfort level should guide your selection.
Always lean towards an approach that gives you a smoother, more intuitive development experience. Happy coding!