popsicle-cache

library5.0.1jsnpmunverified

A caching plugin for the Popsicle HTTP client, version 5.0.1. It provides middleware to cache HTTP responses using pluggable catbox engines. Built-in support for TTL-based expiry, cacheable conditions, serializers (JSON, stream), and handlers (freshness validation). No external caching engine is included; you must provide one (e.g., catbox-fs, catbox-memory). Updated as needed following Popsicle releases.

storage

npm install popsicle-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POPSICLE-CACHE

popsicle-cache

storagejavascriptv5.0.1

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.

plugin

✓ import { plugin } from 'popsicle-cache'

✗ const { plugin } = require('popsicle-cache')

ESM-only since v5; CommonJS require may not work depending on Node.js version.

cacheables

✓ import { cacheables } from 'popsicle-cache'

Named export for built-in cacheable implementations (standard, always).

ttls

✓ import { ttls } from 'popsicle-cache'

✗ import ttls from 'popsicle-cache'

Default import is undefined; must use named import.

PopsicleCachePlugin

✓ import type { PopsicleCachePlugin } from 'popsicle-cache'

TypeScript type export; use import type for type-only usage.

Demonstrates creation of a Popsicle cache middleware with catbox-fs engine, usage with .use(), force update, and clean stop.

import { request } from 'popsicle'; import { plugin, ttls } from 'popsicle-cache'; import catboxFs from 'catbox-fs'; // or any catbox engine // Create cache middleware with filesystem engine and 1-hour TTL const cache = plugin({ engine: catboxFs({ path: './cache' }), ttl: ttls.standard(0, 1000 * 60 * 60) // min 0ms, max 1h }); async function cachedGet(url: string) { const response = await request(url).use(cache.handle); return response.body; } // Force update (skip reading cache) async function forceUpdate(url: string) { const response = await request(url).use(cache.forceUpdate); return response.body; } // Stop engine when done cache.stop();

Debug

Known issues

breakingpopsicle-cache v5 drops CommonJS support; only ESM imports work.

fix

Use ES module imports (import ... from 'popsicle-cache'). If using CommonJS, stay on v4.

affects: >=5.0.0

gotchaThe engine option must be a catbox-compatible engine instance; using a plain object will fail silently.

fix

Ensure engine has Policy.prototype.get and Policy.prototype.set methods (from @hapi/catbox).

affects: *

gotchattls.forever() does not set Infinity correctly in all serializers; JSON.stringify converts Infinity to null.

fix

Use a finite TTL or custom serializer that handles Infinity.

affects: *

deprecatedThe 'handlers.standard()' default may not handle all HTTP caching headers (e.g., Vary).

fix

Check if Vary headers are properly implemented; use custom handler if needed.

affects: *

gotchacatbox engines like catbox-fs store data on disk; ensure write permissions and avoid concurrent access.

fix

Use catbox-memory for ephemeral caching or configure file paths securely.

affects: *

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'handle')

plugin() returned undefined because no engine was provided or engine initialization failed.

fix

Ensure engine is passed and correctly instantiated (e.g., require('catbox-fs')({ /* options */ })).

Error: The 'cache()' callback must be called exactly once

Serializer's stringify method called cache callback multiple times or not at all.

fix

Use built-in serializers (serializers.standard() or serializers.stream()) or implement call correctly.

Error: item key can not be longer than 255 bytes

catbox key is too long (e.g., long URL).

fix

Use a shorter key by hashing the URL or using a custom segment.

Upgrade

Version history

5.0.1latest on npm

Audit

Dependencies

popsiclerequiredPeer dependency; the library is a plugin for Popsicle HTTP client.

catboxoptionalUses Catbox engine interface for caching (engine must implement catbox policy).

Agent activity

19 hits · last 30 days

node

Amazon

Resources

githubgit://github.com/blakeembrey/popsicle-cache ↗

packagepopsicle-cache ↗

homepagehttps://github.com/blakeembrey/popsicle-cache ↗