@effect/atom-react 4.0.0-beta.7 → 4.0.0-beta.71

package/src/Hooks.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * React hooks for reading, writing, mounting, refreshing, and subscribing to
+ * Effect atoms from the registry provided by `RegistryContext`.
+ *
+ * **Common tasks**
+ *
+ * - Read atom values in React components with {@link useAtomValue}
+ * - Read and write writable atoms with {@link useAtom}
+ * - Write without subscribing to the value with {@link useAtomSet}
+ * - Seed registry-local initial values with {@link useAtomInitialValues}
+ * - Integrate `AsyncResult` atoms with React Suspense through {@link useAtomSuspense}
+ * - Subscribe to atom changes or derive stable `AtomRef` properties
+ *
+ * **Gotchas**
+ *
+ * - Hooks use the current `RegistryContext`, so each provider has an independent atom registry
+ * - Writable atoms are mounted by the write-oriented hooks before updates are sent
+ * - Suspense support throws promises for initial or waiting `AsyncResult` values and defects for failures unless `includeFailure` is enabled
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -55,8 +73,20 @@ function useStore<A>(registry: AtomRegistry.AtomRegistry, atom: Atom.Atom<A>): A
 const initialValuesSet = new WeakMap<AtomRegistry.AtomRegistry, WeakSet<Atom.Atom<any>>>()
 
 /**
- * @since 1.0.0
+ * Seeds initial atom values in the current React atom registry.
+ *
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
+ *
+ * **Gotchas**
+ *
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom<any>, any]>): void => {
   const registry = React.useContext(RegistryContext)
@@ -74,18 +104,66 @@ export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to an atom in the current React registry and returns its current
+ * value, optionally mapped through a selector.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomValue: {
   /**
-   * @since 1.0.0
+   * Subscribes to an atom in the current React registry and returns its current
+   * value, optionally mapped through a selector.
+   *
+   * **When to use**
+   *
+   * Use when a React component needs to render from an atom value without also
+   * returning a setter.
+   *
+   * **Details**
+   *
+   * When a selector is provided, the hook maps the atom before subscribing so the
+   * component reads the selected value from the current `RegistryContext`.
+   *
+   * @see {@link useAtom} for reading and updating a writable atom from one component
+   * @see {@link useAtomRef} for reading an `AtomRef` directly
+   *
    * @category hooks
+   * @since 4.0.0
    */
   <A>(atom: Atom.Atom<A>): A
   /**
-   * @since 1.0.0
+   * Subscribes to an atom in the current React registry and returns its current
+   * value, optionally mapped through a selector.
+   *
+   * **When to use**
+   *
+   * Use when a React component needs to render from an atom value without also
+   * returning a setter.
+   *
+   * **Details**
+   *
+   * When a selector is provided, the hook maps the atom before subscribing so the
+   * component reads the selected value from the current `RegistryContext`.
+   *
+   * @see {@link useAtom} for reading and updating a writable atom from one component
+   * @see {@link useAtomRef} for reading an `AtomRef` directly
+   *
    * @category hooks
+   * @since 4.0.0
    */
   <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B
 } = <A>(atom: Atom.Atom<A>, f?: (_: A) => A): A => {
@@ -137,8 +215,25 @@ const flattenExit = <A, E>(exit: Exit.Exit<A, E>): A => {
 }
 
 /**
- * @since 1.0.0
+ * Mounts an atom in the current React registry for the lifetime of the
+ * component.
+ *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
   const registry = React.useContext(RegistryContext)
@@ -146,8 +241,23 @@ export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
 }
 
 /**
- * @since 1.0.0
+ * Mounts a writable atom and returns a setter without subscribing to its value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSet = <
   R,
@@ -172,8 +282,23 @@ export const useAtomSet = <
 }
 
 /**
- * @since 1.0.0
+ * Mounts an atom and returns a callback that refreshes it in the current React
+ * registry.
+ *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
   const registry = React.useContext(RegistryContext)
@@ -184,8 +309,19 @@ export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to a writable atom and returns its current value together with a
+ * setter for updating it.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtom = <R, W, const Mode extends "value" | "promise" | "promiseExit" = never>(
   atom: Atom.Writable<R, W>,
@@ -251,8 +387,28 @@ function atomResultOrSuspend<A, E>(
 }
 
 /**
- * @since 1.0.0
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
+ * result is initial or configured as waiting.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = false>(
   atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
@@ -270,8 +426,24 @@ export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = fal
 }
 
 /**
- * @since 1.0.0
+ * Subscribes a callback to an atom in the current React registry for the
+ * component lifetime.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSubscribe = <A>(
   atom: Atom.Atom<A>,
@@ -286,8 +458,23 @@ export const useAtomSubscribe = <A>(
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to an atom ref and returns its latest value.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
   const [, setValue] = React.useState(ref.value)
@@ -296,15 +483,47 @@ export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
 }
 
 /**
- * @since 1.0.0
+ * Returns a memoized atom ref for a property of another atom ref.
+ *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefProp = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): AtomRef.AtomRef<A[K]> =>
   React.useMemo(() => ref.prop(prop), [ref, prop])
 
 /**
- * @since 1.0.0
+ * Subscribes to a property ref derived from an atom ref and returns its current
+ * value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefPropValue = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): A[K] =>
   useAtomRef(useAtomRefProp(ref, prop))

package/src/ReactHydration.ts

@@ -1,5 +1,26 @@
 /**
- * @since 1.0.0
+ * React helpers for hydrating Atom registry state that was serialized on the
+ * server or produced by a previous render. This module exposes
+ * {@link HydrationBoundary}, a client component that receives dehydrated Atom
+ * values and applies them to the nearest {@link RegistryContext} before
+ * rendering children when it is safe to do so.
+ *
+ * **Common use cases**
+ *
+ * - Reusing Atom values that were collected during server rendering
+ * - Restoring client-side Atom state around a routed subtree
+ * - Keeping Atom-backed React trees consistent during hydration and transitions
+ *
+ * **React gotchas**
+ *
+ * - New Atom values can be hydrated during render so children see them
+ *   immediately.
+ * - Existing Atom values are queued until after commit to avoid updating the
+ *   current UI with transition data that might later be discarded.
+ * - Hydration is idempotent, so repeated or older dehydrated values are safe to
+ *   pass through the boundary.
+ *
+ * @since 4.0.0
  */
 "use client"
 import * as Hydration from "effect/unstable/reactivity/Hydration"
@@ -7,8 +28,11 @@ import * as React from "react"
 import { RegistryContext } from "./RegistryContext.ts"
 
 /**
- * @since 1.0.0
+ * Props for a boundary that applies dehydrated Atom values to the nearest
+ * {@link RegistryContext} while rendering its children.
+ *
  * @category components
+ * @since 4.0.0
  */
 export interface HydrationBoundaryProps {
   state?: Iterable<Hydration.DehydratedAtom>
@@ -16,8 +40,25 @@ export interface HydrationBoundaryProps {
 }
 
 /**
- * @since 1.0.0
+ * Hydrates dehydrated Atom values into the current Atom registry for a React
+ * subtree.
+ *
+ * **When to use**
+ *
+ * Use to apply dehydrated Atom state to a React subtree that reads from the
+ * nearest `RegistryContext`.
+ *
+ * **Details**
+ *
+ * New Atom values are hydrated during render so descendants can read them
+ * immediately, while values for existing Atoms are deferred until after commit
+ * so transition data does not update the current UI before React accepts it.
+ *
+ * @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+ * @see {@link Hydration.hydrate} for lower-level non-React hydration
+ *
  * @category components
+ * @since 4.0.0
  */
 export const HydrationBoundary: React.FC<HydrationBoundaryProps> = ({
   children,

package/src/RegistryContext.ts

@@ -1,5 +1,27 @@
 /**
- * @since 1.0.0
+ * The `RegistryContext` module provides the React context used by Effect Atom
+ * hooks to share an `AtomRegistry` across a component tree. The registry owns
+ * atom state, scheduling, and idle cleanup, so components that read or write
+ * atoms can coordinate through the same runtime instead of each creating an
+ * isolated registry.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link RegistryProvider} to scope atom state to a React subtree
+ * - Seed atoms for tests, stories, or server-provided data with `initialValues`
+ * - Override scheduling or idle timing for custom rendering environments
+ * - Read {@link RegistryContext} when integrating lower-level atom APIs
+ *
+ * **Gotchas**
+ *
+ * - This is a client module because it depends on React runtime hooks and the
+ *   scheduler package
+ * - A provider keeps the registry stable across renders and disposes it shortly
+ *   after unmount, allowing React remounts to reuse the same registry
+ * - Overriding `scheduleTask` changes when atom work is flushed, so it should
+ *   return a cancellation function compatible with React unmounts
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -9,8 +31,11 @@ import * as React from "react"
 import * as Scheduler from "scheduler"
 
 /**
- * @since 1.0.0
+ * Schedules Atom registry work with React's scheduler at low priority and
+ * returns a cancellation function for the scheduled task.
+ *
  * @category context
+ * @since 4.0.0
  */
 export function scheduleTask(f: () => void): () => void {
   const node = Scheduler.unstable_scheduleCallback(Scheduler.unstable_LowPriority, f)
@@ -18,8 +43,20 @@ export function scheduleTask(f: () => void): () => void {
 }
 
 /**
- * @since 1.0.0
+ * React context that supplies the `AtomRegistry` used by Atom hooks and
+ * hydration helpers, defaulting to a standalone registry when no provider is
+ * present.
+ *
+ * **When to use**
+ *
+ * Use to supply an existing `AtomRegistry` through React context when hooks or
+ * hydration helpers need to share registry state that is managed outside
+ * `RegistryProvider`.
+ *
+ * @see {@link RegistryProvider} for creating and providing a registry for a React subtree
+ *
  * @category context
+ * @since 4.0.0
  */
 export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(AtomRegistry.make({
   scheduleTask,
@@ -27,8 +64,30 @@ export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(At
 }))
 
 /**
- * @since 1.0.0
+ * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
+ * initial atom values and overriding registry scheduling or idle settings.
+ *
+ * **When to use**
+ *
+ * Use to scope atom state, scheduling, and idle cleanup to a React subtree.
+ *
+ * **Details**
+ *
+ * The provider creates one `AtomRegistry` with `AtomRegistry.make`, passes it
+ * through `RegistryContext.Provider`, and forwards `initialValues`,
+ * `scheduleTask`, `timeoutResolution`, and `defaultIdleTTL` only when that
+ * registry is created.
+ *
+ * **Gotchas**
+ *
+ * Option changes after the first render do not rebuild the registry. When the
+ * provider unmounts, registry disposal is delayed briefly and canceled if the
+ * provider remounts before the timeout fires.
+ *
+ * @see {@link RegistryContext} for the React context supplied by this provider
+ *
  * @category context
+ * @since 4.0.0
  */
 export const RegistryProvider = (options: {
   readonly children?: React.ReactNode | undefined

package/src/ScopedAtom.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * The `ScopedAtom` module provides a small React integration for creating atom
+ * instances that are scoped to a component subtree. A scoped atom bundles a
+ * React provider, context, and `use` accessor so each mounted provider owns its
+ * own atom instance instead of sharing a single module-level atom.
+ *
+ * Use `ScopedAtom` when an atom needs to be isolated per feature, route,
+ * component instance, test harness, or provider input. The provider may receive
+ * an initial `value` that is passed to the atom factory, making it useful for
+ * state that should be seeded from React props while still being consumed by the
+ * atom hooks in descendants.
+ *
+ * **Gotchas**
+ *
+ * - `use` must be called under the matching provider or it throws.
+ * - The provider creates the atom once for its lifetime; changing the provider
+ *   `value` prop after mount does not recreate the atom.
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -7,35 +24,42 @@ import type * as Atom from "effect/unstable/reactivity/Atom"
 import * as React from "react"
 
 /**
- * @since 1.0.0
- * @category Type IDs
+ * Literal type used as the `ScopedAtom` type identifier.
  *
- * Type identifier for ScopedAtom.
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/atom-react/ScopedAtom"
 
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
 
 /**
- * @since 1.0.0
- * @category models
- *
  * Scoped Atom interface with a provider-backed instance.
  *
- * @example
+ * **Example** (Providing and reading a scoped atom)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import { make, useAtomValue } from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const Counter = ScopedAtom.make(() => Atom.make(0))
+ * const Counter = make(() => Atom.make(0))
  *
  * function View() {
  *   const atom = Counter.use()
@@ -47,29 +71,45 @@ export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
  *   return React.createElement(Counter.Provider, null, React.createElement(View))
  * }
  * ```
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
   readonly [TypeId]: TypeId
   use(): A
-  Provider: Input extends never ? React.FC<{ readonly children?: React.ReactNode | undefined }>
+  Provider: [Input] extends [never] ? React.FC<{ readonly children?: React.ReactNode | undefined }>
     : React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }>
   Context: React.Context<A>
 }
 
 /**
- * @since 1.0.0
- * @category constructors
- *
  * Creates a ScopedAtom from a factory function.
  *
- * @example
+ * **When to use**
+ *
+ * Use to create an atom instance that is owned by a React provider and scoped
+ * to a component subtree.
+ *
+ * **Details**
+ *
+ * The returned scoped atom includes a `Provider`, `Context`, and `use`
+ * accessor. The provider creates the atom once for its lifetime, passing the
+ * `value` prop to the factory when the scoped atom expects input.
+ *
+ * **Gotchas**
+ *
+ * `use` must run under the matching provider. Changing the provider `value`
+ * prop after mount does not recreate the atom.
+ *
+ * **Example** (Creating a scoped atom with input)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import { make, useAtomValue } from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
+ * const User = make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
@@ -85,6 +125,9 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
  *   )
  * }
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = <A extends Atom.Atom<any>, Input = never>(
   f: (() => A) | ((input: Input) => A)

package/src/index.ts

@@ -1,23 +1,23 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./Hooks.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./RegistryContext.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ReactHydration.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ScopedAtom.ts"