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:

| Command | Description | |---------|-------------| | npm test | Stress test (1 worker, 5000 ops) | | npm run stress | Stress test (default workers/ops) | | npm run stress:stability | Long-running stability test (60s) | | npm run benchmark | Throughput and latency benchmark | | npm run example | Multi-worker cluster example |

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

| Method | Signature | Description | |--------|-----------|-------------| | init | init(name, sizeMB) | Create or attach to POSIX shm segment. name becomes /name. Call once per process before any other call. | | set | set(key, value [, ttlMs]) | Insert or update. Returns true on success, false if table full or key/value too long. Optional ttlMs for TTL in milliseconds. | | get | get(key) | Returns string value or null if not found or expired. | | del | del(key) | Remove key. Returns true if removed, false if not found. | | clear | clear() | Set all slots to empty (visible to all processes). | | stats | stats() | Returns { capacity, count, keyMaxBytes, valueMaxBytes }. | | incr | incr(key, delta) | Atomic increment. Creates numeric slot if missing. Returns new value. | | decr | decr(key, delta) | Atomic decrement. Returns new value. | | close | close() | Release process-local mapping and fd. Safe to call multiple times; called on process exit by default. |

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

| Operation | Throughput (ops/s) | Latency (avg ms) | |-----------|--------------------|------------------| | set | ~1,200,000 | ~0.0008 | | get | ~1,500,000 | ~0.0007 |

Latency percentiles (μs), single process:

| | p50 | p95 | p99 | |-----------|-------|-------|-------| | set | ~0.6 | ~1.2 | ~2 | | get | ~0.5 | ~1.0 | ~1.5 |

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