lru-cache 7.18.3: Basic LRUCache get set and TTL eviction

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: Basic LRUCache get set and TTL eviction
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/lru-cache@7.18.3
Demonstrate these symbols/APIs:
  - LRUCache
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:44dc98230fd93476fbb932970764810e9a406cdf27de3a9e8f37b02f4cc4aee4","constraints":{"executionContext":"node"},"contract":["LRUCache set and get operations retrieve cached values and respect maximum capacity (max) by evicting the least recently used entries","LRUCache ttl configuration automatically expires entries after the specified duration while allowStale and purgeStale control stale item visibility","LRUCache methods has, delete, clear, and peek allow querying and manipulating cache entries without disrupting LRU ordering"],"goal":"Basic LRUCache get set and TTL eviction","kind":"HOW","packages":["pkg:npm/lru-cache@7.18.3"],"schemaVersion":1,"symbols":["LRUCache"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/lru-cache@7.18.3"],"schemaVersion":1,"symbols":["LRUCache"],"verifierAdapter":"node-typescript@1"}

{
  "name": "lru-cache-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "lru-cache-sample",
      "version": "1.0.0",
      "dependencies": {
        "lru-cache": "7.18.3"
      }
    },
    "node_modules/lru-cache": {
      "version": "7.18.3",
      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-7.18.3.tgz",
      "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==",
      "license": "ISC",
      "engines": {
        "node": ">=12"
      }
    }
  }
}

