pocketcache

A fast, lightweight in-memory cache server written in Go — with a Node.js client that spawns and talks to it directly from your project.

Think Redis, but embedded in your project with zero infrastructure setup.

npm install pocketcache
# or
pnpm add pocketcache

The postinstall script automatically downloads the correct binary for your platform.

Quick start

import { PocketCache } from "pocketcache";

const cache = new PocketCache({ authKey: "my-secret", port: 8287 });

await cache.spawn();

await cache.set("user:1", { name: "alice" });
const user = await cache.get("user:1");

cache.stop();

API

new PocketCache(options)

| Option | Type | Default | Description | |---|---|---|---| | authKey | string | required | Sent as X-Server-Key on every request | | host | string | "localhost" | Host to connect to | | port | number | 8287 | Port to connect to |

cache.spawn(options?)

Starts the binary and resolves once the HTTP server is accepting connections.

| Option | Type | Default | Description | |---|---|---|---| | port | number | constructor port | Override port at spawn time | | persist | boolean | false | Enable SQLite persistence |

cache.stop()

Kills the server process.

cache.isActive / cache.port

isActive is true after a successful spawn(). All methods throw if false. port reflects the port the server actually bound to.

Key-value

await cache.set(key, value)                    // no expiry
await cache.set(key, value, { expiry: 60 })    // TTL in seconds
await cache.get(key)                           // null if missing or expired
await cache.del(key)                           // true if key existed
await cache.expire(key, seconds)               // true if key existed
await cache.ttl(key)                           // -1 no expiry, -2 missing

Counters

await cache.incr(key)   // starts at 1 for new keys
await cache.decr(key)

Hash maps

await cache.hset(key, field, value)   // true if field already existed
await cache.hget(key, field)          // null if missing
await cache.hgetall(key)              // null if key missing

Pub/sub

const unsub = cache.subscribe("events", (data) => {
  console.log(data);
});

await cache.publish("events", { type: "ping" });

unsub();

Persistence

await cache.spawn({ persist: true });

Writes a pocketcache.db SQLite file to the server's working directory. Keys survive restarts.

CLI

pocketcache --authkey=my-secret --port=8287 --persist

Also available

pocketcache-sub — lightweight subscriber-only client for when you only need to listen to events.