Key-value store

kv keeps small JSON values and counters under a key, with an optional expiry, scoped to the tenant. It runs on a file or memory in development and on Redis in production.

kv:
  driver: redis
  redis: { url: secret:REDIS_URL, prefix: myapp }

import { kv } from "mainsdk";

const hits = await kv.incr(`rate:${ip}`, { ttl: "1m" });   // a fixed one-minute window
await kv.set(`draft:${user.id}`, { step: 2 }, { ttl: "1d" });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

describe("draft", () => {
  it("expires after its ttl", async () => {
    const app = createTestApp({ main: "./main.yaml" });
    await app.kv.set("draft:u1", { step: 2 }, { ttl: "1d" });
    app.clock.advance("23h");
    assert.deepEqual(await app.kv.get("draft:u1"), { step: 2 });
    app.clock.advance("2h");
    assert.equal(await app.kv.get("draft:u1"), null);
  });
});

kv:
  driver: local

Quick start

kv:
  driver: local

import { kv } from "mainsdk";

export async function POST() {
  const hits = await kv.incr("hits:home", { ttl: "1m" });   // a fixed one-minute window
  return Response.json({ hits });
}

use mainsdk::prelude::*;
let app = App::test();
Context::new().tenant("tnt_a").user("u1").scope(async {
app.kv().set("cart", 3).await?;
assert_eq!(app.kv().get("cart").await?, Some(3.into()));
Ok::<_, MainError>(())
}).await?;

Configuration

kv:
  driver: redis                  # local (default) | redis
  redis: { url: secret:REDIS_URL, prefix: myapp }

The Redis host is added to the app's network allow list as a driver host, and every connection is checked before it opens. See Network permissions.

What you get

Keys are scoped to the tenant, so one customer never reads or counts another's. The same calls run on a file or memory in development and on Redis in production, and kv is free. Reach for it for drafts, short-lived codes, feature counters and fixed-window rate counts. Records you must keep belong in db.

Examples

Keep a draft for a day

"use server";
import { auth, kv } from "mainsdk";

export async function saveDraftStep(req: Request, step: number) {
  const session = await auth.require(req);
  await kv.set(`onboarding:${session.user}`, { step }, { ttl: "1d" });
}

export async function draftStep(req: Request) {
  const session = await auth.require(req);
  return kv.get<{ step: number }>(`onboarding:${session.user}`);   // null when missing or expired
}

Count in a fixed window

import { kv } from "mainsdk";

export async function invitesThisHour(userId: string) {
  // The one-hour window starts when the key is created and does not move on later calls.
  return kv.incr(`invites:${userId}`, { ttl: "1h" });
}

For a refusal with Retry-After, use limits, which builds on the same stores.

Delete a key

import { kv } from "mainsdk";

export async function POST() {
  const existed = await kv.delete("hits:home");   // true when the key was there
  return Response.json({ existed });
}

Reference

The SDK runs these itself; you call them only when you build a store by hand or write a driver.

Errors and checks

Outside a tenant a call fails with MAIN-TENANT-0001; see Tenants. kv adds no check rules.

Swapping drivers

kv:
  driver: redis   # was local

Your calls stay the same. Values are not carried over between drivers. See Swap a driver.

Testing

createTestApp runs kv in memory with a fake clock, so clock.advance() passes a ttl without waiting.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

describe("draft", () => {
  it("expires after its ttl", async () => {
    const app = createTestApp({ main: "./main.yaml" });
    await app.kv.set("draft:u1", { step: 2 }, { ttl: "1d" });
    app.clock.advance("23h");
    assert.deepEqual(await app.kv.get("draft:u1"), { step: 2 });
    app.clock.advance("2h");
    assert.equal(await app.kv.get("draft:u1"), null);
  });
});

Security and privacy

• Every key is prefixed with the tenant, so tenants never see each other's values, and delete and incr stay inside the tenant.
• The Redis host must be declared, and the connection fails before it opens when the network layer refuses it.
• Values are stored as plain JSON. Don't keep personal data in kv; labelled fields belong in db.

FAQ

Can I set a value that never expires? Yes: leave ttl out and the key stays until you delete it. A ttl that is zero or malformed fails instead of being ignored.

Does incr move the expiry on each call? No. The expiry is set when the call creates the key, so the window is fixed; the next call after it expires starts a new one.

Next

• Data and records
• Rate limits and quotas
• Network permissions