💾 キャッシュユーティリティ

Nodeblocks SDK は、サービスレベルのメモ化のために TTL 付きインメモリ LRU キャッシュを提供します。実行中プロセス内で高コストな検索の繰り返しを避けるために使用します。

---

🎯 概要

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

const { createCache } = utils;

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

このモジュールは 1 つのファクトリー関数、createCache をエクスポートします。

---

🏭 createCache

TTL 有効期限付きのインメモリ LRU キャッシュを作成します。

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

const { createCache } = utils;

const cache = createCache<string, Address>({
  maxEntries: 1000,
  ttl: 60 * 60 * 1000, // 1 時間（ミリ秒）
});

オプション

オプション	型	デフォルト	説明
maxEntries	number	5000	最大エントリー数。超過時は最も長く使用されていないエントリーを破棄します。
ttl	number	604800000（7 日）	エントリーの有効期間（ミリ秒）。

返される API

メソッド	説明
get(key)	存在し期限切れでなければ値を返し、LRU の新しさを更新します。欠落または期限切れの場合は undefined を返します。
set(key, value)	新しい有効期限で値を保存します。maxEntries 超過時は LRU エントリーを破棄します。
del(key)	エントリーを削除します。
clear()	すべてのエントリーを消去します。
pruneExpired(limit?)	最大 limit 件（デフォルト 1000）を走査して、期限切れエントリーを削除します。
size()	削除またはアクセスされるまで、期限切れエントリーを含む総エントリー数を返します。

使用例

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 の動作

• get: ヒット時にエントリーを最新使用位置へ移動します。
• set: キーを MRU 位置に再挿入し、maxEntries 超過時には最も古いエントリーを破棄します。
• 有効期限: 期限切れエントリーは get 時に削除されます。バックグラウンドクリーンアップには pruneExpired() を使用してください。

---

📐 ベストプラクティス

1. キャッシュのスコープをサービスのライフタイムにする

インメモリキャッシュはプロセスごとです。インスタンス間または再起動後には同期されません。

2. データの鮮度に応じて TTL を選ぶ

頻繁に変化するデータには短い TTL を使用し、安定した参照データにはデフォルトを使用します。

3. 期限切れエントリーを定期的に削除する

// 長時間実行するサービスでの任意のメンテナンス
setInterval(() => cache.pruneExpired(), 60_000);

---

🔗 関連項目

• 共通ユーティリティ — キャッシュパターンと併用する一般ヘルパー