Skip to content

Atom

Reactive state primitives for values managed by an AtomRegistry.

An Atom describes how to produce or update one piece of reactive state. The registry runs atom reads, remembers current values, tracks dependencies between atoms, starts effects and streams, and cleans up atoms that are no longer used. This module includes the atom constructors and update helpers used for cached values, effect-backed values, streams, browser state, stored values, and server-rendered values.

76 exports Added in v4.0.0 Source

Batching

batch

Added in v4.0.0 Source

Runs synchronous atom updates as a batch.

Details

Stale nodes are rebuilt and listeners are notified after the callback completes, so dependent updates observe the final batched state.

Signature

declare const batch: (f: () => void) => void;

Combinators

autoDispose

Added in v4.0.0 Source

Allows a reactive value to be disposed of when it is not in use.

Details

Atoms have this behavior by default, so use this to undo keepAlive on a copied atom.

Signature

declare function autoDispose<A extends Atom<any>>(self: A): A;

debounce

Added in v4.0.0 Source

Creates an atom that publishes source changes only after the source has stopped changing for the specified duration.

Details

The current source value is used immediately, and any pending debounce timer is cleared when the derived atom is disposed.

Signature

declare const debounce: {
  (duration: Input): <A extends Atom<any>>(self: A) => WithoutSerializable<A>;
  <A extends Atom<any>>(self: A, duration: Input): WithoutSerializable<A>;
};

initialValue

Added in v4.0.0 Source

Pairs an atom with an initial value for registry initialization.

When to use

Use to preload an atom value when constructing or seeding a registry.

Details

The returned tuple can be supplied to AtomRegistry initial values so the atom starts with the provided value before it is first rebuilt.

Signature

declare const initialValue: {
  <A>(initialValue: A): (self: Atom<A>) => readonly [Atom<A>, A];
  <A>(self: Atom<A>, initialValue: A): readonly [Atom<A>, A];
};

keepAlive

Added in v4.0.0 Source

Returns a copy of an atom that remains cached and mounted even when no subscribers are using it.

Signature

declare function keepAlive<A extends Atom<any>>(self: A): A;

map

Added in v4.0.0 Source

Maps the current value of an atom with a pure function.

Details

When the source atom is writable, the returned atom remains writable and keeps the source atom's write input type.

Signature

declare const map: {
  <R extends Atom<any>, B>(
    f: (_: Type<R>) => B,
  ): (self: R) => [R] extends [Writable<_, RW>] ? Writable<B, RW> : Atom<B>;
  <R extends Atom<any>, B>(
    self: R,
    f: (_: Type<R>) => B,
  ): [R] extends [Writable<_, RW>] ? Writable<B, RW> : Atom<B>;
};

mapResult

Added in v4.0.0 Source

Maps the successful value inside an AsyncResult atom.

Details

Initial and failure states are preserved, and writable source atoms keep their original write input type.

Signature

declare const mapResult: {
  <R extends Atom<AsyncResult<any, any>>, B>(
    f: (_: Success<Type<R>>) => B,
  ): (
    self: R,
  ) => [R] extends [Writable<_, RW>]
    ? Writable<AsyncResult<B, Failure<Type<R>>>, RW>
    : Atom<AsyncResult<B, Failure<Type<R>>>>;
  <R extends Atom<AsyncResult<any, any>>, B>(
    self: R,
    f: (_: Success<Type<R>>) => B,
  ): [R] extends [Writable<_, RW>]
    ? Writable<AsyncResult<B, Failure<Type<R>>>, RW>
    : Atom<AsyncResult<B, Failure<Type<R>>>>;
};

optimisticFn

Added in v4.0.0 Source

Creates an AtomResultFn that applies an optimistic update before running the underlying mutation.

Details

The reducer computes the provisional value from the current value and mutation input. The wrapped function result then completes the transition or updates the optimistic value through the provided setter callback.

Signature

declare const optimisticFn: {
  <A, W, XA, XE, OW = void>(options: {
    readonly fn: AtomResultFn<OW, XA, XE> | (set: (result: NoInfer<W>) => void) => AtomResultFn<OW, XA, XE>;
    readonly reducer: (current: NoInfer<A>, update: OW) => NoInfer<W>;
  }): (self: Writable<A, Atom<AsyncResult<W, unknown>>>) => AtomResultFn<OW, XA, XE>;
  <A, W, XA, XE, OW = void>(self: Writable<A, Atom<AsyncResult<W, unknown>>>, options: {
    readonly fn: AtomResultFn<OW, XA, XE> | (set: (result: NoInfer<W>) => void) => AtomResultFn<OW, XA, XE>;
    readonly reducer: (current: NoInfer<A>, update: OW) => NoInfer<W>;
  }): AtomResultFn<OW, XA, XE>;
}

refreshOnWindowFocus

