Atom.ts

Atom.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• Focus
  • makeRefreshOnSignal
  • refreshOnWindowFocus
  • windowFocusSignal
• KeyValueStore
  • kvs
• Optimistic
  • optimistic
  • optimisticFn
• Serializable
  • Serializable (interface)
  • isSerializable
• ServerValue
  • getServerValue
  • withServerValue
  • withServerValueInitial
• batching
  • batch
• combinators
  • autoDispose
  • debounce
  • initialValue
  • keepAlive
  • map
  • mapResult
  • serializable
  • setIdleTTL
  • setLazy
  • swr
  • transform
  • withFallback
  • withLabel
  • withRefresh
• constructors
  • context
  • family
  • fn
  • fnSync
  • make
  • pull
  • readable
  • subscriptionRef
  • writable
• context
  • AtomContext (interface)
  • WriteContext (interface)
  • defaultMemoMap
  • runtime
• converting
  • get
  • getResult
  • modify
  • mount
  • refresh
  • set
  • toStream
  • toStreamResult
  • update
• guards
  • isAtom
• models
  • Atom (interface)
  • AtomResultFn (interface)
  • AtomRuntime (interface)
  • FnContext (interface)
  • PullResult (type alias)
  • RuntimeFactory (interface)
  • Writable (interface)
• reactivity
  • withReactivity
• refinements
  • isWritable
• search params
  • searchParam
• symbols
  • Interrupt
  • Interrupt (type alias)
  • Reset
  • Reset (type alias)
• type IDs
  • SerializableTypeId
  • SerializableTypeId (type alias)
  • ServerValueTypeId
  • TypeId
  • TypeId (type alias)
  • WritableTypeId
  • WritableTypeId (type alias)
• utility types
  • Failure (type alias)
  • PullSuccess (type alias)
  • Success (type alias)
  • Type (type alias)
  • WithoutSerializable (type alias)

---

Focus

makeRefreshOnSignal

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 const makeRefreshOnSignal: <_>(signal: Atom<_>) => <A extends Atom<any>>(self: A) => WithoutSerializable<A>

Source

Since v4.0.0

refreshOnWindowFocus

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>

Source

Since v4.0.0

windowFocusSignal

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>

Source

Since v4.0.0

KeyValueStore

kvs

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 const kvs: <S extends Schema.Codec<any, any>, const Mode extends "sync" | "async" = never>(options: {
  readonly runtime: AtomRuntime<KeyValueStore.KeyValueStore, any>
  readonly key: string
  readonly schema: S
  readonly defaultValue: LazyArg<S["Type"]>
  readonly mode?: Mode | undefined
}) => Writable<"async" extends Mode ? AsyncResult.AsyncResult<S["Type"]> : S["Type"], S["Type"]>

Source

Since v4.0.0

Optimistic

optimistic

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 const optimistic: <A>(self: Atom<A>) => Writable<A, Atom<AsyncResult.AsyncResult<A, unknown>>>

Source

Since v4.0.0

optimisticFn

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 reducer: (current: NoInfer<A>, update: OW) => NoInfer<W>
    readonly fn: AtomResultFn<OW, XA, XE> | ((set: (result: NoInfer<W>) => void) => AtomResultFn<OW, XA, XE>)
  }): (self: Writable<A, Atom<AsyncResult.AsyncResult<W, unknown>>>) => AtomResultFn<OW, XA, XE>
  <A, W, XA, XE, OW = void>(
    self: Writable<A, Atom<AsyncResult.AsyncResult<W, unknown>>>,
    options: {
      readonly reducer: (current: NoInfer<A>, update: OW) => NoInfer<W>
      readonly fn: AtomResultFn<OW, XA, XE> | ((set: (result: NoInfer<W>) => void) => AtomResultFn<OW, XA, XE>)
    }
  ): AtomResultFn<OW, XA, XE>
}

Source

Since v4.0.0

Serializable

Serializable (interface)

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

export interface Serializable<S extends Schema.Constraint> {
  readonly [SerializableTypeId]: {
    readonly key: string
    readonly encode: (value: S["Type"]) => S["Encoded"]
    readonly decode: (value: S["Encoded"]) => S["Type"]
  }
}

