Skip to content

LayerRef

Creates refreshable references to a single layer-built service context.

A LayerRef<I, E> builds one Layer into a cached Context<I>, exposes it back as a layer or scoped effect, and supports invalidation so later users can acquire a fresh context.

4 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a LayerRef from a Layer.

When to use

Use when you have one layer-built resource that should be shared, optionally kept alive while idle, and refreshed on demand.

Details

The layer is built lazily on first use unless preload is true. idleTimeToLive keeps the context cached after it stops being used, and invalidationSchedule can periodically invalidate it. When preload is true, scheduled invalidation also reacquires the context.

Gotchas

Invalidation does not revoke contexts already borrowed by active scopes; those contexts remain usable until their scopes close.

See

  • Service for defining a reusable service class around a LayerRef

Signature

declare const make: <I, E, R, X, Preload extends boolean = never, SE = never, SR = never>(
  ...args: [
    layer: Layer<I, E, R>,
    options?: {
      readonly idleTimeToLive?: Input;
      readonly invalidationSchedule?: Schedule<X, unknown, SE, SR>;
      readonly preload?: Preload;
    },
  ]
) => Effect<LayerRef<I, E>, [Preload] extends [true] ? E : never, Scope | R | SR>;

Models

LayerRef interface

Added in v4.0.0 Source

A refreshable reference to a single layer-built service context.

When to use

Use when you want to share one scoped layer resource across many users while retaining the ability to invalidate it and rebuild it later.

Details

A LayerRef is the unkeyed counterpart to a layer cache: it lazily builds the layer on first use, reuses the resulting context while it is borrowed or kept idle, and can invalidate the cached context so the next use rebuilds it.

See

  • make for constructing a LayerRef from a layer
  • Service for defining a LayerRef as a service class

Signature

interface LayerRef<in out I, in out E = never> {
  readonly "~effect/LayerRef": "~effect/LayerRef";
  readonly contextEffect: Effect<Context<I>, E, Scope>;
  readonly get: Layer<I, E>;
  readonly invalidate: Effect<void>;
  readonly rcRef: RcRef<Context<I>, E>;
  readonly refresh: Effect<void, E>;
}

Services

Service

Added in v4.0.0 Source

Creates a service class for a LayerRef.

When to use

Use when you want to name a shared layer reference as an application service and expose static helpers for providing, retrieving, and invalidating it.

Details

The returned class is a Context.Service whose value is a LayerRef. It also includes .layer, .layerNoDeps, .get, .contextEffect, and .invalidate helpers so callers do not need to access the LayerRef value directly.

See

  • make for creating a LayerRef value without defining a service class

Signature

declare function Service<Self>(): <Id extends string, I, E, R, X, Deps extends readonly Array<Layer<any, any, any>> = [], Preload extends boolean = never, SE = never, SR = never>(id: Id, options: {
  readonly dependencies?: Deps;
  readonly idleTimeToLive?: Input;
  readonly invalidationSchedule?: Schedule<X, unknown, SE, SR>;
  readonly layer: Layer<I, E, R>;
  readonly preload?: Preload;
}) => TagClass<Self, Id, I, E, R | SR, [Preload] extends [true] ? E : never, Deps[number]>

TagClass interface

Added in v4.0.0 Source

Service class shape produced by LayerRef.Service.

When to use

Use as the public type for classes returned by LayerRef.Service when an API needs to accept, return, or alias the generated service class and its static helpers.

Details

It combines a Context.Service tag for the LayerRef with default layers and helper accessors for retrieving, using, and invalidating the cached resource.

See

  • Service for creating concrete LayerRef service classes

Signature

interface TagClass<
  in out Self,
  in out Id extends string,
  in out I,
  in out E,
  in out R,
  in out LE,
  in out Deps extends Layer.Layer<any, any, any>,
> extends ServiceClass<Self, Id, LayerRef<I, E>> {
  constructor(_: never);
  readonly contextEffect: Effect<Context<I>, E, Scope | Self>;
  readonly get: Layer<I, E, Self>;
  readonly invalidate: Effect<void, never, Self>;
  readonly layer: Layer<
    Self,
    LE | Deps extends Layer<_A, _E, _R> ? _E : never,
    Exclude<R, Deps extends Layer<_A, _E, _R> ? _A : never> | Deps extends Layer<_A, _E, _R>
      ? _R
      : never
  >;
  readonly layerNoDeps: Layer<Self, LE, R>;
  readonly refresh: Effect<void, E, Self>;
}