Added in v4.0.0 Source

Refreshes an atom whenever windowFocusSignal changes.

Details

This helper is browser-only because windowFocusSignal depends on window and document.visibilityState.

Signature

declare const refreshOnWindowFocus: <A extends Atom<any>>(self: A) => WithoutSerializable<A>;

serializable

Added in v4.0.0 Source

Attaches serialization metadata to an atom using a schema and stable key.

Details

The schema is converted to a JSON codec for synchronous encode/decode, and the key is also used as the atom label when the atom does not already have one.

Signature

declare const serializable: {
  <R extends Atom<any>, S extends ConstraintCodec<Type<R>, any, never, never>>(options: {
    readonly key: string;
    readonly schema: S;
  }): (self: R) => R & Serializable<S>;
  <R extends Atom<any>, S extends ConstraintCodec<Type<R>, any, never, never>>(
    self: R,
    options: {
      readonly key: string;
      readonly schema: S;
    },
  ): R & Serializable<S>;
};

setIdleTTL

Added in v4.0.0 Source

Returns a copy of an atom with an idle time-to-live: finite durations dispose it after inactivity, while an infinite duration keeps it alive.

Signature

declare const setIdleTTL: {
  (duration: Input): <A extends Atom<any>>(self: A) => A;
  <A extends Atom<any>>(self: A, duration: Input): A;
};

setLazy

Added in v4.0.0 Source

Sets whether an atom should be lazy.

Details

Lazy atoms defer recomputation while they have no active listeners or active non-lazy dependents, rebuilding the next time their value is observed.

Signature

declare const setLazy: {
  (lazy: boolean): <A extends Atom<any>>(self: A) => A;
  <A extends Atom<any>>(self: A, lazy: boolean): A;
};

swr

Added in v4.0.0 Source

Adds stale-while-revalidate refresh behavior to an async result atom.

Details

Automatic revalidation during reads is skipped while the current value is fresh within staleTime. Manual refresh calls remain forceful and always forward to the wrapped atom. Use revalidateOnMount to control whether stale data should trigger a background refresh on first mount. Use revalidateOnFocus to control focus behavior. true respects staleTime and "always" forces refetch.

Signature

declare const swr: {
  (options: {
    readonly focusSignal?: Atom<any>;
    readonly revalidateOnFocus?: boolean | "always";
    readonly revalidateOnMount?: boolean;
    readonly staleTime: Duration.Input;
  }): <R extends Atom<AsyncResult<any, any>>>(self: R) => WithoutSerializable<R>;
  <R extends Atom<AsyncResult<any, any>>>(
    self: R,
    options: {
      readonly focusSignal?: Atom<any>;
      readonly revalidateOnFocus?: boolean | "always";
      readonly revalidateOnMount?: boolean;
      readonly staleTime: Duration.Input;
    },
  ): WithoutSerializable<R>;
};

transform

Added in v4.0.0 Source

Creates a derived atom by reading another atom with a custom AtomContext function.

Details

If the source is writable, the derived atom keeps the source write input and forwards writes to the source. initialValueTarget controls which atom receives preloaded initial values for the derived atom.

Signature

declare const transform: {
  <R extends Atom<any>, B>(
    f: (get: AtomContext, atom: R) => B,
    options?: {
      readonly initialValueTarget?: Atom<B>;
    },
  ): (self: R) => [R] extends [Writable<_, RW>] ? Writable<B, RW> : Atom<B>;
  <R extends Atom<any>, B>(
    self: R,
    f: (get: AtomContext, atom: R) => B,
    options?: {
      readonly initialValueTarget?: Atom<B>;
    },
  ): [R] extends [Writable<_, RW>] ? Writable<B, RW> : Atom<B>;
};

withEquality

Added in v4.0.0 Source

Returns a copy of an atom that uses a custom equality function to detect value changes.

Details

When an atom's value is rebuilt or written, the registry compares the new value against the current one to decide whether dependents and listeners should be notified. By default the comparison uses Object.is, so a structurally equal but referentially distinct value still triggers notifications. Providing an equality function lets the atom skip updates when the new value is equal to the current one.

Signature

declare const withEquality: {
  <A>(equals: (value: A, next: A) => boolean): <T extends Atom<A>>(self: T) => T;
  <T extends Atom<any>>(self: T, equals: (value: Type<T>, next: Type<T>) => boolean): T;
};

withFallback

Added in v4.0.0 Source

Uses a fallback AsyncResult atom while the primary atom is Initial, marking the fallback result as waiting until the primary atom produces a non-initial result.

Signature

