# record-cache

> Cache optimised for record like things

Latest version **2.0.0** (published 2026-01-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install record-cache
pnpm add record-cache
yarn add record-cache
bun add record-cache
```

## Health

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

Positive: no vulnerabilities.

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

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-01-01 |
| First published | 2018-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 12.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 26 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/record-cache
- Repository: https://github.com/mafintosh/record-cache
- Issues: https://github.com/mafintosh/record-cache/issues
- npm.io page: https://npm.io/package/record-cache

## Dependencies (1)

- [b4a](https://npm.io/package/b4a.md) ^1.3.1

## Recent versions

- 2.0.0 (latest) — 2026-01-01
- 1.2.0 — 2022-02-18
- 1.1.1 — 2021-05-21
- 1.1.0 — 2018-05-19
- 1.0.2 — 2018-04-23
- 1.0.1 — 2018-02-12
- 1.0.0 — 2018-01-26
- 0.0.0 — 2018-01-26

## README

# record-cache

Cache optimised for record like things like `host:port` or `domain.names`.

```
npm install record-cache
```

[![build status](https://travis-ci.org/mafintosh/record-cache.svg?branch=master)](https://travis-ci.org/mafintosh/record-cache)

## Usage

```js
var RecordCache = require('record-cache')

var cache = new RecordCache({
  maxSize: 1000 // store ~1000 values at max
  maxAge: 1000 // gc values older than ~1000ms
})

cache.add('hello', '127.0.0.1')
cache.add('hello', '127.0.1.1')
cache.add('hello', '127.0.0.2')

console.log(cache.get('hello', 2)) // prints two of the above

// wait 2s
setTimeout(function () {
  console.log(cache.get('hello', 2)) // prints []
}, 2000)
```

## API

#### `var cache = new RecordCache([options])`

Create a new record cache.

Options include:

```js
{
  maxSize: 1000, // approximate max size
  maxAge: 1000, // approximate max age in ms
  onStale: false // function called when evicting stale records
}
```

In the worst case the cache will be `2 * maxSize` large, and
if `maxAge` is used old values are gc'ed every `0.66 * maxAge - 1.33 * maxAge` with an optional callback to the `onStale` function upon record eviction.

This is to greatly simplify the data structures and also gives us a pretty decent
perf boost compared to other cache modules out there.

#### `cache.add(recordName, value)`

Push a new value to the record set. `value` should be serialisable.

#### `cache.remove(recordName, value)`

Remove a value from the record set. `value` should be a previously added value.

#### `var list = cache.get(recordName, [maxCount])`

Get a list of values from the record set. The list will be randomised.
Specify `maxCount` to only get this many values at max.

#### `cache.size`

Get the actual size of the cache.

#### `cache.clear()`

Clear all values from the cache.

#### `cache.destroy()`

Completely destroy the cache. Needed if you are using the `maxAge` option to
cancel the gc timer.

## License

MIT

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