Store Classes

Persist provides four store classes: records, events, blobs, and key-value.

Overview

Every Persist store exposes four sub-stores, each optimized for a different data pattern. You access them as properties on the store instance returned by createStore.

Records

Records are key-value documents where each key maps to a JSON object. Records support versioning and conflict resolution during sync. Use records for structured data like user profiles, settings, or entity models.

// Write a record
await store.records.put("project:42", {
  name: "Persist",
  status: "active",
  members: ["alice", "bob"],
});

// Read it back
const project = await store.records.get("project:42");

// List all records matching a prefix
const projects = await store.records.list({ prefix: "project:" });

Events

Events are append-only log entries. Once written, events are immutable. Use events for audit trails, activity logs, or event-sourcing patterns.

// Append an event
await store.events.append("deploy", {
  service: "api",
  version: "2.4.1",
  triggeredBy: "ci",
});

// Read the last 10 events
const recent = await store.events.list({ limit: 10, order: "desc" });

Blobs

Blobs store binary data (files, images, backups). Blob storage supports streaming reads and writes and integrates with adapters like S3 for large object storage.

// Write a blob from a buffer
await store.blobs.put("backup/2026-05-11.tar.gz", buffer);

// Read it back as a stream
const stream = await store.blobs.getStream("backup/2026-05-11.tar.gz");

// List blobs in a directory
const backups = await store.blobs.list({ prefix: "backup/" });

Key-Value (KV)

KV is a simple string-to-string store for lightweight data like feature flags, counters, or cached tokens. KV operations are atomic and fast.

// Set a value
await store.kv.set("feature:dark-mode", "enabled");

// Get it
const flag = await store.kv.get("feature:dark-mode");

// Delete it
await store.kv.delete("feature:dark-mode");

Choosing the right class