TTL Set

1.0.0 · active · verified Sun Apr 19

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`.

Common errors

```
TypeError: TTLSet is not a constructor
```
cause Attempting to use `TTLSet` without the `new` keyword, or incorrectly importing it in an ESM context.

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');`.
```
TypeError: cache.get is not a function
```
cause Trying to use `Map`-like methods (`get`, `set`) on a `TTLSet` instance. `TTLSet` implements the `Set` API, not the `Map` API.

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.

Warnings

gotcha 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.
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.
gotcha 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.
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.

Install

npm install ttl-set npm
yarn add ttl-set yarn
pnpm add ttl-set pnpm

Imports

TTLSet
wrong:
```
const { TTLSet } = require('ttl-set');
```
correct:
```
import TTLSet from 'ttl-set';
```
The package exports `TTLSet` as a default export for ESM. CommonJS users should `const TTLSet = require('ttl-set');`.
TTLSet (CommonJS)
wrong:
```
import TTLSet from 'ttl-set';
```
correct:
```
const TTLSet = require('ttl-set');
```
This is the correct CommonJS `require` syntax as demonstrated in the package's README for Node.js environments.

Quickstart

This quickstart demonstrates how to create a `TTLSet`, add elements, and observe their automatic expiration over time based on the defined TTL.

const TTLSet = require('ttl-set');

// Create a new TTLSet instance with a 1-minute (60,000 ms) time-to-live
const cache = new TTLSet(60 * 1000);

console.log('Adding "hello" to cache...');
cache.add('hello');

// Simulate waiting 40 seconds
setTimeout(() => {
  console.log('Adding "world" to cache after 40s...');
  cache.add('world');
  // "hello" is still alive (40s elapsed < 60s TTL)
  console.log('Has "hello" (40s)?', cache.has('hello')); // true
  console.log('Current cache size:', cache.size); // 2

  // Simulate waiting another 40 seconds (total 80s)
  setTimeout(() => {
    console.log('Checking cache after another 40s (total 80s)...');
    // "hello" should have expired (80s > 60s TTL)
    console.log('Has "hello" (80s)?', cache.has('hello')); // false
    // "world" should still be alive (40s elapsed for "world" < 60s TTL)
    console.log('Has "world" (40s for "world")?', cache.has('world')); // true
    console.log('Current cache size:', cache.size); // 1

    // Simulate waiting another 40 seconds (total 120s)
    setTimeout(() => {
      console.log('Checking cache after another 40s (total 120s)...');
      // "world" should now have expired (80s elapsed for "world" > 60s TTL)
      console.log('Has "world" (80s for "world")?', cache.has('world')); // false
      console.log('Current cache size:', cache.size); // 0
    }, 40 * 1000);

  }, 40 * 1000);

}, 40 * 1000);

view raw JSON →