Source

Since v4.0.0

isSerializable

Returns true when an atom carries Serializable metadata.

Signature

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

Source

Since v4.0.0

ServerValue

getServerValue

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: Registry.AtomRegistry): <A>(self: Atom<A>) => A
  <A>(self: Atom<A>, registry: Registry.AtomRegistry): A
}

Source

Since v4.0.0

withServerValue

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
}

Source

Since v4.0.0

withServerValueInitial

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

Signature

declare const withServerValueInitial: <A extends Atom<AsyncResult.AsyncResult<any, any>>>(self: A) => A

Source

Since v4.0.0

batching

batch

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

Source

Since v4.0.0

combinators

autoDispose

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 const autoDispose: <A extends Atom<any>>(self: A) => A

Source

Since v4.0.0

debounce

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: Duration.Input): <A extends Atom<any>>(self: A) => WithoutSerializable<A>
  <A extends Atom<any>>(self: A, duration: Duration.Input): WithoutSerializable<A>
}

Source

Since v4.0.0

initialValue

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

Source

Since v4.0.0

keepAlive

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

Signature

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

Source

Since v4.0.0

map

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<infer _, infer RW>] ? Writable<B, RW> : Atom<B>
  <R extends Atom<any>, B>(
    self: R,
    f: (_: Type<R>) => B
  ): [R] extends [Writable<infer _, infer RW>] ? Writable<B, RW> : Atom<B>
}

Source

Since v4.0.0

mapResult

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.AsyncResult<any, any>>, B>(
    f: (_: AsyncResult.AsyncResult.Success<Type<R>>) => B
  ): (
    self: R
  ) => [R] extends [Writable<infer _, infer RW>]
    ? Writable<AsyncResult.AsyncResult<B, AsyncResult.AsyncResult.Failure<Type<R>>>, RW>
    : Atom<AsyncResult.AsyncResult<B, AsyncResult.AsyncResult.Failure<Type<R>>>>
  <R extends Atom<AsyncResult.AsyncResult<any, any>>, B>(
    self: R,
    f: (_: AsyncResult.AsyncResult.Success<Type<R>>) => B
  ): [R] extends [Writable<infer _, infer RW>]
    ? Writable<AsyncResult.AsyncResult<B, AsyncResult.AsyncResult.Failure<Type<R>>>, RW>
    : Atom<AsyncResult.AsyncResult<B, AsyncResult.AsyncResult.Failure<Type<R>>>>
}

Source

Since v4.0.0

serializable

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 Schema.Codec<Type<R>, any>>(options: {
    readonly key: string
    readonly schema: S
  }): (self: R) => R & Serializable<S>
  <R extends Atom<any>, S extends Schema.Codec<Type<R>, any>>(
    self: R,
    options: { readonly key: string; readonly schema: S }
  ): R & Serializable<S>
}

Source

Since v4.0.0

setIdleTTL

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: Duration.Input): <A extends Atom<any>>(self: A) => A
  <A extends Atom<any>>(self: A, duration: Duration.Input): A
}

Source

Since v4.0.0

setLazy

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
}

Source

Since v4.0.0

swr

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 staleTime: Duration.Input
    readonly revalidateOnMount?: boolean | undefined
    readonly revalidateOnFocus?: boolean | "always" | undefined
    readonly focusSignal?: Atom<any> | undefined
  }): <R extends Atom<AsyncResult.AsyncResult<any, any>>>(self: R) => WithoutSerializable<R>
  <R extends Atom<AsyncResult.AsyncResult<any, any>>>(
    self: R,
    options: {
      readonly staleTime: Duration.Input
      readonly revalidateOnMount?: boolean | undefined
      readonly revalidateOnFocus?: boolean | "always" | undefined
      readonly focusSignal?: Atom<any> | undefined
    }
  ): WithoutSerializable<R>
}

Source

Since v4.0.0

