@multisystemsuite/query-cache

Cache query results in memory or via a pluggable backend (Redis-compatible LockStore-style API). Supports TTL, invalidation, analytics, and wrap() helper.

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/query-cache on npm

Installation

pnpm add @multisystemsuite/query-cache

Quick start

import { QueryCache } from '@multisystemsuite/query-cache';

const cache = new QueryCache({ ttlSeconds: 300, prefix: 'app:' });

await cache.set('SELECT * FROM products WHERE category = ?', products);
const hit = await cache.get('SELECT * FROM products WHERE category = ?');

// Or wrap an async loader
const data = await cache.wrap('SELECT ...', () => db.query(sql));

Configuration

| Option | Default | Description | |--------|---------|-------------| | ttlSeconds | 300 | Default TTL | | prefix | dbtk: | Key prefix | | maxSize | 1000 | Max in-memory entries (LRU eviction) | | backend | in-memory | CacheBackend implementation |

API reference

| Method | Description | |--------|-------------| | get<T>(query) | Return cached JSON or null | | set<T>(query, value, ttlSeconds?) | Store result | | invalidate(query) | Remove one entry | | invalidatePattern(table) | Clear entries (backend clear or memory scan) | | wrap<T>(query, fn, ttl?) | Cache-aside pattern | | setBackend(backend) | Switch backend at runtime | | getAnalytics() | Hits, misses, hit rate |

CacheAnalytics

{ hits, misses, sets, invalidations, hitRate }

Redis / custom backend

import { InMemoryCacheBackend, type CacheBackend } from '@multisystemsuite/query-cache';

class RedisBackend implements CacheBackend {
  async get(key: string) { /* ... */ }
  async set(key: string, value: string, ttlSeconds: number) { /* ... */ }
  async delete(key: string) { /* ... */ }
  async clear?(pattern: string) { /* optional */ }
}

const cache = new QueryCache({ backend: new RedisBackend() });

InMemoryCacheBackend is included for testing.

Cache key strategy

Keys are prefix + query fingerprint (from @multisystemsuite/shared), so logically identical queries share cache entries regardless of literal values.

Invalidation tips

• Call invalidate(query) after writes to that query shape.
• Use invalidatePattern('users') after bulk updates to users table (best with backend clear).

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/query-cache
• Install: npm install @multisystemsuite/query-cache