TypeScript SDK

Install and use @cuitty/persist — the primary TypeScript SDK for records, events, blobs, and kv.

Installation

npm install @cuitty/persist
# or
bun add @cuitty/persist

The SDK requires Node.js 18+ or Bun 1.0+. It ships with full TypeScript type definitions.

Creating a store

import { createStore } from "@cuitty/persist";

const store = await createStore("my-app", {
  adapter: "sqlite",
  path: "./data/my-app.db",
});

The createStore function is async because it initializes the adapter (opening the database file, running migrations, etc.).

CRUD operations

Records

// Create or update
await store.records.put("user:1", { name: "Alice", role: "admin" });

// Read
const user = await store.records.get("user:1");
// user.key === "user:1"
// user.value === { name: "Alice", role: "admin" }
// user.version === 1
// user.updatedAt === Date

// Delete
await store.records.delete("user:1");

// List with prefix
const admins = await store.records.list({
  prefix: "user:",
  filter: (r) => r.value.role === "admin",
  limit: 50,
});

Events

await store.events.append("audit", { action: "login", userId: "1" });

const events = await store.events.list({
  stream: "audit",
  since: new Date("2026-01-01"),
  limit: 100,
});

Key-Value

await store.kv.set("config:theme", "dark");
const theme = await store.kv.get("config:theme"); // "dark"
await store.kv.delete("config:theme");

Type safety

Generic type parameters let you constrain record values:

interface User {
  name: string;
  email: string;
  plan: "free" | "pro";
}

const users = store.records.typed<User>();
await users.put("user:1", { name: "Alice", email: "a@b.com", plan: "pro" });
const u = await users.get("user:1");
// u.value.plan is typed as "free" | "pro"

Error handling

All SDK methods throw typed errors from the PersistError hierarchy:

import { NotFoundError, CapabilityError } from "@cuitty/persist";

try {
  await store.records.get("nonexistent");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log("Record not found");
  }
}

Common error types: NotFoundError, CapabilityError, ConflictError, AdapterError, ValidationError.