transform

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> | undefined }
  ): (self: R) => [R] extends [Writable<infer _, infer RW>] ? Writable<B, RW> : Atom<B>
  <R extends Atom<any>, B>(
    self: R,
    f: (get: AtomContext, atom: R) => B,
    options?: { readonly initialValueTarget?: Atom<B> | undefined }
  ): [R] extends [Writable<infer _, infer RW>] ? Writable<B, RW> : Atom<B>
}

Source

Since v4.0.0

withFallback

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.AsyncResult<A2, E2>>
  ): <R extends Atom<AsyncResult.AsyncResult<any, any>>>(
    self: R
  ) => [R] extends [Writable<infer _, infer RW>]
    ? Writable<
        AsyncResult.AsyncResult<
          AsyncResult.AsyncResult.Success<Type<R>> | A2,
          AsyncResult.AsyncResult.Failure<Type<R>> | E2
        >,
        RW
      >
    : Atom<
        AsyncResult.AsyncResult<
          AsyncResult.AsyncResult.Success<Type<R>> | A2,
          AsyncResult.AsyncResult.Failure<Type<R>> | E2
        >
      >
  <R extends Atom<AsyncResult.AsyncResult<any, any>>, A2, E2>(
    self: R,
    fallback: Atom<AsyncResult.AsyncResult<A2, E2>>
  ): [R] extends [Writable<infer _, infer RW>]
    ? Writable<
        AsyncResult.AsyncResult<
          AsyncResult.AsyncResult.Success<Type<R>> | A2,
          AsyncResult.AsyncResult.Failure<Type<R>> | E2
        >,
        RW
      >
    : Atom<
        AsyncResult.AsyncResult<
          AsyncResult.AsyncResult.Success<Type<R>> | A2,
          AsyncResult.AsyncResult.Failure<Type<R>> | E2
        >
      >
}

Source

Since v4.0.0

withLabel

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
}

Source

Since v4.0.0

withRefresh

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: Duration.Input): <A extends Atom<any>>(self: A) => WithoutSerializable<A>
  <A extends Atom<any>>(self: A, duration: Duration.Input): WithoutSerializable<A>
}

Source

Since v4.0.0

constructors

context

Creates a RuntimeFactory backed by the supplied Layer.MemoMap.

Signature

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

Source

Since v4.0.0

family

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

Source

Since v4.0.0

fn

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.Effect<A, E, Scope.Scope | AtomRegistry>,
    options?: { readonly initialValue?: A | undefined; readonly concurrent?: boolean | undefined }
  ) => AtomResultFn<Arg, A, E>
  <E, A, Arg = void>(
    fn: (arg: Arg, get: FnContext) => Effect.Effect<A, E, Scope.Scope | AtomRegistry>,
    options?: { readonly initialValue?: A | undefined; readonly concurrent?: boolean | undefined }
  ): AtomResultFn<Arg, A, E>
  <Arg>(): <E, A>(
    fn: (arg: Arg, get: FnContext) => Stream.Stream<A, E, AtomRegistry>,
    options?: { readonly initialValue?: A | undefined; readonly concurrent?: boolean | undefined }
  ) => AtomResultFn<Arg, A, E | Cause.NoSuchElementError>
  <E, A, Arg = void>(
    fn: (arg: Arg, get: FnContext) => Stream.Stream<A, E, AtomRegistry>,
    options?: { readonly initialValue?: A | undefined; readonly concurrent?: boolean | undefined }
  ): AtomResultFn<Arg, A, E | Cause.NoSuchElementError>
}

Source

Since v4.0.0

fnSync

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.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.Option<A>, Arg>
  <A, Arg = void>(f: (arg: Arg, get: FnContext) => A, options: { readonly initialValue: A }): Writable<A, Arg>
}

Source

Since v4.0.0

