@jointly/cache-candidate 1.0.2 → 1.1.0

package/README.md

@@ -1,39 +1,36 @@
 # 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.
+This is a library providing both a higher-order function and a decorator to cache the result of a function/method if given conditions are met.
 
 # Examples
 
-## Use-case #1: Generic example
+## Use-case #1: DB query
 
-```ts
+In this scenario, we want to cache the result of the function if the same parameters are passed 3 times in the last 30 seconds, but we want to keep the cache record for 60 seconds.
+
+```js
 import { cacheCandidate } from '@jointly/cache-candidate';
 
-let counter = 0;
-// The function to be cached. In the example, it's a simple function that returns a Promise fulfilled with the sum of the current counter and the passed step.
-const mockFn = (step: number) =>
-  new Promise((resolve) => {
-    counter += step;
-    resolve(counter);
-  });
-
-// The wrapped function. The options are the default ones.
-const wrappedMockFn = cacheCandidate(mockFn, {
-  requestsThreshold: 1,
-  ttl: 800,
+function getUsers(filters = {}) {
+  return db.query('SELECT * FROM users WHERE ?', filters);
+}
+
+const cachedGetUsers = cacheCandidate(getUsers, {
+  requestsThreshold: 3,
+  ttl: 60000,
+  timeFrame: 30000
 });
 
-let result: unknown;
-result = await wrappedMockFn(1);
-await sleep(EXECUTION_MARGIN); // Simulating a delay to allow the event loop to run
-expect(result).toBe(1);
-result = await wrappedMockFn(1);
-await sleep(EXECUTION_MARGIN);
-expect(result).toBe(1);
+await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3 in the last 30 seconds
+await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3 in the last 30 seconds
+await cachedGetUsers({ name: 'John' }); // <-- This WILL be cached, because the requestsThreshold is 3 in the last 30 seconds!
+await cachedGetUsers({ name: 'Jack' }); // <-- This won't be cached, because parameters are different
+await sleep(60000); // <-- This will flush the cache because of the ttl
+await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3 in the last 30 seconds
 ```
+## Use-case #2: DB query - Different timeFrame
 
-## Use-case #2: DB query
-
+In this scenario, we want to cache the result of the function if the same parameters are passed 3 times in the last 45 seconds, but we want to keep the cache record for 30 seconds. This example could reflect a scenario in which you are paying for the cache storage, yet you want to cache the same result again if the same parameters are passed 3 times in a short period of time.
 ```js
 import { cacheCandidate } from '@jointly/cache-candidate';
 
@@ -44,14 +41,37 @@ function getUsers(filters = {}) {
 const cachedGetUsers = cacheCandidate(getUsers, {
   requestsThreshold: 3,
   ttl: 30000,
+  timeFrame: 45000 // <-- Notice the different timeFrame, higher than cache ttl
 });
 
-await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3
-await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3
-await cachedGetUsers({ name: 'John' }); // <-- This will be cached, because the requestsThreshold is 3!
+await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3 in the last 45 seconds
+await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3 in the last 45 seconds
+await cachedGetUsers({ name: 'John' }); // <-- This WILL be cached, because the requestsThreshold is 3 in the last 45 seconds!
 await cachedGetUsers({ name: 'Jack' }); // <-- This won't be cached, because parameters are different
+await sleep(30000); // <-- This will flush the cache because of the ttl
+await cachedGetUsers({ name: 'John' }); // <-- This WILL be cached, because the requestsThreshold is 3 in the last 45 seconds!
+```
+
+## Use-case #3: Advanced Usage - Candidate Function
+
+You can also pass a candidate function to check if the conditions are met.
+
+```js
+import { cacheCandidate } from '@jointly/cache-candidate';
+
+function getUsers(filters = {}) {
+  return db.query('SELECT * FROM users WHERE ?', filters);
+}
+
+const cachedGetUsers = cacheCandidate(getUsers, {
+  ttl: 30000,
+  candidateFunction: ({ timeFrameCacheRecords, options, args }) => args[0].name === 'John',
+});
+
+await cachedGetUsers({ name: 'John' }); // <-- This will be cached, because the candidateFunction returns true
+await cachedGetUsers({ name: 'John' }); // <-- This will return the cached value
+await cachedGetUsers({ name: 'Jack' }); // <-- This won't be cached, because the candidateFunction returns false
 await sleep(30000); // <-- This will invalidate the cache because of the ttl
-await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3
 ```
 
 # How does it work?
@@ -59,25 +79,35 @@ await cachedGetUsers({ name: 'John' }); // <-- This won't be cached, because the
 ## Higher-order function
 
 The library exposes the `cacheCandidate` function which accepts the function to be cached as the first argument and the options as the second argument.  
-The returned function is an async function which returns a Promise fulfilled with the cached value if the method has already been called with the same arguments and the conditions are met.  
-The options available are:
+The returned function is an async function which returns a Promise fulfilled with the cached value if the method has already been called with the same arguments and/or the conditions are met.  
 
+The options available are:
 - `ttl` (_optional_): The time to live of the cache record in milliseconds. Default: `600000` (10 minutes).
-- `timeFrame` (_optional_): The timeframe considered for the condition checks. Default: `30000` (30 seconds).
-- `candidateFunction` (_optional_): The function to be called to check if the conditions are met. If not passed, this criteria will be ignored.
+- `timeFrame` (_optional_): The timeframe considered for the condition checks. Default: `30000` (30 seconds).  
+  Consider the timeFrame as `the execution history of the last X milliseconds`. This timeframe collects information about the function's execution time. 
+  For example, if you set the timeFrame to 30000 (30 seconds), the library will check the execution history of the last 30 seconds.  
+  This means that if you set the `requestsThreshold` (explained below) to 3, the function will be cached only if the same parameters are passed 3 times in the last 30 seconds.
+- `candidateFunction` (_optional_): The function to be called to check if the conditions are met. If not passed, this criteria will be ignored.  
+  The candidateFunction receives an object with the following properties:
+  - `options`: The options passed to the `cacheCandidate` function.
+  - `executionTime`: The execution time of the current function execution in milliseconds.
+  - `args`: The arguments passed to the current function.
+  - `timeFrameCacheRecords`: The cache records of the last `timeFrame` milliseconds.
 - `millisecondThreshold` (_optional_): The threshold in milliseconds to be considered for the condition checks. If not passed, this criteria will be ignored.
 - `requestsThreshold` (_optional_): The number of requests to be considered for the condition checks. Default: `3`.
 - `keepAlive` (_optional_): If `true`, the cache record will be kept alive at every request. Default: `false`.
-- `cache` (_optional_): The cache adapter to be used. Default: `A memory cache based on Maps, but with Promises`.  
+- `cache` (_optional_): The cache adapter to be used. Defaults to `an in-memory cache based on Maps, but with Promises`.  
   Available adapters are:
-  - `makeRedisCache`: A cache adapter based on Redis. Pass a Redis client as the first argument.
-- `events` (_optional_): Listener functions to be called at specific bits of the process.  
+  - `makeRedisCache`: A cache adapter based on Redis. Receives a Redis client as the first and only argument.
+- `events` (_optional_): Listener functions to be called at specific steps of the process.  
   Available events are:
   - `onCacheHit`: Called when the cache entry is hit.
   - `onCacheSet`: Called when the cache entry is set.
   - `onCacheDelete`: Called when the cache entry is deleted.
   - `onBeforeFunctionExecution`: Called before the function execution.
   - `onAfterFunctionExecution`: Called after the function execution.
+  Every event receives an object containing the `key` property, which is the key used for the cache.  
+  The `onAfterFunctionExecution` event also receives the `executionTime` property, which is the execution time of the current function in milliseconds.
 - `plugins` (_optional_): An array of plugins to be used. Default: `[]`.  
   Please, refer to the [@jointly/cache-candidate-plugin-base](https://github.com/JointlyTech/cache-candidate-plugin-base) package for more information.
 
@@ -103,7 +133,7 @@ class MyClass {
 const myInstance = new MyClass();
 await myInstance.getUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3
 await myInstance.getUsers({ name: 'John' }); // <-- This won't be cached, because the requestsThreshold is 3
-await myInstance.getUsers({ name: 'John' }); // <-- This will be cached, because the requestsThreshold is 3!
+await myInstance.getUsers({ name: 'John' }); // <-- This WILL be cached, because the requestsThreshold is 3!
 ```
 
 ## Conditions / Criterias
@@ -111,8 +141,8 @@ The conditions are, within the given `timeFrame`:
 
 - If a `candidateFunction` is provided, it returns `true` at least once.  
   The candidateFunction ignores all the other conditions.  
-- 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.
+- If a `millisecondsThreshold` is provided, the function execution time passed such threshold at least `requestThreshold` times.
+- If only a `requestThreshold` is provided (default), the function is called at least `requestThreshold` times.
 
 # Other Info
 
@@ -121,49 +151,44 @@ The conditions are, within the given `timeFrame`:
 The library supports plugins to extend its functionality.  
 Please, refer to the [@jointly/cache-candidate-plugin-base](https://github.com/JointlyTech/cache-candidate-plugin-base) package for the documentation on how to create a plugin.  
 
-### Available plugins
+### First-party plugins
 
-- [@jointly/cache-candidate-plugin-dependency-keys](https://github.com/JointlyTech/cache-candidate-plugin-dependency-keys): Allows to define dependency keys when setting the cache record.  
-  This allows to invalidate the cache record when a dependency changes.
+- [@jointly/cache-candidate-plugin-dependency-keys](https://github.com/JointlyTech/cache-candidate-plugin-dependency-keys): A plugin allowing to define dependency keys when setting the cache record.  
+  This provides a mechanism to delete one or more cache records when a dependency key is invalidated.
 
 ## Constraints
 
-- The decorator should only be applied to methods that return a `Promise`.  
-  Please, refer to the [Considerations on synchronous methods](#considerations-on-synchronous-methods) section for more information.
-- 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.
+- The higher-order function and the decorator only work with async functions.  
+  Please, refer to the [Considerations on synchronous functions](#considerations-on-synchronous-functions) section for more information.
+- The `candidateFunction` must be synchronous. If passed an async function bypassing type checking, the candidateFunction will return a Promise thus not working properly. This choice was made to avoid the overhead and the performance burden of an async function call.
 
 ## 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.
+The library prevents the cache stampede problem by using a `Map` called `runningQueries` which saves the promise of the function call.  
+If multiple calls are made to the same function with the same arguments, the function will be called only once and the other calls will wait for the Promise to finish.  
+The `runningQueries` Map will be cleaned after the function execution is finished.  
+The `onCacheHit` event will be called also when the running query is returned.
 
 ## 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 library doesn't consider the correct execution of the given cache functions.  
+It isn't the library's responsibility to check if the cache functions 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` Promise method to delete the key from the `runningQueries` Map and set the timeout to clean the cache record.
 
-## Problems with synchronous methods
+## Problems with synchronous functions
 
-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.  
+If the given function is synchronous, the library could not work as expected.  
+The reason is that the library internally transforms the function to an asynchronous one, so executing the same function 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.
-
 ## Key composition
 
-The cache key is composed based on the following criteria, allowing multiple files to export the same class name with the same method name / the same function names without conflicts:
+The cache key is composed based on the following criteria, allowing multiple files to export the same class name with the same method name / the same function names without conflicts.
 
 ### 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.
+- `uniqueIdentifier`: A uniqid generated to allow multiple files to contain the same function name.
 
 ### Decorator
 
@@ -172,21 +197,6 @@ The cache key is composed based on the following criteria, allowing multiple fil
 - `instanceIdentifier`: A uniqid generated for each instance of the class. It uses the instance properties to generate the id. (JSON.stringify)
 - The arguments passed to the method. (JSON.stringify)
 
+# Contributing
 
-## 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.
+Please, refer to the [CONTRIBUTING.md](https://github.com/JointlyTech/cache-candidate/blob/main/CONTRIBUTING.md) file for more information.

package/dist/index.js

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

package/dist/plugins/index.d.ts

@@ -1,3 +1,7 @@
 import { CacheCandidatePluginWithAdditionalParameters, Hooks, PluginPayload } from '@jointly/cache-candidate-plugin-base';
+import { CacheCandidateOptions } from '../models';
 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;
+export declare function checkHooks({ options }: {
+    options: CacheCandidateOptions;
+}): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jointly/cache-candidate",
   "private": false,
-  "version": "1.0.2",
+  "version": "1.1.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,7 +34,8 @@
   "devDependencies": {
     "@commitlint/cli": "^17.3.0",
     "@commitlint/config-conventional": "^17.3.0",
-    "@types/jest": "^29.2.4",
+    "@jointly/cache-candidate-plugin-base": "^1.0.0",
+    "@types/jest": "^29.2.5",
     "@types/node": "^18.11.12",
     "@types/redis": "^4.0.11",
     "@typescript-eslint/eslint-plugin": "^5.46.0",
@@ -48,8 +49,7 @@
     "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"
+    "typescript": "^4.9.4"
   },
   "lint-staged": {
     "src/**/*.{js,jsx,ts,tsx}": [