FastKV

A high-performance, local-only key-value database built for Bun runtime with TypeScript. Designed for extreme speed with performance targets of 1-5M inserts/sec, 1-10M reads/sec, and 0.5-2M deletions/sec.

Features

• Ultra-fast in-memory operations with optimized data structures
• Binary encoding using Uint8Array and TextEncoder/TextDecoder
• Memory pool allocation for reduced garbage collection
• Batch operations for maximum throughput
• TCP and Unix socket servers for network access
• Optional persistence with append-only logging
• Built-in benchmarking tools
• TypeScript-first with full type safety
• Zero dependencies (except Bun runtime)

Performance Targets

Operation	Target	Typical Performance
Insert	1-5M ops/sec	2-4M ops/sec
Get	1-10M ops/sec	5-8M ops/sec
Delete	0.5-2M ops/sec	1-2M ops/sec

Installation

bun install

Quick Start

Basic Usage

import { FastKV } from "./index.js";

const db = new FastKV({
  initialCapacity: 1000000,
  enablePersistence: false,
});

// Basic operations
db.set("user:1", "John Doe");
db.set("user:2", "Jane Smith");

console.log(db.getString("user:1")); // "John Doe"
console.log(db.has("user:1")); // true
console.log(db.size()); // 2

// Batch operations for maximum performance
for (let i = 0; i < 10000; i++) {
  db.batchSet(`key:${i}`, `value_${i}`);
}
db.flushBatch();

db.close();

TCP Server

import { FastKV } from "./index.js";

const db = new FastKV({
  enableTCPServer: true,
  tcpOptions: {
    port: 9999,
    host: "localhost",
  },
});

await db.startTCPServer();
console.log("FastKV server running on localhost:9999");

Client Connection

import { FastKVClient } from "./index.js";

const client = new FastKVClient({
  host: "localhost",
  port: 9999,
});

await client.connect();

await client.set("test", "Hello World");
const value = await client.get("test");
console.log(value); // "Hello World"

client.disconnect();

API Reference

FastKV Class

Constructor Options

interface FastKVOptions {
  initialCapacity?: number; // Default: 1000000
  enablePersistence?: boolean; // Default: false
  logPath?: string; // Default: './fastkv.log'
  memoryPoolSize?: number; // Default: 10000
  enableTCPServer?: boolean; // Default: false
  enableUnixServer?: boolean; // Default: false
  tcpOptions?: TCPServerOptions;
  unixOptions?: UnixServerOptions;
}

Core Methods

• set(key: string, value: string | Uint8Array): boolean
• get(key: string): Uint8Array | null
• getString(key: string): string | null
• delete(key: string): boolean
• has(key: string): boolean
• clear(): void
• size(): number
• keys(): IterableIterator<string>

Batch Operations

• batchSet(key: string, value: string | Uint8Array): void
• batchDelete(key: string): void
• flushBatch(): BatchResult
• flushAllBatches(): BatchResult[]

Server Management

• startTCPServer(): Promise<void>
• startUnixServer(): Promise<void>
• startAllServers(): Promise<void>
• stopServers(): void

Benchmarking

• runBenchmark(options?: BenchmarkOptions): Promise<BenchmarkResult[]>
• printBenchmarkResults(results: BenchmarkResult[]): void

Examples

Run the included examples:

# Basic usage
bun run examples/basic-usage.ts

# Performance benchmark
bun run examples/benchmark.ts

# TCP server
bun run examples/tcp-server.ts

# Client test (run server first)
bun run examples/client-test.ts

Performance Optimizations

1. Native Map Usage: Leverages JavaScript's optimized Map implementation
2. Binary Encoding: Uses Uint8Array for efficient memory usage
3. Memory Pooling: Pre-allocated buffers reduce GC pressure
4. Batch Processing: Groups operations for maximum throughput
5. Zero-Copy Operations: Minimal data copying where possible
6. Efficient Serialization: Fast JSON parsing for network protocols

Network Protocol

The TCP and Unix socket servers use a simple JSON-based protocol:

Request Format

{
  "type": "GET|SET|DEL|HAS|SIZE|CLEAR|STATS|PING",
  "key": "string",
  "value": "string",
  "id": "string"
}

Response Format

{
  "success": boolean,
  "data": any,
  "error": "string",
  "id": "string",
  "timestamp": number
}

Persistence

When enabled, FastKV writes operations to an append-only log file:

const db = new FastKV({
  enablePersistence: true,
  logPath: "./my-database.log",
});

The log format is binary-optimized for fast writes and recovery.

Memory Management

FastKV includes several memory optimization features:

• Memory pools for frequently allocated buffers
• Efficient string encoding with reused TextEncoder/TextDecoder
• Automatic memory tracking in database stats
• Configurable capacity to pre-allocate Map size

Benchmarking

Built-in benchmarking tools help you measure performance:

const results = await db.runBenchmark({
  keyCount: 1000000,
  valueSize: 64,
  iterations: 3,
  warmupRounds: 1,
});

db.printBenchmarkResults(results);

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Requirements

• Bun runtime (latest version)
• TypeScript 5+
• Node.js types for development