Atom unstable

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.

77 exports Since v4.0.0 Source

Batching

batch

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Refreshes an atom whenever windowFocusSignal changes.

Details

Without window, this helper does not trigger refreshes. Source atom updates are still forwarded.

Signature

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

serializable

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Details

Returns the current result and defers stale-source revalidation until after the read. Skips revalidation if the source becomes fresh or the atom is disposed. Manual refreshes still forward to the source. revalidateOnMount controls initial stale refreshes; revalidateOnFocus controls focus refreshes (true respects staleTime, "always" forces refresh).

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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;
}

Example Comparing values structurally

import { Atom } from "effect/reactivity"

const point = Atom.make({ x: 0, y: 0 }).pipe(
  Atom.withEquality<{ x: number; y: number }>((a, b) => a.x === b.x && a.y === b.y)
)
point.equals({ x: 1, y: 2 }, { x: 1, y: 2 }) // => true

withFallback

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Creates a 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. Without window, it stays at 0 and adds no listener.

Signature

declare const windowFocusSignal: Atom<number>

Constructors

family

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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;
}

runtime

unstable

Since v4.0.0

Default registry-scoped RuntimeFactory.

Signature

declare const runtime: RegistryRuntimeFactory

WriteContext

interface unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

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

getResult

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Returns true when a value is an Atom.

Signature

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

isSerializable

unstable

Since v4.0.0

Returns true when an atom carries Serializable metadata.

Signature

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

isWritable

unstable

Since v4.0.0

Returns true when an atom is writable.

Signature

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

Models

Atom

interface unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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, ER | E>, A>;
}

FnContext

interface unstable

Since v4.0.0

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 unstable

Since v4.0.0

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>

RegistryRuntimeFactory

interface unstable

Since v4.0.0

A RuntimeFactory backed by an atom whose memo map is scoped to each registry.

Signature

interface RegistryRuntimeFactory extends RuntimeFactory {
  <R, E>(create: Layer<R, E, Reactivity | AtomRegistry> | (get: AtomContext) => Layer<R, E, Reactivity | AtomRegistry>): AtomRuntime<R, E>;
  readonly memoMap: Atom<MemoMap>;
}

RuntimeFactory

interface unstable

Since v4.0.0

Factory for AtomRuntime values that share 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 withReactivity: (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>) => <A extends Atom<any>>(atom: A) => A;
}

Serializable

interface unstable

Since v4.0.0

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;
  };
}

SharedRuntimeFactory

interface unstable

Since v4.0.0

A RuntimeFactory backed by a concrete memo map shared across registries.

Signature

interface SharedRuntimeFactory extends RuntimeFactory {
  <R, E>(create: Layer<R, E, Reactivity | AtomRegistry> | (get: AtomContext) => Layer<R, E, Reactivity | AtomRegistry>): AtomRuntime<R, E>;
  readonly memoMap: MemoMap;
}

Writable

interface unstable

Since v4.0.0

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;
}

Other

context

unstable

Signature

declare function context(): RegistryRuntimeFactory
declare function context(options: {
  readonly memoMap: Atom<MemoMap>;
}): RegistryRuntimeFactory
declare function context(options: {
  readonly memoMap: MemoMap;
}): SharedRuntimeFactory

Reactivity

withReactivity

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

Type of the Interrupt control symbol accepted by AtomResultFn writes.

Signature

type Interrupt = typeof Interrupt

Reset

unstable

Since v4.0.0

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 unstable

Since v4.0.0

Type of the Reset control symbol accepted by AtomResultFn writes.

Signature

type Reset = typeof Reset

Transforming

withServerValue

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

declare const SerializableTypeId: SerializableTypeId

SerializableTypeId

type unstable

Since v4.0.0

The literal type of the serializable atom marker.

Signature

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

ServerValueTypeId

unstable

Since v4.0.0

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

Signature

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

TypeId

unstable

Since v4.0.0

Runtime identifier attached to Atom values and used by isAtom.

Signature

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

TypeId

type unstable

Since v4.0.0

Type-level identifier used to recognize Atom values.

Signature

type TypeId = "~effect/reactivity/Atom"

WritableTypeId

unstable

Since v4.0.0

Runtime identifier attached to writable atoms and used by isWritable.

Signature

declare const WritableTypeId: WritableTypeId

WritableTypeId

type unstable

Since v4.0.0

Type-level identifier used to recognize writable atoms.

Signature

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

Utility Types

Failure

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

Extracts the value type produced by an Atom.

Signature

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

WithoutSerializable

type unstable

Since v4.0.0

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>>