declare const withFallback: {
  <E2, A2>(
    fallback: Atom<AsyncResult<A2, E2>>,
  ): <R extends Atom<AsyncResult<any, any>>>(
    self: R,
  ) => [R] extends [Writable<_, RW>]
    ? Writable<AsyncResult<A2 | Success<Type<R>>, E2 | Failure<Type<R>>>, RW>
    : Atom<AsyncResult<A2 | Success<Type<R>>, E2 | Failure<Type<R>>>>;
  <R extends Atom<AsyncResult<any, any>>, A2, E2>(
    self: R,
    fallback: Atom<AsyncResult<A2, E2>>,
  ): [R] extends [Writable<_, RW>]
    ? Writable<AsyncResult<A2 | Success<Type<R>>, E2 | Failure<Type<R>>>, RW>
    : Atom<AsyncResult<A2 | Success<Type<R>>, E2 | Failure<Type<R>>>>;
};

withLabel

Added in v4.0.0 Source

Attaches a diagnostic label to an atom.

Details

The label is used for inspection and debugging metadata and does not change the atom's read or write behavior.

Signature

declare const withLabel: {
  (name: string): <A extends Atom<any>>(self: A) => A;
  <A extends Atom<any>>(self: A, name: string): A;
};

withRefresh

Added in v4.0.0 Source

Creates a derived atom that reads the source and schedules a refresh after the specified duration.

Details

The scheduled refresh is canceled when the derived atom's lifetime is disposed.

Signature

declare const withRefresh: {
  (duration: Input): <A extends Atom<any>>(self: A) => WithoutSerializable<A>;
  <A extends Atom<any>>(self: A, duration: Input): WithoutSerializable<A>;
};

Constants

windowFocusSignal

Added in v4.0.0 Source

Creates a browser-only signal atom that increments when the document becomes visible.

Details

It listens for visibilitychange events on window and removes the listener when the atom is disposed.

Signature

declare const windowFocusSignal: Atom<number>;

Constructors

context

Added in v4.0.0 Source

Creates a RuntimeFactory backed by the supplied Layer.MemoMap.

Signature

declare const context: (options: { readonly memoMap: Layer.MemoMap }) => RuntimeFactory;

family

Added in v4.0.0 Source

Creates a memoized atom factory that returns the same object for the same argument, using weak references for cached values when the platform supports them.

Signature

declare const family: <Arg, T extends object>(f: (arg: Arg) => T) => (arg: Arg) => T;

fn

Added in v4.0.0 Source

Creates a writable atom for an Effect or Stream function; writing an argument starts the computation and exposes its state as an AsyncResult.

Signature

declare const fn: {
  <Arg>(): <E, A>(
    fn: (arg: Arg, get: FnContext) => Effect<A, E, Scope | AtomRegistry>,
    options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
    },
  ) => AtomResultFn<Arg, A, E>;
  <E, A, Arg = void>(
    fn: (arg: Arg, get: FnContext) => Effect<A, E, Scope | AtomRegistry>,
    options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
    },
  ): AtomResultFn<Arg, A, E>;
  <Arg>(): <E, A>(
    fn: (arg: Arg, get: FnContext) => Stream<A, E, AtomRegistry>,
    options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
    },
  ) => AtomResultFn<Arg, A, NoSuchElementError | E>;
  <E, A, Arg = void>(
    fn: (arg: Arg, get: FnContext) => Stream<A, E, AtomRegistry>,
    options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
    },
  ): AtomResultFn<Arg, A, NoSuchElementError | E>;
};

fnSync

Added in v4.0.0 Source

Creates a writable atom for a synchronous function; writing an argument re-runs the function, returning Option.none before the first call unless an initial value is supplied.

Signature

declare const fnSync: {
  <Arg>(): {
    <A>(f: (arg: Arg, get: FnContext) => A): Writable<Option<A>, Arg>;
    <A>(
      f: (arg: Arg, get: FnContext) => A,
      options: {
        readonly initialValue: A;
      },
    ): Writable<A, Arg>;
  };
  <A, Arg = void>(f: (arg: Arg, get: FnContext) => A): Writable<Option<A>, Arg>;
  <A, Arg = void>(
    f: (arg: Arg, get: FnContext) => A,
    options: {
      readonly initialValue: A;
    },
  ): Writable<A, Arg>;
};

kvs

Added in v4.0.0 Source

Creates a writable atom backed by a KeyValueStore entry.

Details

Values are encoded and decoded with the supplied schema. In sync mode the atom exposes the decoded value and writes the default value when the key is missing; in async mode it exposes an AsyncResult of the decoded value.

Signature

declare function kvs<
  S extends ConstraintCodec<any, any, never, never>,
  Mode extends "sync" | "async" = never,
>(options: {
  readonly defaultValue: LazyArg<S["Type"]>;
  readonly key: string;
  readonly mode?: Mode;
  readonly runtime: AtomRuntime<KeyValueStore, any>;
  readonly schema: S;
}): Writable<"async" extends Mode ? AsyncResult<S["Type"], never> : S["Type"], S["Type"]>;