make

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.Effect<A, E, Scope.Scope | AtomRegistry>,
    options?: { readonly initialValue?: A | undefined; readonly uninterruptible?: boolean | undefined }
  ): Atom<AsyncResult.AsyncResult<A, E>>
  <A, E>(
    effect: Effect.Effect<A, E, Scope.Scope | AtomRegistry>,
    options?: { readonly initialValue?: A; readonly uninterruptible?: boolean | undefined }
  ): Atom<AsyncResult.AsyncResult<A, E>>
  <A, E>(
    create: (get: AtomContext) => Stream.Stream<A, E, AtomRegistry>,
    options?: { readonly initialValue?: A }
  ): Atom<AsyncResult.AsyncResult<A, E | Cause.NoSuchElementError>>
  <A, E>(
    stream: Stream.Stream<A, E, AtomRegistry>,
    options?: { readonly initialValue?: A }
  ): Atom<AsyncResult.AsyncResult<A, E | Cause.NoSuchElementError>>
  <A>(create: (get: AtomContext) => A): Atom<A>
  <A>(initialValue: A): Writable<A>
}

Source

Since v4.0.0

pull

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 const pull: <A, E>(
  create: ((get: AtomContext) => Stream.Stream<A, E, AtomRegistry>) | Stream.Stream<A, E, AtomRegistry>,
  options?: { readonly disableAccumulation?: boolean | undefined }
) => Writable<PullResult<A, E>, void>

Source

Since v4.0.0

readable

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

Signature

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

Source

Since v4.0.0

subscriptionRef

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.SubscriptionRef<A> | ((get: AtomContext) => SubscriptionRef.SubscriptionRef<A>)): Writable<A>
  <A, E>(
    effect:
      | Effect.Effect<SubscriptionRef.SubscriptionRef<A>, E, Scope.Scope | AtomRegistry>
      | ((get: AtomContext) => Effect.Effect<SubscriptionRef.SubscriptionRef<A>, E, Scope.Scope | AtomRegistry>)
  ): Writable<AsyncResult.AsyncResult<A, E>, A>
}

Source

Since v4.0.0

writable

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

Signature

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

Source

Since v4.0.0

context

AtomContext (interface)

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

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

Source

Since v4.0.0

WriteContext (interface)

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

Signature

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

Source

Since v4.0.0

defaultMemoMap

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

Signature

declare const defaultMemoMap: Layer.MemoMap

Source

Since v4.0.0

runtime

Default RuntimeFactory created with defaultMemoMap.

Signature

declare const runtime: RuntimeFactory

Source

Since v4.0.0

converting

get

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

Signature

declare const get: <A>(self: Atom<A>) => Effect.Effect<A, never, AtomRegistry>

Source

Since v4.0.0

getResult

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 const getResult: <A, E>(
  self: Atom<AsyncResult.AsyncResult<A, E>>,
  options?: { readonly suspendOnWaiting?: boolean | undefined }
) => Effect.Effect<A, E, AtomRegistry>

Source

Since v4.0.0

modify

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.Effect<A, never, AtomRegistry>
  <R, W, A>(self: Writable<R, W>, f: (_: R) => [returnValue: A, nextValue: W]): Effect.Effect<A, never, AtomRegistry>
}

Source

Since v4.0.0

mount

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 const mount: <A>(self: Atom<A>) => Effect.Effect<void, never, AtomRegistry | Scope.Scope>

Source

Since v4.0.0

refresh

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 const refresh: <A>(self: Atom<A>) => Effect.Effect<void, never, AtomRegistry>

Source

Since v4.0.0

set

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

Signature

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

Source

Since v4.0.0

toStream

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 const toStream: <A>(self: Atom<A>) => Stream.Stream<A, never, AtomRegistry>

Source

Since v4.0.0

toStreamResult

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 const toStreamResult: <A, E>(self: Atom<AsyncResult.AsyncResult<A, E>>) => Stream.Stream<A, E, AtomRegistry>

Source

Since v4.0.0

update

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.Effect<void, never, AtomRegistry>
  <R, W>(self: Writable<R, W>, f: (_: R) => W): Effect.Effect<void, never, AtomRegistry>
}

Source

Since v4.0.0

guards

isAtom

Returns true when a value is an Atom.

Signature

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

Source

Since v4.0.0

models

Atom (interface)

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

Signature

export interface Atom<A> extends Pipeable, Inspectable.Inspectable {
  readonly [TypeId]: TypeId
  readonly keepAlive: boolean
  readonly lazy: boolean
  readonly read: (get: AtomContext) => A
  readonly refresh?: (f: <A>(atom: Atom<A>) => void) => void
  readonly label?: readonly [name: string, stack: string]
  readonly idleTTL?: number
  readonly initialValueTarget?: Atom<A>
}

