Reactivity unstable

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

Accessors

invalidate

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

declare const layer: Layer.Layer<Reactivity>

Models

Reactivity

interface unstable

Since v4.0.0

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

unstable

Since v4.0.0

Service key for reactive invalidation.

Signature

declare const Reactivity: Service<Reactivity, Reactivity>

Type IDs

TypeId

unstable

Since v4.0.0

Brand for Reactivity implementations.

Signature

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

TypeId

type unstable

Since v4.0.0

Brand type for Reactivity.

Signature

type TypeId = "~effect/reactivity/Reactivity"