KvNamespace

interface KvNamespace {
  get(key: string, options?: KvGetTextOptions): Promise<string | null>;
  get<T>(key: string, options: KvGetJsonOptions): Promise<T | null>;
  put(key: string, value: string, options?: KvPutOptions): Promise<void>;
  delete(key: string): Promise<void>;
  list(options?: KvListOptions): Promise<KvListResult>;
}

interface KvGetTextOptions { type?: "text" }   // default
interface KvGetJsonOptions { type: "json" }    // JSON.parse the stored value

// Text (default) -> string | null
const raw = await env.MY_KV.get("user/123");

// JSON -> T | null (JSON.parse applied; an empty stored value yields null)
const user = await env.MY_KV.get<{ name: string }>("user/123", { type: "json" });

interface KvPutOptions {
  expirationTtl?: number;   // seconds until the key expires server-side
  /** @deprecated Not supported by the API. Accepted but ignored. */
  metadata?: unknown;
}

await env.MY_KV.put("user/123", JSON.stringify({ name: "Alice" }));

// Expire automatically after one hour
await env.MY_KV.put("session/abc", token, { expirationTtl: 3600 });

await env.MY_KV.delete("user/123");

interface KvListOptions {
  prefix?: string;
  limit?: number;
  cursor?: string;   // from a previous result's `cursor`
}

interface KvListResult {
  keys: KvKeyInfo[];
  list_complete: boolean;
  cursor?: string;   // present when list_complete is false
}

interface KvKeyInfo {
  name: string;
  sizeBytes?: number;   // stored value size, from the API's size_bytes
  updatedAt?: Date;     // last write time, from the API's updated_at
  /** @deprecated Not populated by the API. Always undefined. */
  metadata?: unknown;
}

const { keys } = await env.MY_KV.list({ prefix: "user/" });
// [{ name: "user/123", sizeBytes: 21, updatedAt: 2026-06-18T14:48:17.475Z }, …]