ObliviousSet

2.0.0 · active · verified Sun Apr 19

ObliviousSet provides a JavaScript Set-like data structure where each entry is associated with a Time-To-Live (TTL). Unlike traditional caching mechanisms that often rely on intervals or timeouts for eviction, ObliviousSet's design avoids these, enabling proper garbage collection of the set instance when no active references exist. The current stable version is 2.0.0, which targets modern Node.js environments (>=16). While a strict release cadence isn't published, the package is actively maintained with updates released as needed for features or bug fixes. Its key differentiator is the efficient, passive expiration model where entries are only 'removed' (marked as expired) when explicitly checked via the `has()` method or when iterating over active elements, rather than through eager background processes. This minimizes overhead and resource consumption.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/oblivious-set/dist/index.mjs not supported.
```
cause Attempting to import `oblivious-set` using CommonJS `require()` syntax in a project that is configured as CommonJS, while `oblivious-set` is an ESM-first package.

fix Convert your project to use ES Modules by setting `"type": "module"` in your `package.json` and using `import` statements, or use dynamic import: `const { ObliviousSet } = await import('oblivious-set');`.
```
TypeError: ObliviousSet is not a constructor
```
cause This typically occurs when trying to instantiate `ObliviousSet` with `new` after an incorrect `require()` or `import` that didn't correctly resolve the default or named export.

fix Ensure you are using the correct named import: `import { ObliviousSet } from 'oblivious-set';` and that your environment supports ES Modules.
```
ReferenceError: ObliviousSet is not defined
```
cause The `ObliviousSet` class was used without being correctly imported or declared in the current scope.

fix Add the import statement `import { ObliviousSet } from 'oblivious-set';` at the top of your file.

Warnings

gotcha ObliviousSet entries are not eagerly purged or deleted via background timers. An entry's TTL is only evaluated and applied when `has()`, `get()`, or an iteration method (`forEach`, `values`, `entries`, `keys`) is called on it. This means `size` can include expired items until such an operation occurs.
Fix: Be aware that the `size` property might not immediately reflect the number of *active* items. Explicitly use `has()` or iterate over the set to trigger expiration checks for stale entries.
breaking Version 2.0.0 of `oblivious-set` moved to an ESM-first distribution and raised the minimum Node.js requirement to version 16. Projects targeting older Node.js versions or relying exclusively on CommonJS `require()` syntax may encounter import errors.
Fix: Ensure your project uses Node.js 16 or newer. If you are in a CommonJS module, you might need to convert your project to ESM or use dynamic `import()` if supported by your runtime/toolchain, e.g., `const { ObliviousSet } = await import('oblivious-set');`.
gotcha Adding a value that already exists in the set will reset its Time-To-Live (TTL) to the initial duration configured for the set. This means subsequent `has()` checks will reflect the new expiration time.
Fix: If you intend to 'touch' an item without resetting its TTL, ensure you only `add()` new, unique items or implement custom logic to avoid resetting the TTL on existing ones.

Install

npm install oblivious-set npm
yarn add oblivious-set yarn
pnpm add oblivious-set pnpm

Imports

ObliviousSet
wrong:
```
const ObliviousSet = require('oblivious-set');
```
correct:
```
import { ObliviousSet } from 'oblivious-set';
```
Package is ESM-first. CommonJS `require` syntax is not supported in modern Node.js environments for this package (engines.node >= 16).
ObliviousSet (Type)
wrong:
```
import { ObliviousSet } from 'oblivious-set';
```
correct:
```
import type { ObliviousSet } from 'oblivious-set';
```
When only importing the type definition in TypeScript, use `import type` for clarity and to ensure tree-shaking.

Quickstart

Demonstrates how to create an ObliviousSet, add elements, check for their existence before and after expiration, and clear the set.

import { ObliviousSet } from 'oblivious-set';

// Create a set with a TTL of 100 milliseconds
const obliviousSet = new ObliviousSet(100);

// Add a value; its TTL starts now
obliviousSet.add('user_session_123');

// Check existence immediately
console.log('Has user_session_123 after add:', obliviousSet.has('user_session_123')); // true

// Wait for the TTL to expire
setTimeout(() => {
  console.log('Has user_session_123 after 150ms:', obliviousSet.has('user_session_123')); // false

  // Add another value and check its initial state
  obliviousSet.add('another_item');
  console.log('Has another_item:', obliviousSet.has('another_item')); // true

  // Clear all entries from the set
  obliviousSet.clear();
  console.log('Set size after clear:', obliviousSet.size); // 0
}, 150);

view raw JSON →