Skip to content
// EFFECT DAYS 2026

KeyValueStore unstable

Provides effectful key/value storage for persistence backends.

KeyValueStore is a service for storing string or binary values by key. It is useful for lightweight durable state, browser storage, local files, SQL tables, tests, and as a storage building block for higher-level persistence APIs. This module includes store operations, prefixed views, schema-aware JSON storage, error values, and layers for memory, filesystem, Web Storage, and SQL-backed stores.

15 exports Since v4.0.0 Source

Combinators

prefix

unstable
Since v4.0.0

Returns a view of a KeyValueStore that prepends the given prefix to every key.

Details

keys, size, isEmpty, and clear only see entries whose key starts with the prefix, and keys returns them with the prefix removed. keys, size, and isEmpty list every key in the underlying store and filter the result, while clear delegates to clearPrefix.

Signature

declare const prefix: {
  (prefix: string): (self: KeyValueStore) => KeyValueStore;
  (self: KeyValueStore, prefix: string): KeyValueStore;
}

Constructors

make

unstable
Since v4.0.0

Constructs a KeyValueStore from primitive store operations.

Details

Default implementations are derived for has, isEmpty, clearPrefix, modify, and modifyUint8Array unless they are provided in the options.

If clearPrefix is not provided, it delegates to clear for an empty prefix and otherwise removes each key returned by keys that starts with the prefix.

Signature

declare function make(options: MakeOptions): KeyValueStore

makeStringOnly

unstable
Since v4.0.0

Adapts a string-only backing store into a KeyValueStore.

Details

Uint8Array values are stored as base64 strings. getUint8Array decodes base64 values and falls back to UTF-8 encoding for non-base64 strings.

Signature

declare function makeStringOnly(options: MakeStringOptions): KeyValueStore

Converting

toSchemaStore

unstable
Since v4.0.0

Adapts a KeyValueStore into a SchemaStore using the schema's JSON codec.

Signature

declare function toSchemaStore<S extends Constraint>(self: KeyValueStore, schema: S): SchemaStore<S>

Errors

KeyValueStoreError

unstable
Since v4.0.0

Error raised by key/value store operations, including the failed method, optional key, message, and cause.

Signature

declare class KeyValueStoreError extends YieldableError<this> & {
  readonly _tag: "KeyValueStoreError";
} & Readonly<{
  cause?: unknown;
  key?: string;
  message: string;
  method: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly key?: string;
    readonly message: string;
    readonly method: string;
  });
  readonly "~effect/persistence/KeyValueStore/KeyValueStoreError": "~effect/persistence/KeyValueStore/KeyValueStoreError";
}

Layers

layerFileSystem

unstable
Since v4.0.0

Provides a KeyValueStore backed by files in the specified directory.

Details

The directory is created if needed, and each key is percent-encoded as a single file name. Empty keys, . and .. are rejected. Keys are only guaranteed to be distinct on case-sensitive file systems.

clear removes the directory recursively, so it must not be shared with unrelated data.

Signature

declare function layerFileSystem(directory: string): Layer<KeyValueStore, PlatformError, FileSystem | Path>

layerMemory

unstable
Since v4.0.0

Provides a process-local in-memory KeyValueStore backed by a Map.

Signature

declare const layerMemory: Layer.Layer<KeyValueStore>

layerSql

unstable
Since v4.0.0

Provides a SQL-backed KeyValueStore.

Details

The layer creates the configured table if it does not exist and stores both string and binary values through the current SqlClient.

Signature

declare function layerSql(options: LayerSqlOptions): Layer<KeyValueStore, never, SqlClient>

LayerSqlOptions

interface unstable
Since v4.0.0

Options for configuring the SQL-backed KeyValueStore layer.

Signature

interface LayerSqlOptions {
  readonly table?: string;
}

layerStorage

unstable
Since v4.0.0

Provides a KeyValueStore backed by a Web Storage instance such as localStorage or sessionStorage.

Details

This layer uses the Web Storage API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API

Signature

declare function layerStorage(evaluate: LazyArg<Storage>): Layer<KeyValueStore>

Models

KeyValueStore

interface unstable
Since v4.0.0

Effectful key/value store service for string and binary values.

Signature

