Proposal: KV cache

[terrablue]

Simple key-value interface for caching, sessions, and ephemeral state.

Interface

interface KV {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T, options?: { ttl?: number }): Promise<void>;
  delete(key: string): Promise<void>;
  has(key: string): Promise<boolean>;
}

ttl is in seconds.

Config

Default (in-memory):

// config/kv.ts
import kv from "primate/kv";

export default kv();

Redis:

// config/kv.ts
import redis from "@primate/redis";

export default redis({
  url: "redis://localhost:6379", // optional, this is the default
});

No config file = in-memory by default.

Usage

import kv from "#kv"; // given a tsconfig alias

await kv.set("session:abc", { userId: 123 }, { ttl: 3600 });

const session = await kv.get<{ userId: number }>("session:abc");

if (await kv.has("session:abc")) {
  // ...
}

await kv.delete("session:abc");

Drivers

primate/kv — in-memory, development/single-instance. Data lost on restart.
@primate/redis — distributed, production.

[terrablue]

Counterproposal:

Provide @primate/kv, drivers are peer deps.

Implicit: detect environment and try to use native KVs if available, otherwise fall back to ephemeral MemoryKV.

import kv from "@primate/kv";

export default {
  kv: kv(),
};

Explicit (redis must be available as a peerdep):

import kv from "@primate/kv";

export default {
  kv: kv({
    driver: "redis",
    url: "redis://localhost:6379",
  }),
};