Registry / storage / urlcache

urlcache

JSON →
library0.7.0jsnpmunverified

URL key-value cache for Node.js (>=0.10) that stores values keyed by URL strings or parsed URL objects. Version 0.7.0 is the latest release, supporting Node.js v9. It normalizes URLs by default to avoid duplicate keys, offers optional expiry times for cached values, and can strip URL hashes. Compared to simple Map-based caching, urlcache provides URL normalization and expiry out of the box. The API is minimal: get, set, clear, and length methods. Note that versions <0.7 require an Object.assign polyfill for Node <4, and the API has changed across releases (Promises removed in 0.5, .length added in 0.6).

storagedevops
npm install urlcache
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · URLCACHE
U
urlcache
storagejavascriptv0.7.0
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.

UrlCache
✓ var UrlCache = require('urlcache');
✗ import UrlCache from 'urlcache';
Package uses CommonJS, not ESM. 'import' will fail with default Node.js setups.
UrlCache (constructor)
✓ var cache = new UrlCache(options);
✗ var cache = UrlCache(options);
UrlCache must be called with 'new', otherwise instance methods will not work.
cache.get
✓ cache.get('http://example.com');
✗ cache.get('/relative/path');
Keys are expected to be absolute URLs or parsed URL objects; relative strings may not match after normalization.
cache.set with Promise
✓ cache.set('url', somePromise);
✗ cache.set('url', somePromise, 5000);
When setting a Promise, expiry time as third argument still works, but the cached value will be the resolved value once the promise settles.

Demonstrates basic usage of urlcache: setting, getting, clearing a cached value with expiry, and handling promises as values.

var UrlCache = require('urlcache'); var cache = new UrlCache({ expiryTime: 60000 }); cache.set('http://example.com', 'value', 30000); console.log(cache.get('http://example.com')); // 'value' console.log(cache.length()); // 1 cache.clear('http://example.com'); console.log(cache.get('http://example.com')); // undefined // Using a Promise var promise = new Promise(function(resolve) { setTimeout(function() { resolve('async value'); }, 100); }); cache.set('http://example.com', promise); promise.then(function(value) { console.log(cache.get('http://example.com')); // 'async value' });
Debug
Known issues
breakingIn version 0.5.0, Promises were removed from the API. The .set() method no longer returns a promise, and .get() no longer resolves promises automatically. If you relied on promise-based behavior, you must update your code to handle promises manually.
fix
Use Promise.resolve(cache.get(url)) if you expect promise-wrapped values, or remove .then() calls on .set().
affects: >=0.5.0
breakingIn version 0.6.0, the .length() method was added and the Object.assign polyfill was removed. Node.js <4.0 will crash if Object.assign is not polyfilled.
fix
Node.js >=4.0 is recommended; for older versions, provide a global Object.assign polyfill (e.g., require('object.assign').shim()).
affects: >=0.6.0
breakingIn version 0.4.0, the API was changed to a simpler promise-based version. Code written for 0.3.0 or earlier will not work without migration.
fix
Refer to the changelog and update your usage of .set() and .get() to match the new API.
affects: >=0.4.0
gotchaThe 'options.stripUrlHashes' option defaults to true, which removes URL fragments. This can lead to unexpected cache collisions if you rely on fragments for distinct caching.
fix
Set options.stripUrlHashes: false if you need to differentiate cache entries by URL fragments.
gotchaThe 'options.normalizeUrls' option is true by default, which modifies the URL key. This may cause keys that appear different to be considered identical (e.g., because of trailing slashes or default ports).
fix
Set options.normalizeUrls: false if you want to use raw URLs as keys.
Errors
Common errors & fixes
TypeError: UrlCache is not a constructor
Forgetting the 'new' keyword when creating a UrlCache instance.
fix
Use 'new UrlCache(options)' instead of 'UrlCache(options)'.
ReferenceError: require is not defined
Trying to use require() in an ESM environment (e.g., .mjs file or type: module in package.json).
fix
Use dynamic import: const UrlCache = (await import('urlcache')).default; Or switch to CommonJS.
TypeError: cache.length is not a function
Using version 0.5.x or earlier where .length() did not exist.
fix
Upgrade to version 0.6.0+ and use .length() method.
TypeError: cache.get(...).then is not a function
Expecting .get() to return a Promise (removed in 0.5.0).
fix
If you set a Promise as a value, use Promise.resolve(cache.get(url)).then(...) to handle the resolved value.
Cannot find module 'urlobj'
Missing peer dependency 'urlobj' is not installed automatically.
fix
Run 'npm install urlobj' alongside urlcache.
Upgrade
Version history
0.7.0latest on npm
Audit
Dependencies
urlobjrequiredUsed for URL parsing and normalization via urlobj.parse()
Agent activity
41 hits · last 30 days
node
36
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/stevenvachon/urlcache ↗
packageurlcache ↗
homepagehttps://github.com/stevenvachon/urlcache#readme ↗
urlcache — npm install urlcache · libregistry