tkv-cache
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

TypeScript KvCache

Build Status npm version

Minimal Keyv powered caching helper with added support for:

  • Objects as keys with key ordering and hashing
  • Function to normalize keys to optimize cache hit rate
  • Helper function for wrapping functions with caching
  • Strongly typed set/get with generic types

All storage is handled by the Keyv instance passed, so you can use the in-memory default, or any of the storage adapters.

Usage

Install

Install tkv-cache with your favorite package manager: npm, yarn, pnpm, etc.

You also need to install keyv and any adapters like @keyv/redis.

KvCache

The KvCache class wraps Keyv with support for object keys and key normalization.

import Keyv from 'keyv';
import { KvCache } from 'tkv-cache';

// Simple usage
const cache = new KvCache<string, string>(new Keyv());
await cache.set('key', 'value');
const val = await cache.get('key'); // val is: string | null

// Object as the key
type ObjKey = { name: string };
const cache2 = new KvCache<ObjKey, string>(new Keyv());
await cache2.set({ name: 'key1' }, 'value');
const val2 = await cache2.get({ name: 'key1' }); // val2 is: string | null

// With a custom normalizeKey function
const cache3 = new KvCache<string, string>(
  new Keyv(),
  (key) => key.toUpperCase()
);
await cache3.set('key', 'value');
const val3 = await cache3.get('KEY'); // val3 is: string | null
console.log(val3); // 'value' because keys were normalized to 'KEY'

Easy KvCache Creation

You can create a KVCache instance using the createKvCache() function by passing in a Keyv options object.

const cache = createKvCache<string, string>({
  ttl: 1000,
});
await cache.set('key', 'value');
const val = await cache.get('key');
type verify = Expect<Equal<typeof val, string | null>>;
assert.equal(val, 'value');

Cachify

The cachify function wraps a function with a KvCache and optional key normalization function.

import Keyv from 'keyv';
import { cachify } from 'tkv-cache';

// The function to cache. Something slow/expensive like an OpenAI API call.
const func = (key: string) => Promise.resolve(`value for ${key}`);

// The cached function
const cachedFunc = cachify({}, func);

const response = await cachedFunc('key1'); // API call
const response2 = await cachedFunc('key1'); // Cache hit
const response3 = await cachedFunc('key2'); // API call

// Use key normalization to avoid cache misses
const cachedFunc2 = cachify(new Keyv(), func, (key) => key.toUpperCase());

const res = await cachedFunc('key1'); // API call
const res2 = await cachedFunc('key1'); // Cache hit
const res3 = await cachedFunc('KEY1'); // Cache hit (key normalization)
const res4 = await cachedFunc('Key1'); // Cache hit (key normalization)
const res5 = await cachedFunc('key2'); // API call

Error Handling

KvCache defaults to handling errors by calling console.error to prevent caching from breaking execution. You can pass a custom error handler to the KvCache constructor if you want to change the behavior.

Examples

See the KvCache tests and cachify tests for more example usage.

Readme

Keywords

none

Package Sidebar

Install

npm i tkv-cache

Weekly Downloads

243

Version

1.0.1

License

MIT

Unpacked Size

20.6 kB

Total Files

17

Last publish

Collaborators

  • rileytomasek