interface KeyValueStore {
  readonly "~effect/persistence/KeyValueStore": "~effect/persistence/KeyValueStore";
  readonly clear: Effect<void, KeyValueStoreError>;
  readonly clearPrefix: (prefix: string) => Effect<void, KeyValueStoreError>;
  readonly get: (key: string) => Effect<string | undefined, KeyValueStoreError>;
  readonly getUint8Array: (key: string) => Effect<Uint8Array<ArrayBufferLike> | undefined, KeyValueStoreError>;
  readonly has: (key: string) => Effect<boolean, KeyValueStoreError>;
  readonly isEmpty: Effect<boolean, KeyValueStoreError>;
  readonly keys: Effect<readonly Array<string>, KeyValueStoreError>;
  readonly modify: (key: string, f: (value: string) => string) => Effect<string | undefined, KeyValueStoreError>;
  readonly modifyUint8Array: (key: string, f: (value: Uint8Array) => Uint8Array) => Effect<Uint8Array<ArrayBufferLike> | undefined, KeyValueStoreError>;
  readonly remove: (key: string) => Effect<void, KeyValueStoreError>;
  readonly set: (key: string, value: string | Uint8Array<ArrayBufferLike>) => Effect<void, KeyValueStoreError>;
  readonly size: Effect<number, KeyValueStoreError>;
}

SchemaStore

interface unstable
Since v4.0.0

Schema-aware view of a KeyValueStore that stores values as encoded JSON.

Signature

interface SchemaStore<S extends Schema.Constraint> {
  readonly "~effect/persistence/KeyValueStore/SchemaStore": "~effect/persistence/KeyValueStore/SchemaStore";
  readonly clear: Effect<void, KeyValueStoreError>;
  readonly get: (key: string) => Effect<Option<S["Type"]>, SchemaError | KeyValueStoreError, S["DecodingServices"]>;
  readonly has: (key: string) => Effect<boolean, KeyValueStoreError>;
  readonly isEmpty: Effect<boolean, KeyValueStoreError>;
  readonly keys: Effect<readonly Array<string>, KeyValueStoreError>;
  readonly modify: (key: string, f: (value: S["Type"]) => S["Type"]) => Effect<Option<S["Type"]>, SchemaError | KeyValueStoreError, S["DecodingServices"] | S["EncodingServices"]>;
  readonly remove: (key: string) => Effect<void, KeyValueStoreError>;
  readonly set: (key: string, value: S["Type"]) => Effect<void, SchemaError | KeyValueStoreError, S["EncodingServices"]>;
  readonly size: Effect<number, KeyValueStoreError>;
}

Options

MakeOptions

type unstable
Since v4.0.0

Implementation callbacks used by make to construct a KeyValueStore.

Details

Primitive operations are required, while helpers such as has, isEmpty, and modify can be supplied to override the defaults.

Signature

type MakeOptions = Partial<KeyValueStore> & {
  readonly clear: Effect.Effect<void, KeyValueStoreError>;
  readonly get: (key: string) => Effect.Effect<string | undefined, KeyValueStoreError>;
  readonly getUint8Array: (key: string) => Effect.Effect<Uint8Array | undefined, KeyValueStoreError>;
  readonly keys: Effect.Effect<ReadonlyArray<string>, KeyValueStoreError>;
  readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
  readonly set: (key: string, value: string | Uint8Array) => Effect.Effect<void, KeyValueStoreError>;
  readonly size: Effect.Effect<number, KeyValueStoreError>;
}

MakeStringOptions

type unstable
Since v4.0.0

Implementation callbacks for adapting a string-only backing store into a KeyValueStore.

Signature

type MakeStringOptions = Partial<Omit<KeyValueStore, "set">> & {
  readonly clear: Effect.Effect<void, KeyValueStoreError>;
  readonly get: (key: string) => Effect.Effect<string | undefined, KeyValueStoreError>;
  readonly keys: Effect.Effect<ReadonlyArray<string>, KeyValueStoreError>;
  readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
  readonly set: (key: string, value: string) => Effect.Effect<void, KeyValueStoreError>;
  readonly size: Effect.Effect<number, KeyValueStoreError>;
}

Services

KeyValueStore

unstable
Since v4.0.0

Service tag for string and binary key/value storage.

When to use

Use to access or provide the persistence store used for lightweight durable state.

Signature

declare const KeyValueStore: Service<KeyValueStore, KeyValueStore>