Popsicle-cache NPM

Popsicle Cache

Cache HTTP responses using popsicle.

Installation

npm install popsicle-cache --save

Usage

import { request } from 'popsicle'
import { plugin, cacheables, ttls } from 'popsicle-cache'

const cache = plugin({ engine: require('catbox-fs'), ttl: ttls.forever() })

popsicle('http://example.com')
  .use(cache.handle)
  .then(function (res) {
    console.log(res) //=> If still fresh, the cached response, otherwise it makes a new request.
  })

Use popsicleCache.plugin(options) to initialize the cache middleware. It returns an object with three methods:

handle - Regular Popsicle middleware for handling the cache.
forceUpdate - Force a refresh of the cache on every request (does not read from cache, only sets it).
stop - Stop the underlying catbox engine.

Options

Popsicle Cache does not include any external caching strategy by default. Instead, it is compatible with catbox strategies.

`engine` (Object | Function)

An engine instance from catbox.

`cacheable` (Function, Default = `cacheables.standard()`)

(req: Request, res: Response) => boolean

A function that determines whether a request/response should be cacheable.

Built-in cacheable implementations:

cacheables.standard() - Caches on res.status === 200 && req.method === 'GET' && !res.get('Cache-Control').contains('no-cache') only.
cacheables.always() - Always caches the response (return true).

`ttl` (Function, Default = `ttls.standard(0, 1000 * 60 * 60 * 24 * 365)`)

(req: Request, res: Response) => number

A function that determines the TTL of the cached response.

Built-in TTL implementations:

ttls.standard(minTtl, maxTtl) - Calculates the freshness from the Cache-Control, Expires and/or Last-Modified headers. Returns minTtl + Math.min(maxTtl, freshness).
ttls.forever() - Caches forever (return Infinity).

`serializer` (Object, Default = `serializers.standard()`)

interface Serializer <T> {
  name: string
  parse (value: string): T
  stringify (value: T, cache: (err: Error | null, value?: string | null) => void): T
}

An object that represents a serializer instance. Must have a name and implement parse and stringify methods. Some serializations are asynchronous in nature, or require the response body to be augmented, so a callback must be used to cache the actual value. Pass null or undefined as the cache value to skip the cache (E.g. cache() or cache(null, null)).

Built-in serializer implementations:

serializers.standard() - Simple implementation using JSON.parse and JSON.stringify.
stream(maxBufferLength?: number) - Buffers the response body from a stream, skipping the cache if the buffer exceeds maxBufferLength (defaults to 1mb)

`handler` (Function, Default = `handlers.standard()`)

class CachedResponse extends popsicle.Response {
  ttl: number
  stored: number
  response: Response
  varyHeaders: Array<[string, string]>
}

(req: Request, cache: CachedResponse, next: () => Promise<Response>): Response | CachedResponse | Promise<Response | CachedResponse>

The request handler that decides whether to use the existing cache, regular response or a combination of both (E.g. by setting If-None-Match or If-Modified-Since).

Built-in handler implmentations:

handlers.standard() - Based on freshness, it will decide whether to use the cache directly or validate the cache by sending the request with If-None-Match or If-Modified-Since. If it responds with 304 (not modified), it will use the cached response body and headers.
handlers.always() - Always return the cached resource, even if expired or stale (return cache.response).