wv-cache-client

A lightweight TypeScript client for communicating with a cache server over TCP.

Installation

Install the client from npm:

npm install @whatsveg/wv-cache-client

To run a local cache server for this client, install the companion server package @whatsveg/wv-cache-server:

npm install @whatsveg/wv-cache-server

Server setup

Start the server with the companion package using the documented startup pattern:

import cacheServer from "@whatsveg/wv-cache-server";

async function startServer() {
  const { tcpService, cleanupHandle, snapshotHandle } = await cacheServer.start({
    tcpPort: 6379,
    enableCleanup: true,
    cleanupIntervalMs: 10000,
    autoRestart: true,
    restartRetries: 5,
    restartDelayMs: 1000,
  });

  if (tcpService && typeof tcpService.on === "function") {
    tcpService.on("error", (err) => console.error("tcp error", err));
  }

  console.log("Server started", { tcpService, cleanupHandle, snapshotHandle });
}

startServer().catch(console.error);

You can disable automatic TTL cleanup by setting enableCleanup: false, and you can stop the server later with await cacheServer.stop() when needed.

Features

• Simple connection handling
• Typed API for TypeScript users
• Support for common cache operations like set, get, del, and auth
• Includes convenience methods for existence checks, tenant listing, cache inspection, and geo commands
• Works well for basic TCP-based cache integrations

How it works

The package exposes a CacheClient class that connects to a server using TCP and sends plain text commands over the socket. It is designed to be easy to use and works well for lightweight cache-style protocols.

Quick start

import { CacheClient } from "@whatsveg/wv-cache-client";

async function main() {
  const client = new CacheClient({ host: "localhost", port: 6379 });

  await client.connect();
  await client.set("greeting", "hello");
  const value = await client.get("greeting");

  console.log(value);

  await client.disconnect();
}

main().catch(console.error);

Storing JSON data

You can store JSON payloads by serializing them to a string before calling set(), and then parsing them again when you read them back.

import { CacheClient } from "@whatsveg/wv-cache-client";

async function main() {
  const client = new CacheClient({ host: "localhost", port: 6379 });

  await client.connect();
  await client.auth("my-client-id");

  const user = { id: 1, name: "Alice", role: "admin" };
  await client.set("user:1", JSON.stringify(user));

  const raw = await client.get("user:1");
  const parsedUser = raw ? JSON.parse(raw) : null;

  console.log(parsedUser);

  await client.disconnect();
}

main().catch(console.error);

Geo commands example

Here is a small Node.js example that uses the geo-related helpers:

import { CacheClient } from "@whatsveg/wv-cache-client";

async function main() {
  const client = new CacheClient({ host: "localhost", port: 6379 });

  await client.connect();
  await client.auth("my-client-id");

  await client.geoAdd("cities", 48.8566, 2.3522, "Paris");
  await client.geoAdd("cities", 52.52, 13.405, "Berlin");

  const points = await client.geoList("cities");
  const distance = await client.geoDist("cities", "Paris", "Berlin", "km");
  const nearby = await client.geoWithin("cities", 48.8566, 2.3522, 1000, "km");

  console.log({ points, distance, nearby });

  await client.disconnect();
}

main().catch(console.error);

API

new CacheClient(options?)

Creates a new client instance.

Parameters:

• options.host (string, optional): Hostname or IP address of the cache server. Defaults to "localhost".
• options.port (number, optional): TCP port of the cache server. Defaults to 6379.

const client = new CacheClient();
const client = new CacheClient({ host: "localhost", port: 6379 });

connect(options?)

Establishes a TCP connection to the server.

Parameters:

• options.retries (number, optional): Number of connection retry attempts before failing. Defaults to 3.
• options.delayMs (number, optional): Base delay between retry attempts in milliseconds. Defaults to 1000.
• options.backoffMultiplier (number, optional): Multiplier applied to the retry delay after each failed attempt. Defaults to 1.

await client.connect();
await client.connect({ retries: 5, delayMs: 250, backoffMultiplier: 2 });

send(command: string)

Sends a raw command to the server.

Parameters:

• command (string): The plain-text command to send to the server, including any arguments.

await client.send("PING");

auth(clientId: string)

Sends an authentication command.

Parameters:

• clientId (string): The tenant or client identifier to authenticate with.

await client.auth("my-client-id");

set(key: string, value: string | number | boolean, ttl?: number | null)

Stores a value with an optional TTL.

Parameters:

• key (string): Cache key to store the value under.
• value (string | number | boolean): Value to save. The client serializes it before sending it to the server.
• ttl (number | null, optional): Time-to-live in seconds. If omitted, the value is stored without an expiration.

await client.set("name", "Alice");
await client.set("score", 42, 60);

get(key: string)

Retrieves a value by key.

Parameters:

• key (string): Cache key to read.

const value = await client.get("name");

del(key: string)

Deletes a value by key.

Parameters:

• key (string): Cache key to delete.

await client.del("name");

exists(key: string)

Checks whether a key exists and returns a boolean.

Parameters:

• key (string): Cache key to check.

const exists = await client.exists("name");

clearAllCache()

Clears all cache entries for the active tenant.

This method takes no parameters.

await client.clearAllCache();

listAll()

Returns the current tenant cache and geo state as an object.

This method takes no parameters.

const state = await client.listAll();

listAllTenants()

Lists all known tenant identifiers.

This method takes no parameters.

const tenants = await client.listAllTenants();

listAllCacheKeys()

Returns all cache keys for the active tenant.

This method takes no parameters.

const keys = await client.listAllCacheKeys();

listAllGeoNames()

Returns all geo point names stored for the active tenant.

This method takes no parameters.

const geoNames = await client.listAllGeoNames();

geoAdd(setName, latitude, longitude, pointName)

Adds a geo point to a named set.

Parameters:

• setName (string): Name of the geo set to update.
• latitude (string | number): Latitude coordinate for the point.
• longitude (string | number): Longitude coordinate for the point.
• pointName (string): Name of the point to add to the set.

await client.geoAdd("cities", 48.8566, 2.3522, "Paris");

geoList(setName)

Returns the points stored in a named geo set.

Parameters:

• setName (string): Name of the geo set to retrieve.

const points = await client.geoList("cities");

geoDist(setName, fromPoint, toPoint, unit?)

Calculates the distance between two geo points.

Parameters:

• setName (string): Name of the geo set that contains the points.
• fromPoint (string): Name of the starting point.
• toPoint (string): Name of the destination point.
• unit ("km" | "mi", optional): Distance unit. Defaults to "km".

const distance = await client.geoDist("cities", "Paris", "Berlin", "km");

geoWithin(setName, latitude, longitude, radius, unit?)

Returns the points within the given radius.

Parameters:

• setName (string): Name of the geo set to query.
• latitude (string | number): Latitude of the center point.
• longitude (string | number): Longitude of the center point.
• radius (string | number): Search radius around the center point.
• unit ("km" | "mi", optional): Unit for the radius. Defaults to "km".

const nearby = await client.geoWithin("cities", 48.8566, 2.3522, 1000, "km");

disconnect()

Closes the active socket connection.

This method takes no parameters.

client.disconnect();

License

ISC