jotai-effect

Effects in jotai-effect follow these behaviors:

• Synchronous Execution: Effects run synchronously in the current task after synchronous evaluations complete.
• Batched Updates: Multiple synchronous updates are batched into a single atomic transaction.
• Infinite Loop Resistance: atomEffect avoids re-running if it updates a value that it is currently watching.
• Idempotency: An effect runs exactly once per state change, regardless of how many times the effect atom is referenced.
• Cleanup: A returned function is invoked on unmount or before the effect re-evaluates due to dependency changes.
• Recursion: You can use set.recurse to trigger updates, but recursion is not supported within cleanup functions.

// Example of loop resistance
atomEffect((get, set) => {
  get(countAtom)
  set(countAtom, (value) => value + 1) // Will not loop
})

// Example of recursion
atomEffect((get, set) => {
  const count = get(countAtom)
  if (count % 10 === 0) return
  set.recurse(countAtom, (value) => value + 1)
})

Effects automatically track dependencies based on how you access atoms:

• Synchronous get: Any atom accessed via get inside the effect body is added as a dependency. Dependencies are recalculated on every run, allowing for conditional dependencies.
• Asynchronous get: Calls to get inside asynchronous blocks (e.g., inside a setTimeout) do not add dependencies.
• Cleanup get: Calls to get inside a returned cleanup function do not add dependencies.
• get.peek: Using get.peek(atom) allows you to read a value without subscribing to it as a dependency.

// Conditional dependencies
atomEffect((get, set) => {
  if (get(isEnabledAtom)) {
    // `isEnabledAtom` and `anAtom` are dependencies
    const aValue = get(anAtom)
  } else {
    // `isEnabledAtom` and `anotherAtom` are dependencies
    const anotherValue = get(anotherAtom)
  }
})

// Using peek to avoid dependencies
atomEffect((get, set) => {
  const count = get.peek(countAtom) // Will not add `countAtom` as a dependency
})

The withAtomEffect function is a higher-order function that wraps an existing Jotai atom to attach an effect to it. This allows the atom to trigger side effects whenever its state changes or when it is mounted/unmounted.

When you wrap an atom with withAtomEffect, the resulting atom retains all the original properties of the targetAtom (read/write capabilities) but gains an additional .effect property containing the Effect logic.

Key behaviors:

• The effect is automatically managed by the Jotai store.
• It handles subscription and invalidation: when the atom's value changes, the effect is re-run.
• It manages lifecycle: the effect is mounted when the atom is mounted and unmounted when the atom is unmounted.
• It provides a specialized getter and setter to the effect function to prevent infinite loops during state updates.

import { withAtomEffect } from 'jotai-effect'

// Assuming 'myAtom' is an existing Jotai atom
const atomWithEffect = withAtomEffect(myAtom, (get, set) => {
  // Your effect logic here
  const value = get(myAtom)
  console.log('Atom value changed:', value)
})

Use atomEffect to create an atom that runs a side effect. This atom is designed to be mounted within the Jotai atom tree. When the atom is mounted (e.g., by being read by a component or another atom), the provided effect function executes.

An Effect function receives two specialized arguments:

1. get: A GetterWithPeek used to read atoms. It includes a .peek() method to read an atom's value without subscribing to it.
2. set: A SetterWithRecurse used to write to atoms. It includes a .recurse() method to allow writing to atoms while bypassing certain dependency tracking constraints (useful for specific recursive update patterns).

The effect function can optionally return a Cleanup function (a function that returns void), which will be called when the atom is unmounted.

import { atomEffect } from 'jotai-effect'

const myEffectAtom = atomEffect((get, set) => {
  // 1. Perform side effect
  console.log('Effect running')

  // 2. Read atoms (subscribes to changes)
  const value = get(someAtom)

  // 3. Read atoms without subscribing
  const peekValue = get.peek(someAtom)

  // 4. Write to atoms
  set(otherAtom, newValue)

  // 5. Return cleanup function
  return () => {
    console.log('Cleaning up...')
  }
})

The observe function allows you to mount an Effect to a Jotai store, enabling side effects to run even when no React components are currently using the atoms. This is useful for running logic in vanilla JavaScript environments, background workers, or outside the React component lifecycle.

To use it, pass an Effect (created via atomEffect) and an optional Jotai Store. If no store is provided, it defaults to the store returned by getDefaultStore() from jotai/vanilla.

observe returns an Unobserve function, which you should call to stop the effect and clean up its subscription to the store.

import { observe } from 'jotai-effect'
import { atomEffect } from 'jotai-effect'
import { getDefaultStore } from 'jotai/vanilla'

const store = getDefaultStore()
const myEffect = atomEffect((...) => { /* side effect logic */ })

// Start the effect
const unobserve = observe(myEffect, store)

// Later, stop the effect
unobserve()