!@thi.ng/cache

!npm downloads

> [!NOTE]
> This is one of 214 standalone projects, maintained as part
> of the @thi.ng/umbrella monorepo
> and anti-framework.
>
> 🚀 Please help me to work full-time on these projects by sponsoring me on
> GitHub. Thank you! ❤️

- About
- Available strategies
- Features
- Status
- Related packages
- Installation
- Dependencies
- Usage examples
- API
- Common config options
- LRU
- TLRU
- MRU
- Authors
- License

About

In-memory cache implementations with different eviction
strategies.

$3

- LRU: Least Recently Used
- TLRU: Time-aware Least Recently Used
- MRU: Most Recently Used

$3

- ES6 Map-like API (with minor differences)
- Supports any types for both keys & values
- Customizable cache limits (no. of items / actual size)
- Customizable key equality checks (@thi.ng/equiv by default)
- Optional item update & release callbacks (e.g. to clean up resources when
value is being updated or evicted)

Status

STABLE - used in production

Search or submit any issues for this package

Related packages

- @thi.ng/associative - ES Map/Set-compatible implementations with customizable equality semantics & supporting operations

Installation

``bash
yarn add @thi.ng/cache
`

ESM import:

`ts
import * as cache from "@thi.ng/cache";
`

Browser ESM import:

`html

`

JSDelivr documentation

For Node.js REPL:

`js
const cache = await import("@thi.ng/cache");
`

Package sizes (brotli'd, pre-treeshake): ESM: 1.09 KB

Dependencies

- @thi.ng/api
- @thi.ng/dcons

Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)

Usage examples

One project in this repo's
/examples
directory is using this package:

| Screenshot | Description | Live demo | Source |
|:------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|:-------------------------------------------------------|:------------------------------------------------------------------------------------|
| | Filterable commit log UI w/ minimal server to provide commit history | Demo | Source |

API

Generated API docs

$3

All caches support at least the following options (all optional):

`ts
interface CacheOpts {
/**
* Key size calculation
*/
ksize: (k: K) => number;
/**
* Value size calculation
*/
vsize: (v: V) => number;
/**
* Eviction callback to clean up resources
*/
release: (k: K, v: V) => void;
/**
* Update callback to clean up resources
*/
update: (k: K, vold: V, vnew: V) => void;
/**
* Factory for ES6 Map compatible instance
* to index cache entries
*/
map: () => Map;
/**
* Max number of items in cache (default: ∞)
*/
maxlen: number;
/**
* Max cache size (computed via ksize & vsize) (default: ∞)
*/
maxsize: number;
}
`

$3

Removes least recently used items if a new item is added, but would not satisfy
cache limit. Every time a cached item is accessed, it's recency is updated.

`ts
import { LRUCache } from "@thi.ng/cache";

// caches can be configured with maxlen, maxsize and sizing functions (see below)
const lru = new LRUCache(null, { maxlen: 3 });
lru.set("foo", 23);
lru.set("bar", 42);
lru.set("baz", 66);

lru.has("foo");
// true
// retrieving a value from the cache updates its timestamp
lru.get("foo");
// 23

// caches are fully iterable
// largely intended for inspection only, does not update recency
// btw. "foo" appears last since most recently accessed
[...lru]
// [ { k: 'bar', v: 42, s: 0 },
// { k: 'baz', v: 66, s: 0 },
// { k: 'foo', v: 23, s: 0 } ]
[...lru.keys()]
// [ 'bar', 'baz', 'foo' ]
[...lru.values()]
// [ 42, 66, 23 ]

// remove from cache
lru.delete("foo");
// true

// caches have a getSet() method to obtain & store a new value
// if its key is not known. this process is asynchronous
lru.getSet("boo", async () => 999).then(console.log);
// 999

// the given retrieval fn is only called if there's a cache miss
// (not the case here). getSet() always returns a promise
lru.getSet("boo", async () => 123).then(console.log);
// 999

// caches can be limited by size instead of (or in addition to)
// number of items. the meaning of size is user-defined.
// sizing fns can be provided for both keys & values (both default to 0)
// here we multiply value size by 8 since JS numbers are doubles by default
// we also provide a release hook for demo purposes

// the first arg is an iterable of KV pairs to store (just as for Map)
lru = new LRUCache(
[ ["a", [1.0, 2.0]], ["b", [3.0, 4.0, 5.0]] ],
{
maxsize: 32,
ksize: (k) => k.length,
vsize: (v) => v.length * 8,
release: (k, v) => console.log("release", k, v),
update: (k, vold, vnew) => console.log("update", k, vold, "->", vnew)
}
);
// release a [1, 2] ("a" is evicted due to maxsize constraint)
lru.size
// 25

[...lru.keys()]
// [ 'b' ]
`

$3

Time-aware LRU cache. Extends LRU strategy with TTL (time-to-live)
values associated with each entry, which has an impact on:

- has() only returns true if a cached value's TTL hasn't yet expired
- get() only returns a cached value if its TTL hasn't yet expired. Using the
autoExtend option given via the cache constructor options, the cache can be
configured such that a successful cache hit will update/extend the expiry time
of that respective entry.
- set() takes an optional entry specific ttl arg. If not given, uses the
cache's default (provided via ctor option arg). Default TTL is 1 hour.

When adding a new value to the cache, first removes expired entries and if
there's still not sufficient space removes entries in LRU order.

`ts
import { TLRUCache } from "@thi.ng/cache";

// same opts as LRUCache, but here with additional custom TTL period (in ms)
tlru = new TLRUCache(null, { ttl: 10000, autoExtend: true });

// with item specific TTL (500ms)
tlru.set("foo", 42, 500)
`

$3

Similar to LRU, but removes most recently accessed items first.
Wikipedia)

`ts
import { MRUCache } from "@thi.ng/cache";

// same opts as LRUCache
mru = new MRUCache();
`

Authors

- Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

`bibtex
@misc{thing-cache,
title = "@thi.ng/cache",
author = "Karsten Schmidt",
note = "https://thi.ng/cache",
year = 2018
}
``

License

© 2018 - 2026 Karsten Schmidt // Apache License 2.0