LRU Cache

/**
 * A simple LRU cache implementation that uses a doubly linked list to track the order of items.
 * When an item is added or accessed, it's marked as the most recently used.
 * When the cache is full, the oldest item is removed automatically.
 *
 * @typeParam K - The type of the key
 * @typeParam V - The type of the value
 */
class LRUCache<K, V> {
  /**
   * Create a new LRU cache.
   * @param config - Optional configuration for the cache
   */
  constructor(config?: LRUCacheOptions);

  /**
   * Adds a new item to the cache.
   * If the key already exists, updates the value and marks it as most recently used.
   * If inserting the new item would exceed max size, removes the oldest item.
   *
   * @param key - The key to add to the cache
   * @param value - The value to add to the cache
   */
  add(key: K, value: V): void;

  /**
   * Returns a value from the cache, or undefined if not in the cache.
   * When a value is returned, it's marked as the most recently used item.
   *
   * @param key - The key to retrieve from the cache
   * @returns The cached value or undefined
   */
  get(key: K): V | undefined;

  /**
   * Returns true if the key exists in the cache, false otherwise.
   *
   * @param key - The key to check for in the cache
   * @returns Boolean indicating if key exists
   */
  has(key: K): boolean;

  /**
   * Removes an item from the cache and reconciles the linked list.
   *
   * @param key - The key to remove from the cache
   */
  remove(key: K): void;

  /**
   * Returns the current size of the cache.
   *
   * @returns Number of items currently in the cache
   */
  size(): number;
}

/**
 * Configuration options for LRU cache.
 */
interface LRUCacheOptions {
  /** Maximum number of items to store in the cache. Defaults to 100 if not specified. */
  maxSize?: number;
}

import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

// Create cache with default max size (100)
const cache = new LRUCache<string, number>();

// Add items
cache.add('user:123', 42);
cache.add('user:456', 99);

// Retrieve items
const value = cache.get('user:123'); // 42

// Check existence
if (cache.has('user:123')) {
  console.log('User 123 exists in cache');
}

// Remove items
cache.remove('user:456');

// Check size
console.log('Cache size:', cache.size());

import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

// Create cache with custom max size
const cache = new LRUCache<string, number>({ maxSize: 50 });

// Add items - oldest items are automatically evicted when size exceeds 50
for (let i = 0; i < 100; i++) {
  cache.add(`item:${i}`, i);
}

console.log('Cache size:', cache.size()); // 50

import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

// Cache for expensive computation results
const resultCache = new LRUCache<string, object>({ maxSize: 100 });

function expensiveOperation(input: string): object {
  // Check cache first
  const cached = resultCache.get(input);
  if (cached !== undefined) {
    return cached;
  }

  // Perform expensive computation
  const result = { /* ... computed result ... */ };

  // Store in cache for future use
  resultCache.add(input, result);

  return result;
}

import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

interface User {
  id: string;
  name: string;
  email: string;
}

// Type-safe user cache
const userCache = new LRUCache<string, User>({ maxSize: 200 });

userCache.add('user:123', {
  id: '123',
  name: 'Alice',
  email: 'alice@example.com',
});

const user = userCache.get('user:123');
if (user) {
  console.log(user.name); // TypeScript knows user is User type
}