@md-oss/cache 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2026 Mirasaki Development
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,471 @@
+# @md-oss/cache
+
+Multi-layer caching with LRU, Redis, and async data fetching support built on cache-manager and Keyv.
+
+## Features
+
+- **Multi-Store Support** - Use LRU cache, Redis, or combine multiple stores
+- **Async Cache Manager** - Automatic data fetching with cache-aside pattern
+- **Promise Caching** - Cache in-flight promises to prevent duplicate requests
+- **Metadata Tracking** - Built-in statistics for hits, misses, and performance
+- **TTL Support** - Configurable time-to-live for all cache entries
+- **Event System** - Listen to cache operations (set, delete, clear, refresh)
+- **Type-Safe** - Full TypeScript support with generics
+
+## Installation
+
+```bash
+pnpm add @md-oss/cache
+```
+
+## Basic Usage
+
+### LRU Cache Manager
+
+```typescript
+import { CacheManager, LRUCache } from '@md-oss/cache';
+import Keyv from 'keyv';
+
+// Create an in-memory LRU cache
+const cache = CacheManager.fromStore<string>(
+  new LRUCache({
+    max: 1000, // Maximum 1000 items
+    ttl: 60000 // 60 seconds TTL
+  })
+);
+
+// Set a value
+await cache.set('user:123', 'John Doe', 30000); // 30 second TTL
+
+// Get a value
+const user = await cache.get('user:123'); // 'John Doe'
+
+// Delete a value
+await cache.del('user:123');
+
+// Clear all
+await cache.clear();
+```
+
+### Async Cache Manager
+
+Automatically fetch and cache data when not found:
+
+```typescript
+import { AsyncCacheManager } from '@md-oss/cache';
+import Keyv from 'keyv';
+
+const userCache = new AsyncCacheManager({
+  stores: [new Keyv()],
+  ttl: 60000, // 60 seconds
+  dataFunction: async (userId: string) => {
+    // This function runs only on cache miss
+    const user = await db.users.findOne({ id: userId });
+    return user;
+  }
+});
+
+// First call - fetches from database and caches
+const user1 = await userCache.get('user:123');
+
+// Second call - returns from cache
+const user2 = await userCache.get('user:123');
+
+console.log(userCache.metadata);
+// { hits: 1, misses: 1, added: 1, deleted: 0, ... }
+```
+
+### Promise Cache
+
+Prevent duplicate in-flight requests:
+
+```typescript
+import { PromiseCache } from '@md-oss/cache';
+
+const apiCache = new PromiseCache<User>(5000); // 5 second cache
+
+async function getUser(id: string) {
+  return apiCache.get(async () => {
+    // This function won't run if a request is already in-flight
+    return await fetch(`/api/users/${id}`).then(r => r.json());
+  });
+}
+
+// These 3 calls will only make 1 API request
+const [user1, user2, user3] = await Promise.all([
+  getUser('123'),
+  getUser('123'),
+  getUser('123')
+]);
+```
+
+## Redis Cache
+
+### Setup
+
+Set the Redis URL in your environment:
+
+```env
+REDIS_URL=redis://localhost:6379
+```
+
+### Usage
+
+```typescript
+import { initializeRedis, getRedisClient } from '@md-oss/cache';
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+// Initialize Redis connection
+await initializeRedis();
+
+// Get Redis client
+const redisClient = getRedisClient();
+
+// Use Redis as cache store
+const cache = CacheManager.fromStore<User>(
+  new Keyv({
+    store: new KeyvRedis(redisClient)
+  })
+);
+
+await cache.set('user:123', userData);
+```
+
+## Advanced Usage
+
+### Multi-Store Caching
+
+Layer multiple caches for optimal performance:
+
+```typescript
+import { CacheManager, LRUCache } from '@md-oss/cache';
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+// Create a multi-layer cache: LRU (L1) → Redis (L2)
+const cache = new CacheManager<User>({
+  stores: [
+    // L1: Fast in-memory cache
+    new Keyv({
+      store: new LRUCache({ max: 500, ttl: 60000 })
+    }),
+    // L2: Shared Redis cache
+    new Keyv({
+      store: new KeyvRedis(redisClient)
+    })
+  ],
+  ttl: 300000 // 5 minutes default TTL
+});
+
+// Get checks L1 first, then L2, populates higher levels on hit
+const user = await cache.get('user:123');
+```
+
+### Async Cache with Callbacks
+
+Track cache performance and errors:
+
+```typescript
+import { AsyncCacheManager } from '@md-oss/cache';
+
+const cache = new AsyncCacheManager({
+  stores: [new Keyv()],
+  ttl: 60000,
+  dataFunction: async (key: string) => {
+    const data = await fetchExpensiveData(key);
+    return data;
+  },
+  callbacks: {
+    onStart: (key) => {
+      console.log(`Fetching data for ${key}`);
+    },
+    onEnd: (key, duration) => {
+      console.log(`Fetch took ${duration}ms for ${key}`);
+    },
+    onSuccess: (key, value) => {
+      console.log(`Successfully cached ${key}`);
+    },
+    onError: (key, error) => {
+      console.error(`Error fetching ${key}:`, error);
+    }
+  }
+});
+
+// Check async metadata
+console.log(cache.metadata.async);
+// { last: 123, total: 456, average: 152, longest: 234, shortest: 89 }
+```
+
+### Cache Events
+
+Listen to cache operations:
+
+```typescript
+import { CacheManager } from '@md-oss/cache';
+
+const cache = CacheManager.fromStore<string>(new LRUCache({ max: 100 }));
+
+cache.on('set', ({ key, value, error }) => {
+  if (!error) {
+    console.log(`Cached: ${key} = ${value}`);
+  }
+});
+
+cache.on('del', ({ key, error }) => {
+  if (!error) {
+    console.log(`Deleted: ${key}`);
+  }
+});
+
+cache.on('clear', () => {
+  console.log('Cache cleared');
+});
+
+cache.on('refresh', ({ key, error }) => {
+  if (!error) {
+    console.log(`Refreshed: ${key}`);
+  }
+});
+```
+
+### Batch Operations
+
+```typescript
+// Get multiple keys
+const users = await cache.mget(['user:1', 'user:2', 'user:3']);
+
+// Set multiple keys
+await cache.mset([
+  { key: 'user:1', value: user1, ttl: 60000 },
+  { key: 'user:2', value: user2, ttl: 60000 },
+  { key: 'user:3', value: user3, ttl: 60000 }
+]);
+
+// Delete multiple keys
+await cache.mdel(['user:1', 'user:2', 'user:3']);
+```
+
+### Cache Wrapping
+
+Wrap expensive operations with automatic caching:
+
+```typescript
+const result = await cache.wrap(
+  'expensive-computation',
+  async () => {
+    // Only runs on cache miss
+    return await performExpensiveComputation();
+  },
+  60000 // TTL in milliseconds
+);
+```
+
+## Use Cases
+
+### 1. API Response Caching
+
+```typescript
+import { AsyncCacheManager } from '@md-oss/cache';
+
+const apiCache = new AsyncCacheManager<ApiResponse>({
+  stores: [new Keyv()],
+  ttl: 300000, // 5 minutes
+  dataFunction: async (endpoint: string) => {
+    const response = await fetch(endpoint);
+    return response.json();
+  }
+});
+
+app.get('/api/proxy/:path', async (req, res) => {
+  const data = await apiCache.get(req.params.path);
+  res.json(data);
+});
+```
+
+### 2. Database Query Caching
+
+```typescript
+const userCache = new AsyncCacheManager<User>({
+  stores: [
+    new Keyv({ store: new LRUCache({ max: 1000, ttl: 60000 }) }),
+    new Keyv({ store: new KeyvRedis(redisClient) })
+  ],
+  ttl: 600000, // 10 minutes
+  dataFunction: async (userId: string) => {
+    return await db.users.findUnique({ where: { id: userId } });
+  }
+});
+
+async function getUser(id: string) {
+  return userCache.get(id);
+}
+```
+
+### 3. Session Management
+
+```typescript
+const sessionCache = CacheManager.fromStore<Session>(
+  new Keyv({ store: new KeyvRedis(redisClient) })
+);
+
+async function getSession(sessionId: string) {
+  return sessionCache.get(`session:${sessionId}`);
+}
+
+async function createSession(sessionId: string, data: Session) {
+  await sessionCache.set(`session:${sessionId}`, data, 3600000); // 1 hour
+}
+```
+
+### 4. Rate Limiting
+
+```typescript
+const rateLimitCache = CacheManager.fromStore<number>(
+  new LRUCache({ max: 10000, ttl: 60000 })
+);
+
+async function checkRateLimit(userId: string): Promise<boolean> {
+  const key = `rate:${userId}`;
+  const count = (await rateLimitCache.get(key)) ?? 0;
+  
+  if (count >= 100) {
+    return false; // Rate limit exceeded
+  }
+  
+  await rateLimitCache.set(key, count + 1);
+  return true;
+}
+```
+
+### 5. Computed Value Caching
+
+```typescript
+const computeCache = new AsyncCacheManager<number>({
+  stores: [new Keyv()],
+  ttl: 3600000, // 1 hour
+  dataFunction: async (key: string) => {
+    const [start, end] = key.split(':');
+    return await calculateComplexMetrics(Number(start), Number(end));
+  }
+});
+
+async function getMetrics(startDate: Date, endDate: Date) {
+  const key = `${startDate.getTime()}:${endDate.getTime()}`;
+  return computeCache.get(key);
+}
+```
+
+## Cache Metadata
+
+Track cache performance:
+
+```typescript
+const cache = new AsyncCacheManager({ /* ... */ });
+
+// Basic metadata
+console.log(cache.metadata);
+// {
+//   hits: 150,
+//   misses: 50,
+//   added: 50,
+//   deleted: 10,
+//   updated: 20,
+//   cleared: 0,
+//   errors: 0,
+//   async: {
+//     last: 123,
+//     total: 6150,
+//     average: 123,
+//     longest: 456,
+//     shortest: 45
+//   }
+// }
+
+// Calculate hit rate
+const hitRate = cache.metadata.hits / (cache.metadata.hits + cache.metadata.misses);
+console.log(`Cache hit rate: ${(hitRate * 100).toFixed(2)}%`);
+```
+
+## Performance Considerations
+
+- **LRU Cache**: O(1) operations, best for hot data
+- **Redis**: Network overhead, best for shared/persistent cache
+- **Multi-Store**: Checks stores in order, populates higher levels on hit
+- **Promise Cache**: Prevents thundering herd for in-flight requests
+
+### Best Practices
+
+```typescript
+// Use appropriate TTLs
+const shortTTL = 60000;     // 1 minute for volatile data
+const mediumTTL = 600000;   // 10 minutes for regular data
+const longTTL = 3600000;    // 1 hour for stable data
+
+// Layer caches appropriately
+const cache = new CacheManager({
+  stores: [
+    new Keyv({ store: new LRUCache({ max: 100, ttl: shortTTL }) }),  // Hot cache
+    new Keyv({ store: new KeyvRedis(redis), ttl: longTTL })         // Warm cache
+  ]
+});
+
+// Use promise caching for expensive operations
+const promiseCache = new PromiseCache(5000);
+const result = await promiseCache.get(() => expensiveOperation());
+```
+
+## API Reference
+
+### CacheManager
+
+- `get(key)` - Get a value from cache
+- `mget(keys)` - Get multiple values
+- `set(key, value, ttl?)` - Set a value
+- `mset(entries)` - Set multiple values
+- `del(key)` - Delete a value
+- `mdel(keys)` - Delete multiple values
+- `clear()` - Clear all cache entries
+- `wrap(key, fn, ttl?)` - Wrap function with caching
+- `ttl(key)` - Get remaining TTL for a key
+- `keys()` - Get all cached keys
+- `on(event, listener)` - Listen to cache events
+- `extend(options)` - Create extended cache manager
+- `disconnect()` - Disconnect all stores
+
+### AsyncCacheManager
+
+Extends `CacheManager` with:
+- `dataFunction` - Automatic data fetching on cache miss
+- `callbacks` - Lifecycle callbacks (onStart, onEnd, onSuccess, onError)
+- Additional metadata tracking for async operations
+
+### PromiseCache
+
+- `get(generator)` - Get or generate cached promise
+- `clear()` - Clear cached promise
+
+### Redis
+
+- `initializeRedis()` - Initialize Redis connection
+- `getRedisClient()` - Get Redis client instance
+- `redisSetKv(key, value, ttl)` - Set key-value with TTL
+
+## Types
+
+```typescript
+import type {
+  AbstractCache,
+  CacheManagerMetadata,
+  AsyncCacheManagerMetadata,
+  WithCacheDetails,
+  SetCacheArguments,
+  LRUArgs
+} from '@md-oss/cache';
+```
+
+## Environment Variables
+
+```env
+REDIS_URL=redis://localhost:6379  # Required for Redis support
+```

