💾 Cache Utilities

The Nodeblocks SDK provides an in-memory LRU cache with TTL for service-level memoization. Use it to avoid repeated expensive lookups within a running process.

---

🎯 Overview

import { utils } from '@nodeblocks/backend-sdk';

const { createCache } = utils;

const addressCache = createCache<string, unknown>();

The module exports one factory function: createCache.

---

🏭 createCache

Creates an in-memory LRU cache with TTL expiration.

import { utils } from '@nodeblocks/backend-sdk';

const { createCache } = utils;

const cache = createCache<string, Address>({
  maxEntries: 1000,
  ttl: 60 * 60 * 1000, // 1 hour in milliseconds
});

Options

Option	Type	Default	Description
maxEntries	number	5000	Maximum entries; least-recently-used entries are evicted when exceeded
ttl	number	604800000 (7 days)	Entry lifetime in milliseconds

Returned API

Method	Description
get(key)	Returns the value if present and not expired; refreshes LRU recency; returns undefined if missing or expired
set(key, value)	Stores a value with a new expiry; evicts LRU entries when over maxEntries
del(key)	Removes an entry
clear()	Clears all entries
pruneExpired(limit?)	Scans up to limit entries (default 1000) and removes expired ones
size()	Returns total entry count including expired entries until pruned or accessed

Usage Example

import { utils } from '@nodeblocks/backend-sdk';

const { createCache } = utils;

const findAddressCache = createCache<string, unknown>({ maxEntries: 500 });

async function findAddressByPostalCode(code: string): Promise<unknown | undefined> {
  const cached = findAddressCache.get(code);
  if (cached) return cached;

  const address = await lookupAddress(code);
  if (address) {
    findAddressCache.set(code, address);
  }
  return address;
}

LRU Behavior

• get: On a hit, the entry is moved to most-recently-used position
• set: Re-inserts the key at the MRU position; evicts the oldest entry when maxEntries is exceeded
• Expiry: Expired entries are removed on get; use pruneExpired() for background cleanup

---

📐 Best Practices

1. Scope caches to service lifetime

In-memory caches are per-process. They do not synchronize across instances or restarts.

2. Choose TTL based on data freshness

Use shorter TTL for frequently changing data; rely on defaults for stable reference data.

3. Periodically prune expired entries

// Optional maintenance in long-running services
setInterval(() => cache.pruneExpired(), 60_000);

---

🔗 See Also

• Common Utilities — general helpers used alongside caching patterns