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