npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jtkunley/reference-data-cache

v1.0.1

Published

Read-through cache for reference data in Node.js. A reader caches in memory; an owner also shares values through Redis and can invalidate. Single-flight loading, and Redis failures never fail a read.

Readme

reference-data-cache

npm CI Node.js TypeScript Dependencies License: MIT

Named, read-through caching for reference data in Node.js: country lists, product catalogs, feature tables, anything small, read often, and loaded as a whole.

It comes in two shapes, one per use case:

| | Reader | Owner (read-write) | | ---------------------- | --------------------- | ------------------------------------------------- | | Create with | createCacheReader() | createCacheOwner() | | Where values live | This process's memory | This process's memory, plus a shared tier (Redis) | | On a miss | Calls your loader | Tries the shared tier, then calls your loader | | Writes the shared tier | Never | After each load, in the background | | Can invalidate | No | Yes, locally and in the shared tier | | Needs Redis | No | Yes, or any custom CacheTier |

Both load single-flight: concurrent misses for a domain share one load per client. Neither has runtime dependencies or requires a particular Redis client.

Install

npm install @jtkunley/reference-data-cache

Requires Node.js 22 or later. Ships ESM, CommonJS, and type declarations.

Use case 1: Reader, a local cache in front of a loader

Use a reader when a process just needs to avoid reloading reference data on every request, and doesn't need to share loaded values with other processes.

import { createCacheReader } from '@jtkunley/reference-data-cache';

const cache = createCacheReader({ inMemoryPolicy: { ttlMs: 60_000 } });

cache.register({
  name: 'countries',
  loader: { load: () => db.query('SELECT code, name FROM countries') },
});

const countries = await cache.get<Country[]>('countries');

How a reader serves get:

flowchart LR
  get["get(name)"] --> local{"Fresh in memory?"}
  local -- yes --> done["Return value"]
  local -- no --> flight{"Load already running?"}
  flight -- yes --> join["Wait for it"] --> done
  flight -- no --> load["loader.load()"] --> store["Keep in memory"] --> done
  • Values expire ttlMs after they were loaded (default 5 minutes); reads don't extend them.
  • A failed load rejects every waiting caller and isn't cached, so the next read tries again.
  • There's no background refresh: an expired value is reloaded by the next read.

Use case 2: Owner, sharing loaded values through Redis

Use an owner when several processes read the same reference data and you want one load to serve all of them, or when you change the data and need to invalidate the cached copy.

An owner reads from and writes to a shared tier. RedisCacheTier takes any client that fits a three-method interface; here it wraps redis v4 or later:

import { createClient } from 'redis';
import { RedisCacheTier, createCacheOwner } from '@jtkunley/reference-data-cache';

const redis = createClient();
await redis.connect();

const sharedTier = new RedisCacheTier({
  get: (key) => redis.get(key),
  set: async (key, value, ttlMs) => {
    await redis.set(key, value, { PX: ttlMs });
  },
  delete: async (key) => {
    await redis.del(key);
  },
});

const cache = createCacheOwner({
  sharedTier,
  inMemoryPolicy: { ttlMs: 60_000 },
  onTierError: ({ domain, operation, kind, error }) => {
    logger.warn({ domain, operation, kind, err: error }, 'shared cache failure');
  },
});

cache.register({
  name: 'countries',
  loader: { load: loadCountries },
  sharedPolicy: { ttlMs: 3_600_000 },
});

const countries = await cache.get<Country[]>('countries');

// After you change the source data:
await cache.invalidate('countries');

How an owner serves get:

flowchart LR
  get["get(name)"] --> local{"Fresh in memory?"}
  local -- yes --> done["Return value"]
  local -- no --> flight{"Load already running?"}
  flight -- yes --> join["Wait for it"] --> done
  flight -- no --> shared{"In Redis?"}
  shared -- yes --> promote["Keep in memory"] --> done
  shared -- "no, or Redis failed" --> load["loader.load()"]
  load --> store["Keep in memory, write to Redis in the background"] --> done
  • Redis problems never fail a read. Timeouts, outages, and corrupt entries are passed to onTierError, and the loader is used instead. A corrupt entry is also deleted.
  • Writes are not awaited. get returns as soon as the value is loaded; a successful read doesn't mean the value reached Redis.
  • TTLs must nest. The in-memory TTL can't exceed the shared TTL. The shared TTL comes from sharedPolicy, or the tier's default (12 hours) at registration time.
  • Invalidation is local plus shared. invalidate clears this process's copy immediately, deletes the Redis entry, and resolves once that delete succeeds. Other processes keep their in-memory copies until they expire.
  • One tier instance per owner. Several RedisCacheTier instances can share one Redis connection.

