# @imqueue/tag-cache 3.0.3 · API reference

Source: https://imqueue.org/api/tag-cache/latest/
Published: 2026-07-31
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/tag-cache 3.0.3 — generated reference, not hand-written

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](https://imqueue.org/api/tag-cache/latest/tag-cache.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()](https://imqueue.org/api/tag-cache/latest/tag-cache.tagcache.get/) returning `null` therefore means "not cached OR lookup failed", and [TagCache.invalidate()](https://imqueue.org/api/tag-cache/latest/tag-cache.tagcache.invalidate/) resolves once the work is ISSUED, not once the keys are gone.

## Example


```typescript
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](https://imqueue.org/api/tag-cache/latest/tag-cache.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: ```typescript 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()](https://imqueue.org/api/tag-cache/latest/tag-cache.tagcache.destroy/) tears it down for every instance — see that method. |


## Variables


| Variable | Description |
| --- | --- |
| [REDIS\_INIT\_ERROR](https://imqueue.org/api/tag-cache/latest/tag-cache.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()](https://imqueue.org/api/tag-cache/latest/tag-cache.tagcache.destroy/) has already been called on this instance. |