AtomRegistry

Stores and runs atoms for one reactive runtime.

An AtomRegistry evaluates atoms, caches their current values, tracks dependencies, applies writes and refreshes, manages subscriptions, and disposes unused nodes. Each registry is independent, so the same atom can hold different values in different registries. Serializable atom values can also be preloaded before the first read.

13 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates an AtomRegistry.

Details

Options can preload initial atom values, provide a custom task scheduler, configure timeout bucket resolution, and set a default idle time-to-live for unused atoms.

Signature

declare function make(options?: {
  readonly defaultIdleTTL?: number;
  readonly initialValues?: Iterable<readonly [Atom<any>, any], any, any>;
  readonly scheduleTask?: (f: () => void) => () => void;
  readonly timeoutResolution?: number;
}): AtomRegistry;

Converting

getResult

Added in v4.0.0 Source

Reads an AsyncResult atom from this registry as an effect.

Details

The effect waits for the result to leave Initial, and also waits through waiting results when suspendOnWaiting is enabled.

Signature

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

mount

Added in v4.0.0 Source

Mounts an atom in this registry for the lifetime of the current scope.

Details

The atom is subscribed with a no-op listener and the subscription is released when the scope finalizer runs.

Signature

declare const mount: {
  <A>(atom: Atom<A>): (self: AtomRegistry) => Effect<void, never, Scope>;
  <A>(self: AtomRegistry, atom: Atom<A>): Effect<void, never, Scope>;
};

toStream

Added in v4.0.0 Source

Converts an atom in this registry into a stream.

Details

The stream emits the current value immediately, emits subsequent changes, and unsubscribes from the registry when the stream scope closes.

Signature

declare const toStream: {
  <A>(atom: Atom<A>): (self: AtomRegistry) => Stream<A>;
  <A>(self: AtomRegistry, atom: Atom<A>): Stream<A>;
};

toStreamResult

Added in v4.0.0 Source

Converts an AsyncResult atom in this registry into a stream of successful values.

Details

Initial results are skipped, failures fail the stream with their cause, and duplicate stream values are dropped with Stream.changes.

Signature

declare const toStreamResult: {
  <A, E>(atom: Atom<AsyncResult<A, E>>): (self: AtomRegistry) => Stream<A, E>;
  <A, E>(self: AtomRegistry, atom: Atom<AsyncResult<A, E>>): Stream<A, E>;
};

Guards

isAtomRegistry

Added in v4.0.0 Source

Returns true when the value has the AtomRegistry type id.

Signature

declare function isAtomRegistry(u: unknown): u is AtomRegistry;

Layers

layer

Added in v4.0.0 Source

The default layer that provides a fresh AtomRegistry.

Signature

declare const layer: Layer.Layer<AtomRegistry>;

layerOptions

Added in v4.0.0 Source

Creates a layer that provides an AtomRegistry configured with the supplied options.

Details

The registry is disposed when the layer scope is finalized.

Signature

declare function layerOptions(options?: {
  readonly defaultIdleTTL?: number;
  readonly initialValues?: Iterable<readonly [Atom<any>, any], any, any>;
  readonly scheduleTask?: (f: () => void) => () => void;
  readonly timeoutResolution?: number;
}): Layer<AtomRegistry>;

Models

AtomRegistry interface

Added in v4.0.0 Source

The runtime registry that stores atom nodes and coordinates reads, writes, refreshes, subscriptions, and disposal.

Details

It also manages scheduler configuration, serializable preloaded values, and node addition/removal callbacks.

Signature

interface AtomRegistry {
  readonly "~effect/reactivity/AtomRegistry": "~effect/reactivity/AtomRegistry";
  readonly dispose: () => void;
  readonly get: <A>(atom: Atom<A>) => A;
  readonly getNodes: () => ReadonlyMap<string | Atom<any>, Node<any>>;
  readonly modify: <R, W, A>(
    atom: Writable<R, W>,
    f: (_: R) => [returnValue: A, nextValue: W],
  ) => A;
  readonly mount: <A>(atom: Atom<A>) => () => void;
  onNodeAdded?: (node: Node<any>) => void;
  onNodeRemoved?: (node: Node<any>) => void;
  readonly refresh: <A>(atom: Atom<A>) => void;
  readonly reset: () => void;
  readonly scheduler: Scheduler;
  readonly schedulerAsync: Scheduler;
  readonly set: <R, W>(atom: Writable<R, W>, value: W) => void;
  readonly setSerializable: (key: string, encoded: unknown) => void;
  readonly subscribe: <A>(
    atom: Atom<A>,
    f: (_: A) => void,
    options?: {
      readonly immediate?: boolean;
    },
  ) => () => void;
  readonly update: <R, W>(atom: Writable<R, W>, f: (_: R) => W) => void;
}

Node interface

Added in v4.0.0 Source

A registry node for a single atom.

Details

Nodes expose the current value, parent and child dependency links, listener set, and current lifecycle state.

Signature

interface Node<A> {
  readonly atom: Atom<A>;
  children: Set<Node<any>>;
  listeners: Set<() => void>;
  parents: Set<Node<any>>;
  readonly value: () => A;
  currentState(): "uninitialized" | "stale" | "valid" | "removed";
}

Services

AtomRegistry

Added in v4.0.0 Source

Service tag for the active atom runtime cache.

When to use

Use to access or provide the registry that stores atom values, dependencies, subscriptions, and disposal state for a reactive lifetime.

Signature

declare const AtomRegistry: Service<AtomRegistry, AtomRegistry>;

Type IDs

TypeId

Added in v4.0.0 Source

The runtime type id used to identify AtomRegistry services and values.

Signature

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

TypeId type

Added in v4.0.0 Source

The literal type used to identify AtomRegistry services and values.

Signature

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