petty-cache

library3.7.0jsnpmunverified

Two-level cache for Node.js (in-memory + Redis) with automatic serialization, jitter, double-checked locking to prevent cache stampedes and thundering herds. Version 3.7.0 released under MIT license with monthly releases. Key differentiators: built-in distributed mutex and semaphore primitives, jittered TTLs (default 30-60s Redis, 2-5s in-memory), and double-checked locking on cache miss functions. ESM-only since v3.0.0.

storage

npm install petty-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PETTY-CACHE

petty-cache

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

PettyCache

✓ import PettyCache from 'petty-cache'

✗ const PettyCache = require('petty-cache')

Default import. ESM-only since v3.0.0. CommonJS require() will fail.

Mutex

✓ import { Mutex } from 'petty-cache/mutex'

✗ import { Mutex } from 'petty-cache'

Mutex and Semaphore are in separate subpath exports. They are not exported from the main entry.

Semaphore

✓ import { Semaphore } from 'petty-cache/semaphore'

✗ import { Semaphore } from 'petty-cache'

Semaphore is in a subpath export, not from the main entry.

Shows creation of PettyCache client with environment-based Redis config, and usage of fetch() with a cache miss function.

import PettyCache from 'petty-cache'; const cache = new PettyCache({ host: process.env.REDIS_HOST ?? '127.0.0.1', port: parseInt(process.env.REDIS_PORT ?? '6379'), auth_pass: process.env.REDIS_PASS ?? '' }); // Fetch with cache miss function cache.fetch('mykey', (cb) => { fetchFromDatabase((err, data) => { if (err) return cb(err); cb(null, JSON.stringify(data)); }); }, (err, value) => { if (err) console.error(err); else console.log('Cached value:', value); }); function fetchFromDatabase(callback) { // Simulate async DB call setTimeout(() => callback(null, { foo: 'bar' }), 100); }

Debug

Known issues

breakingESM-only since v3.0.0. CommonJS require() will throw a MODULE_NOT_FOUND error.

fix

Use import PettyCache from 'petty-cache' instead of require().

affects: >=3.0.0

breakingConstructor signature changed in v3.0.0: port, host, options as object or RedisClient directly. The old positional arguments are deprecated.

fix

Use new PettyCache({ host, port }) or pass the RedisClient directly.

affects: >=3.0.0

gotchaThe cacheMissFunction in fetch() must call callback with (error, value). If value is not a string, it will be serialized with JSON.stringify().

fix

Ensure your cache miss function properly serializes complex objects if needed. PettyCache automatically serializes/deserializes, but custom serialization may be required for non-JSON-safe types.

affects: *

Errors

Common errors & fixes

ERR MODULE_NOT_FOUND: require is not supported in ESM

Using CommonJS require() with an ESM-only package version.

fix

Change to import PettyCache from 'petty-cache' and ensure your project is ESM-enabled (add type: 'module' to package.json).

TypeError: PettyCache is not a constructor

Using import PettyCache from 'petty-cache' in a TypeScript project without setting esModuleInterop or using default import syntax incorrectly.

fix

Ensure tsconfig.json has 'esModuleInterop': true and use 'import PettyCache from 'petty-cache''.

Error: The 'redis' package is required to instantiate PettyCache

Missing peer dependency redis.

fix

npm install redis (must be version >=2.6.0).

Upgrade

Version history

3.7.0latest on npm

Audit

Dependencies

redisrequiredRequired for Redis-based distributed caching and locking. Must be at least v2.6.0.

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/stores-com/petty-cache ↗

packagepetty-cache ↗

homepagehttps://github.com/stores-com/petty-cache ↗