{"id":12757,"library":"ttl-set","title":"TTL Set","description":"The `ttl-set` package provides a JavaScript `Set`-like data structure where each entry automatically expires after a specified time-to-live (TTL). It is currently at version 1.0.0, indicating a stable API with a well-defined feature set. The library's release cadence is likely infrequent due to its focused and stable utility functionality, serving as a robust solution for simple, time-bound caching needs. Its primary differentiator is the direct integration of TTL expiration into the `Set` interface, distinguishing it from general-purpose `Set` objects or more complex caching libraries that might offer LRU/LFU policies. This makes it ideal for scenarios requiring a basic, memory-efficient, and self-cleaning collection of unique values, such as tracking active sessions, recently seen items, or implementing basic rate-limiting without external dependencies or elaborate configuration. The core API mirrors `Set.prototype`, offering `add`, `has`, `clear`, and `size`.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/watson/ttl-set","tags":["javascript","ttl","set","cache","time"],"install":[{"cmd":"npm install ttl-set","lang":"bash","label":"npm"},{"cmd":"yarn add ttl-set","lang":"bash","label":"yarn"},{"cmd":"pnpm add ttl-set","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports `TTLSet` as a default export for ESM. CommonJS users should `const TTLSet = require('ttl-set');`.","wrong":"const { TTLSet } = require('ttl-set');","symbol":"TTLSet","correct":"import TTLSet from 'ttl-set';"},{"note":"This is the correct CommonJS `require` syntax as demonstrated in the package's README for Node.js environments.","wrong":"import TTLSet from 'ttl-set';","symbol":"TTLSet (CommonJS)","correct":"const TTLSet = require('ttl-set');"}],"quickstart":{"code":"const TTLSet = require('ttl-set');\n\n// Create a new TTLSet instance with a 1-minute (60,000 ms) time-to-live\nconst cache = new TTLSet(60 * 1000);\n\nconsole.log('Adding \"hello\" to cache...');\ncache.add('hello');\n\n// Simulate waiting 40 seconds\nsetTimeout(() => {\n  console.log('Adding \"world\" to cache after 40s...');\n  cache.add('world');\n  // \"hello\" is still alive (40s elapsed < 60s TTL)\n  console.log('Has \"hello\" (40s)?', cache.has('hello')); // true\n  console.log('Current cache size:', cache.size); // 2\n\n  // Simulate waiting another 40 seconds (total 80s)\n  setTimeout(() => {\n    console.log('Checking cache after another 40s (total 80s)...');\n    // \"hello\" should have expired (80s > 60s TTL)\n    console.log('Has \"hello\" (80s)?', cache.has('hello')); // false\n    // \"world\" should still be alive (40s elapsed for \"world\" < 60s TTL)\n    console.log('Has \"world\" (40s for \"world\")?', cache.has('world')); // true\n    console.log('Current cache size:', cache.size); // 1\n\n    // Simulate waiting another 40 seconds (total 120s)\n    setTimeout(() => {\n      console.log('Checking cache after another 40s (total 120s)...');\n      // \"world\" should now have expired (80s elapsed for \"world\" > 60s TTL)\n      console.log('Has \"world\" (80s for \"world\")?', cache.has('world')); // false\n      console.log('Current cache size:', cache.size); // 0\n    }, 40 * 1000);\n\n  }, 40 * 1000);\n\n}, 40 * 1000);","lang":"javascript","description":"This quickstart demonstrates how to create a `TTLSet`, add elements, and observe their automatic expiration over time based on the defined TTL."},"warnings":[{"fix":"If refresh-on-access or refresh-on-update behavior is desired, you must manually `delete` and then `add` the value again, or consider a different caching library.","message":"The TTL for an entry is set when it is first `add`ed to the set. Subsequent `add` calls with the same value do *not* refresh the existing entry's TTL, nor does checking `has()` extend its life. The expiration time is fixed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For extremely high-volume, long-lived caches, evaluate if `ttl-set`'s individual timer approach is suitable or if a more advanced caching strategy (e.g., using a single timer to scan for expirations or an external cache service) is required.","message":"The `ttl-set` internally uses `setTimeout` for each entry to manage expiration. For very large sets with long TTLs, this can lead to a significant number of active timers, potentially impacting event loop performance and memory usage, although modern JavaScript engines are highly optimized.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always instantiate `TTLSet` using `new TTLSet(ttl)`. For ESM, ensure `import TTLSet from 'ttl-set';` is used. For CommonJS, `const TTLSet = require('ttl-set');`.","cause":"Attempting to use `TTLSet` without the `new` keyword, or incorrectly importing it in an ESM context.","error":"TypeError: TTLSet is not a constructor"},{"fix":"Use `cache.has(value)` to check for existence and `cache.add(value)` to add elements. If you need key-value pairs with TTL, consider a `TTLMap` implementation or build one using `ttl-set` for keys and a regular `Map` for values.","cause":"Trying to use `Map`-like methods (`get`, `set`) on a `TTLSet` instance. `TTLSet` implements the `Set` API, not the `Map` API.","error":"TypeError: cache.get is not a function"}],"ecosystem":"npm"}