@boredland/node-ts-cache 4.4.0

package/README.md

@@ -0,0 +1,101 @@
+# 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)
+
+Simple and extensible caching module supporting decorators.
+
+## Install
+
+```bash
+yarn add boredland/node-ts-cache
+```
+
+_Note: The underlying storage layer must be installed separately._
+
+## Storage
+
+| 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```|
+
+## Usage
+
+## With decorator
+
+Caches function response using the given options.
+Works with the above listed storages.
+By default, uses all arguments to build an unique key.
+
+`@Cache(container, options)`
+
+- `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
+
+_Note: @Cache will consider the return type of the function. If the return type is a thenable, it will stay that way, otherwise not._
+
+```ts
+import { Cache, CacheContainer } from '@boredland/node-ts-cache'
+import { MemoryStorage } from '@boredland/node-ts-cache-storage-memory'
+
+const userCache = new CacheContainer(new MemoryStorage())
+
+class MyService {
+    @Cache(userCache, {ttl: 60})
+    public async getUsers(): Promise<string[]> {
+        return ["Max", "User"]
+    }
+}
+```
+
+## Directly
+
+```ts
+import { CacheContainer } from '@boredland/node-ts-cache'
+import { MemoryStorage } from '@boredland/node-ts-cache-storage-memory'
+
+const myCache = new CacheContainer(new MemoryStorage())
+
+class MyService {
+    public async getUsers(): Promise<string[]> {
+        const cachedUsers = await myCache.getItem<string[]>("users")
+
+        if (cachedUsers) {
+            return cachedUsers
+        }
+
+        const newUsers = ["Max", "User"]
+
+        await myCache.setItem("users", newUsers, {ttl: 60})
+
+        return newUsers
+    }
+}
+```
+
+## Logging
+
+This project uses [debug](https://github.com/visionmedia/debug) to log useful caching information.
+Set environment variable **DEBUG=node-ts-cache** to enable logging.
+
+## Development & Testing
+
+This project follows the monorepo architecture using yarn workspaces.
+
+To start development and run tests for all the packages, run:
+
+```bash
+cd node-ts-cache
+yarn
+yarn build
+yarn test
+```

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

@@ -0,0 +1,18 @@
+export declare type CachedItem<T = any> = {
+    content: T;
+    meta: {
+        createdAt: number;
+        ttl: number;
+        isLazy: boolean;
+    };
+};
+export declare type CachingOptions = {
+    ttl: number;
+    isLazy: boolean;
+    isCachedForever: boolean;
+    calculateKey: (data: {
+        className: string;
+        methodName: string;
+        args: any[];
+    }) => string;
+};

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,11 @@
+import type { IStorage } from "../storage";
+import type { CachingOptions } from "./cache-container-types";
+export declare class CacheContainer {
+    private storage;
+    constructor(storage: IStorage);
+    getItem<T>(key: string): Promise<T | undefined>;
+    setItem(key: string, content: any, options: Partial<CachingOptions>): Promise<void>;
+    clear(): Promise<void>;
+    private isItemExpired;
+    private unsetKey;
+}

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

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheContainer = void 0;
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)("node-ts-cache");
+const DEFAULT_TTL_SECONDS = 60;
+class CacheContainer {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async getItem(key) {
+        const item = await this.storage.getItem(key);
+        if (item?.meta?.ttl && this.isItemExpired(item)) {
+            await this.unsetKey(key);
+            return undefined;
+        }
+        return item ? item.content : undefined;
+    }
+    async setItem(key, content, options) {
+        const finalOptions = {
+            ttl: DEFAULT_TTL_SECONDS,
+            isLazy: true,
+            isCachedForever: false,
+            ...options
+        };
+        const meta = {
+            createdAt: Date.now(),
+            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() {
+        await this.storage.clear();
+        debug("Cleared cache");
+    }
+    isItemExpired(item) {
+        if (item.meta.ttl === Infinity)
+            return false;
+        return Date.now() > item.meta.createdAt + item.meta.ttl;
+    }
+    async unsetKey(key) {
+        await this.storage.setItem(key, undefined);
+    }
+}
+exports.CacheContainer = CacheContainer;

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

@@ -0,0 +1,2 @@
+export * from "./cache-container";
+export * from "./cache-container-types";

package/dist/cache-container/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cache-container"), exports);
+__exportStar(require("./cache-container-types"), exports);

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

@@ -0,0 +1,2 @@
+import type { CacheContainer, CachingOptions } from "../cache-container";
+export declare function Cache(container: CacheContainer, options?: Partial<CachingOptions>): MethodDecorator;

package/dist/decorator/cache-decorator.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)("node-ts-cache");
+const jsonCalculateKey = (data) => {
+    return `${data.className}:${data.methodName}:${JSON.stringify(data.args)}`;
+};
+function Cache(container, options) {
+    return function (target, methodName, descriptor) {
+        const originalMethod = descriptor.value;
+        const className = target.constructor.name;
+        descriptor.value = async function (...args) {
+            options ??= {};
+            const keyOptions = {
+                args,
+                methodName: methodName,
+                className
+            };
+            const cacheKey = options.calculateKey
+                ? options.calculateKey(keyOptions)
+                : jsonCalculateKey(keyOptions);
+            const runOriginalMethod = async () => {
+                const methodCall = originalMethod.apply(this, args);
+                const isAsync = methodCall?.constructor?.name === "AsyncFunction" ||
+                    methodCall?.constructor?.name === "Promise";
+                if (isAsync) {
+                    return await methodCall;
+                }
+                else {
+                    return methodCall;
+                }
+            };
+            if (!target.__node_ts_cache_method_run_queue) {
+                target.__node_ts_cache_method_run_queue = {};
+            }
+            if (target.__node_ts_cache_method_run_queue[cacheKey]) {
+                debug(`Method is already enqueued ${cacheKey}`);
+                return target.__node_ts_cache_method_run_queue[cacheKey];
+            }
+            target.__node_ts_cache_method_run_queue[cacheKey] = (async () => {
+                try {
+                    const entry = await container.getItem(cacheKey);
+                    if (entry) {
+                        debug(`Cache HIT ${cacheKey}`);
+                        return entry;
+                    }
+                    debug(`Cache MISS ${cacheKey}`);
+                    const methodResult = await runOriginalMethod();
+                    await container.setItem(cacheKey, methodResult, options);
+                    return methodResult;
+                }
+                finally {
+                    target.__node_ts_cache_method_run_queue[cacheKey] =
+                        undefined;
+                }
+            })();
+            return target.__node_ts_cache_method_run_queue[cacheKey];
+        };
+        debug(`Added caching for method ${className}:${methodName.toString()}`);
+        return descriptor;
+    };
+}
+exports.Cache = Cache;

package/dist/decorator/index.d.ts

@@ -0,0 +1 @@
+export * from "./cache-decorator";

package/dist/decorator/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cache-decorator"), exports);

package/dist/hasher.d.ts

@@ -0,0 +1,3 @@
+import objectHash from 'node-object-hash';
+declare const hash: (object: any, opts?: objectHash.HasherOptions | undefined) => string;
+export { hash };

package/dist/hasher.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hash = void 0;
+const node_object_hash_1 = __importDefault(require("node-object-hash"));
+const { hash } = (0, node_object_hash_1.default)();
+exports.hash = hash;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./decorator";
+export * from "./storage";
+export * from "./cache-container";
+export * from "./withCache";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./decorator"), exports);
+__exportStar(require("./storage"), exports);
+__exportStar(require("./cache-container"), exports);
+__exportStar(require("./withCache"), exports);

package/dist/storage/index.d.ts

@@ -0,0 +1 @@
+export * from "./storage-types";

package/dist/storage/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./storage-types"), exports);

package/dist/storage/storage-types.d.ts

@@ -0,0 +1,6 @@
+import type { CachedItem } from "../cache-container";
+export interface IStorage {
+    getItem(key: string): Promise<CachedItem | undefined>;
+    setItem(key: string, content: CachedItem | undefined): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/storage/storage-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/withCache.d.ts

@@ -0,0 +1,12 @@
+import type { CacheContainer, CachingOptions } from "./cache-container";
+declare type WithCacheOptions<Parameters> = Partial<Omit<CachingOptions, 'calculateKey'>> & {
+    prefix: string;
+    calculateKey?: (prefix: string, input: Parameters) => string;
+};
+/**
+ * wrapped function factory
+ * @param container - cache container to create the fn for
+ * @returns a wrapped 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 {};

package/dist/withCache.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCacheFactory = void 0;
+/**
+ * wrapped function factory
+ * @param container - cache container to create the fn for
+ * @returns a wrapped function
+ */
+const withCacheFactory = (container) => {
+    const withCache = (operation, { calculateKey, prefix, ...options }) => {
+        return async (...parameters) => {
+            const key = calculateKey ? calculateKey(prefix, parameters) : `${prefix}_${JSON.stringify(parameters)}`;
+            const cachedResponse = await container.getItem(key);
+            if (cachedResponse) {
+                return cachedResponse;
+            }
+            const result = await operation(...parameters);
+            await container.setItem(key, result, options);
+            return result;
+        };
+    };
+    return withCache;
+};
+exports.withCacheFactory = withCacheFactory;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@boredland/node-ts-cache",
+  "description": "Simple and extensible caching module supporting decorators",
+  "version": "4.4.0",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig-build.json",
+    "prepublishOnly": "cp ../../README.md ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boredland/node-ts-cache.git"
+  },
+  "keywords": [
+    "node",
+    "nodejs",
+    "cache",
+    "typescript",
+    "ts",
+    "caching",
+    "memcache",
+    "memory-cache",
+    "redis-cache",
+    "redis",
+    "cache",
+    "file-cache",
+    "node-cache",
+    "ts-cache"
+  ],
+  "author": "Himmet Avsar <avsar.himmet1@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/boredland/node-ts-cache/issues"
+  },
+  "homepage": "https://github.com/boredland/node-ts-cache#readme",
+  "dependencies": {
+    "debug": "4.3.4"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.7"
+  }
+}