lru-cache 5.1.1

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: verify pkg:npm/lru-cache@5.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/lru-cache@5.1.1
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:40ef9482591a6b22125b3821804aac4dface7d99d47be353cd5593a22edf5c35","constraints":{"executionContext":"node"},"contract":["LRUCache get and set operations retrieve cached values and respect maximum capacity (max) by evicting the least recently used entries","LRUCache maxAge configuration expires entries after duration while allowStale and prune manage stale item retrieval and cleanup","LRUCache length calculation tracks weighted item sizes and triggers eviction when total length exceeds max capacity"],"goal":"verify pkg:npm/lru-cache@5.1.1","kind":"HOW","packages":["pkg:npm/lru-cache@5.1.1"],"schemaVersion":1},"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@5.1.1"],"schemaVersion":1,"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": "5.1.1"
      }
    },
    "node_modules/lru-cache": {
      "version": "5.1.1",
      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
      "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^3.0.2"
      }
    },
    "node_modules/yallist": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
      "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
      "license": "ISC"
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/lru-cache@5.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/lru-cache@5.1.1"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

/**
 * Creates an LRU cache instance with given options.
 * @param {object} [options] - Cache options (max, maxAge, length, dispose, stale, etc.)
 * @returns {LRU}
 */
function createCache(options = {}) {
  return new LRU(options);
}

/**
 * Stores a value in the cache with an optional per-item maxAge.
 * @param {LRU} cache
 * @param {string} key
 * @param {*} value
 * @param {number} [maxAge]
 */
function setCacheValue(cache, key, value, maxAge) {
  return cache.set(key, value, maxAge);
}

/**
 * Retrieves a value from the cache.
 * @param {LRU} cache
 * @param {string} key
 * @returns {*}
 */
function getCacheValue(cache, key) {
  return cache.get(key);
}

/**
 * Retrieves a value without updating the recently-used ordering.
 * @param {LRU} cache
 * @param {string} key
 * @returns {*}
 */
function peekCacheValue(cache, key) {
  return cache.peek(key);
}

/**
 * Checks if key exists in cache.
 * @param {LRU} cache
 * @param {string} key
 * @returns {boolean}
 */
function hasCacheKey(cache, key) {
  return cache.has(key);
}

/**
 * Deletes a key from the cache.
 * @param {LRU} cache
 * @param {string} key
 */
function deleteCacheKey(cache, key) {
  return cache.del(key);
}

/**
 * Resets the entire cache.
 * @param {LRU} cache
 */
function resetCache(cache) {
  cache.reset();
}

/**
 * Proactively prunes expired entries from the cache.
 * @param {LRU} cache
 */
function pruneCache(cache) {
  cache.prune();
}

module.exports = {
  createCache,
  setCacheValue,
  getCacheValue,
  peekCacheValue,
  hasCacheKey,
  deleteCacheKey,
  resetCache,
  pruneCache,
  LRU,
};

const assert = require('node:assert/strict');
const {
  createCache,
  setCacheValue,
  getCacheValue,
  peekCacheValue,
  hasCacheKey,
  deleteCacheKey,
  resetCache,
  pruneCache,
} = require('../src/index.js');

