# @0k/cache

> Kids cache implementation

Latest version **0.3.0** (published 2026-07-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @0k/cache
pnpm add @0k/cache
yarn add @0k/cache
bun add @0k/cache
```

## Health

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

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

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

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-07-11 |
| First published | 2025-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 111.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Valentin LAB |
| Maintainers | vaab |

## Links

- npm: https://www.npmjs.com/package/@0k/cache
- Repository: https://github.com/0k/cache
- Issues: https://github.com/0k/cache/issues
- npm.io page: https://npm.io/package/@0k/cache

## Recent versions

- 0.3.0 (latest) — 2026-07-11
- 0.2.0 — 2026-04-17
- 0.1.4 — 2026-04-14
- 0.1.2 — 2026-04-08
- 0.1.1 — 2026-04-07
- 0.0.7 — 2025-10-18
- 0.0.6 — 2025-08-20
- 0.0.5 — 2025-08-19
- 0.0.2 — 2025-08-04
- 0.0.1 — 2025-08-03

## README

This packages holds a cache decorator implementation. It draws its
inspiration on [kids.cache](https://pypi.python.org/pypi/kids.cache/) a python simple yet powerful cache
decorator.


This implementation leverage decorator in typescript to reach same goals:

 * no dependencies
 * cache clearing support


Its still in infancy and lacks:

 * support for normal function (only methods and properties are cachable)
 * cache stats
 * 100% coverage
 * doc


# Adding `@0k/cache` to your project

From the root of your project:

```sh
npm install --save @0k/cache
```

Or better, as `@0k/cache` is still in early release,

```sh
npm install --save @0k/cache#master
```

To be sure to get the latest version, relaunch this last command
whenever you want to update.

# Contributing to `@0k/cache`

This package is using `npm` to track dependendies, so you can install them
with:

```sh
   npm install
```

As this package is written in `typescript`. You can transpile to
`javascript` and transpile on file change with:

```sh
   ## Compile and watch
   npx tspc -w
```

Tests are managed through `vitest`


```sh
   ## Run test once
   npm run test
```

Note that you can also use `npx vitest` command to launch tests in
watch mode.
# Changelog


## 0.3.0 (2026-07-10)

### Fix

* Make ``feedCache`` store-agnostic via a ``feed()`` store method. [Valentin Lab]

  ``feedCache`` computed the args-key itself and called the store's
  ``set()`` directly, assuming the plain-``Map`` dialect of
  ``JsonKeyCacheStore``.  With ``TimeoutJsonKeyTTLCacheStore`` this
  broke silently: its ``set()`` destructures ``{argsKey, ttl}`` from
  its first argument, so the fed entry landed under the ``undefined``
  key with a raw (untupled) value, and ``getValue`` never saw it.
  Callers relying on ``feedCache`` to pre-seed a TTL cache (e.g. a
  login prefetch) always fell through to a recomputation.

  Mirror the ``getValue``/``delete`` opaque-token protocol on the
  write side: each store now owns key computation and value wrapping
  through a ``feed(instance, args, value)`` method, and the decorator's
  ``feedCache`` merely delegates to it.  ``TimeoutJsonKeyTTLCacheStore``
  resolves its ``ttl`` (including the ttl-as-function case) so fed
  entries also get their eviction timer.

  Tests cover feed-then-hit on all three stores, TTL expiry of fed
  values, overwrite of previously cached entries, and the
  rejection-then-feed login-prefetch pattern.


## 0.2.0 (2026-04-17)

### New

* Export ``unwrapObject`` function and ``CacheDecoratedMethod`` type. [Valentin Lab]

  ``CacheDecoratedMethod<F>`` types the return of the ``cache`` decorator,
  giving typed access to ``.clearCache()`` and ``.feedCache()`` without
  casting.

  ``unwrapObject`` extracts the proxy-unwrap loop previously duplicated
  inline, and exports it so callers can resolve the underlying object the
  same way the cache does.

  Overload signatures added to ``cache`` for accurate TypeScript inference
  on the various call forms.


## 0.1.4 (2026-04-08)

### New

* Add ``feedCache`` to programmatically inject values into the cache. [Valentin Lab]

  Allows pre-populating or overriding cached entries for specific argument
  keys without triggering the underlying computation. Exposed as a
  per-instance property alongside ``clearCache`` on both methods and
  getters. Also adds ``set`` to the ``CacheStore`` type.

* Add ``cancelOnClear`` option to abort in-flight cached promises. [Valentin Lab]

  When enabled, cached promises that settle after their cache entry has
  been cleared throw a ``CancelledCache`` error instead of returning
  stale results. This prevents consumers from acting on values whose
  cache was invalidated mid-flight.

### Changes

* Ensure same object promise returned even with ``cancelOnClear`` [Valentin Lab]

  Move the ``cancelOnClear`` wrapper from the shared ``wrapped`` function into
  the per-instance ``ownMethod``/getter in the initializer. Uses ``async/await``
  instead of ``.then()``. The wrapper is memoized per source promise so
  concurrent callers get the same object, preserving promise identity.

### Fix

* Scope ``clearCache`` per instance instead of shared prototype. [Valentin Lab]

  ``clearCache`` was attached to the prototype-level ``wrapped`` function,
  so when multiple instances initialized, the last closure would overwrite
  all previous ones. Shadow the prototype method/getter with per-instance
  own properties carrying their own ``clearCache``.


## 0.1.3 (2026-04-08)

### New

* Add ``feedCache`` to programmatically inject values into the cache. [Valentin Lab]

  Allows pre-populating or overriding cached entries for specific argument
  keys without triggering the underlying computation. Exposed as a
  per-instance property alongside ``clearCache`` on both methods and
  getters. Also adds ``set`` to the ``CacheStore`` type.

### Fix

* Scope ``clearCache`` per instance instead of shared prototype. [Valentin Lab]

  ``clearCache`` was attached to the prototype-level ``wrapped`` function,
  so when multiple instances initialized, the last closure would overwrite
  all previous ones. Shadow the prototype method/getter with per-instance
  own properties carrying their own ``clearCache``.


## 0.1.2 (2026-04-08)

### New

* Add ``cancelOnClear`` option to abort in-flight cached promises. [Valentin Lab]

  When enabled, cached promises that settle after their cache entry has
  been cleared throw a ``CancelledCache`` error instead of returning
  stale results. This prevents consumers from acting on values whose
  cache was invalidated mid-flight.


## 0.1.1 (2026-04-07)

### Fix

* Correct ``noCacheOnReject`` to return scalar value instead of tuple. [Valentin Lab]

  The rejection recovery path was returning the full [result, argsKey, isHit]
  tuple instead of just the value at index 0. This caused callers awaiting a
  cached async method to receive corrupted data when the rejection-retry path
  triggered.


## 0.1.0 (2026-03-23)

### Fix

* Unwrap ``this`` in ``clearCaches`` before cache map deletion. [Valentin Lab]

  When ``clearCaches()`` was called on a proxied instance, ``this``
  referred to the proxy, but cache maps are keyed by the unwrapped
  raw instance. ``map.delete(this)`` silently missed, leaving caches
  uncleared.

  Apply the same unwrap loop used in the cached method wrapper so
  ``clearCaches`` resolves to the correct identity before deletion.


## 0.0.7 (2025-10-18)

### Fix

* Prevent possible loss of prior ``unWrapFn`` registration. [Valentin Lab]


## 0.0.6 (2025-08-20)

### New

* Make most of the test try each cache store implementation. [Valentin Lab]

* Add a ``setTimeout`` implementation of the ``JsonKeyTTLCacheStore`` [Valentin Lab]

  Memory footprint is less in most cases

### Fix

* Make ``noCacheOnReject`` compatible with non-promise values. [Valentin Lab]


## 0.0.5 (2025-08-19)

### New

* Add option ``cacheOnSettled`` for async cached object. [Valentin Lab]

* Add option ``noCacheOnReject`` for async cached objects. [Valentin Lab]

* Add tests for not caching upon exception. [Valentin Lab]


## 0.0.4 (2025-08-15)

### New

* Add option ``noCacheOnReject`` for async cached objects. [Valentin Lab]

* Add tests for not caching upon exception. [Valentin Lab]


## 0.0.2 (2025-08-04)

### New

* Add support of decorating getters. [Valentin Lab]

### Fix

* Support proxying ``this`` [Valentin Lab]

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