Skip to main content
Version: Next

Key-Value Store

The CommandKit Key-Value (KV) store provides a simple, persistent storage solution using SQLite. It supports storing any JSON-serializable data types directly, including objects, arrays, dates, maps, sets, and more.

Features​

  • JSON Serialization: Store any JSON-serializable data types directly
  • Dot Notation: Access nested properties using dot notation (e.g., user:123.settings.theme)
  • Namespaces: Organize data into separate namespaces
  • Expiration: Set time-to-live (TTL) for automatic cleanup
  • Transactions: Execute multiple operations atomically
  • Iteration: Iterate over all key-value pairs
  • Type Safety: Full TypeScript support with strong typing

Quick Start​

import { KV } from '@commandkit/kv';

// Create a new KV store
const kv = new KV('data.db');

// Store any data type directly
kv.set('user:123', { name: 'John', age: 30 });
kv.set('counter', 42);
kv.set('active', true);
kv.set('tags', ['javascript', 'typescript']);

// Use dot notation for nested properties
kv.set('user:123.settings.theme', 'dark');
kv.set('user:123.settings.notifications', true);

// Retrieve data
const user = kv.get('user:123'); // { name: 'John', age: 30, settings: { theme: 'dark', notifications: true } }
const theme = kv.get('user:123.settings.theme'); // 'dark'

// Set expiration
kv.setex('session:123', { userId: 123, token: 'abc123' }, 60 * 60 * 1000); // 1 hour

// Use namespaces
const userKv = kv.namespace('users');
userKv.set('123', { name: 'John', age: 30 });

Supported Data Types​

The KV store supports storing and retrieving the following data types:

  • Primitives: string, number, boolean, bigint, null, undefined
  • Objects: Plain objects, nested objects
  • Arrays: Any array of supported types
  • Dates: JavaScript Date objects
  • Collections: Map, Set
  • Buffers: Node.js Buffer objects
  • Regular Expressions: RegExp objects
  • Functions: Function objects (serialized as strings)

Installation​

The KV store is included with CommandKit. No additional installation is required.

npm install @commandkit/kv

Next Steps​