Registry / storage / ttl-file-cache

ttl-file-cache

JSON →
library1.0.5jsnpmunverified

A Node.js disk-based cache module that writes cached items as files and manages automatic pruning of expired entries. Version 1.0.5 is the latest stable; it is a small utility with minimal dependencies (none notable). Key differentiator: it stores data on disk (file-based) with TTL expiry, automatically prunes expired items, and returns buffers with metadata (key, ttl, expires, parse method). It is useful for caching in environments with limited memory or when persistence across restarts is desired. The package supports both synchronous and asynchronous operations (getAll is async). It has not seen updates since 2022, suggesting maintenance mode.

npm install ttl-file-cache
INSTALL
IMPORT
SIG · TTL-FILE-CACHE
T
ttl-file-cache
storagejavascriptv1.0.5
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('ttl-file-cache')
import Cache from 'ttl-file-cache'
Package is CommonJS-only; does not support ES module imports natively.
ttl-file-cache
const Cache = require('ttl-file-cache'); const cache = new Cache()
const cache = require('ttl-file-cache') // returns the class, not an instance
Require returns the class constructor, not a singleton instance.
ttl-file-cache (type definitions)
No official TypeScript types; use @types/ttl-file-cache if available or define own.
none (no types)
The package has no built-in TypeScript definitions.

Shows instantiation, set, get with buffer and parse, del, clear, and async getAll.

const Cache = require('ttl-file-cache'); const cache = new Cache({ dir: '/tmp/my-cache' }); // Cache a string for 60 seconds cache.set('greeting', 'Hello, world!', 60); // Retrieve it const buf = cache.get('greeting'); if (buf) { console.log(buf.toString()); // 'Hello, world!' console.log(buf.parse()); // 'Hello, world!' } else { console.log('Cache expired or not found'); } // Cache an object (auto-converted to JSON) cache.set('user', { name: 'Alice', age: 30 }, 120); const userBuf = cache.get('user'); if (userBuf) { console.log(userBuf.parse()); // { name: 'Alice', age: 30 } } // Remove an item cache.del('greeting'); // Clear all cached files cache.clear(); // Note: getAll() is async and may be expensive cache.getAll().then(console.log).catch(console.error);
Debug
Known issues
gotchaget() returns null for expired or missing keys; always check for null before calling .parse().
fix
Use if (buf) { buf.parse(); } else { /* handle miss */ }
affects: *
gotchagetAll() is asynchronous and may be very slow with many items; do not call in tight loops.
fix
Use with caution; consider pagination or a scan alternative if performance is critical.
affects: *
gotchaThe package uses synchronous I/O for set/get/del; this can block the event loop under heavy load.
fix
Avoid using in latency-sensitive or high-concurrency scenarios. Consider an async file cache library instead.
affects: *
gotchaDefault cache directory is os.tmpdir() which may be cleared on reboot; always specify a persistent dir if needed.
fix
Pass a custom dir option to the constructor: new Cache({ dir: '/persistent/path' })
affects: *
gotchaBuffers returned from get() have extra properties (dataType, key, ttl, expires, parse). do NOT treat them as plain buffers.
fix
If you need only the raw buffer, use buf.slice(0) or convert via buf.toString('utf8') for string data.
affects: *
Errors
Common errors & fixes
TypeError: buf.parse is not a function
Calling .parse() on a buffer that is null or undefined (cache miss).
fix
Always check if cache.get() returns a value: const buf = cache.get('key'); if (buf) { buf.parse(); }
Error: ENOENT: no such file or directory, open '/tmp/ttl-file-cache/...'
The cache directory does not exist or has been deleted manually.
fix
Ensure the dir exists before creating Cache instance, or use the default (created automatically if parent exists).
Error: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView.
Passing a non-serializable value (e.g., undefined, function, Symbol) to cache.set().
fix
Convert complex objects to JSON strings or Buffers before caching.
Warning: cache.getAll() called but may be slow with many items.
Calling getAll() on a cache with thousands of files; it reads all files synchronously and returns an array.
fix
Avoid getAll() on large caches; consider using get() with known keys or implementing pagination.
Upgrade
Version history
1.0.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
1
Resources
ttl-file-cache — npm install ttl-file-cache · libregistry