package/dist/async.cjs

@@ -0,0 +1,2 @@
+"use strict";var f=Object.defineProperty;var o=(u,a)=>f(u,"name",{value:a,configurable:!0});var p=require("debug"),d=require("keyv"),l=require("./lru.cjs"),m=require("./manager.cjs");require("lru-cache"),require("cache-manager");class n extends m.CacheManager{static{o(this,"AsyncCacheManager")}debug=p("md-oss:cache:async-manager");cacheOptions;metadata={hits:0,misses:0,added:0,deleted:0,updated:0,cleared:0,errors:0,async:{last:0,total:0,average:0,longest:0,shortest:0}};dataFunction;constructor(a){super(a),this.cacheOptions=a,this.dataFunction=a.dataFunction}extend(a){return new n({...this.cacheOptions,...a})}static fromStore(a){return new n({dataFunction:a.dataFunction,stores:[a instanceof d?a:new d({...a,store:a instanceof l.LRUCache?a:new l.LRUCache(a)})]})}async get(a){const r=await super.get(a);if(typeof r<"u")return r;const t=await this.dataWrapper(a);return typeof t<"u"&&await this.set(a,t),t}async getWithDetails(a){const r=await super.get(a);if(typeof r<"u")return[r,{source:"cache",cached:!1,cachedFor:null}];const t=await this.dataWrapper(a);let e;return typeof t<"u"?(await this.set(a,t),e={source:"no-cache",cached:!0,cachedFor:await this.ttl(a)}):e={source:"no-cache",cached:!1,cachedFor:null},[t,e]}dataWrapper=o(async a=>{const r=process.hrtime();this.cacheOptions.callbacks?.onStart&&this.cacheOptions.callbacks.onStart(a);let t,e,h=!1;try{t=this.dataFunction(a),e=t instanceof Promise?await t:t,typeof e<"u"&&this.cacheOptions.callbacks?.onSuccess&&(h=!0,this.cacheOptions.callbacks.onSuccess(a,e))}catch(s){const c=h?"Error in onSuccess callback for key":"Failed to fetch/process data for key",i=typeof s=="object"&&s&&"message"in s?new Error(`${c} "${a}": ${s.message}`):new Error(`${c} "${a}": ${s}`);throw this.metadata.errors++,delete i.stack,this.cacheOptions.callbacks?.onError&&this.cacheOptions.callbacks.onError(a,i),i}finally{const s=process.hrtime(r),c=s[0]*1e3+s[1]/1e6;this.metadata.async.last=c,this.metadata.async.total+=c,this.metadata.async.average=this.metadata.async.total/this.metadata.hits,this.metadata.async.longest=Math.max(this.metadata.async.longest,c),this.metadata.async.shortest=Math.min(this.metadata.async.shortest,c),this.cacheOptions.callbacks?.onEnd&&this.cacheOptions.callbacks.onEnd(a,c)}return e},"dataWrapper")}exports.AsyncCacheManager=n;
+//# sourceMappingURL=async.cjs.map

