keyv-cache-proxy

library0.2.3jsnpmunverified

KeyvCacheProxy (v0.2.3) is a JavaScript/TypeScript library that provides a transparent caching proxy for any object's method calls using Keyv as the underlying store. It automatically caches return values of all methods with configurable TTL support, handling nested objects via deep proxy. Released under active development with a focus on zero-configuration wrapping of API clients (Octokit, Notion, Slack). Key differentiators: automatic caching of all method calls without decorators, supports any Keyv-compatible storage backend (memory, Redis, MongoDB, etc.), cache hooks for observability, and async-by-default conversion. Requires Node >=18 and TypeScript ^5.9.3 as peer dependency.

storage

npm install keyv-cache-proxy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KEYV-CACHE-PROXY

keyv-cache-proxy

storagejavascriptv0.2.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeyvCacheProxy

✓ import { KeyvCacheProxy } from 'keyv-cache-proxy'

✗ const KeyvCacheProxy = require('keyv-cache-proxy').KeyvCacheProxy

ESM-only; CJS require may work if bundler handles it, but types are ESM.

KeyvCacheProxy (default import)

✓ import { KeyvCacheProxy } from 'keyv-cache-proxy'

✗ import KeyvCacheProxy from 'keyv-cache-proxy'

The package only exports a named export KeyvCacheProxy, not a default export.

Keyv

✓ import Keyv from 'keyv'

✗ import { Keyv } from 'keyv'

Keyv uses default export. Verify your Keyv version if using named import.

Demonstrates wrapping an object with a 60-second TTL cache, showing first call execution and subsequent cache hit.

import { KeyvCacheProxy } from 'keyv-cache-proxy'; import Keyv from 'keyv'; const myObject = { expensiveOperation(a: number, b: number) { console.log('Computing...'); return a + b; } }; const cached = KeyvCacheProxy({ store: new Keyv(), ttl: 60000, })(myObject); // First call: executes the method await cached.expensiveOperation(1, 2); // Logs: "Computing..." // Second call: returns cached result await cached.expensiveOperation(1, 2); // No log, returns from cache

Debug

Known issues

breakingTypeScript version requirement: The package requires TypeScript ^5.9.3 as a peer dependency. If your project uses an older TypeScript version (< 5.9), you may encounter type errors.

fix

Update TypeScript to ^5.9.3 or later: npm install typescript@^5.9.3

affects: >=0.0.0

breakingNode version requirement: Requires Node >=18.0.0. Older Node versions may cause runtime errors due to modern JavaScript features.

fix

Upgrade Node.js to version 18 or later.

affects: >=0.0.0

gotchaAll methods become async: The proxy wraps all methods, converting synchronous methods to return Promises. If you expect synchronous execution, wrap with 'await' or handle Promise accordingly.

fix

Always use 'await' when calling cached methods.

affects: >=0.0.0

gotchaCache key generation: The cache key is constructed from the method name and serialized arguments. If arguments contain complex objects (e.g., Date, custom classes), serialization may produce unexpected keys, leading to cache misses or collisions.

fix

Ensure arguments are JSON-serializable or implement custom key generation via the 'prefix' option.

affects: >=0.0.0

gotchaCaching of non-deterministic methods: Methods that return different results for the same arguments (e.g., random, timestamps) will be cached incorrectly, returning stale values.

fix

Do not wrap objects with non-deterministic methods, or set TTL appropriately.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'keyv' or its corresponding type declarations.

Missing required dependency 'keyv'.

fix

Install keyv: npm install keyv

error TS2307: Cannot find module 'keyv-cache-proxy'.

Package not installed or incorrect import path.

fix

Install the package: npm install keyv-cache-proxy

TypeError: KeyvCacheProxy is not a function

Importing 'KeyvCacheProxy' incorrectly (e.g., as a default import instead of named import).

fix

Use named import: import { KeyvCacheProxy } from 'keyv-cache-proxy'

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

keyvrequiredRequired peer dependency; provides the underlying cache store interface

typescriptoptionalPeer dependency for type definitions; version ^5.9.3 required

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/snomiao/keyv-cache-proxy ↗

packagekeyv-cache-proxy ↗

homepagehttps://github.com/snomiao/keyv-cache-proxy#readme ↗