TypeScript SDK

Install and use @cuitty/store/client for records, events, blobs, and kv.

Installation

npm install @cuitty/store/client
# or
bun add @cuitty/store/client

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

Creating a client

import { createStore } from "@cuitty/store/client";

const store = await createStore({
  module: "my-app",
  profile: {
    id: "local-dev",
    name: "Local Dev",
    local: { adapter: "local.sqlite", path: ".cuitty/store/dev.sqlite" },
    remotes: [],
    routes: [],
    encryption: { atRest: "disabled", remote: "disabled", p2p: "disabled" },
    sync: { mode: "manual" },
  },
  schema: {
    users: { class: "record" },
    audit: { class: "event" },
    settings: { class: "kv" },
  },
  actorId: "device:local",
});

The createStore function is async because it initializes the profile, local state, and storage handles.

CRUD operations

Records

const users = store.record("users");

await users.put("user:1", { name: "Alice", role: "admin" });

const user = await users.get("user:1");
// user === { name: "Alice", role: "admin" }

await users.delete("user:1");

const admins = await users.query({
  where: { role: "admin" },
  limit: 50,
});

Events

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

const events = await audit.query({
  orderBy: [{ field: "createdAt", direction: "desc" }],
  limit: 100,
});

Key-Value

const settings = store.kv("settings");

await settings.set("config:theme", "dark");
const theme = await settings.get("config:theme"); // "dark"
await settings.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.record<User>("users");
await users.put("user:1", { name: "Alice", email: "a@b.com", plan: "pro" });
const u = await users.get("user:1");
// u?.plan is typed as "free" | "pro"

Error handling

Read methods return null when a record or key is missing. Configuration and profile validation failures throw regular Error objects with redacted messages.

const missing = await store.record("users").get("nonexistent");
if (missing === null) {
  console.log("Record not found");
}

For adapter-level validation and health checks, use testAdapter() from @cuitty/store/adapters.