# serviceberry-cache-control

> A Cache Control plugin for Serviceberry

Latest version **0.2.4** (published 2025-03-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install serviceberry-cache-control
pnpm add serviceberry-cache-control
yarn add serviceberry-cache-control
bun add serviceberry-cache-control
```

## Health

**Score 35/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2025-03-06 |
| First published | 2018-06-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Bob Gray |
| Maintainers | bob-gray |
| Keywords | cache-control, no-cache, max-age |

## Links

- npm: https://www.npmjs.com/package/serviceberry-cache-control
- Repository: https://github.com/bob-gray/serviceberry-cache-control
- Homepage: https://github.com/bob-gray/serviceberry-cache-control#readme
- Issues: https://github.com/bob-gray/serviceberry-cache-control/issues
- npm.io page: https://npm.io/package/serviceberry-cache-control

## Dependencies (1)

- [vary](https://npm.io/package/vary.md) ^1.1.2

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 0.2.4 (latest) — 2025-03-06
- 0.2.3 — 2020-07-10
- 0.2.2 — 2019-05-30
- 0.2.1 — 2019-05-14
- 0.1.1 — 2019-02-25
- 0.0.1 — 2018-06-19

## README

serviceberry-cache-control
==========================

[![CircleCI](https://circleci.com/gh/bob-gray/serviceberry-cache-control.svg?style=svg)](https://circleci.com/gh/bob-gray/serviceberry-cache-control)
[![Test Coverage](https://api.codeclimate.com/v1/badges/7f550210acb7451260cd/test_coverage)](https://codeclimate.com/github/bob-gray/serviceberry-cache-control/test_coverage)
[![Maintainability](https://api.codeclimate.com/v1/badges/7f550210acb7451260cd/maintainability)](https://codeclimate.com/github/bob-gray/serviceberry-cache-control/maintainability)
[![npm version](https://badge.fury.io/js/serviceberry-cache-control.svg)](https://badge.fury.io/js/serviceberry-cache-control)

Cache control plugin for [Serviceberry](https://serviceberry.js.org).

Install
-------

```shell-script
npm install serviceberry-cache-control
```

Usage
-----

This plugin exports an abstract class `CacheControl` for extending by your
class that knows how to get ETags and Last Modified for the requested resource.
To use this plugin extend `CacheControl` and implement at least `getETag(request, response)`
or `getLastModified(request, response)`. The ETag or Last Modified is then used
to validate the client cache using information passed in request headers.

This plugin sets a `Cache-Control` response header describing how the response
should be cached based on the plugin options and halts the request and responds
with a `304 Not Modified` status if the cache validates using the ETag or Last
Modified as described above.

```js
const CacheControl = require("serviceberry-cache-control");

class Caching extends CacheControl {
	getETag (request) {
		return data.getETag(request.getUrl()); // can also return a promise or use async/await
	}
}

trunk.use(new Caching(options));
```

Options
-------

  - **noStore** *boolean*

    When true the `no-store` directive is set in the `Cache-Control` response header.
	Defaults to `false`.

  - **noCache** *boolean*

	When true the `no-cache` directive is set in the `Cache-Control` response header.
	Defaults to `false`.

  - **mustRevalidate** *boolean*

  	When true the `must-revalidate` directive is set in the `Cache-Control` response header.
  	Defaults to `false`.

  - **public** *boolean*

  	When true the `public` directive is set in the `Cache-Control` response header.
  	Defaults to `false`.

  - **private** *boolean*

  	When true the `private` directive is set in the `Cache-Control` response header.
  	Defaults to `false`.

  - **maxAge** *number*

  	When greater than `0` the `max-age` directive is set in the `Cache-Control` response header.
  	Defaults to `NaN`.

  - **vary** *array*

  	An array of header field names that might may vary the response and should be
	considered by caches. Values are appended to the `Vary` response header.

  	Defaults to `[]`.

CacheControl
------------
Abstract class

### constructor([options])

  - **options**

    Sets `this.options`. See [options](#options) above.

### getETag(request, response)

**You should extend this class and at least implement this method or `getLastModified()`.**

Called by the `setETag` method for fetching an ETag to be set as a response headers
and used to validate the cache. This can be an async function or it can return a promise.
It should return an ETag string or eventually resolve to one.

  - **request** *object*

    Serviceberry [`request`](https://serviceberry.js.org/docs/request.html).

  - **response** *object*

    Serviceberry [`response`](https://serviceberry.js.org/docs/response.html).

### getLastModified(request, response)

**You should extend this class and at least implement this method or `getETag()`.**

Called by the `validate` method for fetching the date the requested resource
was last modified to be used to validate the cache. This can be an async function
or it can return a promise. It should return an ETag string or eventually resolve to one.

  - **request** *object*

    Serviceberry [`request`](https://serviceberry.js.org/docs/request.html).

  - **response** *object*

    Serviceberry [`response`](https://serviceberry.js.org/docs/response.html).

### use(request, response)

The handler method. This is the method called by Serviceberry. This is an `async` function.
If it determines the response status should be `304 Not Modified` the request will be
halted and the response sent with a `304` status.

  - **request** *object*

    Serviceberry [`request`](https://serviceberry.js.org/docs/request.html).

  - **response** *object*

    Serviceberry [`response`](https://serviceberry.js.org/docs/response.html).

### validate(request, response)

Called by the `use` method to validate the cache. This is an `async` function.

  - **request** *object*

    Serviceberry [`request`](https://serviceberry.js.org/docs/request.html).

  - **response** *object*

    Serviceberry [`response`](https://serviceberry.js.org/docs/response.html).

---
_Source: https://npm.io/package/serviceberry-cache-control · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._