@kv-storage/client (Node.js)

Fast HTTP/2 client for the KV Storage server with TypeScript support.

Features

• HTTP/2 support with h2c (plaintext) and h2 (TLS)
• Automatic key percent-encoding for special characters
• TLS/SSL support with certificate fingerprint pinning
• Self-signed certificate support
• Connection pooling and reuse
• Full TypeScript types
• Full API coverage: PUT, GET, DELETE, HEAD, LIST, BATCH, METRICS

Installation

npm install @kv-storage/client

Quick Start

import { KVStorage } from '@kv-storage/client';

const client = new KVStorage({
  endpoint: 'http://localhost:3000',
  token: 'your-token'
});

// PUT
const result = await client.put('my-key', 'Hello, World!');
console.log('Hash:', result.hash);

// GET
const value = await client.get('my-key');
console.log('Value:', value); // 'Hello, World!'

// DELETE
const deleted = await client.delete('my-key');
console.log('Deleted:', deleted); // true

HTTPS with Self-Signed Certificates

const client = new KVStorage({
  endpoint: 'https://localhost:3443',
  token: 'your-token',
  rejectUnauthorized: false  // Accept self-signed certs
});

Certificate Fingerprint Pinning

const client = new KVStorage({
  endpoint: 'https://localhost:3443',
  token: 'your-token',
  sslFingerprint: 'AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99'
});

Special Characters in Keys

The client automatically percent-encodes keys, so you can use any UTF-8 string:

// Spaces, unicode, special characters - all handled automatically
await client.put('my key', 'value');
await client.put('path/to/file.txt', data);
await client.put('ключ', data);
await client.put('test#hash', data);

Binary Data

// Get as text (default)
const text = await client.get('my-key');

// Get as Buffer
const buffer = await client.get('my-key', 'binary');

// PUT binary data
await client.put('binary-key', Buffer.from([0, 1, 2, 3]));
await client.put('binary-key', new Uint8Array([0, 1, 2, 3]));

Batch Operations

const response = await client.batch([
  { op: 'put', key: 'key1', value: 'value1' },
  { op: 'put', key: 'key2', value: 'value2' },
  { op: 'get', key: 'key1' },
  { op: 'delete', key: 'key2' }
]);

console.log(response.results);

List Keys

const result = await client.list({ limit: 100 });
console.log('Total keys:', result.total);
for (const key of result.keys) {
  console.log('  -', key);
}

HEAD Request (Metadata)

const info = await client.head('my-key');
if (info) {
  console.log('Content-Length:', info['content-length']);
  console.log('Hash:', info['x-hash']);
  console.log('Refs:', info['x-refs']);
}

Metrics

const metrics = await client.metrics();
console.log(metrics);
// Prometheus-format metrics output

Running Tests

The tests require a running KV Storage server. You can configure the server endpoint via environment variables:

# Run against local server (default: http://127.0.0.1:3456)
npm test

# Run against external server
SERVER=http://localhost:3000 TOKEN=your-token npm test

# Run with HTTPS + self-signed certs
SERVER=https://localhost:3443 TOKEN=your-token SSL_ALLOW_SELFSIGNED=true npm test

# Run with certificate fingerprint pinning
SERVER=https://localhost:3443 TOKEN=your-token SSL_FINGERPRINT=AA:BB:CC:DD... npm test

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SERVER | http://127.0.0.1:3456 | Server endpoint (alias: TEST_ENDPOINT) | | TOKEN | test-token | Authentication token (alias: TEST_TOKEN) | | SSL_ALLOW_SELFSIGNED | false | Accept self-signed certificates (true/false) | | SSL_FINGERPRINT | - | Certificate fingerprint for pinning (SHA-256 hex, alias: TEST_SSL_FINGERPRINT) |

API Reference

Constructor Options

interface KVStorageOptions {
  endpoint: string;              // Server URL (http:// or https://)
  token: string;                 // Authentication token
  timeout?: number;              // Request timeout in ms (default: 5000)
  rejectUnauthorized?: boolean;  // SSL certificate verification (default: true)
  sslFingerprint?: string;       // Certificate fingerprint for pinning
}

Methods

• put(key: string, value: string | Buffer | Uint8Array): Promise<PutResult>
• get(key: string, format?: 'text' | 'binary'): Promise<string | Buffer | null>
• delete(key: string): Promise<boolean>
• head(key: string): Promise<Headers | null>
• list(options?: { offset?: number; limit?: number }): Promise<ListResult>
• batch(ops: BatchOp[]): Promise<BatchResponse>
• metrics(): Promise<string>

License

MIT