KeyValueStore

The @effect/platform/KeyValueStore module provides a robust and effectful interface for managing key-value pairs. It supports asynchronous operations, ensuring data integrity and consistency, and includes built-in implementations for in-memory, file system-based, and schema-validated stores.

Basic Usage

The module exposes a single service, KeyValueStore, which acts as the gateway for interacting with the store.

Example (Accessing the KeyValueStore Service)

1
import { KeyValueStore } from "@effect/platform"
2
import { Effect } from "effect"
3

4
const program = Effect.gen(function* () {
5
  const kv = yield* KeyValueStore.KeyValueStore
6

7
  // Use `kv` to perform operations on the store
8
})

The KeyValueStore interface includes the following operations:

Operation	Description
get	Returns the value as `string` of the specified key if it exists.
getUint8Array	Returns the value as `Uint8Array` of the specified key if it exists.
set	Sets the value of the specified key.
remove	Removes the specified key.
clear	Removes all entries.
size	Returns the number of entries.
modify	Updates the value of the specified key if it exists.
modifyUint8Array	Updates the value of the specified key if it exists.
has	Check if a key exists.
isEmpty	Check if the store is empty.
forSchema	Create a `SchemaStore` for the specified schema.

Example (Basic Operations with a Key-Value Store)

1
import { KeyValueStore, layerMemory } from "@effect/platform/KeyValueStore"
2
import { Effect } from "effect"
3

4
const program = Effect.gen(function* () {
5
  const kv = yield* KeyValueStore
6

7
  // Store is initially empty
8
  console.log(yield* kv.size)
9

10
  // Set a key-value pair
11
  yield* kv.set("key", "value")
12
  console.log(yield* kv.size)
13

14
  // Retrieve the value
15
  const value = yield* kv.get("key")
16
  console.log(value)
17

18
  // Remove the key
19
  yield* kv.remove("key")
20
  console.log(yield* kv.size)
21
})
22

23
// Run the program using the in-memory store implementation
24
Effect.runPromise(program.pipe(Effect.provide(layerMemory)))
25
/*
26
Output:
27
0
28
1
29
{ _id: 'Option', _tag: 'Some', value: 'value' }
30
0
31
*/

Built-in Implementations

The module includes two built-in implementations of the KeyValueStore interface. Both are provided as layers that you can inject into your effectful programs.

Implementation	Description
In-Memory Store	`layerMemory` provides a simple, in-memory key-value store, ideal for lightweight or testing scenarios.
File System Store	`layerFileSystem` offers a file-based store for persistent storage needs.

Working with Non-String Values

By default, KeyValueStore works with string and Uint8Array values. To store other types such as objects, numbers, or booleans, use the forSchema method to create a SchemaStore.

A SchemaStore uses a schema to validate and convert values. Internally, it serializes data using JSON.stringify and deserializes it with JSON.parse.

Example (Storing a Typed Object Using a Schema)

1
import { KeyValueStore, layerMemory } from "@effect/platform/KeyValueStore"
2
import { Effect, Schema } from "effect"
3

4
// Define a JSON-compatible schema
5
const Person = Schema.Struct({
6
  name: Schema.String,
7
  age: Schema.Number,
8
})
9

10
const program = Effect.gen(function* () {
11
  // Create a typed store based on the schema
12
  const kv = (yield* KeyValueStore).forSchema(Person)
13

14
  // Store a typed value
15
  const value = { name: "Alice", age: 30 }
16
  yield* kv.set("user1", value)
17
  console.log(yield* kv.size)
18

19
  // Retrieve the value
20
  console.log(yield* kv.get("user1"))
21
})
22

23
// Use the in-memory store for this example
24
Effect.runPromise(program.pipe(Effect.provide(layerMemory)))
25
/*
26
Output:
27
1
28
{ _id: 'Option', _tag: 'Some', value: { name: 'Alice', age: 30 } }
29
*/