make

Added in v4.0.0 Source

Creates an atom from a synchronous value or read function, or from an Effect or Stream whose state is exposed as an AsyncResult; plain values create writable state atoms.

Signature

declare const make: {
  <A, E>(
    create: (get: AtomContext) => Effect<A, E, Scope | AtomRegistry>,
    options?: {
      readonly initialValue?: A;
      readonly uninterruptible?: boolean;
    },
  ): Atom<AsyncResult<A, E>>;
  <A, E>(
    effect: Effect<A, E, Scope | AtomRegistry>,
    options?: {
      readonly initialValue?: A;
      readonly uninterruptible?: boolean;
    },
  ): Atom<AsyncResult<A, E>>;
  <A, E>(
    create: (get: AtomContext) => Stream<A, E, AtomRegistry>,
    options?: {
      readonly initialValue?: A;
    },
  ): Atom<AsyncResult<A, NoSuchElementError | E>>;
  <A, E>(
    stream: Stream<A, E, AtomRegistry>,
    options?: {
      readonly initialValue?: A;
    },
  ): Atom<AsyncResult<A, NoSuchElementError | E>>;
  <A>(create: (get: AtomContext) => A): Atom<A>;
  <A>(initialValue: A): Writable<A>;
};

makeRefreshOnSignal

Added in v4.0.0 Source

Creates a combinator that refreshes an atom whenever the supplied signal atom changes.

Details

The derived atom also subscribes to the source atom so normal source updates are forwarded to its own value.

Signature

declare function makeRefreshOnSignal<_>(
  signal: Atom<_>,
): <A extends Atom<any>>(self: A) => WithoutSerializable<A>;

optimistic

Added in v4.0.0 Source

Wraps an atom in a writable optimistic atom.

Details

Writes accept transition atoms containing AsyncResult values. Waiting successes are shown optimistically while transitions run; when successful transitions finish, the source atom is refreshed, and failures roll the value back to the latest source value.

Signature

declare function optimistic<A>(self: Atom<A>): Writable<A, Atom<AsyncResult<A, unknown>>>;

pull

Added in v4.0.0 Source

Creates a writable atom that pulls an initial chunk from a stream and then pulls the next chunk whenever it is written to, accumulating items unless disableAccumulation is enabled.

Signature

declare function pull<A, E>(create: Stream<A, E, AtomRegistry> | (get: AtomContext) => Stream<A, E, AtomRegistry>, options?: {
  readonly disableAccumulation?: boolean;
}): Writable<PullResult<A, E>, void>

readable

Added in v4.0.0 Source

Creates a read-only atom from a read function and an optional custom refresh registration callback.

Signature

declare function readable<A>(
  read: (get: AtomContext) => A,
  refresh?: (f: <A>(atom: Atom<A>) => void) => void,
): Atom<A>;

searchParam

Added in v4.0.0 Source

Creates an atom that reads and writes a URL search parameter.

Gotchas

If you pass a schema, it has to be synchronous and have no context.

Signature

declare function searchParam<S extends ConstraintCodec<any, string, never, never> = never>(
  name: string,
  options?: {
    readonly schema?: S;
  },
): Writable<[S] extends [never] ? string : Option<S["Type"]>>;

subscriptionRef

Added in v4.0.0 Source

Creates a writable atom backed by a SubscriptionRef, or by an effect that produces one, updating from ref changes and writing atom updates back to the ref.

Signature

declare const subscriptionRef: {
  <A>(ref: SubscriptionRef<A> | (get: AtomContext) => SubscriptionRef<A>): Writable<A>;
  <A, E>(effect: Effect<SubscriptionRef<A>, E, Scope | AtomRegistry> | (get: AtomContext) => Effect<SubscriptionRef<A>, E, Scope | AtomRegistry>): Writable<AsyncResult<A, E>, A>;
}

writable

Added in v4.0.0 Source

Creates a writable atom from read and write functions, with an optional custom refresh registration callback.

Signature

declare function writable<R, W>(
  read: (get: AtomContext) => R,
  write: (ctx: WriteContext<R>, value: W) => void,
  refresh?: (f: <A>(atom: Atom<A>) => void) => void,
): Writable<R, W>;

Context

AtomContext interface

Added in v4.0.0 Source

Context passed to atom read functions for reading dependencies, awaiting AsyncResult or Option values, managing subscriptions and finalizers, refreshing atoms, and updating writable atoms.

Signature