Source

Since v4.0.0

AtomResultFn (interface)

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

Signature

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

Source

Since v4.0.0

AtomRuntime (interface)

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

Signature

export interface AtomRuntime<R, ER = never> extends Atom<AsyncResult.AsyncResult<Context.Context<R>, ER>> {
  readonly factory: RuntimeFactory

  readonly layer: Atom<Layer.Layer<R, ER>>

  readonly atom: {
    <A, E>(
      create: (get: AtomContext) => Effect.Effect<A, E, Scope.Scope | R | AtomRegistry | Reactivity.Reactivity>,
      options?: {
        readonly initialValue?: A
        readonly uninterruptible?: boolean | undefined
      }
    ): Atom<AsyncResult.AsyncResult<A, E | ER>>
    <A, E>(
      effect: Effect.Effect<A, E, Scope.Scope | R | AtomRegistry | Reactivity.Reactivity>,
      options?: {
        readonly initialValue?: A
        readonly uninterruptible?: boolean | undefined
      }
    ): Atom<AsyncResult.AsyncResult<A, E | ER>>
    <A, E>(
      create: (get: AtomContext) => Stream.Stream<A, E, AtomRegistry | Reactivity.Reactivity | R>,
      options?: {
        readonly initialValue?: A
      }
    ): Atom<AsyncResult.AsyncResult<A, E | ER | Cause.NoSuchElementError>>
    <A, E>(
      stream: Stream.Stream<A, E, AtomRegistry | Reactivity.Reactivity | R>,
      options?: {
        readonly initialValue?: A
      }
    ): Atom<AsyncResult.AsyncResult<A, E | ER | Cause.NoSuchElementError>>
  }

  readonly fn: {
    <Arg>(): {
      <E, A>(
        fn: (arg: Arg, get: FnContext) => Effect.Effect<A, E, Scope.Scope | AtomRegistry | Reactivity.Reactivity | R>,
        options?: {
          readonly initialValue?: A | undefined
          readonly reactivityKeys?: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
          readonly concurrent?: boolean | undefined
        }
      ): AtomResultFn<Arg, A, E | ER>
      <E, A>(
        fn: (arg: Arg, get: FnContext) => Stream.Stream<A, E, AtomRegistry | Reactivity.Reactivity | R>,
        options?: {
          readonly initialValue?: A | undefined
          readonly reactivityKeys?: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
          readonly concurrent?: boolean | undefined
        }
      ): AtomResultFn<Arg, A, E | ER | Cause.NoSuchElementError>
    }
    <E, A, Arg = void>(
      fn: (arg: Arg, get: FnContext) => Effect.Effect<A, E, Scope.Scope | AtomRegistry | Reactivity.Reactivity | R>,
      options?: {
        readonly initialValue?: A | undefined
        readonly reactivityKeys?: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
        readonly concurrent?: boolean | undefined
      }
    ): AtomResultFn<Arg, A, E | ER>
    <E, A, Arg = void>(
      fn: (arg: Arg, get: FnContext) => Stream.Stream<A, E, AtomRegistry | Reactivity.Reactivity | R>,
      options?: {
        readonly initialValue?: A | undefined
        readonly reactivityKeys?: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
        readonly concurrent?: boolean | undefined
      }
    ): AtomResultFn<Arg, A, E | ER | Cause.NoSuchElementError>
  }

  readonly pull: <A, E>(
    create:
      | ((get: AtomContext) => Stream.Stream<A, E, R | AtomRegistry | Reactivity.Reactivity>)
      | Stream.Stream<A, E, R | AtomRegistry | Reactivity.Reactivity>,
    options?: {
      readonly disableAccumulation?: boolean
      readonly initialValue?: ReadonlyArray<A>
    }
  ) => Writable<PullResult<A, E | ER>, void>

