# ceych

> Wraps any asynchronous function and provides caching of the result

Latest version **5.1.0** (published 2026-08-18) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install ceych
pnpm add ceych
yarn add ceych
bun add ceych
```

## Health

**Score 50/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated.

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

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2026-08-18 |
| First published | 2016-02-12 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14.0.0 |
| Dependencies | 2 |
| Unpacked size | 13.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Maintainers | ibl, kieranjoyce, pjlangley, szpytfire-bbc, simontanner, simongregory, tonymcbeth, johnnewman, jamiebower185, onlyonehas, gingertonicst, iuketaylor, notten13, npmbs, brotherkaif, naivinh.ta.bbc, pshaw03, amitsavant, eobr, paulyb, cjewell47, vinodrane, sbason, lexedwardsbbc, dwalker487, katyasa, felixmercermoss, nikitaagg19, mattfrost86, marinos-papamichael, joepock33c, giavente, charles_alexis, emathar, jackperry2187, jim-beeb, nbc-bbc, irex-team |
| Keywords | cache, caching, asynchronous, function, ceych, wrapper, promise, memoize |

## Links

- npm: https://www.npmjs.com/package/ceych
- Repository: https://github.com/bbc/ceych
- Issues: https://github.com/bbc/ceych/issues
- npm.io page: https://npm.io/package/ceych

## Dependencies (2)

- [@hapi/catbox](https://npm.io/package/@hapi/catbox.md) ^12.1.1
- [@hapi/catbox-memory](https://npm.io/package/@hapi/catbox-memory.md) ^6.0.1

## 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

- 5.1.0 (latest) — 2026-08-18
- 5.0.0 — 2025-09-16
- 4.4.1 — 2025-09-01
- 4.4.0 — 2025-08-29
- 4.3.0 — 2025-07-23
- 4.2.0 — 2025-04-28
- 4.1.0 — 2025-01-23
- 4.0.0 — 2020-06-18
- 3.0.1 — 2019-09-11
- 2.1.0 — 2019-03-08
- 3.0.0 — 2017-08-08
- 2.0.0 — 2017-01-03
- 1.0.1 — 2016-02-12
- 1.0.0 — 2016-02-12

## README

# ceych

> Wraps any asynchronous function and provides caching of the result

## Installation

```
pnpm install --save ceych
```

## Usage

```js
'use strict';

const request = require('request');
const Catbox = require('@hapi/catbox').Client;
const Redis = require('@hapi/catbox-redis');

const ceych = require('ceych').createClient({
  cacheClient: new Catbox(new Redis({
    port: 6379,
    host: '127.0.0.1',
    partition: 'cache'
  })),
  defaultTTL: 30
});

function loadData(cb) {
  request.get('https://www.big-data.com/datum.csv', cb);
}

const loadDataCached = ceych.wrap(loadData);

const miss = loadDataCached(); // returned from the server and stored in the cache
const hit = loadDataCached(); // returned from the server and stored in the cache
```

## How does it work?

Ceych automatically creates cache keys based on the wrapped function's body and the arguments passed. This saves you from having to create a unique cache key every time you want the result of a function to be cached.

Return values and arguments need to be serializable to/from JSON. This means that while strings, numbers and basic objects are supported, objects with custom constructors or prototypes are not.

### StatsD integration

When using a [node-statsd](https://github.com/sivy/node-statsd) client, ceych will increment a counter each time there is a cache hit or miss. The following metrics are sent:

|Metric|Type|Description|
|------|----|-----------|
|ceych.hits|`counter`|Incremented whenever there is a cache hit|
|ceych.misses|`counter`|Incremented whenever there is a cache miss|

## API

#### `Ceych.createClient(opts)`

Creates a ceych client.

##### Parameters

* `cacheClient` - _optional_ - A [Catbox](https://github.com/hapijs/catbox) client (defaults to an in-memory client).
* `defaultTTL` - _optional_ - The default TTL for caching in seconds (default _30_).
* `statsClient` - _optional_ - An instance of the [node-statsd](https://github.com/sivy/node-statsd) client

#### `ceych.wrap(fn, ttl, suffix)`

Returns a wrapped function that implements caching.

##### Parameters

* `fn` - An asynchronous function to be wrapped.
* `ttl` - _optional_ - Overrides the default TTL.
* `suffix` - _optional_ - A string appended to cache keys to differentiate between identical functions.

#### `ceych.invalidate(funcOrOpts, ...args)`

Invalidates the current cache entry for the given function and args combination. The function passed should be the unwrapped, initial function.

#### `ceych.set()`

Use this to manually set the cache entry for the given function and args combination. You can use this to overwrite an existing cache entry to a newer one.

The new cache key will have a TTL (time to live) set randomly between this.defaultTtl/2 and this.defaultTtl. This is to ensure that when manually setting a lot of cache keys at the same time, they don't end up all expiring at the same time and causing lots of caches misses.

##### Parameters

* `funcOrOpts` - Either a function or a set of options of the format `{ func: yourFunction, suffix: 'yourSuffix' }` if you wish to include a suffix.
* `updatedValue` - The new value to store in the cache.
* `...args` - The args that you passed to the wrapped function call which initially stored the cache entry.

#### `ceych.disableCache()`

Disables the use of the cache. This can be useful if you want to toggle usage of the cache for operational purposes - e.g. for operational purposes, or unit tests.

#### `ceych.enableCache()`

Re-enables the cache client. This can be useful if you want to toggle usage of the cache for operational purposes - e.g. for operational purposes, or unit tests.

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