@systemfsoftware/effect-atom-react 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,487 @@
+import * as Atom from "@systemfsoftware/effect-atom/Atom";
+import * as AtomRegistry from "@systemfsoftware/effect-atom/Registry";
+import * as AsyncResult from "@systemfsoftware/effect-atom/Result";
+import * as Effect from "effect/Effect";
+import * as React from "react";
+import * as Hydration from "@systemfsoftware/effect-atom/Hydration";
+import * as AtomRef from "@systemfsoftware/effect-atom/AtomRef";
+//#region src/Hooks.d.ts
+/**
+ * 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
+ */
+declare const useAtomInitialValues: (initialValues: Iterable<readonly [Atom.Atom<unknown>, unknown]>) => void;
+/**
+ * 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
+ */
+declare const useAtomValue: {
+  <A>(atom: Atom.Atom<A>): A;
+  <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B;
+};
+/**
+ * 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
+ */
+declare const useAtomMount: <A>(atom: Atom.Atom<A>) => void;
+/**
+ * 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.
+ *
+ * The hook mounts the atom and returns a setter that writes a complete value.
+ * For updates computed from the current value use `useAtomUpdate`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ * @see {@link useAtomSetResult} for a setter that resolves once the write settles
+ * @see {@link useAtomUpdate} for a setter that applies an updater function
+ *
+ * @category hooks
+ * @since 4.0.0
+ */
+declare const useAtomSet: <R, W>(atom: Atom.Writable<R, W>) => (value: W) => void;
+/**
+ * Mounts a writable `AsyncResult` atom and returns a setter whose returned
+ * effect resolves to the settled success value.
+ *
+ * **When to use**
+ *
+ * Use when a component writes to an `AsyncResult` atom and needs to know when
+ * the write has been applied, so a save button can show a confirming state or
+ * report a failure.
+ *
+ * The hook mounts the atom and returns a setter that writes a new value and
+ * returns the effect of the atom leaving its initial state, failing with the
+ * write result's cause when the write fails.
+ *
+ * @see {@link useAtomSet} for writing without waiting for settlement
+ *
+ * @category hooks
+ * @since 4.0.0
+ */
+declare const useAtomSetResult: <A, E, W>(atom: Atom.Writable<AsyncResult.Result<A, E>, W>) => (value: W) => Effect.Effect<A, E>;
+/**
+ * Mounts a writable atom and returns an updater that applies a function to the
+ * current value.
+ *
+ * **When to use**
+ *
+ * Use when a component needs to update a writable atom from its current value,
+ * such as incrementing a counter, without subscribing to the atom.
+ *
+ * @see {@link useAtomSet} for writing a complete value
+ *
+ * @category hooks
+ * @since 4.0.0
+ */
+declare const useAtomUpdate: <R, W>(atom: Atom.Writable<R, W>) => (f: (previous: R) => W) => void;
+/**
+ * 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
+ */
+declare const useAtomRefresh: <A>(atom: Atom.Atom<A>) => () => void;
+/**
+ * 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
+ */
+declare const useAtom: <R, W>(atom: Atom.Writable<R, W>) => readonly [value: R, write: (value: W) => void];
+/**
+ * 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
+ */
+declare const useAtomSuspense: <A, E>(atom: Atom.Atom<AsyncResult.Result<A, E>>, options?: {
+  readonly suspendOnWaiting?: boolean | undefined;
+  readonly includeFailure?: boolean | undefined;
+}) => AsyncResult.Success<A, E> | AsyncResult.Failure<A, E>;
+/**
+ * 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
+ */
+declare const useAtomSubscribe: <A>(atom: Atom.Atom<A>, f: (_: A) => void, options?: {
+  readonly immediate?: boolean;
+}) => void;
+/**
+ * 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
+ */
+declare const useAtomRef: <A>(ref: AtomRef.ReadonlyRef<A>) => A;
+/**
+ * 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
+ */
+declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => AtomRef.AtomRef<A[K]>;
+/**
+ * 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
+ */
+declare const useAtomRefPropValue: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => A[K];
+//#endregion
+//#region src/RegistryContext.d.ts
+/**
+ * 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
+ */
+declare function scheduleTask(f: () => void): () => void;
+/**
+ * Provides a 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
+ */
+declare const RegistryContext: React.Context<AtomRegistry.Registry>;
+/**
+ * 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
+ */
+declare const RegistryProvider: (options: {
+  readonly children?: React.ReactNode | undefined;
+  readonly initialValues?: Iterable<readonly [Atom.Atom<unknown>, unknown]> | undefined;
+  readonly scheduleTask?: ((f: () => void) => () => void) | undefined;
+  readonly timeoutResolution?: number | undefined;
+  readonly defaultIdleTTL?: number | undefined;
+}) => React.FunctionComponentElement<React.ProviderProps<AtomRegistry.Registry>>;
+//#endregion
+//#region src/ReactHydration.d.ts
+/**
+ * Props for a boundary that applies dehydrated Atom values to the nearest
+ * {@link RegistryContext} while rendering its children.
+ *
+ * @category components
+ * @since 4.0.0
+ */
+interface HydrationBoundaryProps {
+  state?: Iterable<Hydration.DehydratedAtomValue>;
+  children?: React.ReactNode;
+}
+/**
+ * Provides a React hydration boundary that loads dehydrated Atom values into
+ * the current Atom registry.
+ *
+ * **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
+ */
+declare const HydrationBoundary: React.FC<HydrationBoundaryProps>;
+//#endregion
+//#region src/ScopedAtom.d.ts
+/**
+ * Literal type used as the `ScopedAtom` type identifier.
+ *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+type TypeId = '~@effect/atom-react/ScopedAtom';
+/**
+ * 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
+ */
+declare const TypeId: TypeId;
+/**
+ * Scoped Atom interface with a provider-backed instance.
+ *
+ * **Example** (Providing and reading a scoped atom)
+ *
+ * ```ts import.meta.vitest
+ * import { make, useAtomValue } from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
+ * import * as React from "react"
+ * import { renderToStaticMarkup } from "react-dom/server"
+ *
+ * const Counter = make(() => Atom.make(0))
+ *
+ * function View() {
+ *   const atom = Counter.use()
+ *   const value = useAtomValue(atom)
+ *   return React.createElement("div", null, value)
+ * }
+ *
+ * export function App() {
+ *   return React.createElement(Counter.Provider, null, React.createElement(View))
+ * }
+ *
+ * renderToStaticMarkup(React.createElement(App)) // => "<div>0</div>"
+ * ```
+ *
+ * @category models
+ * @since 4.0.0
+ */
+interface ScopedAtom<A extends Atom.Atom<unknown>, Input = never> {
+  readonly [TypeId]: TypeId;
+  use(): A;
+  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 | undefined>;
+}
+/**
+ * Creates a ScopedAtom from a factory function.
+ *
+ * **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.meta.vitest
+ * import { make, useAtomValue } from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
+ * import * as React from "react"
+ * import { renderToStaticMarkup } from "react-dom/server"
+ *
+ * const User = make((name: string) => Atom.make(name))
+ *
+ * function UserName() {
+ *   const atom = User.use()
+ *   const value = useAtomValue(atom)
+ *   return React.createElement("span", null, value)
+ * }
+ *
+ * export function App() {
+ *   return React.createElement(
+ *     User.Provider,
+ *     { value: "Ada" },
+ *     React.createElement(UserName)
+ *   )
+ * }
+ *
+ * renderToStaticMarkup(React.createElement(App)) // => "<span>Ada</span>"
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const make: <A extends Atom.Atom<unknown>, Input = never>(f: (() => A) | ((input: Input) => A)) => ScopedAtom<A, Input>;
+//#endregion
+export { HydrationBoundary, HydrationBoundaryProps, RegistryContext, RegistryProvider, ScopedAtom, TypeId, make, scheduleTask, useAtom, useAtomInitialValues, useAtomMount, useAtomRef, useAtomRefProp, useAtomRefPropValue, useAtomRefresh, useAtomSet, useAtomSetResult, useAtomSubscribe, useAtomSuspense, useAtomUpdate, useAtomValue };