fastkv-client

A lightweight, zero-dependency, ultra-fast TypeScript/Node.js client for the FastKV in-memory key-value TCP server.

Features

• Zero Dependencies - Pure Node.js net module, no external packages.
• Async/Await - Fully promise-based API built on native TCP sockets.
• TypeScript First - Written in TypeScript with full type declarations shipped out of the box.
• Buffered I/O - Efficient socket communication with automatic line-based response parsing.

Installation

npm install fastkv-client

Quick Start

import { FastKvClient } from "fastkv-client";

async function main() {
  // 1. Connect to the FastKV server
  const client = await FastKvClient.connect("127.0.0.1:6379");

  // 2. Basic operations
  await client.set("planet", "Earth");
  const val = await client.get("planet"); // "Earth"
  console.log("Value:", val);

  // 3. Dynamic expirations
  await client.setWithExpiry("session_token", "abc123xyz", 3600);

  // 4. Core checkers
  const isActive = await client.exists("session_token"); // true

  // 5. Server snapshots
  await client.save("backup.bin");

  // 6. Disconnect when done
  client.disconnect();
}

main().catch(console.error);

Connection

// Simple address string
const client = await FastKvClient.connect("127.0.0.1:6379");

// Options object
const client = await FastKvClient.connect({
  host: "127.0.0.1",
  port: 6379,
  timeout: 5000,
});

API

FastKvClient.connect(addr: string): Promise<FastKvClient>

FastKvClient.connect(options: FastKvClientOptions): Promise<FastKvClient>

Connect to a FastKV server. Returns a connected client instance.

client.set(key, value): Promise<string>

Store a key-value pair.

client.get(key): Promise<string>

Retrieve the value for a key. Returns (nil) if the key doesn't exist or has expired.

client.del(key): Promise<string>

Delete a key from the store.

client.exists(key): Promise<boolean>

Check whether a key exists. Returns true or false.

client.setWithExpiry(key, value, ttl): Promise<string>

Store a key-value pair with a TTL (time-to-live) in seconds.

client.save(path): Promise<string>

Instruct the server to persist its in-memory data to an LZ4 compressed binary file.

client.load(path): Promise<string>

Instruct the server to load data from an LZ4 compressed binary file.

client.disconnect(): void

Close the TCP connection.

client.isConnected: boolean

Check whether the client is currently connected.

License

MIT