LayerRef

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

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>

import { Context, Effect, Layer, LayerRef } from "effect"

class Database extends Context.Service<Database, {
  readonly query: Effect.Effect<string>
}>()("Database") {}

const databaseLayer = Layer.succeed(Database, {
  query: Effect.succeed("result")
})

const query = Effect.gen(function*() {
  const database = yield* Database
  return yield* database.query
})

const program = Effect.scoped(
  Effect.gen(function*() {
    const ref = yield* LayerRef.make(databaseLayer, {
      idleTimeToLive: "5 seconds"
    })

    const result = yield* Effect.provide(query, ref.get)

    yield* ref.invalidate

    return result
  })
)

await Effect.runPromise(program) // => "result"

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

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

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

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

import { Context, Effect, Layer, LayerRef } from "effect"

class Database extends Context.Service<Database, {
  readonly query: Effect.Effect<string>
}>()("Database") {}

const databaseLayer = Layer.succeed(Database, {
  query: Effect.succeed("result")
})

class DatabaseRef extends LayerRef.Service<DatabaseRef>()("DatabaseRef", {
  layer: databaseLayer,
  preload: true
}) {}

const program = Effect.gen(function*() {
  const database = yield* Database
  return yield* database.query
}).pipe(
  Effect.provide(DatabaseRef.get),
  Effect.provide(DatabaseRef.layer)
)

await Effect.runPromise(program) // => "result"

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

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