oblivious-set

library2.0.0jsnpmunverified

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.

database

npm install oblivious-set

github ↗package ↗

INSTALL

IMPORT

SIG · OBLIVIOUS-SET

oblivious-set

databasejavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ObliviousSet

✓ import { ObliviousSet } from 'oblivious-set';

✗ const ObliviousSet = require('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)

✓ import type { ObliviousSet } from 'oblivious-set';

✗ import { ObliviousSet } from 'oblivious-set';

When only importing the type definition in TypeScript, use `import type` for clarity and to ensure tree-shaking.

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);

Debug

Known issues

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

affects: >=1.0.0

breakingVersion 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');`.

affects: >=2.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/oblivious-set/dist/index.mjs not supported.

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

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

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.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/pubkey/oblivious-set ↗

packagehttps://www.npmjs.com/package/oblivious-set ↗