@probitas/client-deno-kv

Deno KV client for Probitas scenario testing framework.

This package provides a Deno KV client designed for integration testing of applications using Deno KV storage.

Features

• Key-Value Operations: get, set, delete with structured keys
• Listing: Iterate over keys by prefix, start, end
• Atomic Transactions: Atomic operations with version checking
• Type Safety: Generic type parameters for stored values
• Resource Management: Implements AsyncDisposable for proper cleanup

Installation

deno add jsr:@probitas/client-deno-kv

Quick Start

import { createDenoKvClient } from "@probitas/client-deno-kv";

const kv = await createDenoKvClient();

// Set a value
const setResult = await kv.set(["users", "1"], { name: "Alice", age: 30 });
console.log("Versionstamp:", setResult.versionstamp);

// Get a value with type
const getResult = await kv.get<{ name: string; age: number }>(["users", "1"]);
console.log("User:", getResult.value);

// List entries by prefix
const listResult = await kv.list<{ name: string }>({ prefix: ["users"] });
console.log("Entries:", listResult.entries);

await kv.close();

Atomic Operations

// Atomic transaction with version check
const atomic = kv.atomic();
atomic.check({ key: ["counter"], versionstamp: null }); // Only if key doesn't exist
atomic.set(["counter"], 1n);
await atomic.commit();

// Atomic increment
const current = await kv.get<bigint>(["counter"]);
const atomic2 = kv.atomic();
atomic2.check({ key: ["counter"], versionstamp: current.versionstamp });
atomic2.set(["counter"], (current.value ?? 0n) + 1n);
await atomic2.commit();

Using with using Statement

await using kv = await createDenoKvClient();

await kv.set(["test"], "value");
const result = await kv.get(["test"]);
console.log(result.value);
// Client automatically closed when block exits

Related Packages

Package	Description
@probitas/client	Core utilities and types
@probitas/client-redis	Redis client

Links

• GitHub Repository
• Probitas Framework
• Deno KV

deno add jsr:@probitas/client-deno-kv

class DenoKvAtomicBuilderImpl implements DenoKvAtomicBuilder

new DenoKvAtomicBuilderImpl(kv: Deno.Kv)

check(): unknown

set(): unknown

delete(): unknown

sum(): unknown

min(): unknown

max(): unknown

commit(): unknown

class DenoKvAtomicCheckError extends DenoKvError

new DenoKvAtomicCheckError(message: string, failedChecks: readonly Deno.KvKey[], options?: ErrorOptions)

class DenoKvError extends ClientError

new DenoKvError(message: string, _: unknown, options?: ErrorOptions)

class DenoKvQuotaError extends DenoKvError

new DenoKvQuotaError(message: string, options?: ErrorOptions)

interface DenoKvAtomicBuilder

check(_: Deno.AtomicCheck[]): this

set<T>(key: Deno.KvKey, value: T, options?: { expireIn?: number }): this

delete(key: Deno.KvKey): this

sum(key: Deno.KvKey, n: bigint): this

min(key: Deno.KvKey, n: bigint): this

max(key: Deno.KvKey, n: bigint): this

commit(): Promise<DenoKvAtomicResult>

interface DenoKvAtomicResult

interface DenoKvClient extends AsyncDisposable

get<T>(key: Deno.KvKey, options?: CommonOptions): Promise<DenoKvGetResult<T>>

getMany<T extends readonly unknown[]>(keys: readonly [unknown], options?: CommonOptions): Promise<unknown>

set<T>(key: Deno.KvKey, value: T, options?: DenoKvSetOptions): Promise<DenoKvSetResult>

delete(key: Deno.KvKey, options?: CommonOptions): Promise<DenoKvDeleteResult>

list<T>(selector: Deno.KvListSelector, options?: DenoKvListOptions): Promise<DenoKvListResult<T>>

atomic(): DenoKvAtomicBuilder

close(): Promise<void>

interface DenoKvClientConfig extends CommonOptions

interface DenoKvDeleteResult

interface DenoKvEntries<T> extends ReadonlyArray<DenoKvEntry<T>>

first(): DenoKvEntry<T> | undefined

firstOrThrow(): DenoKvEntry<T>

last(): DenoKvEntry<T> | undefined

lastOrThrow(): DenoKvEntry<T>

interface DenoKvEntry<T>

interface DenoKvGetResult<T>

interface DenoKvListOptions extends CommonOptions

interface DenoKvListResult<T>

interface DenoKvSetOptions extends CommonOptions

interface DenoKvSetResult

async function createDenoKvClient(config?: DenoKvClientConfig): Promise<DenoKvClient>

const kv = await createDenoKvClient();

await kv.set(["users", "123"], { name: "Alice", email: "alice@example.com" });

const result = await kv.get<User>(["users", "123"]);
console.log(result.value);  // { name: "Alice", email: "alice@example.com" }

await kv.close();

const kv = await createDenoKvClient({
  path: "./data.kv",
});

await kv.set(["sessions", sessionId], sessionData, {
  expireIn: 3600_000,  // Expire in 1 hour
});

const result = await kv.list<User>({ prefix: ["users"] });
for (const entry of result.entries) {
  console.log(entry.key, entry.value);
}

const atomicResult = await kv.atomic()
  .check({ key: ["counter"], versionstamp: null })
  .set(["counter"], 1)
  .commit();

await using kv = await createDenoKvClient();

await kv.set(["test"], "value");
// Client automatically closed when scope exits

function createDenoKvEntries<T>(entries: DenoKvEntry<T>[]): DenoKvEntries<T>

type DenoKvResult<T = unknown> = DenoKvGetResult<T> | DenoKvSetResult | DenoKvDeleteResult | DenoKvListResult<T> | DenoKvAtomicResult