# toad-cache

> LRU and FIFO caches for Client or Server

Latest version **3.7.4** (published 2026-07-03) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.7.4 |
| Published | 2026-07-03 |
| First published | 2023-04-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 49.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Igor Savin <kibertoad@gmail.com> |
| Maintainers | kibertoad |
| Keywords | LRU, FIFO, cache, client, server, least, recently, used, first, browser |

## Links

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

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

- 3.7.4 (latest) — 2026-07-03
- 3.3.1-RC7 (next) — 2023-11-29
- 3.7.1 — 2026-05-17
- 3.7.0 — 2024-01-09
- 3.6.0 — 2024-01-09
- 3.5.0 — 2024-01-08
- 3.4.1 — 2023-12-06
- 3.4.0 — 2023-12-06
- 3.3.1 — 2023-11-29
- 3.3.1-RC6 — 2023-11-29
- 3.3.1-RC5 — 2023-11-29
- 3.3.1-RC4 — 2023-11-29
- 3.3.1-RC3 — 2023-11-29
- 3.3.1-RC2 — 2023-11-29
- 3.3.1-RC1 — 2023-11-29
- … 21 more at https://npm.io/package/toad-cache/versions

## README

# Toad Cache

[![NPM Version](https://img.shields.io/npm/v/toad-cache.svg)](https://npmjs.org/package/toad-cache)
[![NPM Downloads](https://img.shields.io/npm/dm/toad-cache.svg)](https://npmjs.org/package/toad-cache)
![](https://github.com/kibertoad/toad-cache/workflows/ci/badge.svg)
[![Coverage Status](https://coveralls.io/repos/kibertoad/toad-cache/badge.svg?branch=main)](https://coveralls.io/r/kibertoad/toad-cache?branch=main)

Least-Recently-Used and First-In-First-Out caches for Client or Server.

## Getting started

```javascript
import { Lru, Fifo } from 'toad-cache'
const lruCache = new Lru(max, ttl = 0)
const fifoCache = new Fifo(max, ttl = 0)
```

## clear

### Method

Clears the contents of the cache

**Example**

```javascript
cache.clear()
```

## delete

### Method

Removes item from cache

    param  {String} key Item key

**Example**

```javascript
cache.delete('myKey')
```

## deleteMany

### Method

Removes items from cache

    param  {String[]} keys Item keys

**Example**

```javascript
cache.deleteMany(['myKey', 'myKey2'])
```

## evict

### Method

Evicts the least recently used item from cache

**Example**

```javascript
cache.evict()
```

## expiresAt

### Method

Gets expiration time for cached item

    param  {String} key Item key
    return {Mixed}      Undefined or number (epoch time)

**Example**

```javascript
const item = cache.expiresAt('myKey')
```

## first

### Property

Item in "first" or "bottom" position

**Example**

```javascript
const cache = new Lru()

cache.first // null - it's a new cache!
```

## get

### Method

Gets cached item and marks it as recently used (pushes to the back of the list of the candidates for the eviction)

    param  {String} key Item key
    return {Mixed}      Undefined or Item value

**Example**

```javascript
const item = cache.get('myKey')
```

## getMany

### Method

Gets multiple cached items and marks them as recently used (pushes to the back of the list of the candidates for the eviction)

    param  {String[]} keys Item keys
    return {Mixed[]}      Undefined or Item values

**Example**

```javascript
const item = cache.getMany(['myKey', 'myKey2'])
```

## keys

### Method

Returns an `Array` of cache item keys.

    return {Array} Array of keys

**Example**

```javascript
console.log(cache.keys())
```

## max

### Property

Max items to hold in cache (1000). Must be a non-negative integer; `0` means no size limit.

**Example**

```javascript
const cache = new Lru(500)

cache.max // 500
```

## last

### Property

Item in "last" or "top" position

**Example**

```javascript
const cache = new Lru()

cache.last // null - it's a new cache!
```

## set

### Method

Sets item in cache as `first`

    param  {String} key   Item key
    param  {Mixed}  value Item value

**Example**

```javascript
cache.set('myKey', { prop: true })
```

## size

### Property

Number of items in cache

**Example**

```javascript
const cache = new Lru()

cache.size // 0 - it's a new cache!
```

## ttl

### Property

Milliseconds an item will remain in cache; lazy expiration upon next `get()` of an item. Must be a non-negative integer; `0` disables expiration.

**Example**

```javascript
const cache = new Lru()

cache.ttl = 3e4
```

Note: entries stored while `ttl` was `0` have no expiry timestamp, so enabling a TTL at runtime immediately expires them on their next `get()`. Prefer setting the TTL via the constructor.

## Hit/miss/expiration tracking

In case you want to gather information on cache hit/miss/expiration ratio, as well as cache size and eviction statistics, you can use LruHitStatistics class:

```js
const sharedRecord = new HitStatisticsRecord() // if you want to use single record object for all of caches, create it manually and pass to each cache

const max = 1000
const ttlInMsecs = 0
const cacheId = 'some-cache-id'
const statisticTtlInHours = 24 // how often to reset statistics. On every rotation previously accumulated data is removed

const cache = new LruHitStatistics(max, ttlInMsecs, cacheId, sharedRecord, statisticTtlInHours)
```

You can retrieve accumulated statistics from the cache, or from the record directly:

```js
// this is the same
const statistics = sharedRecord.getStatistics()
const alsoStatistics = cache.getStatistics()

/*
{
  'some-cache-id': {
    '2023-04-06': {
      cacheSize: 100, // how many elements does cache currently have
      evictions: 5, // how many elements were evicted due to cache being at max capacity    
      expirations: 0, // how many elements were removed during get due to their ttl being exceeded
      hits: 0, // how many times element was successfully retrieved from cache during get
      emptyHits: 0, // out of all hits, how many were null, undefined or ''?
      falsyHits: 0, // out of all hits, how many were falsy?      
      misses: 1, // how many times element was not in cache or expired during get
      invalidateOne: 1, // how many times element was invalidated individually
      invalidateAll: 2, // how many times entire cache was invalidated
      sets: 0, // how many times new element was added      
    },
  },
}

Note that date here reflects start of the rotation. If statistics weren't rotated yet, and another day started, it will still be counted against the day of the rotation start
*/
```

## License

Copyright (c) 2023 Igor Savin

Based on [tiny-lru](https://github.com/avoidwork/tiny-lru), created by Jason Mulligan

Licensed under the MIT license.

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