@jointly/cache-candidate 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jointly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# What is it?
+
+This is a library providing both a decorator and a higher-order function to cache the result of a method if given conditions are met.
+
+# How does it work?
+
+## Decorator
+
+The decorator expects to receive an object with a partial of the properties contained in the `CacheCandidateOptions` interface.  
+Every non-passed property will be set to its default value using the `CacheCandidateOptionsDefault` object.  
+The decorator will return a method that will return a Promise fulfilled with the cached value if the method has already been called with the same arguments and the conditions are met.  
+The conditions are, within the given `timeFrame`:
+
+- If a `candidateFunction` is provided, it returns `true` for at least `requestThreshold` times.
+- If a `millisecondsThreshold` is provided, it passed such threshold (Execution time) at least `requestThreshold` times.
+- If only a `requestThreshold` is provided (default), it is called at least `requestThreshold` times.
+
+You can pass an additional `dependencyKeys` property to the decorator options which provides an invalidation mechanism to be called manually in your codebase.  
+This property can be either an array of string, a function that returns an array of string or a function that returns a Promise fulfilled with an array of string.  
+Both the function and the Promise will receive the result of the method on which the CacheCandidate operates.  
+In case of an async method, the promise will be fulfilled before passing the result to the `dependencyKeys` function.  
+The `dependencyKeys` function will be called only if the cache adapter correctly sets the value in the cache (i.e. the `.set` method is fulfilled).
+
+## Higher-order function
+
+Everything is the same as the decorator, but the function takes the original function as the first argument and the options as the second argument.  
+The function returns a new function that will return a Promise fulfilled with the cached value if the method has already been called with the same arguments and the conditions are met.
+
+## Key composition
+
+The cache key is composed based on the following criteria:
+
+### Decorator
+
+- The class constructor name.
+- The method name.
+- The arguments passed to the method. (JSON.stringify)
+- `instanceIdentifier`: A uniqid generated for each instance of the class. It uses the instance properties to generate the id. (JSON.stringify)
+- `uniqueIdentifier`: A uniqid generated to allow multiple files to contain the same class with the same method.
+
+
+### Higher-order function
+
+- The arguments passed to the method. (JSON.stringify)
+- `uniqueIdentifier`: A uniqid generated to allow multiple files to contain the same class with the same method.
+
+
+## Cache invalidation
+
+The cache invalidation is done using the exported `cacheCandidateDependencyManager` object.  
+The object exposes the `invalidate` method which accepts a string.  
+The string is one of the dependency keys returned by the `dependencyKeys` function/array defined in the decorator options.  
+
+### Example
+
+```typescript
+import { cacheCandidate, cacheCandidateDependencyManager } from 'cache-candidate';
+
+class MyClass {
+  @CacheCandidate({
+    dependencyKeys: (users) => {
+      return users.map((user) => `users-${user.id}`);
+      },
+  })
+  public async getUsers() {
+    // Do something
+    return users;
+  }
+
+  public async updateUser(user) {
+    // Do something
+    cacheCandidateDependencyManager.invalidate(`users-${user.id}`);
+  }
+}
+
+const myClass = new MyClass();
+const users = await myClass.getUsers();
+users[0].name = 'New name';
+await myClass.updateUser(users[0]); // This will invalidate the cache
+```
+
+
+# Other Info
+
+## Constraints
+
+- The decorator can only be applied to methods that return a `Promise`.
+- The `candidateFunction` must be synchronous to maintain good performances. If passed an async function bypassing type checking, the candidateFunction will return a Promise thus not working properly.
+
+## Cache Stampede
+
+The decorator prevents the cache stampede problem by using a `Map` called `runningQueries` which saves the promise of the method call.  
+If multiple calls are made to the same method with the same arguments, the method will be called only once and the other calls will wait for the Promise to finish.  
+The `runningQueries` Map will be cleaned after the method execution is finished.
+
+## Considerations on cache operations
+
+The decorator doesn't consider the correct execution of the given cache methods.  
+It isn't the decorator's responsibility to check if the cache methods are working properly.  
+The only consideration done is based on the fact that the `set` method will eventually fulfill or reject the Promise as it uses the `.finally` method to delete the key from the `runningQueries` Map and set the timeout to clean the cache record.
+
+## Problems with synchronous methods
+
+If the given method is synchronous, the decorator could not work as expected.  
+The reason is that the decorator internally transforms the method to an asynchronous one, so executing the same method multiple times during the same Event Loop tick will prevent the cache from setting the value in time, thus not working as expected.  
+The expected result will still be achieved, but please consider the multiple cache set operations during development.
+
+## Considerations on identification
+
+The decorator uses the `instanceIdentifier` and `uniqueIdentifier` to identify the class instance and the method.  
+The `instanceIdentifier` is generated using the instance properties, so if the instance properties change, the `instanceIdentifier` will change as well, thus changing the data cache key.  
+The `uniqueIdentifier` is generated using the class name and the method name.
+
+## Dictionary
+
+### DataCache
+
+The effective cache instance.
+
+### TimeFrameCache
+
+The Map containing the method executions in a given timeframe.
+
+### RunningQueryCache
+
+The Map containing the running queries (Promises fulfilled or yet to be fulfilled).
+
+### Comparation Value
+
+The value calculated based on candidate conditions which is then compared to the requestThreshold.

