@0k/cache

This packages holds a cache decorator implementation. It draws its inspiration on 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:

npm install --save @0k/cache

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

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:

   npm install

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

   ## Compile and watch
   npx tspc -w

Tests are managed through vitest

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