Skip to main content
Version: 🚧 Canary

💾 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​

OptionTypeDefaultDescription
maxEntriesnumber5000Maximum entries; least-recently-used entries are evicted when exceeded
ttlnumber604800000 (7 days)Entry lifetime in milliseconds

Returned API​

MethodDescription
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​