interface AtomContext {
  <A>(atom: Atom<A>): A;
  readonly registry: AtomRegistry;
  addFinalizer(this: AtomContext, f: () => void): void;
  get<A>(this: AtomContext, atom: Atom<A>): A;
  mount<A>(this: AtomContext, atom: Atom<A>): void;
  once<A>(this: AtomContext, atom: Atom<A>): A;
  refresh<A>(this: AtomContext, atom: Atom<A>): void;
  refreshSelf(this: AtomContext): void;
  result<A, E>(
    this: AtomContext,
    atom: Atom<AsyncResult<A, E>>,
    options?: {
      readonly suspendOnWaiting?: boolean;
    },
  ): Effect<A, E>;
  resultOnce<A, E>(
    this: AtomContext,
    atom: Atom<AsyncResult<A, E>>,
    options?: {
      readonly suspendOnWaiting?: boolean;
    },
  ): Effect<A, E>;
  self<A>(this: AtomContext): Option<A>;
  set<R, W>(this: AtomContext, atom: Writable<R, W>, value: W): void;
  setResult<A, E, W>(
    this: AtomContext,
    atom: Writable<AsyncResult<A, E>, W>,
    value: W,
  ): Effect<A, E>;
  setSelf<A>(this: AtomContext, a: A): void;
  some<A>(this: AtomContext, atom: Atom<Option<A>>): Effect<A>;
  someOnce<A>(this: AtomContext, atom: Atom<Option<A>>): Effect<A>;
  stream<A>(
    this: AtomContext,
    atom: Atom<A>,
    options?: {
      readonly bufferSize?: number;
      readonly withoutInitialValue?: boolean;
    },
  ): Stream<A>;
  streamResult<A, E>(
    this: AtomContext,
    atom: Atom<AsyncResult<A, E>>,
    options?: {
      readonly bufferSize?: number;
      readonly withoutInitialValue?: boolean;
    },
  ): Stream<A, E>;
  subscribe<A>(
    this: AtomContext,
    atom: Atom<A>,
    f: (_: A) => void,
    options?: {
      readonly immediate?: boolean;
    },
  ): void;
}

defaultMemoMap

Added in v4.0.0 Source

Default Layer.MemoMap used by the module-level runtime factory.

Signature

declare const defaultMemoMap: Layer.MemoMap;

runtime

Added in v4.0.0 Source

Default RuntimeFactory created with defaultMemoMap.

Signature

declare const runtime: RuntimeFactory;

WriteContext interface

Added in v4.0.0 Source

Context passed to writable atom write functions for reading atoms, refreshing or setting the current atom, and writing to other writable atoms.

Signature

interface WriteContext<A> {
  get<T>(this: WriteContext<A>, atom: Atom<T>): T;
  refreshSelf(this: WriteContext<A>): void;
  set<R, W>(this: WriteContext<A>, atom: Writable<R, W>, value: W): void;
  setSelf(this: WriteContext<A>, a: A): void;
}

Converting

get

Added in v4.0.0 Source

Reads an atom's current value from the AtomRegistry service.

Signature

declare function get<A>(self: Atom<A>): Effect<A, never, AtomRegistry>;

getResult

Added in v4.0.0 Source

Reads an AsyncResult atom as an effect through the AtomRegistry service.

Details

The effect waits while the result is Initial, and also while it is waiting when suspendOnWaiting is enabled. Successes succeed with the value and failures fail with the result cause.

Signature

declare function getResult<A, E>(
  self: Atom<AsyncResult<A, E>>,
  options?: {
    readonly suspendOnWaiting?: boolean;
  },
): Effect<A, E, AtomRegistry>;

modify

Added in v4.0.0 Source

Reads a writable atom, computes a return value and next write value, writes the next value, and returns the computed result.

Signature

declare const modify: {
  <R, W, A>(
    f: (_: R) => [returnValue: A, nextValue: W],
  ): (self: Writable<R, W>) => Effect<A, never, AtomRegistry>;
  <R, W, A>(
    self: Writable<R, W>,
    f: (_: R) => [returnValue: A, nextValue: W],
  ): Effect<A, never, AtomRegistry>;
};

mount

Added in v4.0.0 Source

Mounts an atom in the AtomRegistry for the lifetime of the current scope.

Details

Mounting keeps the atom subscribed with a no-op listener until the scope finalizer releases it.

Signature

declare function mount<A>(self: Atom<A>): Effect<void, never, Scope | AtomRegistry>;

refresh

Added in v4.0.0 Source

Runs a refresh request for an atom through the AtomRegistry service.

When to use

Use to invalidate and recompute an atom from an Effect that has access to the active registry.

Signature

declare function refresh<A>(self: Atom<A>): Effect<void, never, AtomRegistry>;

set

Added in v4.0.0 Source

Writes a value to a writable atom through the AtomRegistry service.

Signature

declare const set: {
  <W>(value: W): <R>(self: Writable<R, W>) => Effect<void, never, AtomRegistry>;
  <R, W>(self: Writable<R, W>, value: W): Effect<void, never, AtomRegistry>;
};

toStream

Added in v4.0.0 Source

