Skip to content

KeyValueStore

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 Added in v4.0.0 Source

Combinators

prefix

Added in v4.0.0 Source

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

Signature

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

Constructors

make

Added in v4.0.0 Source

Constructs a KeyValueStore from primitive store operations.

Details

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

Signature

declare function make(options: MakeOptions): KeyValueStore;

makeStringOnly

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

declare const layerMemory: Layer.Layer<KeyValueStore>;

layerSql

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Options for configuring the SQL-backed KeyValueStore layer.

Signature

interface LayerSqlOptions {
  readonly table?: string;
}

layerStorage

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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