tag-cache package

Tagged cache over Redis: every value is stored with a set of tags, and invalidating a tag drops everything stored under it.

Start from TagCache, built on an initialised RedisCache from @imqueue/rpc.

Remarks

This exists for the case plain key-based caching cannot express: one cached value that several unrelated events should invalidate. Tagging a result with every entity it derives from means any one of those entities changing drops it, whatever key it was stored under.

Reads and writes never throw on a Redis failure — they log and report it in the return value, so an outage degrades to cache misses. Note that TagCache.get() returning null therefore means "not cached OR lookup failed", and TagCache.invalidate() resolves once the work is ISSUED, not once the keys are gone.

Example

import { RedisCache } from '@imqueue/rpc';
import { TagCache } from '@imqueue/tag-cache';

const cache = new TagCache(await new RedisCache().init({ prefix: 'app' }));

await cache.set('user:1:invoices', invoices, ['user:1', 'invoices'], 60000);
await cache.invalidate('user:1'); // drops it, and anything else tagged user:1

Classes

Class

Description

TagCache

Tagged cache over redis: values are stored under their own keys, and each key is additionally added to a redis set per tag. Invalidating a tag then drops every value that was stored with it, which is what plain key-based caching cannot express — one write can be invalidated by any of several unrelated events.

The typical use is caching a computed result that depends on several entities and dropping it when any one of them changes:

import { RedisCache } from '@imqueue/rpc';
import { TagCache } from '@imqueue/tag-cache';

const cache = new TagCache(await new RedisCache().init({ prefix: 'app' }));

await cache.set('user:1:invoices', invoices, ['user:1', 'invoices'], 60000);

// later, when user 1 changes — drops the entry above and anything else
// tagged 'user:1', whatever key it was stored under
await cache.invalidate('user:1');

Two things to know before relying on it. Read and write operations do NOT throw on a redis failure: they log a warning and report the failure in their return value, so a cache outage degrades to cache misses instead of taking the caller down. And the underlying redis connection is shared and owned by RedisCache, so TagCache.destroy() tears it down for every instance — see that method.

Variables

Variable	Description
REDIS_INIT_ERROR	Message of the `TypeError` thrown by every cache operation when no redis connection is available — either `RedisCache.init()` was never awaited, or TagCache.destroy() has already been called on this instance.

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.