Using redis v3 (callback API)

import redis from 'redis';
import { createRedisCacheTierFromRedisV3 } from '@jtkunley/reference-data-cache';

const sharedTier = createRedisCacheTierFromRedisV3(redis.createClient(), {
  operationTimeoutMs: 250,
});

The adapter calls get(key, cb), set(key, payload, 'PX', ttlMs, cb), and del(key, cb). In both setups, creating, reconnecting, and closing the Redis connection stay with you.

Concepts

Domain. One named cached value with a loader. Names are exact and case-sensitive. Loaders take no arguments and must not resolve to null or undefined; falsy values like 0, false, '', [], and {} are fine.

Policies. { ttlMs }, measured from the latest write. Set a client-wide in-memory default with inMemoryPolicy and override it per domain. Policies are copied and frozen on registration, so mutating your objects later has no effect.

References and JSON. In-memory values are kept by reference, not cloned or frozen. Values that pass through Redis go through JSON, so use JSON-compatible data if results must match across tiers.

API

Reader

| Member | Description | | ----------------------------- | --------------------------------------------------------------------------- | | createCacheReader(options?) | Creates a CacheReader. options.inMemoryPolicy sets the default TTL. | | register(domain) | Registers { name, loader, inMemoryPolicy? } without loading. Synchronous. | | get<T>(name) | Resolves the value, loading it on a miss. T is an unchecked assertion. |

Owner

Everything a reader has, plus:

| Member | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | createCacheOwner(options) | Creates a CacheOwner. Requires sharedTier; accepts inMemoryPolicy and onTierError. | | register(domain) | Also accepts sharedPolicy, and registers the domain with the shared tier. | | invalidate(name) | Clears the local copy and deletes the shared one. Rejects if the delete fails, but the local copy is cleared either way. |

onTierError receives { domain, tier: 'shared', operation, kind, error } once per failed shared operation. operation is get, set, or delete; kind is timeout, serialize, corrupt-value, or error; error is the original failure. The hook's return value is ignored, and anything it throws or rejects is contained.

Shared tiers

| Class | NAME | Default TTL | TTL rule | | ------------------- | ------------- | ----------- | --------------------- | | RedisCacheTier | 'redis' | 12 hours | positive safe integer | | InMemoryCacheTier | 'in-memory' | 5 minutes | finite, >= 0 |

Both implement CacheTier (defaultPolicy, setDefaultPolicy, register, unregister, get, set, delete), which you can also implement yourself. get resolves { hit: false } or { hit: true, value }. InMemoryCacheTier is mainly useful in tests or as a stand-in for Redis.

RedisCacheTier stores JSON under reference-data-cache:v1:<name> and gives each Redis call its own deadline, operationTimeoutMs (default DEFAULT_REDIS_OPERATION_TIMEOUT_MS, 500 ms). Its unregister leaves the stored key in place.

Errors

| Error | When | | ----------------------------------- | -------------------------------------------- | | CacheDomainAlreadyRegisteredError | Registering a name twice on a client or tier | | CacheDomainNotRegisteredError | Using a name that was never registered | | CacheTierTimeoutError | A Redis call exceeded operationTimeoutMs | | CacheTierSerializationError | A value could not be converted to JSON | | CacheTierCorruptValueError | A stored Redis value was not valid JSON |

All expose domainName; the timeout error also exposes operation and timeoutMs. Invalid policies and options throw TypeError or RangeError, and a failed registration leaves nothing registered.

Guarantees and limits

The library deliberately does not provide:

  • Cross-process coordination. Single-flight loading is per client instance. Other processes may load the same domain at the same time.
  • Invalidation broadcast. Other processes keep their in-memory copies until they expire.
  • A freshness barrier. Reads that overlap an invalidation may see older values, and a Redis write dispatched before invalidation may still land afterwards. If the delete fails, later reads may bring the old value back from Redis.
  • Write confirmation or draining. Redis writes are best effort, and nothing waits for them on shutdown.
  • Cancellation. A Redis timeout stops waiting but doesn't cancel the request. Loaders and custom tiers have no timeout; if they hang, callers wait.
  • Scheduled refresh or eviction. No background refresh, stale-while-revalidate, or capacity limit.
  • Schema validation. Values are not checked at runtime.

The full behavioral contract is in docs/behavior-spec.md.

Development

npm install
npm run check   # typecheck, lint, format check, tests
npm run build   # dist/ (ESM + CJS + type declarations)

See CONTRIBUTING.md for the project layout.

License

MIT