@boredland/node-ts-cache 5.0.0 → 5.1.0

package/README.md

@@ -1,14 +1,15 @@
-# boredland/node-ts-cache
+# @boredland/node-ts-cache
 
 [![CI](https://github.com/boredland/node-ts-cache/actions/workflows/ci.yml/badge.svg)](https://github.com/boredland/node-ts-cache/actions/workflows/ci.yml)
 [![The MIT License](https://img.shields.io/npm/l/node-ts-cache.svg)](http://opensource.org/licenses/MIT)
+[![Coverage Status](https://coveralls.io/repos/github/boredland/node-ts-cache/badge.svg?branch=main)](https://coveralls.io/github/boredland/node-ts-cache?branch=main)
 
 Simple and extensible caching module supporting decorators.
 
 ## Install
 
 ```bash
-yarn add boredland/node-ts-cache
+yarn add @boredland/node-ts-cache
 ```
 
 _Note: The underlying storage layer must be installed separately._
@@ -17,29 +18,32 @@ _Note: The underlying storage layer must be installed separately._
 
 | Storage                                                               | Install                                         |
 |-----------------------------------------------------------------------|-------------------------------------------------|
-| [memory](https://www.npmjs.com/package/boredland/node-ts-cache-storage-memory)| ```yarn add boredland/node-ts-cache-storage-memory```|
-| [node-fs](https://www.npmjs.com/package/boredland/node-ts-cache-storage-node-fs)| ```yarn add boredland/node-ts-cache-storage-node-fs```|
-| [ioredis](https://www.npmjs.com/package/boredland/node-ts-cache-storage-ioredis)| ```yarn add boredland/node-ts-cache-storage-ioredis```|
+| [memory](https://www.npmjs.com/package/boredland/node-ts-cache-storage-memory)| ```yarn add @boredland/node-ts-cache-storage-memory```|
+| [node-fs](https://www.npmjs.com/package/boredland/node-ts-cache-storage-node-fs)| ```yarn add @boredland/node-ts-cache-storage-node-fs```|
+| [ioredis](https://www.npmjs.com/package/boredland/node-ts-cache-storage-ioredis)| ```yarn add @boredland/node-ts-cache-storage-ioredis```|
 
 ## Usage
 
-## With decorator
+### withCacheFactory
 
-Caches function response using the given options.
-Works with the above listed storages.
-By default, uses all arguments to build an unique key.
+Function wrapper factory for arbitrary functions. The cache key is caculated based on the parameters passed to the function.
 
-`@Cache(container, options)`
+```ts
+import { withCacheFactory, CacheContainer } from '@boredland/node-ts-cache'
+import { MemoryStorage } from '@boredland/node-ts-cache-storage-memory'
+
+const doThingsCache = new CacheContainer(new MemoryStorage())
+
+const someFn = (input: { a: string, b: number })
+
+const wrappedFn = withCacheFactory(doThingsCache)(someFn);
+
+const result = someFn({ a: "lala", b: 123 })
+```
+
+### With decorator
 
-- `options`:
-  - `ttl`: _(Default: 60)_ Number of seconds to expire the cachte item
-  - `isLazy`: _(Default: true)_ If true, expired cache entries will be deleted on touch. If false, entries will be deleted after the given _ttl_.
-  - `isCachedForever`: _(Default: false)_ If true, cache entry has no expiration.
-  - `calculateKey(data => string)`: _(Default: JSON.stringify combination of className, methodName and call args)_
-    - `data`:
-    - `className`: The class name for the method being decorated
-    - `methodName`: The method name being decorated
-    - `args`: The arguments passed to the method when called
+Caches function response using the given options. By default, uses all arguments to build an unique key.
 
 _Note: @Cache will consider the return type of the function. If the return type is a thenable, it will stay that way, otherwise not._
 
@@ -57,7 +61,7 @@ class MyService {
 }
 ```
 
-## Directly
+### Direct usage
 
 ```ts
 import { CacheContainer } from '@boredland/node-ts-cache'

package/dist/cache-container/cache-container-types.d.ts

@@ -7,12 +7,19 @@ export declare type CachedItem<T = any> = {
     };
 };
 export declare type CachingOptions = {
+    /** (Default: 60) Number of seconds to expire the cachte item */
     ttl: number;
+    /** (Default: true) If true, expired cache entries will be deleted on touch and returned anyway. If false, entries will be deleted after the given ttl. */
     isLazy: boolean;
+    /** (Default: false) If true, cache entry has no expiration. */
     isCachedForever: boolean;
+    /** (Default: JSON.stringify combination of className, methodName and call args) */
     calculateKey: (data: {
+        /** The class name for the method being decorated */
         className: string;
+        /** The method name being decorated */
         methodName: string;
+        /** The arguments passed to the method when called */
         args: any[];
     }) => string;
 };

package/dist/cache-container/cache-container.d.ts

@@ -3,7 +3,13 @@ import type { CachingOptions } from "./cache-container-types";
 export declare class CacheContainer {
     private storage;
     constructor(storage: IStorage);
-    getItem<T>(key: string): Promise<T | undefined>;
+    getItem<T>(key: string): Promise<{
+        content: T;
+        meta: {
+            expired: boolean;
+            createdAt: number;
+        };
+    } | undefined>;
     setItem(key: string, content: any, options: Partial<CachingOptions>): Promise<void>;
     clear(): Promise<void>;
     private isItemExpired;

package/dist/cache-container/cache-container.js

@@ -14,11 +14,20 @@ class CacheContainer {
     }
     async getItem(key) {
         const item = await this.storage.getItem(key);
-        if (item?.meta?.ttl && this.isItemExpired(item)) {
+        if (!item)
+            return;
+        const result = {
+            content: item.content,
+            meta: {
+                createdAt: item.meta.createdAt,
+                expired: this.isItemExpired(item)
+            }
+        };
+        if (result.meta.expired)
             await this.unsetKey(key);
+        if (result.meta.expired && !item.meta.isLazy)
             return undefined;
-        }
-        return item ? item.content : undefined;
+        return result;
     }
     async setItem(key, content, options) {
         const finalOptions = {
@@ -32,12 +41,6 @@ class CacheContainer {
             isLazy: finalOptions.isLazy,
             ttl: finalOptions.isCachedForever ? Infinity : finalOptions.ttl * 1000
         };
-        if (!finalOptions.isCachedForever && !finalOptions.isLazy) {
-            setTimeout(() => {
-                this.unsetKey(key);
-                debug(`Expired key ${key} removed from cache`);
-            }, meta.ttl);
-        }
         await this.storage.setItem(key, { meta, content });
     }
     async clear() {

package/dist/decorator/cache-decorator.js

@@ -46,7 +46,7 @@ function Cache(container, options) {
                     const entry = await container.getItem(cacheKey);
                     if (entry) {
                         debug(`Cache HIT ${cacheKey}`);
-                        return entry;
+                        return entry.content;
                     }
                     debug(`Cache MISS ${cacheKey}`);
                     const methodResult = await runOriginalMethod();

package/dist/withCache.d.ts

@@ -1,12 +1,16 @@
 import type { CacheContainer, CachingOptions } from "./cache-container";
 declare type WithCacheOptions<Parameters> = Partial<Omit<CachingOptions, 'calculateKey'>> & {
-    prefix: string;
-    calculateKey?: (prefix: string, input: Parameters) => string;
+    /** an optional prefix to prepend to the key */
+    prefix?: string;
+    /** an optional function to calculate a key based on the parameters of the wrapped function */
+    calculateKey?: (input: Parameters) => string;
+    /** an optional function that is called when a lazy item has expired and thus got removed  */
+    afterExpired?: () => Promise<void>;
 };
 /**
  * wrapped function factory
  * @param container - cache container to create the fn for
- * @returns a wrapped function
+ * @returns wrapping function
  */
-export declare const withCacheFactory: (container: CacheContainer) => <Parameters_1 extends unknown[], Result extends Promise<unknown>>(operation: (...parameters: Parameters_1) => Result, { calculateKey, prefix, ...options }: WithCacheOptions<Parameters_1>) => (...parameters: Parameters_1) => Promise<Result>;
+export declare const withCacheFactory: (container: CacheContainer) => <Parameters_1 extends unknown[], Result extends Promise<unknown>>(operation: (...parameters: Parameters_1) => Result, options?: WithCacheOptions<Parameters_1>) => (...parameters: Parameters_1) => Promise<Result>;
 export {};

package/dist/withCache.js

@@ -4,18 +4,29 @@ exports.withCacheFactory = void 0;
 /**
  * wrapped function factory
  * @param container - cache container to create the fn for
- * @returns a wrapped function
+ * @returns wrapping function
  */
 const withCacheFactory = (container) => {
-    const withCache = (operation, { calculateKey, prefix, ...options }) => {
+    /**
+     * function wrapper
+     * @param operation - the function to be wrapped
+     * @param options - caching options
+     * @returns wrapped operation
+     */
+    const withCache = (operation, options = {}) => {
         return async (...parameters) => {
-            const key = calculateKey ? calculateKey(prefix, parameters) : `${prefix}_${JSON.stringify(parameters)}`;
+            let { prefix, calculateKey, ...rest } = options;
+            prefix = prefix ?? 'default';
+            const key = `${operation.name}:${prefix}:${calculateKey ? calculateKey(parameters) : JSON.stringify(parameters)}`;
             const cachedResponse = await container.getItem(key);
             if (cachedResponse) {
-                return cachedResponse;
+                if (cachedResponse.meta.expired && options.afterExpired) {
+                    await options.afterExpired();
+                }
+                return cachedResponse.content;
             }
             const result = await operation(...parameters);
-            await container.setItem(key, result, options);
+            await container.setItem(key, result, rest);
             return result;
         };
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boredland/node-ts-cache",
   "description": "Simple and extensible caching module supporting decorators",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,7 +32,6 @@
     "node-cache",
     "ts-cache"
   ],
-  "author": "Himmet Avsar <avsar.himmet1@gmail.com>",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/boredland/node-ts-cache/issues"