package/dist/cache-adapters/memory.d.ts

@@ -0,0 +1,2 @@
+import { CacheCandidateCacheAdapter, DataCacheRecord } from '../models';
+export declare const makeAsyncMap: (map?: Map<string, DataCacheRecord>) => CacheCandidateCacheAdapter;

package/dist/cache-adapters/redis.d.ts

@@ -0,0 +1,3 @@
+import { createClient } from 'redis';
+import { CacheCandidateCacheAdapter } from '../models';
+export declare const makeRedisCache: (client: ReturnType<typeof createClient>) => CacheCandidateCacheAdapter;

package/dist/default.d.ts

@@ -0,0 +1,2 @@
+import { CacheCandidateOptions } from './models';
+export declare const CacheCandidateOptionsDefault: CacheCandidateOptions;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './default';
+export * from './models';
+export * from './lib';

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var U=Object.create;var f=Object.defineProperty;var Q=Object.getOwnPropertyDescriptor;var K=Object.getOwnPropertyNames;var G=Object.getPrototypeOf,j=Object.prototype.hasOwnProperty;var _=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports),q=(e,t)=>{for(var n in t)f(e,n,{get:t[n],enumerable:!0})},x=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of K(t))!j.call(e,a)&&a!==n&&f(e,a,{get:()=>t[a],enumerable:!(r=Q(t,a))||r.enumerable});return e};var H=(e,t,n)=>(n=e!=null?U(G(e)):{},x(t||!e||!e.__esModule?f(n,"default",{value:e,enumerable:!0}):n,e)),J=e=>x(f({},"__esModule",{value:!0}),e);var F=_((ve,v)=>{"use strict";var y=Object.defineProperty,X=Object.getOwnPropertyDescriptor,W=Object.getOwnPropertyNames,$=Object.prototype.hasOwnProperty,B=(e,t)=>{for(var n in t)y(e,n,{get:t[n],enumerable:!0})},Y=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of W(t))!$.call(e,a)&&a!==n&&y(e,a,{get:()=>t[a],enumerable:!(r=X(t,a))||r.enumerable});return e},z=e=>Y(y({},"__esModule",{value:!0}),e),N={};B(N,{Hook:()=>ee,hook:()=>te});v.exports=z(N);var V={before:()=>{},after:()=>{}},Z={before:()=>{},after:()=>{}};function ee(e){return function(t,n,r){let a={},i=r.value,{before:o,after:c}={...V,...e};return r.value=function(...u){o({context:a,args:u,target:t,propertyKey:n,descriptor:r});let s=i.apply(this,u);return c({context:a,args:u,target:t,propertyKey:n,descriptor:r,result:s}),s},r}}function te(e){return function(t){let n={},{before:r,after:a}={...Z,...e};return function(...i){r({context:n,args:i});let o=t(...i);return a({context:n,args:i,result:o}),o}}}});var w=_((be,S)=>{"use strict";var D=Object.defineProperty,re=Object.getOwnPropertyDescriptor,ie=Object.getOwnPropertyNames,oe=Object.prototype.hasOwnProperty,ce=(e,t)=>{for(var n in t)D(e,n,{get:t[n],enumerable:!0})},ue=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of ie(t))!oe.call(e,a)&&a!==n&&D(e,a,{get:()=>t[a],enumerable:!(r=re(t,a))||r.enumerable});return e},se=e=>ue(D({},"__esModule",{value:!0}),e),b={};ce(b,{Hooks:()=>I});S.exports=se(b);var I=(e=>(e.INIT="INIT",e.EXECUTION_PRE="EXECUTION_PRE",e.EXECUTION_POST="EXECUTION_POST",e.DATACACHE_RECORD_ADD_PRE="DATACACHE_RECORD_ADD_PRE",e.DATACACHE_RECORD_ADD_POST="DATACACHE_RECORD_ADD_POST",e.DATACACHE_RECORD_DELETE_PRE="DATACACHE_RECORD_DELETE_PRE",e.DATACACHE_RECORD_DELETE_POST="DATACACHE_RECORD_DELETE_POST",e.CACHE_HIT="CACHE_HIT",e))(I||{})});var Oe={};q(Oe,{CacheCandidate:()=>Ae,CacheCandidateOptionsDefault:()=>T,DataCacheRecordNotFound:()=>h,Events:()=>p,RunningQueryRecordNotFound:()=>g,cacheCandidate:()=>Re});module.exports=J(Oe);var P=(e=new Map)=>({get:async t=>e.get(JSON.stringify(t)),has:async t=>e.has(JSON.stringify(t)),set:async(t,n)=>e.set(JSON.stringify(t),n),delete:async t=>e.delete(JSON.stringify(t))});var T={ttl:6e5,timeFrame:3e4,requestsThreshold:3,cache:P(),keepAlive:!1,plugins:[],events:{onCacheHit:e=>e,onCacheSet:e=>e,onCacheDelete:e=>e,onBeforeFunctionExecution:e=>e,onAfterFunctionExecution:e=>e,onLog:e=>e}};var p=(a=>(a.RUNNING_QUERY="RUNNING_QUERY",a.CHECKING_CANDIDATE_FUNCTION="CHECKING_CANDIDATE_FUNCTION",a.CHECKING_MILLISECOND_THRESHOLD="CHECKING_MILLISECOND_THRESHOLD",a.CHECKING_REQUESTS_THRESHOLD="CHECKING_REQUESTS_THRESHOLD",a))(p||{}),h=Symbol("DataCacheRecordNotFound"),g=Symbol("RunningQueryRecordNotFound");var M=require("crypto");var ne=H(F());async function C(e,t=[],n){for(let r of t){let a=r.hooks.filter(o=>o.hook===e);if(a.length>1)throw new Error(`Only one hook instance per plugin is allowed. ${r.name} has ${a.length} instances of ${e}}`);if(a.length===0)continue;let i=a[0];if(ae(i))await i.action(n,r.additionalParameters);else throw new Error(`Hook ${e} for plugin ${r.name} is not actionable.`)}}function ae(e){return[e.action!==void 0,typeof e.action=="function"].every(t=>t===!0)}var l=H(w());function de(e,t){return Date.now()<e+t.timeFrame}function Ce({key:e,timeframeCache:t,executionTime:n,executionEnd:r}){t.has(e)?t.get(e).push({executionTime:n,executionEnd:r}):t.set(e,[{executionEnd:r,executionTime:n}])}function le({options:e,key:t,timeframeCache:n}){if(n.has(t)){let r=n.get(t),a=r.filter(({executionEnd:i})=>de(i,e));r.length!==a.length&&n.set(t,a)}}function me({options:e,key:t,runningQueryCache:n}){return n.has(t)?(e.events.onLog({key:t,event:"RUNNING_QUERY"}),n.get(t)):g}function A(...e){return(0,M.createHash)("sha256").update(e.join("|")).digest("hex")}function he({birthTime:e,options:t}){return Date.now()-e>=t.timeFrame}async function fe({options:e,key:t,HookPayload:n}){if(await e.cache.has(t)){let{result:r,birthTime:a}=await e.cache.get(t);return he({birthTime:a,options:e})?(await k({options:e,key:t,HookPayload:n}),h):r}return h}async function ge({options:e,key:t,result:n}){return e.cache.set(t,{result:n,birthTime:Date.now()},e.ttl)}async function k({options:e,key:t,HookPayload:n}){await C(l.Hooks.DATACACHE_RECORD_DELETE_PRE,e.plugins,n),await e.cache.delete(t),await C(l.Hooks.DATACACHE_RECORD_DELETE_POST,e.plugins,n),e.events.onCacheDelete({key:t})}async function L({result:e,runningQueryCache:t,key:n,executionStart:r,options:a,timeframeCache:i,timeFrameTimeoutCache:o,args:c,HookPayload:u}){let s=Date.now(),m=s-r;a.events.onAfterFunctionExecution({key:n,executionTime:m}),Ce({key:n,timeframeCache:i,executionTime:m,executionEnd:s}),Ee({options:a,key:n,timeframeCache:i,executionTime:m,args:c})>=a.requestsThreshold&&(await C(l.Hooks.DATACACHE_RECORD_ADD_PRE,a.plugins,u),ge({options:a,key:n,result:e}).then(async()=>{await C(l.Hooks.DATACACHE_RECORD_ADD_POST,a.plugins,{...u,result:e}),a.events.onCacheSet({key:n})}).finally(()=>{t.delete(n),o.set(n,setTimeout(()=>{k({options:a,key:n,HookPayload:u})},a.ttl).unref())}))}function Ee({options:e,key:t,timeframeCache:n,executionTime:r,args:a}){let i=0,o=n.get(t);return e.candidateFunction?(e.events.onLog({key:t,event:"CHECKING_CANDIDATE_FUNCTION"}),i=pe(e,r,a,o)):e.millisecondThreshold?(e.events.onLog({key:t,event:"CHECKING_MILLISECOND_THRESHOLD"}),i=Te(r,e,o)):(e.events.onLog({key:t,event:"CHECKING_REQUESTS_THRESHOLD"}),i=o.length),i}function Te(e,t,n){let r=0;return e>t.millisecondThreshold&&(r=n.filter(a=>a.executionTime>t.millisecondThreshold).length),r}function pe(e,t,n,r){let a=0;return e.candidateFunction({timeFrameCacheRecords:r,options:e,args:n})&&(a=e.requestsThreshold),a}function ye({timeFrameTimeoutCache:e,key:t,options:n}){clearTimeout(e.get(t)),e.set(t,setTimeout(()=>{n.cache.delete(t)},n.ttl).unref())}function De(e=10){return Math.random().toString(36).substring(2,e+2)}async function R({options:e,key:t,timeFrameTimeoutCache:n,runningQueryCache:r,timeframeCache:a,args:i,originalMethod:o}){let c={options:{...e,plugins:void 0},key:t,timeFrameTimeoutCache:n,runningQueryCache:r,timeframeCache:a,fnArgs:i};await C(l.Hooks.INIT,e.plugins,c);let u=await fe({options:e,key:t,HookPayload:c});if(u!==h)return e.keepAlive&&ye({timeFrameTimeoutCache:n,key:t,options:e}),await C(l.Hooks.CACHE_HIT,e.plugins,{...c,result:u}),e.events.onCacheHit({key:t}),Promise.resolve(u);let s=me({options:e,key:t,runningQueryCache:r});if(s!==g)return await C(l.Hooks.CACHE_HIT,e.plugins,{...c,result:s}),e.events.onCacheHit({key:t}),s;le({options:e,key:t,timeframeCache:a}),await C(l.Hooks.EXECUTION_PRE,e.plugins,c),e.events.onBeforeFunctionExecution({key:t});let m=Date.now(),d=o(...i);return await C(l.Hooks.EXECUTION_POST,e.plugins,{...c,result:d}),d instanceof Promise?(r.set(t,d),d.then(E=>L({result:E,runningQueryCache:r,key:t,executionStart:m,options:e,timeframeCache:a,timeFrameTimeoutCache:n,args:i,HookPayload:c})),d):(L({result:d,runningQueryCache:r,key:t,executionStart:m,options:e,timeframeCache:a,timeFrameTimeoutCache:n,args:i,HookPayload:c}),d)}function O(e){let t=new Map,n=new Map,r=De(),a=new Map,i={...T,...e};return{timeframeCache:t,runningQueryCache:n,uniqueIdentifier:r,timeFrameTimeoutCache:a,options:i}}function Ae(e={}){let{timeframeCache:t,runningQueryCache:n,uniqueIdentifier:r,timeFrameTimeoutCache:a,options:i}=O(e);return function(o,c,u){let s=u.value;u.value=async function(...m){let d=o.constructor.name+JSON.stringify(this),E=A([o.constructor.name,c,r,d,JSON.stringify(m)]);return R({options:i,key:E,timeFrameTimeoutCache:a,runningQueryCache:n,timeframeCache:t,args:m,originalMethod:s})}}}function Re(e,t={}){let{timeframeCache:n,runningQueryCache:r,uniqueIdentifier:a,timeFrameTimeoutCache:i,options:o}=O(t);return async(...c)=>R({options:o,key:A([a,JSON.stringify(c)]),timeFrameTimeoutCache:i,runningQueryCache:r,timeframeCache:n,args:c,originalMethod:e})}0&&(module.exports={CacheCandidate,CacheCandidateOptionsDefault,DataCacheRecordNotFound,Events,RunningQueryRecordNotFound,cacheCandidate});

