Skip to content

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.

7 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<{
  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>;
}, 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>;

Services

Reactivity

Added in v4.0.0 Source

Service for key-based reactive invalidation.

When to use

Use to provide the invalidation service that refreshes queries, streams, and atoms when application keys change.

Details

The service can register handlers for keys, invalidate those keys, wrap mutations so successful effects invalidate keys, and turn query effects into queues or streams that rerun when keys are invalidated.

Signature

declare class Reactivity extends Shape<"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>;
}, this> {
  constructor(_: never);
}