{"id":11485,"library":"oblivious-set","title":"ObliviousSet","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/pubkey/oblivious-set","tags":["javascript","set","oblivious","cache","typescript"],"install":[{"cmd":"npm install oblivious-set","lang":"bash","label":"npm"},{"cmd":"yarn add oblivious-set","lang":"bash","label":"yarn"},{"cmd":"pnpm add oblivious-set","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-first. CommonJS `require` syntax is not supported in modern Node.js environments for this package (engines.node >= 16).","wrong":"const ObliviousSet = require('oblivious-set');","symbol":"ObliviousSet","correct":"import { ObliviousSet } from 'oblivious-set';"},{"note":"When only importing the type definition in TypeScript, use `import type` for clarity and to ensure tree-shaking.","wrong":"import { ObliviousSet } from 'oblivious-set';","symbol":"ObliviousSet (Type)","correct":"import type { ObliviousSet } from 'oblivious-set';"}],"quickstart":{"code":"import { ObliviousSet } from 'oblivious-set';\n\n// Create a set with a TTL of 100 milliseconds\nconst obliviousSet = new ObliviousSet(100);\n\n// Add a value; its TTL starts now\nobliviousSet.add('user_session_123');\n\n// Check existence immediately\nconsole.log('Has user_session_123 after add:', obliviousSet.has('user_session_123')); // true\n\n// Wait for the TTL to expire\nsetTimeout(() => {\n  console.log('Has user_session_123 after 150ms:', obliviousSet.has('user_session_123')); // false\n\n  // Add another value and check its initial state\n  obliviousSet.add('another_item');\n  console.log('Has another_item:', obliviousSet.has('another_item')); // true\n\n  // Clear all entries from the set\n  obliviousSet.clear();\n  console.log('Set size after clear:', obliviousSet.size); // 0\n}, 150);","lang":"typescript","description":"Demonstrates how to create an ObliviousSet, add elements, check for their existence before and after expiration, and clear the set."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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');`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","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":"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');`.","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.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/oblivious-set/dist/index.mjs not supported."},{"fix":"Ensure you are using the correct named import: `import { ObliviousSet } from 'oblivious-set';` and that your environment supports ES Modules.","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.","error":"TypeError: ObliviousSet is not a constructor"},{"fix":"Add the import statement `import { ObliviousSet } from 'oblivious-set';` at the top of your file.","cause":"The `ObliviousSet` class was used without being correctly imported or declared in the current scope.","error":"ReferenceError: ObliviousSet is not defined"}],"ecosystem":"npm"}