package/dist/internal.d.ts

@@ -0,0 +1,19 @@
+import { CacheCandidateOptions, TimeFrameTimeoutCache, RunningQueryCache, TimeFrameCache } from './models';
+export declare function getDataCacheKey(...args: any[]): string;
+export declare function uniqid(length?: number): string;
+export declare function letsCandidate({ options, key, timeFrameTimeoutCache, runningQueryCache, timeframeCache, args, originalMethod }: {
+    options: CacheCandidateOptions;
+    key: string;
+    timeFrameTimeoutCache: TimeFrameTimeoutCache;
+    runningQueryCache: RunningQueryCache;
+    timeframeCache: TimeFrameCache;
+    args: any[];
+    originalMethod: (...args: any[]) => Promise<unknown>;
+}): Promise<unknown>;
+export declare function getInitialState(_options: Partial<CacheCandidateOptions>): {
+    timeframeCache: TimeFrameCache;
+    runningQueryCache: RunningQueryCache;
+    uniqueIdentifier: string;
+    timeFrameTimeoutCache: TimeFrameTimeoutCache;
+    options: CacheCandidateOptions;
+};

package/dist/lib.d.ts

@@ -0,0 +1,3 @@
+import { CacheCandidateOptions } from './models';
+export declare function CacheCandidate(_options?: Partial<CacheCandidateOptions>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function cacheCandidate(fn: (...args: any[]) => any, _options?: Partial<CacheCandidateOptions>): (...args: any[]) => Promise<unknown>;

package/dist/models.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="node" />
+import { CacheCandidatePluginWithAdditionalParameters } from '@jointly/cache-candidate-plugin-base';
+export interface CandidateFunctionOptions {
+    timeFrameCacheRecords: Array<TimeFrameCacheRecord>;
+    options: CacheCandidateOptions;
+    args: any;
+}
+export interface CacheCandidateCacheAdapter {
+    get: (key: string) => Promise<DataCacheRecord | undefined>;
+    set: (key: string, value: any, ttl: number) => Promise<any>;
+    has: (key: string) => Promise<boolean>;
+    delete: (key: string) => Promise<boolean>;
+}
+export interface CacheCandidateOptions {
+    ttl: number;
+    timeFrame: number;
+    candidateFunction?: (CandidateFunctionOptions: any) => boolean;
+    millisecondThreshold?: number;
+    requestsThreshold: number;
+    keepAlive: boolean;
+    cache: CacheCandidateCacheAdapter;
+    events: {
+        onCacheHit: ({ key }: {
+            key: string;
+        }) => void;
+        onCacheSet: ({ key }: {
+            key: string;
+        }) => void;
+        onCacheDelete: ({ key }: {
+            key: string;
+        }) => void;
+        onBeforeFunctionExecution: ({ key }: {
+            key: string;
+        }) => void;
+        onAfterFunctionExecution: ({ key, executionTime }: {
+            key: string;
+            executionTime: number;
+        }) => void;
+        onLog: ({ key, event }: {
+            key: string;
+            event: Events;
+        }) => void;
+    };
+    plugins?: Array<CacheCandidatePluginWithAdditionalParameters>;
+}
+export interface DataCacheRecord {
+    result: any;
+    birthTime: number;
+}
+export interface TimeFrameCacheRecord {
+    executionTime: number;
+    executionEnd: Date;
+}
+export type TimeFrameCache = Map<string, Array<TimeFrameCacheRecord>>;
+export type RunningQueryCache = Map<string, Promise<any>>;
+export type TimeFrameTimeoutCache = Map<string, NodeJS.Timeout>;
+export declare enum Events {
+    RUNNING_QUERY = "RUNNING_QUERY",
+    CHECKING_CANDIDATE_FUNCTION = "CHECKING_CANDIDATE_FUNCTION",
+    CHECKING_MILLISECOND_THRESHOLD = "CHECKING_MILLISECOND_THRESHOLD",
+    CHECKING_REQUESTS_THRESHOLD = "CHECKING_REQUESTS_THRESHOLD"
+}
+export declare const DataCacheRecordNotFound: unique symbol;
+export declare const RunningQueryRecordNotFound: unique symbol;

package/dist/plugins/index.d.ts

@@ -0,0 +1,3 @@
+import { CacheCandidatePluginWithAdditionalParameters, Hooks, PluginPayload } from '@jointly/cache-candidate-plugin-base';
+export declare function ExecuteHook(hook: Hooks, plugins: CacheCandidatePluginWithAdditionalParameters[] | undefined, payload: PluginPayload): Promise<void>;
+export declare function pluginHookWrap(HookBefore: Hooks, HookAfter: Hooks, payload: PluginPayload): (fn: (...args: any[]) => unknown) => (...args: any[]) => unknown;

package/dist/test/MockClass.d.ts

@@ -0,0 +1,9 @@
+export declare class MockClass {
+    a: number;
+    b: number;
+    aAsync: number;
+    bAsync: number;
+    constructor(a: number, b: number, aAsync: number, bAsync: number);
+    mockAsyncFunction(step: number): Promise<number>;
+    mockFunction(step: number): number;
+}

package/dist/test/MockClass2.d.ts

@@ -0,0 +1,8 @@
+export declare class MockClass {
+    a: number;
+    b: number;
+    aAsync: number;
+    bAsync: number;
+    constructor(a: number, b: number, aAsync: number, bAsync: number);
+    mockFunction(step: number): number;
+}

package/dist/test/options.d.ts

@@ -0,0 +1,9 @@
+import { CacheCandidateOptions } from '../models';
+export declare const sleep: (ms: number) => Promise<unknown>;
+export declare const TTL = 100;
+export declare const EXECUTION_MARGIN = 50;
+export declare const ENOUGH_TIME = 250;
+export declare function step(): () => number;
+export declare const eventHits: Map<string, number>;
+export declare const options: Partial<CacheCandidateOptions>;
+export declare function flushMaps(): void;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jointly/cache-candidate",
+  "private": false,
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "ts-types": "tsc --emitDeclarationOnly --outDir dist",
+    "check": "npm run prettier && npm run lint && npm test",
+    "build": "npm run check && rimraf dist && NODE_ENV=production node esbuild.js && npm run ts-types",
+    "build-doctor-bubbleproof": "rimraf dist && NODE_ENV=development node esbuild.js && npx clinic bubbleproof -- node ./doctor-patient.js",
+    "prettier": "prettier --write ./src",
+    "lint": "eslint ./src --ext .ts",
+    "dev": "jest --watch",
+    "test": "jest --no-cache",
+    "coverage": "jest --coverage",
+    "release:common": "npm run build && git push --follow-tags origin main && npm publish --access public",
+    "release:patch": "changelog -p && git add CHANGELOG.md && git commit -m 'docs: updated changelog' && npm version patch && npm run release:common",
+    "release:minor": "changelog -m && git add CHANGELOG.md && git commit -m 'docs: updated changelog' && npm version minor && npm run release:common",
+    "release:major": "changelog -M && git add CHANGELOG.md && git commit -m 'docs: updated changelog' && npm version major && npm run release:common"
+  },
+  "prepare": "npm run build",
+  "devDependencies": {
+    "@commitlint/cli": "^17.3.0",
+    "@commitlint/config-conventional": "^17.3.0",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^18.11.12",
+    "@types/redis": "^4.0.11",
+    "@typescript-eslint/eslint-plugin": "^5.46.0",
+    "@typescript-eslint/parser": "^5.46.0",
+    "esbuild": "^0.16.4",
+    "eslint": "^8.29.0",
+    "generate-changelog": "^1.8.0",
+    "husky": "^8.0.2",
+    "jest": "^29.3.1",
+    "lint-staged": "^13.1.0",
+    "prettier": "^2.8.1",
+    "rimraf": "^3.0.2",
+    "ts-jest": "^29.0.3",
+    "typescript": "^4.9.4",
+    "@jointly/cache-candidate-plugin-base": "^1.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.{js,jsx,ts,tsx}": [
+      "npx prettier --write",
+      "npx eslint --fix"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/JointlyTech/cache-candidate.git"
+  },
+  "license": "MIT",
+  "author": "Jointly <dev@jointly.pro>",
+  "dependencies": {
+    "hook-fn": "^1.0.3"
+  }
+}