Skip to content

Persistence

Stores encoded results for Persistable requests.

The Persistence service creates scoped stores keyed by each request's PrimaryKey. Stores read and write schema-encoded Exit values with optional TTLs, letting request workflows reuse expensive or idempotent results across fibers, process restarts, or workers that share a backing store.

17 exports Added in v4.0.0 Source

Converting

unsafeTtlToExpires

Added in v4.0.0 Source

Converts a TTL to an absolute expiration timestamp in milliseconds.

Details

Returns null for no TTL and uses clock.currentTimeMillisUnsafe, so it is intended for backing-store internals.

Signature

declare function unsafeTtlToExpires(clock: Clock, ttl: Duration | undefined): number | null;

Errors

PersistenceError

Added in v4.0.0 Source

Error raised by persistence and backing-store operations.

Signature

declare class PersistenceError extends {
  readonly _tag: "PersistenceError";
  readonly cause?: unknown;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "PersistenceError";
    readonly cause?: unknown;
    readonly message: string;
  }, options?: MakeOptions]);
  readonly "~effect/persistence/Persistence/PersistenceError": "~effect/persistence/Persistence/PersistenceError";
}

Layers

layer

Added in v4.0.0 Source

Provides Persistence from BackingPersistence.

Details

The layer serializes and deserializes Persistable exits, applies per-entry TTLs, and skips writes whose TTL is zero or negative.

Signature

declare const layer: Layer<Persistence, never, BackingPersistence>;

layerBackingKvs

Added in v4.0.0 Source

Provides BackingPersistence using a KeyValueStore.

Details

Each store id becomes a key prefix, and values are stored as JSON with optional expiration timestamps.

Signature

declare const layerBackingKvs: Layer.Layer<BackingPersistence, never, KeyValueStore.KeyValueStore>;

layerBackingMemory

Added in v4.0.0 Source

Provides an in-memory BackingPersistence grouped by store id.

Details

Entries are process-local and expire according to their stored TTL.

Signature

declare const layerBackingMemory: Layer.Layer<BackingPersistence>;

layerBackingRedis

Added in v4.0.0 Source

Provides Redis-backed persistence.

Details

Each store id is used as a key prefix, values are JSON-encoded, and finite TTLs are stored with Redis expiration.

Signature

declare const layerBackingRedis: Layer.Layer<BackingPersistence, never, Redis.Redis>;

layerBackingSql

Added in v4.0.0 Source

Provides SQL-backed persistence using a shared effect_persistence table.

Details

Rows are partitioned by store_id and store JSON-encoded values with optional expiration timestamps.

Signature

declare const layerBackingSql: Layer.Layer<BackingPersistence, never, SqlClient.SqlClient>;

layerBackingSqlMultiTable

Added in v4.0.0 Source

Provides SQL-backed persistence using one table per store id.

Details

Each table is created if needed and stores JSON-encoded values with optional expiration timestamps.

Signature

declare const layerBackingSqlMultiTable: Layer.Layer<
  BackingPersistence,
  never,
  SqlClient.SqlClient
>;

layerKvs

Added in v4.0.0 Source

Provides Persistence backed by the current KeyValueStore.

Signature

declare const layerKvs: Layer.Layer<Persistence, never, KeyValueStore.KeyValueStore>;

layerMemory

Added in v4.0.0 Source

Provides Persistence backed by process-local in-memory storage.

Signature

declare const layerMemory: Layer.Layer<Persistence>;

layerRedis

Added in v4.0.0 Source

Provides Persistence backed by the current Redis service.

Signature

declare const layerRedis: Layer.Layer<Persistence, never, Redis.Redis>;

layerSql

Added in v4.0.0 Source

Provides Persistence backed by SQL using a shared persistence table.

Signature

declare const layerSql: Layer.Layer<Persistence, never, SqlClient.SqlClient>;

layerSqlMultiTable

Added in v4.0.0 Source

Provides Persistence backed by SQL with one table per store id.

Signature

declare const layerSqlMultiTable: Layer.Layer<Persistence, never, SqlClient.SqlClient>;

Models

PersistenceStore interface

Added in v4.0.0 Source

Typed store for persisted Exit values keyed by Persistable requests.

Signature

interface PersistenceStore {
  readonly clear: Effect<void, PersistenceError>;
  readonly get: <A extends Constraint, E extends Constraint>(
    key: Persistable<A, E>,
  ) => Effect<
    Exit<A["Type"], E["Type"]> | undefined,
    SchemaError | PersistenceError,
    A["DecodingServices"] | E["DecodingServices"]
  >;
  readonly getMany: <A extends Constraint, E extends Constraint>(
    keys: Iterable<Persistable<A, E>>,
  ) => Effect<
    Array<Exit<A["Type"], E["Type"]> | undefined>,
    SchemaError | PersistenceError,
    A["DecodingServices"] | E["DecodingServices"]
  >;
  readonly remove: <A extends Constraint, E extends Constraint>(
    key: Persistable<A, E>,
  ) => Effect<void, PersistenceError>;
  readonly set: <A extends Constraint, E extends Constraint>(
    key: Persistable<A, E>,
    value: Exit<A["Type"], E["Type"]>,
  ) => Effect<void, SchemaError | PersistenceError, A["EncodingServices"] | E["EncodingServices"]>;
  readonly setMany: <A extends Constraint, E extends Constraint>(
    entries: Iterable<readonly [Persistable<A, E>, Exit<A["Type"], E["Type"]>]>,
  ) => Effect<void, SchemaError | PersistenceError, A["EncodingServices"] | E["EncodingServices"]>;
}

Services

BackingPersistence

Added in v4.0.0 Source

Service for creating raw backing stores for persistence store ids.

Signature

declare class BackingPersistence extends Shape<
  "effect/persistence/BackingPersistence",
  {
    readonly make: (storeId: string) => Effect<BackingPersistenceStore, never, Scope>;
  },
  this
> {
  constructor(_: never);
}

BackingPersistenceStore interface

Added in v4.0.0 Source

Raw persistence backing store for JSON-compatible objects with optional TTLs.

Signature

interface BackingPersistenceStore {
  readonly clear: Effect<void, PersistenceError>;
  readonly get: (key: string) => Effect<object | undefined, PersistenceError>;
  readonly getMany: (
    keys: [string, ...Array<string>],
  ) => Effect<[object | undefined, ...Array<object | undefined>], PersistenceError>;
  readonly remove: (key: string) => Effect<void, PersistenceError>;
  readonly set: (
    key: string,
    value: object,
    ttl: Duration | undefined,
  ) => Effect<void, PersistenceError>;
  readonly setMany: (
    entries: [
      readonly [string, object, Duration | undefined],
      ...Array<readonly [string, object, Duration | undefined]>,
    ],
  ) => Effect<void, PersistenceError>;
}

Persistence

Added in v4.0.0 Source

Service for creating scoped stores of persisted Persistable request results.

Signature

declare class Persistence extends Shape<
  "effect/persistence/Persistence",
  {
    readonly make: (options: {
      readonly storeId: string;
      readonly timeToLive?: (exit: Exit<unknown, unknown>, key: Any) => Input;
    }) => Effect<PersistenceStore, never, Scope>;
  },
  this
> {
  constructor(_: never);
}