Reactivity

Process-local invalidation for connecting writes to dependent reads.

This module does not cache values itself. It lets callers register handlers for keys, invalidate those keys, wrap successful mutations so they invalidate keys, and expose effects as queues or streams that rerun when matching keys change. The service can also batch invalidations so handlers run after the batch completes.

10 exports Added in v4.0.0 Source

Accessors

invalidate

Added in v4.0.0 Source

Invalidates the supplied keys through the Reactivity service.

Details

Registered queries for matching keys are rerun immediately, or collected until the enclosing reactivity batch completes.

Signature

declare function invalidate(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): Effect<void, never, Reactivity>

mutation

Added in v4.0.0 Source

Wraps an effect so the supplied keys are invalidated after the effect succeeds.

Gotchas

If the effect fails, the keys are not invalidated.

Signature

declare const mutation: {
  (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, Reactivity | R>;
  <A, E, R>(effect: Effect<A, E, R>, keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): Effect<A, E, Reactivity | R>;
}

query

Added in v4.0.0 Source

Runs an effect as a query tied to the supplied invalidation keys.

Details

The returned queue receives the initial result and each later result after the keys are invalidated. The registration is removed when the current scope closes.

Signature

declare const query: {
  (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): <A, E, R>(effect: Effect<A, E, R>) => Effect<Dequeue<A, E>, never, Scope | Reactivity | R>;
  <A, E, R>(effect: Effect<A, E, R>, keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): Effect<Dequeue<A, E>, never, Scope | Reactivity | R>;
}

stream

Added in v4.0.0 Source

Runs an effect as a stream of query results tied to the supplied invalidation keys.

Details

The effect runs initially and reruns whenever the keys are invalidated.

Signature

declare const stream: {
  (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): <A, E, R>(effect: Effect<A, E, R>) => Stream<A, E, Reactivity | Exclude<R, Scope>>;
  <A, E, R>(effect: Effect<A, E, R>, keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>): Stream<A, E, Reactivity | Exclude<R, Scope>>;
}

Constructors

make

Added in v4.0.0 Source

Creates an in-memory Reactivity service.

Details

The service tracks handlers by hashed keys and runs the registered handlers when matching keys are invalidated.

Signature

declare const make: Effect<Reactivity, never, never>

Layers

layer

Added in v4.0.0 Source

The default layer that provides an in-memory Reactivity service.

Signature

declare const layer: Layer.Layer<Reactivity>

Models

Reactivity interface

Added in v4.0.0 Source

Registers handlers and reruns queries when their keys are invalidated.

Signature

interface Reactivity {
  readonly "~effect/reactivity/Reactivity": "~effect/reactivity/Reactivity";
  readonly invalidate: (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>) => Effect<void>;
  readonly invalidateUnsafe: (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>) => void;
  readonly mutation: <A, E, R>(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, effect: Effect<A, E, R>) => Effect<A, E, R>;
  readonly query: <A, E, R>(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, effect: Effect<A, E, R>) => Effect<Dequeue<A, E>, never, Scope | R>;
  readonly registerUnsafe: (keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, handler: () => void) => () => void;
  readonly stream: <A, E, R>(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, effect: Effect<A, E, R>) => Stream<A, E, Exclude<R, Scope>>;
  readonly withBatch: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
}

Services

Reactivity

Added in v4.0.0 Source

Service key for reactive invalidation.

Signature

declare const Reactivity: Service<Reactivity, Reactivity>

Type IDs

TypeId

Added in v4.0.0 Source

Brand for Reactivity implementations.

Signature

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

TypeId type

Added in v4.0.0 Source

Brand type for Reactivity.

Signature

type TypeId = "~effect/reactivity/Reactivity"