memcore

Lock-free shared in-memory cache for Node.js — accessible across worker processes on the same machine. Uses POSIX shared memory, N-API, and atomic operations only. No Redis, no network, no locks.

Why memcore?

• No external services — Skip Redis, Memcached, or any daemon. One npm install and you have a shared cache; no config, no ports, no network.
• Sub-microsecond latency — Data lives in mmap’d shared memory. Gets and sets are in-process; no serialization or TCP round-trips.
• True cross-process sharing — Cluster workers share the same cache via POSIX shared memory. Ideal for session storage, rate limiting, and counters without a separate cache server.
• Lock-free design — No mutexes or spinlocks in the hot path. Atomic operations and careful memory ordering keep throughput high and latency predictable under contention.
• Predictable memory — Fixed size and capacity at init; no runtime allocations in the addon. Easier to reason about and tune for production.
• Small surface area — Simple API (init, set, get, del, incr, stats, etc.). No connection pools, no retries, no client libraries to maintain.
• Benchmarks — Single-process: ~1.2M set/s and ~1.5M get/s; p50 latency under 1 µs. Run npm run benchmark on your machine for real numbers (see Benchmarks below).

Use memcore when you need a fast, shared, in-memory cache for multiple Node.js workers on one machine and want to avoid external dependencies and network overhead.

Features

• Lock-free — No mutexes; atomic operations and explicit memory ordering only.
• Cross-process — Multiple Node.js workers (e.g. cluster) share one cache via POSIX shared memory.
• No external services — No daemons, no sockets; everything lives in shared memory.
• Ultra-low latency — In-process mmap access; typical get/set in sub-microsecond range.
• Fixed memory footprint — Size and capacity determined at init; no runtime allocations in the addon.

Installation

npm install memcore

System requirements

• Platform: Linux (primary), macOS (same POSIX APIs; Windows not supported).
• Node.js: 18 or higher.
• Build: node-gyp (usually installed with npm). On Linux: build-essential, Python 3; on macOS: Xcode Command Line Tools.

The native addon is built automatically on npm install via node-gyp rebuild. The JavaScript API is written in TypeScript and provides type definitions (dist/index.d.ts) for consumers.

Build from source

If you need to rebuild the addon or recompile TypeScript (e.g. after changing Node version):

npm run build
# or separately:
npm run build:addon
npm run build:ts

The binary is produced at build/Release/memcore.node. TypeScript compiles to dist/.

Development & Testing

From the repo, install dependencies and build:

npm install
npm run build

Then run tests and examples:

Stress test options: --workers N, --ops N, --duration N, --stability, --shm NAME, --size N, --seed N.

Quick start

const cache = require('memcore');

cache.init('mycache', 8);   // name, size in MB
cache.set('key', 'value');  // true
cache.get('key');           // 'value'
cache.del('key');           // true
cache.stats();              // { capacity, count, keyMaxBytes, valueMaxBytes }
cache.clear();

TypeScript:

import * as cache from 'memcore';

cache.init('mycache', 8);
cache.set('key', 'value');
const value = cache.get('key');  // string | null
const s = cache.stats();         // { capacity, count, keyMaxBytes, valueMaxBytes }

From the repo: npm run build then node dist/examples/quickstart.js. Multi-worker: npm run example or node dist/examples/cluster.js.

Multi-worker example

Using the Node.js cluster module so multiple workers share one cache:

const cluster = require('cluster');
const cache = require('memcore');

const SHM_NAME = 'myapp_cache';
const CACHE_SIZE_MB = 8;

if (cluster.isPrimary) {
  cache.init(SHM_NAME, CACHE_SIZE_MB);
  cache.set('greeting', 'Hello from primary');
  cluster.fork();
  cluster.fork();
} else {
  cache.init(SHM_NAME, CACHE_SIZE_MB);
  console.log(cache.get('greeting'));  // 'Hello from primary'
  cache.set('worker_' + cluster.worker.id, 'data');
}

Run: npm run build then node dist/examples/cluster.js (from repo), or npm run example.

API reference

Constants: cache.KEY_MAX (64), cache.VALUE_MAX (256) — UTF-8 byte limits; keys up to 63 bytes, values up to 255 bytes. Longer strings cause set to return false or throw from the JS wrapper.

Benchmarks

Single-process throughput and latency (example run; your numbers will vary by CPU and load):

Latency percentiles (μs), single process:

Assumptions: Linux or macOS, single process or multi-worker on one machine, 16 MB cache, 100-byte values. Run npm run benchmark on your hardware for representative results.

Use cases

• High-frequency backends — Session or request metadata without network round-trips.
• Rate limiting — Atomic incr/decr across workers.
• Session storage — Shared session map for cluster workers.
• Queue metadata — Head/tail or counters in shared memory.
• Real-time systems — Low-latency state shared across processes.

Limitations

• Single machine only — POSIX shared memory is local to the host; no network.
• Fixed key/value sizes — Key max 63 bytes UTF-8, value max 255 bytes UTF-8; fixed at design time.
• No persistence — Segment is in RAM; process crash or reboot clears data.
• Linux / macOS — Developed on Linux; macOS uses same POSIX APIs. Windows is not supported (no POSIX shm).

Safety notes

• Lifecycle: Call init(name, sizeMB) once per process. The segment persists until all processes unmap it and the segment is removed (e.g. shm_unlink). If a process dies after claiming a slot but before committing, that slot can remain RESERVED until clear() or reinit.
• Cleanup: The addon registers an exit handler to call close(). For long-running servers this releases the fd; the mapping is process-local.
• Concurrency: Lock-free algorithms are used; multiple readers and writers are safe. No blocking except during initial init.

License

MIT