@whatsveg/wv-cache-server

Lightweight in-memory cache server with TCP & HTTP interfaces, TypeScript types, and restart management.

This server is designed to be used with the companion client package @whatsveg/wv-cache-client, which handles TCP connection management and cache operations from Node.js applications.

Server usage

CommonJS

const cacheServer = require('@whatsveg/wv-cache-server');

(async () => {
  const { tcpService, cleanupHandle, snapshotHandle } = await cacheServer.start({
    tcpPort: 6379,
    enableCleanup: true,
    cleanupIntervalMs: 10000,
    enableSnapshot: true,
    snapshotIntervalMs: 30000,
    snapshotFilePath: './snapshot.json',
    autoRestart: true,
    restartRetries: 5,
    restartDelayMs: 1000,
  });

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

  // shutdown when done
  // await cacheServer.stop();
})();

ESM / TypeScript

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

await cacheServer.start({
  tcpPort: 6379,
  enableCleanup: true,
  cleanupIntervalMs: 10000,
  enableSnapshot: true,
  snapshotIntervalMs: 30000,
  snapshotFilePath: './snapshot.json',
  autoRestart: true,
  restartRetries: 5,
  restartDelayMs: 1000,
});

API

• start(options) — starts TCP server, optional TTL cleanup job, and optional snapshot persistence. Returns { tcpService, cleanupHandle, snapshotHandle }.
• stop() — stops the server, cleanup job, and snapshot job.
• restart(options) — restarts the server with the same or new options.

Options

• tcpPort (number) — default 6379
• enableCleanup (boolean) — default true
• cleanupIntervalMs (number) — TTL cleanup interval
• enableSnapshot (boolean) — enable periodic snapshot persistence
• snapshotIntervalMs (number) — snapshot interval in milliseconds
• snapshotFilePath (string) — snapshot file location
• autoRestart (boolean) — enable auto-restart on failure
• restartRetries (number) — max restart attempts
• restartDelayMs (number) — base backoff delay in milliseconds

Cleanup task setup

The server includes a TTL cleanup task that periodically removes expired cache entries. Enable it by setting enableCleanup: true when you call start() and adjust the cleanupIntervalMs value to control how often cleanup runs.

Example:

await cacheServer.start({
  tcpPort: 6379,
  enableCleanup: true,
  cleanupIntervalMs: 10000,
});

If you do not want automatic cleanup, set enableCleanup: false.

Snapshot support

The server can persist the current in-memory state to disk and restore it on startup.

await cacheServer.start({
  tcpPort: 6379,
  enableSnapshot: true,
  snapshotIntervalMs: 30000,
  snapshotFilePath: './snapshot.json',
});

Command reference

After connecting and authenticating with AUTH <tenantId>, you can use these commands.

1. AUTH

• Syntax: AUTH <tenantId>
• Description: Selects the active tenant for subsequent commands.

Terminal:

AUTH tenant-a

Node.js client:

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

const client = new CacheClient({ host: 'localhost', port: 6379 });
await client.connect();
await client.auth('tenant-a');

2. SET

• Syntax: SET <key> <value> [ttl]
• Description: Stores a value in the current tenant's cache. An optional TTL is measured in seconds.

Terminal:

SET greeting hello
SET user:1 Alice 60

Node.js client:

await client.set('greeting', 'hello');
await client.set('user:1', 'Alice', 60);

3. GET

• Syntax: GET <key>
• Description: Reads a cached value.

Terminal:

GET greeting

Node.js client:

const value = await client.get('greeting');
console.log(value);

4. DEL

• Syntax: DEL <key>
• Description: Deletes a cached item.

Terminal:

DEL greeting

Node.js client:

await client.del('greeting');

5. EXISTS

• Syntax: EXISTS <key>
• Description: Checks whether a key exists.

Terminal:

EXISTS greeting

Node.js client:

const exists = await client.exists('greeting');
console.log(exists);

6. CLEARALLCACHE

• Syntax: CLEARALLCACHE
• Description: Clears all cache entries for the current tenant.

Terminal:

CLEARALLCACHE

Node.js client:

await client.clearAllCache();

7. LISTALL

• Syntax: LISTALL
• Description: Returns the current tenant's cache and geo state as JSON.

Terminal:

LISTALL

Node.js client:

const all = await client.listAll();
console.log(all);

8. LISTALLTENANTS

• Syntax: LISTALLTENANTS
• Description: Lists all known tenant IDs.

Terminal:

LISTALLTENANTS

Node.js client:

const tenants = await client.listAllTenants();
console.log(tenants);

9. LISTALLCACHEKEYS

• Syntax: LISTALLCACHEKEYS
• Description: Returns all cache keys for the current tenant.

Terminal:

LISTALLCACHEKEYS

Node.js client:

const keys = await client.listAllCacheKeys();
console.log(keys);

10. LISTALLGEONAMES

• Syntax: LISTALLGEONAMES
• Description: Returns all geo point names stored for the current tenant.

Terminal:

LISTALLGEONAMES

Node.js client:

const geoNames = await client.listAllGeoNames();
console.log(geoNames);

11. EXIT

• Syntax: EXIT
• Description: Closes the current connection.

Terminal:

EXIT

Node.js client:

await client.disconnect();

12. GEOADD

• Syntax: GEOADD <setName> <latitude> <longitude> <pointName>
• Description: Adds a geo point to a named set.

Terminal:

GEOADD cities 48.8566 2.3522 Paris

Node.js client:

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

13. GEOLIST

• Syntax: GEOLIST <setName>
• Description: Lists all points stored in a named geo set.

Terminal:

GEOLIST cities

Node.js client:

const points = await client.geoList('cities');
console.log(points);

14. GEODIST

• Syntax: GEODIST <setName> <fromPoint> <toPoint> [unit]
• Description: Calculates the distance between two geo points. Supported units are km and mi; values under 1km are returned in meters.

Terminal:

GEODIST cities Paris Berlin km

Node.js client:

const distance = await client.geoDist('cities', 'Paris', 'Berlin', 'km');
console.log(distance);

15. GEOWITHIN

• Syntax: GEOWITHIN <setName> <latitude> <longitude> <radius> [unit]
• Description: Returns all points in the set that are within the given radius.

Terminal:

GEOWITHIN cities 48.8566 2.3522 1000 km

Node.js client:

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

Example workflow:

AUTH tenant-a
SET greeting hello
GET greeting
GEOADD cities 48.8566 2.3522 Paris
GEOADD cities 52.52 13.405 Berlin
GEODIST cities Paris Berlin km
GEOWITHIN cities 48.8566 2.3522 1000 km
EXIT

Client integration

Use @whatsveg/wv-cache-client to connect from a Node.js app and manage cache data.

Example client usage

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.set('greeting', 'hello');
  const value = await client.get('greeting');
  console.log(value);
  await client.del('greeting');
  await client.disconnect();
}

main().catch(console.error);

Storing JSON objects

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);

Notes

• This package exports TypeScript declarations so consumers can use IntelliSense when installing the published package.
• The server is optimized for lightweight TCP cache protocols and is intended to work with the client package above.