{
  "name": "lru-cache-sample",
  "version": "1.0.0",
  "dependencies": {
    "lru-cache": "7.18.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "Basic LRUCache get set and TTL eviction",
  "kind": "HOW",
  "packages": [
    "pkg:npm/lru-cache@7.18.3"
  ],
  "symbols": [
    "LRUCache"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const LRUCache = require('lru-cache');

/**
 * Creates and configures an LRU cache instance.
 *
 * @param {object} options - Configuration options for LRUCache.
 * @param {number} options.max - Maximum number of items in cache.
 * @param {number} [options.ttl] - Time to live in milliseconds.
 * @param {boolean} [options.allowStale] - Whether to return stale items.
 * @param {boolean} [options.updateAgeOnGet] - Whether to update age on get.
 * @returns {LRUCache}
 */
function createCache(options) {
  return new LRUCache(options);
}

/**
 * Stores a key-value pair in the cache with optional entry-specific options.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @param {string} key - Cache key.
 * @param {any} value - Cache value.
 * @param {object} [options] - Options such as ttl.
 * @returns {LRUCache}
 */
function setEntry(cache, key, value, options) {
  return cache.set(key, value, options);
}

/**
 * Retrieves a value from the cache by key.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @param {string} key - Cache key.
 * @param {object} [options] - Options such as allowStale.
 * @returns {any}
 */
function getEntry(cache, key, options) {
  return cache.get(key, options);
}

/**
 * Reads a value from the cache without updating its recency or TTL.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @param {string} key - Cache key.
 * @param {object} [options] - Options such as allowStale.
 * @returns {any}
 */
function peekEntry(cache, key, options) {
  return cache.peek(key, options);
}

/**
 * Checks whether an unexpired key exists in the cache.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @param {string} key - Cache key.
 * @returns {boolean}
 */
function hasEntry(cache, key) {
  return cache.has(key);
}

/**
 * Removes an entry from the cache by key.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @param {string} key - Cache key.
 * @returns {boolean}
 */
function deleteEntry(cache, key) {
  return cache.delete(key);
}

/**
 * Clears all entries from the cache.
 *
 * @param {LRUCache} cache - Target cache instance.
 */
function clearCache(cache) {
  cache.clear();
}

/**
 * Purges all expired/stale entries from the cache.
 *
 * @param {LRUCache} cache - Target cache instance.
 */
function purgeStale(cache) {
  cache.purgeStale();
}

/**
 * Returns the current number of items in the cache.
 *
 * @param {LRUCache} cache - Target cache instance.
 * @returns {number}
 */
function getCacheSize(cache) {
  return cache.size;
}

module.exports = {
  createCache,
  setEntry,
  getEntry,
  peekEntry,
  hasEntry,
  deleteEntry,
  clearCache,
  purgeStale,
  getCacheSize,
  LRUCache,
};

const assert = require('node:assert/strict');
const {
  createCache,
  setEntry,
  getEntry,
  peekEntry,
  hasEntry,
  deleteEntry,
  clearCache,
  purgeStale,
  getCacheSize,
  LRUCache,
} = require('../src/index.js');

async function runTests() {
  // Contract 1: LRUCache set and get operations retrieve cached values and respect maximum capacity (max) by evicting the least recently used entries
  {
    const cache = createCache({ max: 3 });
    assert.ok(cache instanceof LRUCache, 'Cache should be instance of LRUCache');
    assert.strictEqual(getCacheSize(cache), 0, 'Initial cache size should be 0');

    setEntry(cache, 'k1', 'val1');
    setEntry(cache, 'k2', 'val2');
    setEntry(cache, 'k3', 'val3');

    assert.strictEqual(getCacheSize(cache), 3, 'Cache size should be 3');
    assert.strictEqual(getEntry(cache, 'k1'), 'val1', 'k1 should return val1');
    assert.strictEqual(getEntry(cache, 'k2'), 'val2', 'k2 should return val2');
    assert.strictEqual(getEntry(cache, 'k3'), 'val3', 'k3 should return val3');

    // Access k1 to make k2 the least recently used
    getEntry(cache, 'k1');

    // Add 4th item, which exceeds max=3, evicting k2
    setEntry(cache, 'k4', 'val4');

    assert.strictEqual(getCacheSize(cache), 3, 'Cache size should remain at max=3');
    assert.strictEqual(hasEntry(cache, 'k2'), false, 'Least recently used item k2 should have been evicted');
    assert.strictEqual(getEntry(cache, 'k2'), undefined, 'Evicted item k2 should return undefined');
    assert.strictEqual(getEntry(cache, 'k1'), 'val1', 'Accessed item k1 should still be present');
    assert.strictEqual(getEntry(cache, 'k3'), 'val3', 'Item k3 should still be present');
    assert.strictEqual(getEntry(cache, 'k4'), 'val4', 'Item k4 should be present');
  }

  // Contract 2: LRUCache ttl configuration automatically expires entries after the specified duration while allowStale and purgeStale control stale item visibility
  {
    const cache = createCache({ max: 10, ttl: 30 });

    setEntry(cache, 'normal-expiring', 'data-1');
    setEntry(cache, 'stale-retrievable', 'data-2');
    setEntry(cache, 'long-living', 'data-3', { ttl: 200 });

    assert.strictEqual(hasEntry(cache, 'normal-expiring'), true, 'Entry should exist immediately');
    assert.strictEqual(hasEntry(cache, 'stale-retrievable'), true, 'Entry should exist immediately');
    assert.strictEqual(getEntry(cache, 'normal-expiring'), 'data-1', 'Entry should return value immediately');

    // Wait for the 30ms default TTL to expire
    await new Promise((resolve) => setTimeout(resolve, 50));

    // 'normal-expiring' should now be expired and return undefined
    assert.strictEqual(hasEntry(cache, 'normal-expiring'), false, 'Expired entry should return false from hasEntry');
    assert.strictEqual(getEntry(cache, 'normal-expiring'), undefined, 'Expired entry should return undefined without allowStale');

    // 'stale-retrievable' is also expired, but can be retrieved when allowStale is explicitly requested
    assert.strictEqual(
      getEntry(cache, 'stale-retrievable', { allowStale: true }),
      'data-2',
      'Expired entry should be accessible with allowStale: true'
    );

    // 'long-living' has 200ms TTL, so it should still be valid
    assert.strictEqual(hasEntry(cache, 'long-living'), true, 'Custom TTL item should not be expired yet');
    assert.strictEqual(getEntry(cache, 'long-living'), 'data-3', 'Custom TTL item should return value');

    // Set another stale item to verify purgeStale
    setEntry(cache, 'to-purge', 'purge-me', { ttl: 10 });
    await new Promise((resolve) => setTimeout(resolve, 20));
    purgeStale(cache);

    assert.strictEqual(
      getEntry(cache, 'to-purge', { allowStale: true }),
      undefined,
      'Purged stale entry should not be retrievable even with allowStale'
    );
  }

  // Contract 3: LRUCache methods has, delete, clear, and peek allow querying and manipulating cache entries without disrupting LRU ordering
  {
    const cache = createCache({ max: 2 });

    setEntry(cache, 'first', 'value1');
    setEntry(cache, 'second', 'value2');

    // peek reads without updating LRU order
    const peeked = peekEntry(cache, 'first');
    assert.strictEqual(peeked, 'value1', 'peekEntry returns value of first key');

    // Because we peeked 'first' instead of get, 'first' remains the oldest (LRU).
    // Adding 'third' should evict 'first'.
    setEntry(cache, 'third', 'value3');
    assert.strictEqual(hasEntry(cache, 'first'), false, 'first should have been evicted because peek did not refresh recency');
    assert.strictEqual(hasEntry(cache, 'second'), true, 'second should still be in cache');
    assert.strictEqual(hasEntry(cache, 'third'), true, 'third should be in cache');

    // deleteEntry
    const deleted = deleteEntry(cache, 'second');
    assert.strictEqual(deleted, true, 'deleteEntry should return true for existing key');
    assert.strictEqual(hasEntry(cache, 'second'), false, 'Deleted key should no longer exist in cache');
    assert.strictEqual(getCacheSize(cache), 1, 'Cache size should decrease after deletion');

    // clearCache
    clearCache(cache);
    assert.strictEqual(getCacheSize(cache), 0, 'Cache size should be 0 after clear');
    assert.strictEqual(hasEntry(cache, 'third'), false, 'Cleared cache should not contain third');
  }

  console.log('All pkg:npm/lru-cache@7.18.3 contracts passed successfully.');
}

runTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});