package/dist/async.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.cjs","sources":["../src/async.ts"],"sourcesContent":["import debug from 'debug';\nimport Keyv from 'keyv';\nimport { type LRUArgs, LRUCache } from './lru';\nimport { CacheManager } from './manager';\nimport type {\n\tCacheManagerMetadata,\n\tResolvedCreateCacheOptions,\n\tWithCacheDataFn,\n\tWithCacheDetails,\n\tWithCacheReturnType,\n} from './types';\n\nexport type AsyncCreateCacheOptions<T extends NonNullable<unknown>> =\n\tResolvedCreateCacheOptions<T> & {\n\t\t/**\n\t\t * The function that fetches/processed data for a key. The function is ran\n\t\t * when the key is not found in the cache, and the data is stored in the cache.\n\t\t * - Values of type `null` are treated as cache, and will be stored as `null`.\n\t\t * - Values of type `undefined` are treated as no-cache, and will not be stored.\n\t\t * - __You are responsible for error handling in this function.__\n\t\t * - __Any unhandled errors will throw, and terminate your process.__\n\t\t * @param key The key to fetch/process data for\n\t\t * @returns The data for the key\n\t\t */\n\t\tdataFunction: WithCacheDataFn<string, T>;\n\t\t/**\n\t\t * Callbacks to run at various stages of the asynchronous caching process.\n\t\t */\n\t\tcallbacks?: AsyncCacheManagerCallbacks<T>;\n\t};\n\nexport type AsyncCacheManagerCallbacks<T extends NonNullable<unknown>> = {\n\t/**\n\t * Callback to execute when `dataFunction` starts. This callback is always executed,\n\t * and ran just before the function is called.\n\t * @param key The key passed to `dataFunction`\n\t */\n\tonStart?: (key: string) => void;\n\t/**\n\t * Callback to execute when `dataFunction` ends. This callback is always executed,\n\t * and ran just after the function finishes/resolves.\n\t * @param key The key passed to `dataFunction`\n\t * @param duration The duration of `dataFunction` in milliseconds\n\t * @returns\n\t */\n\tonEnd?: (key: string, duration: number) => void;\n\t/**\n\t * Callback to execute when `dataFunction` is successful. This callback is only\n\t * executed if the function resolves successfully, without erroring/throwing.\n\t * @param key  The key passed to `dataFunction`\n\t * @param value The value that was returned/resolved by `dataFunction`\n\t * @returns\n\t */\n\tonSuccess?: (key: string, value: T | null) => void;\n\t/**\n\t * Callback to execute when an error occurs while running `dataFunction`.\n\t * - __Please note that this callback does not affect error handling.__\n\t * - __If your `dataFunction` errors and this callback is provided, an error is still thrown.__\n\t * @param key The key passed to `dataFunction`\n\t * @param error The error that occurred while running `dataFunction`\n\t */\n\tonError?: (key: string, error: Error) => void;\n};\n\nexport type AsyncCacheManagerMetadata = CacheManagerMetadata & {\n\t/** The number/amount of errors that occurred while processing data */\n\terrors: number;\n\t/** Metadata specific to async operations */\n\tasync: {\n\t\t/** The duration of the last `dataFunction` in milliseconds */\n\t\tlast: number;\n\t\t/** The total duration the `dataFunction` has taken in milliseconds */\n\t\ttotal: number;\n\t\t/** The average duration of all `dataFunction` runs in milliseconds */\n\t\taverage: number;\n\t\t/** The longest duration of all `dataFunction` runs in milliseconds */\n\t\tlongest: number;\n\t\t/** The shortest duration of all `dataFunction` runs in milliseconds */\n\t\tshortest: number;\n\t};\n};\n\nexport class AsyncCacheManager<\n\tT extends NonNullable<unknown>,\n> extends CacheManager<T> {\n\tprotected override readonly debug: debug.Debugger = debug(\n\t\t'md-oss:cache:async-manager'\n\t);\n\toverride readonly cacheOptions: AsyncCreateCacheOptions<T>;\n\toverride readonly metadata: AsyncCacheManagerMetadata = {\n\t\thits: 0,\n\t\tmisses: 0,\n\t\tadded: 0,\n\t\tdeleted: 0,\n\t\tupdated: 0,\n\t\tcleared: 0,\n\t\terrors: 0,\n\t\tasync: {\n\t\t\tlast: 0,\n\t\t\ttotal: 0,\n\t\t\taverage: 0,\n\t\t\tlongest: 0,\n\t\t\tshortest: 0,\n\t\t},\n\t};\n\n\tprivate readonly dataFunction: WithCacheDataFn<string, T>;\n\n\t//\n\t// Class instantiation\n\t//\n\n\tconstructor(options: AsyncCreateCacheOptions<T>) {\n\t\tsuper(options);\n\t\tthis.cacheOptions = options;\n\t\tthis.dataFunction = options.dataFunction;\n\t}\n\n\toverride extend(options?: AsyncCreateCacheOptions<T>): AsyncCacheManager<T> {\n\t\treturn new AsyncCacheManager({ ...this.cacheOptions, ...options });\n\t}\n\n\tstatic override fromStore<O extends NonNullable<unknown>>(\n\t\tstore: (Keyv<O> | LRUCache<O> | LRUArgs<O>) & {\n\t\t\tdataFunction: WithCacheDataFn<string, O>;\n\t\t}\n\t): AsyncCacheManager<O> {\n\t\treturn new AsyncCacheManager<O>({\n\t\t\tdataFunction: store.dataFunction,\n\t\t\tstores: [\n\t\t\t\tstore instanceof Keyv\n\t\t\t\t\t? store\n\t\t\t\t\t: new Keyv<O>({\n\t\t\t\t\t\t\t...store,\n\t\t\t\t\t\t\tstore: store instanceof LRUCache ? store : new LRUCache(store),\n\t\t\t\t\t\t}),\n\t\t\t],\n\t\t});\n\t}\n\n\t//\n\t// Standard Cache (Manager) operations\n\t//\n\n\toverride async get(key: string): Promise<T | null | undefined> {\n\t\tconst fromCache = await super.get(key);\n\n\t\tif (typeof fromCache !== 'undefined') {\n\t\t\treturn fromCache;\n\t\t}\n\n\t\tconst wrapperResult = await this.dataWrapper(key);\n\n\t\tif (typeof wrapperResult !== 'undefined') {\n\t\t\tawait this.set(key, wrapperResult);\n\t\t}\n\n\t\treturn wrapperResult;\n\t}\n\n\tasync getWithDetails(key: string): Promise<WithCacheReturnType<T>> {\n\t\tconst fromCache = await super.get(key);\n\n\t\tif (typeof fromCache !== 'undefined') {\n\t\t\treturn [fromCache, { source: 'cache', cached: false, cachedFor: null }];\n\t\t}\n\n\t\tconst wrapperResult = await this.dataWrapper(key);\n\n\t\tlet details: WithCacheDetails;\n\n\t\tif (typeof wrapperResult !== 'undefined') {\n\t\t\tawait this.set(key, wrapperResult);\n\t\t\tdetails = {\n\t\t\t\tsource: 'no-cache',\n\t\t\t\tcached: true,\n\t\t\t\tcachedFor: await this.ttl(key),\n\t\t\t};\n\t\t} else {\n\t\t\tdetails = { source: 'no-cache', cached: false, cachedFor: null };\n\t\t}\n\n\t\treturn [wrapperResult, details];\n\t}\n\n\t//\n\t// Wrappers\n\t//\n\n\tprivate readonly dataWrapper = async (\n\t\tkey: string\n\t): Promise<T | null | undefined> => {\n\t\tconst start = process.hrtime();\n\n\t\tif (this.cacheOptions.callbacks?.onStart) {\n\t\t\tthis.cacheOptions.callbacks.onStart(key);\n\t\t}\n\n\t\tlet result: ReturnType<typeof this.dataFunction>;\n\t\tlet resolvedResult: T | null | undefined;\n\t\tlet isUserCallbackError = false;\n\n\t\ttry {\n\t\t\tresult = this.dataFunction(key);\n\t\t\tresolvedResult = result instanceof Promise ? await result : result;\n\t\t\tif (\n\t\t\t\ttypeof resolvedResult !== 'undefined' &&\n\t\t\t\tthis.cacheOptions.callbacks?.onSuccess\n\t\t\t) {\n\t\t\t\tisUserCallbackError = true;\n\t\t\t\tthis.cacheOptions.callbacks.onSuccess(key, resolvedResult);\n\t\t\t}\n\t\t} catch (err) {\n\t\t\tconst reason = isUserCallbackError\n\t\t\t\t? 'Error in onSuccess callback for key'\n\t\t\t\t: 'Failed to fetch/process data for key';\n\t\t\tconst cleanError =\n\t\t\t\ttypeof err === 'object' && err && 'message' in err\n\t\t\t\t\t? new Error(`${reason} \"${key}\": ${err.message}`)\n\t\t\t\t\t: new Error(`${reason} \"${key}\": ${err}`);\n\n\t\t\tthis.metadata.errors++;\n\t\t\tdelete cleanError.stack;\n\n\t\t\tif (this.cacheOptions.callbacks?.onError) {\n\t\t\t\tthis.cacheOptions.callbacks.onError(key, cleanError);\n\t\t\t}\n\n\t\t\tthrow cleanError;\n\t\t} finally {\n\t\t\tconst end = process.hrtime(start);\n\t\t\tconst duration = end[0] * 1e3 + end[1] / 1e6;\n\n\t\t\tthis.metadata.async.last = duration;\n\t\t\tthis.metadata.async.total += duration;\n\t\t\tthis.metadata.async.average =\n\t\t\t\tthis.metadata.async.total / this.metadata.hits;\n\t\t\tthis.metadata.async.longest = Math.max(\n\t\t\t\tthis.metadata.async.longest,\n\t\t\t\tduration\n\t\t\t);\n\t\t\tthis.metadata.async.shortest = Math.min(\n\t\t\t\tthis.metadata.async.shortest,\n\t\t\t\tduration\n\t\t\t);\n\n\t\t\tif (this.cacheOptions.callbacks?.onEnd) {\n\t\t\t\tthis.cacheOptions.callbacks.onEnd(key, duration);\n\t\t\t}\n\t\t}\n\n\t\treturn resolvedResult;\n\t};\n}\n"],"names":["AsyncCacheManager","CacheManager","__name","debug","options","store","Keyv","LRUCache","key","fromCache","wrapperResult","details","start","result","resolvedResult","isUserCallbackError","err","reason","cleanError","end","duration"],"mappings":"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"}

package/dist/async.d.cts

@@ -0,0 +1,92 @@
+import debug from 'debug';
+import Keyv from 'keyv';
+import { LRUCache, LRUArgs } from './lru.cjs';
+import { CacheManager } from './manager.cjs';
+import { ResolvedCreateCacheOptions, WithCacheDataFn, CacheManagerMetadata, WithCacheReturnType } from './types.cjs';
+import 'lru-cache';
+import 'node:events';
+import 'cache-manager';
+
+type AsyncCreateCacheOptions<T extends NonNullable<unknown>> = ResolvedCreateCacheOptions<T> & {
+    /**
+     * The function that fetches/processed data for a key. The function is ran
+     * when the key is not found in the cache, and the data is stored in the cache.
+     * - Values of type `null` are treated as cache, and will be stored as `null`.
+     * - Values of type `undefined` are treated as no-cache, and will not be stored.
+     * - __You are responsible for error handling in this function.__
+     * - __Any unhandled errors will throw, and terminate your process.__
+     * @param key The key to fetch/process data for
+     * @returns The data for the key
+     */
+    dataFunction: WithCacheDataFn<string, T>;
+    /**
+     * Callbacks to run at various stages of the asynchronous caching process.
+     */
+    callbacks?: AsyncCacheManagerCallbacks<T>;
+};
+type AsyncCacheManagerCallbacks<T extends NonNullable<unknown>> = {
+    /**
+     * Callback to execute when `dataFunction` starts. This callback is always executed,
+     * and ran just before the function is called.
+     * @param key The key passed to `dataFunction`
+     */
+    onStart?: (key: string) => void;
+    /**
+     * Callback to execute when `dataFunction` ends. This callback is always executed,
+     * and ran just after the function finishes/resolves.
+     * @param key The key passed to `dataFunction`
+     * @param duration The duration of `dataFunction` in milliseconds
+     * @returns
+     */
+    onEnd?: (key: string, duration: number) => void;
+    /**
+     * Callback to execute when `dataFunction` is successful. This callback is only
+     * executed if the function resolves successfully, without erroring/throwing.
+     * @param key  The key passed to `dataFunction`
+     * @param value The value that was returned/resolved by `dataFunction`
+     * @returns
+     */
+    onSuccess?: (key: string, value: T | null) => void;
+    /**
+     * Callback to execute when an error occurs while running `dataFunction`.
+     * - __Please note that this callback does not affect error handling.__
+     * - __If your `dataFunction` errors and this callback is provided, an error is still thrown.__
+     * @param key The key passed to `dataFunction`
+     * @param error The error that occurred while running `dataFunction`
+     */
+    onError?: (key: string, error: Error) => void;
+};
+type AsyncCacheManagerMetadata = CacheManagerMetadata & {
+    /** The number/amount of errors that occurred while processing data */
+    errors: number;
+    /** Metadata specific to async operations */
+    async: {
+        /** The duration of the last `dataFunction` in milliseconds */
+        last: number;
+        /** The total duration the `dataFunction` has taken in milliseconds */
+        total: number;
+        /** The average duration of all `dataFunction` runs in milliseconds */
+        average: number;
+        /** The longest duration of all `dataFunction` runs in milliseconds */
+        longest: number;
+        /** The shortest duration of all `dataFunction` runs in milliseconds */
+        shortest: number;
+    };
+};
+declare class AsyncCacheManager<T extends NonNullable<unknown>> extends CacheManager<T> {
+    protected readonly debug: debug.Debugger;
+    readonly cacheOptions: AsyncCreateCacheOptions<T>;
+    readonly metadata: AsyncCacheManagerMetadata;
+    private readonly dataFunction;
+    constructor(options: AsyncCreateCacheOptions<T>);
+    extend(options?: AsyncCreateCacheOptions<T>): AsyncCacheManager<T>;
+    static fromStore<O extends NonNullable<unknown>>(store: (Keyv<O> | LRUCache<O> | LRUArgs<O>) & {
+        dataFunction: WithCacheDataFn<string, O>;
+    }): AsyncCacheManager<O>;
+    get(key: string): Promise<T | null | undefined>;
+    getWithDetails(key: string): Promise<WithCacheReturnType<T>>;
+    private readonly dataWrapper;
+}
+
+export { AsyncCacheManager };
+export type { AsyncCacheManagerCallbacks, AsyncCacheManagerMetadata, AsyncCreateCacheOptions };

package/dist/async.d.mts

@@ -0,0 +1,92 @@
+import debug from 'debug';
+import Keyv from 'keyv';
+import { LRUCache, LRUArgs } from './lru.mjs';
+import { CacheManager } from './manager.mjs';
+import { ResolvedCreateCacheOptions, WithCacheDataFn, CacheManagerMetadata, WithCacheReturnType } from './types.mjs';
+import 'lru-cache';
+import 'node:events';
+import 'cache-manager';
+
+type AsyncCreateCacheOptions<T extends NonNullable<unknown>> = ResolvedCreateCacheOptions<T> & {
+    /**
+     * The function that fetches/processed data for a key. The function is ran
+     * when the key is not found in the cache, and the data is stored in the cache.
+     * - Values of type `null` are treated as cache, and will be stored as `null`.
+     * - Values of type `undefined` are treated as no-cache, and will not be stored.
+     * - __You are responsible for error handling in this function.__
+     * - __Any unhandled errors will throw, and terminate your process.__
+     * @param key The key to fetch/process data for
+     * @returns The data for the key
+     */
+    dataFunction: WithCacheDataFn<string, T>;
+    /**
+     * Callbacks to run at various stages of the asynchronous caching process.
+     */
+    callbacks?: AsyncCacheManagerCallbacks<T>;
+};
+type AsyncCacheManagerCallbacks<T extends NonNullable<unknown>> = {
+    /**
+     * Callback to execute when `dataFunction` starts. This callback is always executed,
+     * and ran just before the function is called.
+     * @param key The key passed to `dataFunction`
+     */
+    onStart?: (key: string) => void;
+    /**
+     * Callback to execute when `dataFunction` ends. This callback is always executed,
+     * and ran just after the function finishes/resolves.
+     * @param key The key passed to `dataFunction`
+     * @param duration The duration of `dataFunction` in milliseconds
+     * @returns
+     */
+    onEnd?: (key: string, duration: number) => void;
+    /**
+     * Callback to execute when `dataFunction` is successful. This callback is only
+     * executed if the function resolves successfully, without erroring/throwing.
+     * @param key  The key passed to `dataFunction`
+     * @param value The value that was returned/resolved by `dataFunction`
+     * @returns
+     */
+    onSuccess?: (key: string, value: T | null) => void;
+    /**
+     * Callback to execute when an error occurs while running `dataFunction`.
+     * - __Please note that this callback does not affect error handling.__
+     * - __If your `dataFunction` errors and this callback is provided, an error is still thrown.__
+     * @param key The key passed to `dataFunction`
+     * @param error The error that occurred while running `dataFunction`
+     */
+    onError?: (key: string, error: Error) => void;
+};
+type AsyncCacheManagerMetadata = CacheManagerMetadata & {
+    /** The number/amount of errors that occurred while processing data */
+    errors: number;
+    /** Metadata specific to async operations */
+    async: {
+        /** The duration of the last `dataFunction` in milliseconds */
+        last: number;
+        /** The total duration the `dataFunction` has taken in milliseconds */
+        total: number;
+        /** The average duration of all `dataFunction` runs in milliseconds */
+        average: number;
+        /** The longest duration of all `dataFunction` runs in milliseconds */
+        longest: number;
+        /** The shortest duration of all `dataFunction` runs in milliseconds */
+        shortest: number;
+    };
+};
+declare class AsyncCacheManager<T extends NonNullable<unknown>> extends CacheManager<T> {
+    protected readonly debug: debug.Debugger;
+    readonly cacheOptions: AsyncCreateCacheOptions<T>;
+    readonly metadata: AsyncCacheManagerMetadata;
+    private readonly dataFunction;
+    constructor(options: AsyncCreateCacheOptions<T>);
+    extend(options?: AsyncCreateCacheOptions<T>): AsyncCacheManager<T>;
+    static fromStore<O extends NonNullable<unknown>>(store: (Keyv<O> | LRUCache<O> | LRUArgs<O>) & {
+        dataFunction: WithCacheDataFn<string, O>;
+    }): AsyncCacheManager<O>;
+    get(key: string): Promise<T | null | undefined>;
+    getWithDetails(key: string): Promise<WithCacheReturnType<T>>;
+    private readonly dataWrapper;
+}
+
+export { AsyncCacheManager };
+export type { AsyncCacheManagerCallbacks, AsyncCacheManagerMetadata, AsyncCreateCacheOptions };