  readonly subscriptionRef: <A, E>(
    create:
      | Effect.Effect<SubscriptionRef.SubscriptionRef<A>, E, Scope.Scope | R | AtomRegistry | Reactivity.Reactivity>
      | ((
          get: AtomContext
        ) => Effect.Effect<
          SubscriptionRef.SubscriptionRef<A>,
          E,
          Scope.Scope | R | AtomRegistry | Reactivity.Reactivity
        >)
  ) => Writable<AsyncResult.AsyncResult<A, E>, A>
}

Source

Since v4.0.0

FnContext (interface)

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

Signature

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

Source

Since v4.0.0

PullResult (type alias)

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> = AsyncResult.AsyncResult<
  {
    readonly done: boolean
    readonly items: Arr.NonEmptyArray<A>
  },
  E | Cause.NoSuchElementError
>

Source

Since v4.0.0

RuntimeFactory (interface)

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

Signature

export interface RuntimeFactory {
  <R, E>(
    create:
      | Layer.Layer<R, E, AtomRegistry | Reactivity.Reactivity>
      | ((get: AtomContext) => Layer.Layer<R, E, AtomRegistry | Reactivity.Reactivity>)
  ): AtomRuntime<R, E>
  readonly memoMap: Layer.MemoMap
  readonly addGlobalLayer: <A, E>(layer: Layer.Layer<A, E, AtomRegistry | Reactivity.Reactivity>) => void

  /**
   * Uses the `Reactivity` service from the runtime to refresh the atom whenever
   * the keys change.
   */
  readonly withReactivity: (
    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
  ) => <A extends Atom<any>>(atom: A) => A
}

Source

Since v4.0.0

Writable (interface)

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

Signature

export interface Writable<R, W = R> extends Atom<R> {
  readonly [WritableTypeId]: WritableTypeId
  readonly write: (ctx: WriteContext<R>, value: W) => void
}

Source

Since v4.0.0

reactivity

withReactivity

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

Source

Since v4.0.0

refinements

isWritable

Returns true when an atom is writable.

Signature

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

Source

Since v4.0.0

search params

searchParam

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 const searchParam: <S extends Schema.Codec<any, string> = never>(
  name: string,
  options?: { readonly schema?: S | undefined }
) => Writable<[S] extends [never] ? string : Option.Option<S["Type"]>>

Source

Since v4.0.0

symbols

Interrupt

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: unique symbol

Source

Since v4.0.0

Interrupt (type alias)

Type of the Interrupt control symbol accepted by AtomResultFn writes.

Signature

type Interrupt = typeof Interrupt

Source

Since v4.0.0

Reset

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: unique symbol

Source

Since v4.0.0

Reset (type alias)

Type of the Reset control symbol accepted by AtomResultFn writes.

Signature

type Reset = typeof Reset

Source

Since v4.0.0

type IDs

SerializableTypeId

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

Signature

declare const SerializableTypeId: "~effect-atom/atom/Atom/Serializable"

Source

Since v4.0.0

SerializableTypeId (type alias)

The literal type of the serializable atom marker.

Signature

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

Source

Since v4.0.0

ServerValueTypeId

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

Signature

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

Source

Since v4.0.0

TypeId

Runtime identifier attached to Atom values and used by isAtom.

Signature

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

Source

Since v4.0.0

TypeId (type alias)

Type-level identifier used to recognize Atom values.

Signature

type TypeId = "~effect/reactivity/Atom"

Source

Since v4.0.0

WritableTypeId

Runtime identifier attached to writable atoms and used by isWritable.

Signature

declare const WritableTypeId: "~effect/reactivity/Atom/Writable"

Source

Since v4.0.0

WritableTypeId (type alias)

Type-level identifier used to recognize writable atoms.

Signature

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

Source

Since v4.0.0

utility types

Failure (type alias)

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

Signature

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

Source

Since v4.0.0

PullSuccess (type alias)

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

Signature

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

Source

Since v4.0.0

Success (type alias)

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

Signature

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

Source

Since v4.0.0

Type (type alias)

Extracts the value type produced by an Atom.

Signature

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

Source

Since v4.0.0

WithoutSerializable (type alias)

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

Signature

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

Source

Since v4.0.0