Converts an atom into a stream using the AtomRegistry service.

Details

The stream emits the atom's current value immediately and then emits subsequent changes until the stream scope is closed.

Signature

declare function toStream<A>(self: Atom<A>): Stream<A, never, AtomRegistry>;

toStreamResult

Added in v4.0.0 Source

Converts an AsyncResult atom into a stream using the AtomRegistry service.

Details

Initial results are skipped, successes are emitted as stream values, and failures fail the stream with the result cause.

Signature

declare function toStreamResult<A, E>(self: Atom<AsyncResult<A, E>>): Stream<A, E, AtomRegistry>;

update

Added in v4.0.0 Source

Updates a writable atom by reading its current value from the registry and writing the value returned by the update function.

Signature

declare const update: {
  <R, W>(f: (_: R) => W): (self: Writable<R, W>) => Effect<void, never, AtomRegistry>;
  <R, W>(self: Writable<R, W>, f: (_: R) => W): Effect<void, never, AtomRegistry>;
};

Getters

getServerValue

Added in v4.0.0 Source

Reads an atom from a registry, using its server-side read override when one is present.

Details

Nested reads performed by the override are resolved against the same registry.

Signature

declare const getServerValue: {
  (registry: AtomRegistry): <A>(self: Atom<A>) => A;
  <A>(self: Atom<A>, registry: AtomRegistry): A;
};

Guards

isAtom

Added in v4.0.0 Source

Returns true when a value is an Atom.

Signature

declare function isAtom(u: unknown): u is Atom<any>;

isSerializable

Added in v4.0.0 Source

Returns true when an atom carries Serializable metadata.

Signature

declare function isSerializable(self: Atom<any>): self is Atom<any> & Serializable<any>;

isWritable

Added in v4.0.0 Source

Returns true when an atom is writable.

Signature

declare function isWritable<R, W>(atom: Atom<R>): atom is Writable<R, W>;

Models

Atom interface

Added in v4.0.0 Source

Reactive value read by an AtomRegistry, with metadata controlling caching, laziness, refresh behavior, and initial value targeting.

Signature

interface Atom<A> extends Pipeable, Inspectable {
  readonly "~effect/reactivity/Atom": "~effect/reactivity/Atom";
  readonly idleTTL?: number;
  readonly initialValueTarget?: Atom<A>;
  readonly keepAlive: boolean;
  readonly label?: readonly [string, string];
  readonly lazy: boolean;
  readonly read: (get: AtomContext) => A;
  readonly refresh?: (f: <A>(atom: Atom<A>) => void) => void;
  equals(value: A, next: A): boolean;
}

AtomResultFn interface

Added in v4.0.0 Source

Writable async function atom whose value is an AsyncResult and whose writes accept function arguments plus Reset and Interrupt controls.

Signature

interface AtomResultFn<Arg, A, E = never> extends Writable<
  AsyncResult.AsyncResult<A, E>,
  Arg | Reset | Interrupt
> {}

AtomRuntime interface

Added in v4.0.0 Source

Atom that builds a Context from a Layer and exposes constructors for atoms, functions, pulls, and subscription refs that run with that context.

Signature

interface AtomRuntime<R, ER = never> extends Atom<AsyncResult.AsyncResult<Context.Context<R>, ER>> {
  readonly atom: {
    <A, E>(create: (get: AtomContext) => Effect<A, E, Scope | Reactivity | AtomRegistry | R>, options?: {
      readonly initialValue?: A;
      readonly uninterruptible?: boolean;
    }): Atom<AsyncResult<A, ER | E>>;
    <A, E>(effect: Effect<A, E, Scope | Reactivity | AtomRegistry | R>, options?: {
      readonly initialValue?: A;
      readonly uninterruptible?: boolean;
    }): Atom<AsyncResult<A, ER | E>>;
    <A, E>(create: (get: AtomContext) => Stream<A, E, Reactivity | AtomRegistry | R>, options?: {
      readonly initialValue?: A;
    }): Atom<AsyncResult<A, NoSuchElementError | ER | E>>;
    <A, E>(stream: Stream<A, E, Reactivity | AtomRegistry | R>, options?: {
      readonly initialValue?: A;
    }): Atom<AsyncResult<A, NoSuchElementError | ER | E>>;
  };
  readonly factory: RuntimeFactory;
  readonly fn: {
    <Arg>(): {
      <E, A>(fn: (arg: Arg, get: FnContext) => Effect<A, E, Scope | Reactivity | AtomRegistry | R>, options?: {
        readonly concurrent?: boolean;
        readonly initialValue?: A;
        readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
      }): AtomResultFn<Arg, A, ER | E>;
      <E, A>(fn: (arg: Arg, get: FnContext) => Stream<A, E, Reactivity | AtomRegistry | R>, options?: {
        readonly concurrent?: boolean;
        readonly initialValue?: A;
        readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
      }): AtomResultFn<Arg, A, NoSuchElementError | ER | E>;
    };
    <E, A, Arg = void>(fn: (arg: Arg, get: FnContext) => Effect<A, E, Scope | Reactivity | AtomRegistry | R>, options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
      readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
    }): AtomResultFn<Arg, A, ER | E>;
    <E, A, Arg = void>(fn: (arg: Arg, get: FnContext) => Stream<A, E, Reactivity | AtomRegistry | R>, options?: {
      readonly concurrent?: boolean;
      readonly initialValue?: A;
      readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
    }): AtomResultFn<Arg, A, NoSuchElementError | ER | E>;
  };
  readonly layer: Atom<Layer<R, ER, never>>;
  readonly pull: <A, E>(create: (get: AtomContext) => Stream<A, E, Reactivity | AtomRegistry | R> | Stream<A, E, Reactivity | AtomRegistry | R>, options?: {
    readonly disableAccumulation?: boolean;
    readonly initialValue?: readonly Array<A>;
  }) => Writable<PullResult<A, ER | E>, void>;
  readonly subscriptionRef: <A, E>(create: Effect<SubscriptionRef<A>, E, Scope | Reactivity | AtomRegistry | R> | (get: AtomContext) => Effect<SubscriptionRef<A>, E, Scope | Reactivity | AtomRegistry | R>) => Writable<AsyncResult<A, E>, A>;
}

