clean-cache

library1.0.2jsnpmunverified

Clean Cache is a minimal in-memory JavaScript cache with TTL (time-to-live) support, packaged as a single file with zero dependencies. Current stable version is 1.0.2. It offers a simple API with `add`, `retrieve`, `count`, and `tidy` methods, and validates keys to prevent null/undefined. Unlike larger caching libraries (e.g., node-cache, lru-cache), it keeps dependencies to a minimum and is fully tested. Suitable for small Node.js projects needing a lightweight, ephemeral cache.

storage

npm install clean-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLEAN-CACHE

clean-cache

storagejavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Cache

✓ const { Cache } = require('clean-cache')

✗ import Cache from 'clean-cache'

Package is CommonJS-only. Named export, not default.

Cache

✓ import { Cache } from 'clean-cache'

✗ import Cache from 'clean-cache'

Even in ESM, named import is required.

Cache

✓ const { Cache } = require('clean-cache')

✗ const Cache = require('clean-cache')

Require of the package returns an object with Cache property, not the class directly.

Basic usage: create a cache with TTL, add and retrieve an item, then see it expire.

const { Cache } = require('clean-cache'); const myCache = new Cache(30000); // TTL 30 seconds myCache.add('user1', { name: 'Alice' }); console.log(myCache.retrieve('user1')); // { name: 'Alice' } console.log(myCache.count()); // 1 setTimeout(() => { console.log(myCache.retrieve('user1')); // null after 30s }, 31000);

Debug

Known issues

gotchaPassing null or undefined as key to add/retrieve throws an error.

fix

Always provide a valid string or number key.

affects: >=1.0.0

gotchaTTL is in milliseconds, not seconds. Default TTL is 60000ms (60 seconds).

fix

Use milliseconds. e.g., 5000 for 5 seconds.

affects: >=1.0.0

gotchaPackage uses CommonJS module system, not ESM. Import directly with require.

fix

Use require or use a bundler that handles CJS.

affects: >=1.0.0

gotcharetrieve returns null for non-existent or expired keys. Do not expect undefined.

fix

Check for null explicitly.

affects: >=1.0.0

gotchaCache does not automatically remove expired items; use tidy() to clean them.

fix

Call myCache.tidy() periodically to free memory.

affects: >=1.0.0

gotchaadd with no TTL argument uses the cache default TTL, not infinite.

fix

To avoid unintended expiration, pass a very large number or rely on default behavior.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: myCache.add is not a function

Imported Cache class incorrectly (e.g., `import Cache from 'clean-cache'` instead of `const { Cache } = require('clean-cache')`)

fix

Use named import: `const { Cache } = require('clean-cache')`

TypeError: Cannot read properties of null (reading 'foo')

retrieve returned null because key expired or doesn't exist

fix

Always check for null: `const val = myCache.retrieve('key'); if (val !== null) { ... }`

Error: Invalid key

Passed null or undefined as key to add or retrieve

fix

Pass a valid string or number. Example: `myCache.add('validKey', data)`

Cache is not a constructor

Required the package as default export instead of named export

fix

Use `const { Cache } = require('clean-cache')`

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kuper-adrian/clean-cache ↗

packageclean-cache ↗

homepagehttps://github.com/kuper-adrian/clean-cache#readme ↗