KV

The KV facet is a typed namespace for sessions, cache entries, OTPs, and other short-lived keys. Declare with store.kv(name), then read and write through fx.store(decl) inside Flows.

For developers caching or locking on okengine — one get/set surface; Redis in Docker, memory in tests.

Smallest Example

import { store } from "okengine";

export const sessions = store.kv("sessions");

import { on, flow, http } from "okengine";
import { z } from "zod";
import { sessions } from "@/core";

export const create = on(
  http.post({
    in: z.object({ token: z.string(), userId: z.string() }),
  }),
  flow({
    do: async ({ token, userId }, fx) => {
      await fx.store(sessions).set(`session:${token}`, userId, "1h");
      const cached = await fx.store(sessions).get(`session:${token}`);
      return { userId: cached };
    },
  }),
);

curl -X POST http://localhost:6530/sessions \
  -H "content-type: application/json" \
  -d '{"token":"abc","userId":"u1"}'

{
  "data": { "userId": "u1" },
  "error": null
}

Progressive Patterns

From a plain set to TTL, list/delete, and durable SQL-backed namespaces:

import { on, flow, http } from "okengine";
import { z } from "zod";
import { sessions } from "@/core";

export const get = on(
  http.get({
    in: z.object({ userId: z.string() }),
  }),
  flow({
    do: async ({ userId }, fx) => {
      const prefs = await fx.store(sessions).get(`user:${userId}:prefs`);
      return { prefs: prefs ?? null };
    },
  }),
);

Method Reference

fx.store(kvDecl):

Handle also exposes ref (kv:name) and driverId (memory · redis · postgres · pglite when durable).

There is no public incr, setNx, del alias, or eval on the fx handle. Gate rate strategies use Redis eval internally — not application Flows.

Namespaces

Every store.kv(name) registers a Manifest resource kv:name. The string you pass is the namespace id — keys inside it are relative to that namespace.

Cache namespace (default) — opens on drivers.store.kv (redis / memory):

export const sessions = store.kv("sessions");
// ref → "kv:sessions"

Durable namespace — opens on the shared SQL connection (oke_kv table):

export const drafts = store.kv("drafts", {
  durable: true,
  description: "Compose drafts that survive Redis recreate",
});

Global under tenancy — skip the {tenantId}: prefix when gate.auth.tenant is on:

export const sharedFlags = store.kv("shared-flags", {
  tenantScoped: false,
});

Methods

Each verb binds through fx.store(decl) inside flow({ do }):

import { on, flow, http } from "okengine";
import { z } from "zod";
import { sessions } from "@/core";

export const get = on(
  http.get({
    in: z.object({ token: z.string() }),
    errors: { NotFound: z.object({ token: z.string() }) },
  }),
  flow({
    do: async ({ token }, fx) => {
      const userId = await fx.store(sessions).get(`session:${token}`);
      if (userId === undefined || userId === null) {
        return fx.fail("NotFound", { token });
      }
      return { userId };
    },
  }),
);

Declare Options

Second argument to store.kv(name, options):

Durable Namespaces

Use durable KV when values must survive Redis flushes or Compose recreate (feature flags, compose drafts, webhook registrations). Cache namespaces stay on redis / memory.

import { store } from "okengine";

export const drafts = store.kv("drafts", {
  durable: true,
  description: "Compose drafts",
});

import { on, flow, http } from "okengine";
import { z } from "zod";
import { drafts } from "@/core";

export const save = on(
  http.put("/drafts/:id", {
    in: z.object({
      id: z.string().min(1),
      title: z.string().min(1),
      body: z.string().optional(),
    }),
  }),
  flow({
    do: async ({ id, title, body }, fx) => {
      await fx.store(drafts).set(id, { title, body: body ?? "" }, "7d");
      return { id };
    },
  }),
);

oke store: durable store.kv does not support eval

oke store: durable store.kv needs a configured sql driver

TTL Physics

Valid units match ^(\d+)(ms|s|m|h|d)$. Invalid strings parse to 0 (no useful expiry). Prefer explicit units: "30s", "15m", "1h", "1d".

Redis converts the duration to whole seconds (EX); sub-second "ms" values ceil to at least 1 second when TTL is set.

Tenant Scoping

When gate.auth.tenant is on, KV namespaces default to tenant-prefixed keys. Application code still uses logical keys — the runtime rewrites:

// With tenancy on and fx.tenant.id = "acme":
await fx.store(sessions).set("session:abc", "u1", "1h");
// Physical redis key: oke:kv:sessions:acme:session:abc

Opt out for genuinely global namespaces:

export const catalog = store.kv("catalog", { tenantScoped: false });

Missing tenant on a scoped op throws OKE1810 (TENANT_REQUIRED):

This operation needs a tenant, but none is resolved for this request.

Fix: switch tenant (fx.auth.switchTenant), send a signed tid claim, or pass the tenant header — see Tenancy.

Key Prefixes & Effects

Two prefix layers sit under the logical key you pass to fx.store:

Compiler effects stamp kv:name on reads (get · list · ttlMs) and writes (set · delete). Declare the same refs when you hand-write effects on a Flow.

Drivers

Defaults: redis / memory / redis (dev / test / prod). Pin overrides in oke.config.ts; image pins stay under images.store.kv — the driver id stays redis for Valkey / Dragonfly / Upstash wire-compatible servers.

Gate rate strategies inherit drivers.store.kv (no separate drivers.gate).

Troubleshooting

Learn more

• Store — four facets; driver defaults
• SQL — durable KV shares the SQL driver
• Gate · Tenancy — tenantScoped and fx.tenant.id
• Gate — rate buckets use Redis internally
• fx — fx.store(decl)
• Configuration — drivers.store.kv
• Errors — OKE1810

Next