FnContext interface

Added in v4.0.0 Source

Context passed to fn and fnSync computations for reading atoms, awaiting results, registering finalizers, refreshing atoms, subscribing to changes, and writing updates.

Signature

interface FnContext {
  <A>(atom: Atom<A>): A;
  readonly registry: AtomRegistry;
  addFinalizer(this: FnContext, f: () => void): void;
  mount<A>(this: FnContext, atom: Atom<A>): void;
  refresh<A>(this: FnContext, atom: Atom<A>): void;
  result<A, E>(
    this: FnContext,
    atom: Atom<AsyncResult<A, E>>,
    options?: {
      readonly suspendOnWaiting?: boolean;
    },
  ): Effect<A, E>;
  self<A>(this: FnContext): Option<A>;
  set<R, W>(this: FnContext, atom: Writable<R, W>, value: W): void;
  setResult<A, E, W>(this: FnContext, atom: Writable<AsyncResult<A, E>, W>, value: W): Effect<A, E>;
  setSelf<A>(this: FnContext, a: A): void;
  some<A>(this: FnContext, atom: Atom<Option<A>>): Effect<A>;
  stream<A>(
    this: FnContext,
    atom: Atom<A>,
    options?: {
      readonly bufferSize?: number;
      readonly withoutInitialValue?: boolean;
    },
  ): Stream<A>;
  streamResult<A, E>(
    this: FnContext,
    atom: Atom<AsyncResult<A, E>>,
    options?: {
      readonly bufferSize?: number;
      readonly withoutInitialValue?: boolean;
    },
  ): Stream<A, E>;
  subscribe<A>(
    this: FnContext,
    atom: Atom<A>,
    f: (_: A) => void,
    options?: {
      readonly immediate?: boolean;
    },
  ): void;
}

PullResult type

Added in v4.0.0 Source

AsyncResult produced by pull, containing a non-empty batch of pulled items and a done flag, or NoSuchElementError when the stream completes without items.

Signature

type PullResult<A, E = never> = AsyncResult.AsyncResult<
  {
    readonly done: boolean;
    readonly items: Arr.NonEmptyArray<A>;
  },
  E | Cause.NoSuchElementError
>;

RuntimeFactory interface

Added in v4.0.0 Source

Factory for AtomRuntime values that share a Layer.MemoMap and a set of global layers.

Signature

interface RuntimeFactory {
  <R, E>(create: Layer<R, E, Reactivity | AtomRegistry> | (get: AtomContext) => Layer<R, E, Reactivity | AtomRegistry>): AtomRuntime<R, E>;
  readonly addGlobalLayer: <A, E>(layer: Layer<A, E, Reactivity | AtomRegistry>) => void;
  readonly memoMap: MemoMap;
  readonly withReactivity: (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>) => <A extends Atom<any>>(atom: A) => A;
}

Serializable interface

Added in v4.0.0 Source

Serialization metadata attached to an atom.

Details

The key identifies the atom in dehydrated state, and the encode/decode functions convert between the atom value and the schema encoded value.

Signature

interface Serializable<S extends Schema.Constraint> {
  readonly "~effect-atom/atom/Atom/Serializable": {
    readonly decode: (value: S["Encoded"]) => S["Type"];
    readonly encode: (value: S["Type"]) => S["Encoded"];
    readonly key: string;
  };
}

