AtomRegistry unstable

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 Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Returns true when the value has the AtomRegistry type id.

Signature

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

Layers

layer

unstable

Since v4.0.0

The default layer that provides a fresh AtomRegistry.

Signature

declare const layer: Layer.Layer<AtomRegistry>

layerOptions

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 ensureNode: <A>(atom: Atom<A>) => Node<A>;
  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 preloadedSerializable: Map<string, unknown>;
  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;
  scheduleNodeRemoval(node: Node<any>): void;
}

Node

interface unstable

Since v4.0.0

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>;
  readonly canBeRemoved: boolean;
  children: Set<Node<any>>;
  listeners: Set<() => void>;
  parents: Set<Node<any>>;
  readonly value: () => A;
  readonly valueOption: () => Option<A>;
  currentState(): "uninitialized" | "stale" | "valid" | "removed";
  setInitialValue(value: A): void;
  subscribe(listener: () => void): () => void;
}

Services

AtomRegistry

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

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

TypeId

type unstable

Since v4.0.0

The literal type used to identify AtomRegistry services and values.

Signature

type TypeId = "~effect/reactivity/AtomRegistry"