async function runContracts() {
  // Contract 1: LRUCache get and set operations retrieve cached values and respect maximum capacity (max) by evicting the least recently used entries
  {
    const cache = createCache({ max: 2 });

    setCacheValue(cache, 'a', 100);
    setCacheValue(cache, 'b', 200);

    assert.strictEqual(getCacheValue(cache, 'a'), 100, 'getCacheValue retrieves stored entry for key "a"');
    assert.strictEqual(getCacheValue(cache, 'b'), 200, 'getCacheValue retrieves stored entry for key "b"');
    assert.strictEqual(cache.itemCount, 2, 'Cache itemCount should equal 2');

    // Accessing "a" makes "b" the least recently used
    getCacheValue(cache, 'a');

    // Adding "c" should evict least recently used "b"
    setCacheValue(cache, 'c', 300);

    assert.strictEqual(hasCacheKey(cache, 'b'), false, 'Key "b" should be evicted when capacity 2 is exceeded');
    assert.strictEqual(getCacheValue(cache, 'b'), undefined, 'getCacheValue returns undefined for evicted key');
    assert.strictEqual(getCacheValue(cache, 'a'), 100, 'Key "a" remains in cache');
    assert.strictEqual(getCacheValue(cache, 'c'), 300, 'Key "c" remains in cache');

    // Deleting and resetting
    deleteCacheKey(cache, 'a');
    assert.strictEqual(hasCacheKey(cache, 'a'), false, 'Key "a" should be deleted');
    assert.strictEqual(cache.itemCount, 1, 'Item count should decrease after deletion');

    resetCache(cache);
    assert.strictEqual(cache.itemCount, 0, 'Resetting clears all entries');
  }

  // Contract 2: LRUCache maxAge configuration expires entries after duration while allowStale and prune manage stale item retrieval and cleanup
  {
    const cache = createCache({ max: 10, maxAge: 50 });
    setCacheValue(cache, 'temp1', 'val1');
    setCacheValue(cache, 'temp2', 'val2', 500); // custom maxAge override

    assert.strictEqual(getCacheValue(cache, 'temp1'), 'val1', 'Entry should be immediately available');

    const staleCache = createCache({ max: 10, maxAge: 50, stale: true });
    setCacheValue(staleCache, 'tempStale', 'valStale');

    // Wait for 60ms so 50ms maxAge expires
    await new Promise((resolve) => setTimeout(resolve, 60));

    // temp1 should have expired
    assert.strictEqual(getCacheValue(cache, 'temp1'), undefined, 'Expired entry should return undefined');
    // temp2 with longer maxAge should still be present
    assert.strictEqual(getCacheValue(cache, 'temp2'), 'val2', 'Entry with longer custom maxAge remains valid');

    // staleCache with stale: true returns stale value once on get, then removes it
    assert.strictEqual(getCacheValue(staleCache, 'tempStale'), 'valStale', 'stale: true returns value once after expiration');
    assert.strictEqual(getCacheValue(staleCache, 'tempStale'), undefined, 'stale value is deleted after being accessed');

    // Test prune: add an entry with short maxAge and prune it
    const pruneTestCache = createCache({ max: 10, maxAge: 30 });
    setCacheValue(pruneTestCache, 'toPrune', 'pruneVal');
    await new Promise((resolve) => setTimeout(resolve, 40));
    assert.strictEqual(pruneTestCache.itemCount, 1, 'Item count before prune is 1');
    pruneCache(pruneTestCache);
    assert.strictEqual(pruneTestCache.itemCount, 0, 'pruneCache proactively removes expired entries');
  }

  // Contract 3: LRUCache length calculation tracks weighted item sizes and triggers eviction when total length exceeds max capacity
  {
    const evictions = [];
    const cache = createCache({
      max: 10,
      length: (val) => (typeof val === 'string' ? val.length : 1),
      dispose: (key, val) => {
        evictions.push({ key, val });
      },
    });

    setCacheValue(cache, 'first', '12345'); // length 5
    assert.strictEqual(cache.length, 5, 'Total length should reflect item length calculation');

    setCacheValue(cache, 'second', 'abcde'); // length 5, total 10
    assert.strictEqual(cache.length, 10, 'Total length should sum item lengths');

    // peek should not refresh recency
    assert.strictEqual(peekCacheValue(cache, 'first'), '12345', 'peek retrieves value without updating LRU position');

    // Adding third (length 4) will push total to 14 > 10, causing "first" to be evicted
    setCacheValue(cache, 'third', 'xyzw'); // length 4
    assert.strictEqual(hasCacheKey(cache, 'first'), false, 'first should be evicted due to max length exceeded');
    assert.strictEqual(cache.length, 9, 'Total length is now 5 (second) + 4 (third) = 9');
    assert.deepStrictEqual(evictions, [{ key: 'first', val: '12345' }], 'dispose callback should be triggered on eviction');
  }

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

runContracts().catch((err) => {
  console.error(err);
  process.exit(1);
});