Writable interface

Added in v4.0.0 Source

Atom that can also be written to, using a WriteContext and an input value to update reactive state.

Signature

interface Writable<R, W = R> extends Atom<R> {
  readonly "~effect/reactivity/Atom/Writable": "~effect/reactivity/Atom/Writable";
  readonly write: (ctx: WriteContext<R>, value: W) => void;
}

Reactivity

withReactivity

Added in v4.0.0 Source

Returns Rx.runtime.withReactivity for refreshing an atom whenever the keys change in the Reactivity service.

When to use

Use to refresh an atom whenever one or more invalidation keys change in the default reactivity runtime.

Signature

declare const withReactivity: (
  keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>,
) => <A extends Atom<any>>(atom: A) => A;

Symbols

Interrupt

Added in v4.0.0 Source

Defines the control symbol that can be written to an AtomResultFn to interrupt the current asynchronous computation.

When to use

Use when you need an AtomResultFn write value that interrupts the currently running async computation.

Signature

declare const Interrupt: typeof Interrupt;

Interrupt type

Added in v4.0.0 Source

Type of the Interrupt control symbol accepted by AtomResultFn writes.

Signature

type Interrupt = typeof Interrupt;

Reset

Added in v4.0.0 Source

Defines the control symbol that can be written to an AtomResultFn to reset it to its initial state.

When to use

Use when you need an AtomResultFn write value that clears the current async result and returns it to the initial state.

Signature

declare const Reset: typeof Reset;

Reset type

Added in v4.0.0 Source

Type of the Reset control symbol accepted by AtomResultFn writes.

Signature

type Reset = typeof Reset;

Transforming

withServerValue

Added in v4.0.0 Source

Sets the value of an Atom when read on the server.

Signature

declare const withServerValue: {
  <A extends Atom<any>>(read: (get: <A>(atom: Atom<A>) => A) => Type<A>): (self: A) => A;
  <A extends Atom<any>>(self: A, read: (get: <A>(atom: Atom<A>) => A) => Type<A>): A;
};

withServerValueInitial

Added in v4.0.0 Source

Sets an AsyncResult atom's server-side value to AsyncResult.initial(true).

Signature

declare function withServerValueInitial<A extends Atom<AsyncResult<any, any>>>(self: A): A;

Type IDs

SerializableTypeId

Added in v4.0.0 Source

The type id used to mark atoms that carry serialization metadata.

Signature

declare const SerializableTypeId: SerializableTypeId;

SerializableTypeId type

Added in v4.0.0 Source

The literal type of the serializable atom marker.

Signature

type SerializableTypeId = "~effect-atom/atom/Atom/Serializable";

ServerValueTypeId

Added in v4.0.0 Source

The type id used to mark atoms with a server-side read override.

Signature

declare const ServerValueTypeId: "~effect-atom/atom/Atom/ServerValue";

TypeId

Added in v4.0.0 Source

Runtime identifier attached to Atom values and used by isAtom.

Signature

declare const TypeId: "~effect/reactivity/Atom";

TypeId type

Added in v4.0.0 Source

Type-level identifier used to recognize Atom values.

Signature

type TypeId = "~effect/reactivity/Atom";

WritableTypeId

Added in v4.0.0 Source

Runtime identifier attached to writable atoms and used by isWritable.

Signature

declare const WritableTypeId: WritableTypeId;

WritableTypeId type

Added in v4.0.0 Source

Type-level identifier used to recognize writable atoms.

Signature

type WritableTypeId = "~effect/reactivity/Atom/Writable";

Utility Types

Failure type

Added in v4.0.0 Source

Extracts the failure error type from an atom whose value is an AsyncResult.

Signature

type Failure<T extends Atom<any>> =
  T extends Atom<AsyncResult.AsyncResult<infer _, infer E>> ? E : never;

PullSuccess type

Added in v4.0.0 Source

Extracts the item type from an atom whose value is a PullResult.

Signature

type PullSuccess<T extends Atom<any>> = T extends Atom<PullResult<infer A, infer _>> ? A : never;

Success type

Added in v4.0.0 Source

Extracts the success value type from an atom whose value is an AsyncResult.

Signature

type Success<T extends Atom<any>> =
  T extends Atom<AsyncResult.AsyncResult<infer A, infer _>> ? A : never;

Type type

Added in v4.0.0 Source

Extracts the value type produced by an Atom.

Signature

type Type<T extends Atom<any>> = T extends Atom<infer A> ? A : never;

WithoutSerializable type

Added in v4.0.0 Source

Returns an atom type without serializable metadata, preserving Writable read and write types when the input atom is writable.

Signature

type WithoutSerializable<T extends Atom<any>> =
  T extends Writable<infer R, infer W> ? Writable<R, W> : Atom<Type<T>>;