@meistrari/kv

A TypeScript client library for interacting with the KV Service API. This client provides a simple, strongly-typed interface for all KV operations.

Installation

npm install @meistrari/kv
# or
yarn add @meistrari/kv
# or
pnpm add @meistrari/kv

Features

• Strongly Typed: Full TypeScript support with interfaces for all operations
• Simple API: Clear and consistent methods for all KV operations
• Namespace Support: Organize your keys in logical namespaces
• Batch Operations: Perform multiple operations in a single request
• Caching Utilities: Simple TTL-based caching
• Metadata Support: Store and retrieve metadata alongside values
• Error Handling: Consistent error handling across all API calls
• API Gateway Support: Built-in Authorization header support for API gateways with data-token integration
• Production Ready: Defaults to the Tela KV API at https://api.tela.com/kv
• Dual Package: Both ESM and CommonJS support via unbuild

Usage

import { KVClient } from '@meistrari/kv';

// Create a client instance (defaults to https://api.tela.com/kv)
const kv = new KVClient();

// Basic operations
await kv.put('hello', 'world');
const result = await kv.get('hello');
console.log(result.value); // 'world'

// With namespaces
await kv.putInNamespace('users', 'user-123', {
  name: 'John Doe',
  email: '[email protected]'
});

const user = await kv.getFromNamespace('users', 'user-123');
console.log(user.value.name); // 'John Doe'

// Batch operations
const batchResult = await kv.batch([
  { type: 'get', key: 'hello' },
  { type: 'put', key: 'greeting', value: 'Hello, world!' },
  { type: 'delete', key: 'old-key' }
]);

// Caching with TTL
await kv.cache('weather', { temp: 72, conditions: 'sunny' }, 300); // 5 minute TTL
const weather = await kv.getCached('weather');

API Reference

Basic Key Operations

• get(key, options): Get a value by key
• put(key, value, options): Store a value by key
• delete(key): Delete a value by key
• listKeys(options): List keys, optionally filtered by prefix

Namespace Operations

• getFromNamespace(namespace, key, options): Get a value from a namespace
• putInNamespace(namespace, key, value, options): Store a value in a namespace
• deleteFromNamespace(namespace, key): Delete a value from a namespace
• listNamespaceKeys(namespace, options): List keys in a namespace

Batch Operations

• batch(operations): Perform multiple operations in a single request

Utility Operations

• cache(key, value, ttl): Cache a value with automatic expiration
• getCached(key): Get a cached value
• deleteByPrefix(prefix): Delete all keys with a given prefix
• healthcheck(): Check if the KV service is available

Configuration

// With API key for the API Gateway
const kv = new KVClient('https://api.tela.com/kv', { apiKey: 'your-api-key' });

License

MIT