@@ -26,17 +26,20 @@ interface CacheOptions {
2626}
2727
2828/**
29- * Skip single params in the following format
29+ * Iterates through the provided 'params' array and checks if any argument in 'args' at the specified 'index'
30+ * matches one of the pipe-separated values in 'value'. If a match is found, caching should be skipped.
3031 *
31- * [{
32- * index: '0',
33- * value: 'pending|safe'
34- * }]
32+ * @param args - The IArguments arguments object
33+ * @param params - An array of CacheSingleParam caching rules
34+ * @returns 'true' if any argument matches a rule and caching should be skipped; otherwise, 'false'.
3535 *
36- * @param args
37- * @param params
36+ * @example
37+ * [{
38+ * index: '0',
39+ * value: 'pending|safe'
40+ * }]
3841 */
39- const shouldSkipCachingForSingleParams = ( args : any , params : any = [ ] ) => {
42+ const shouldSkipCachingForSingleParams = ( args : IArguments , params : CacheSingleParam [ ] = [ ] ) : boolean => {
4043 for ( const item of params ) {
4144 const values = item . value . split ( '|' ) ;
4245 if ( values . indexOf ( args [ item . index ] ) > - 1 ) {
@@ -48,23 +51,29 @@ const shouldSkipCachingForSingleParams = (args: any, params: any = []) => {
4851} ;
4952
5053/**
51- * Skip named params in the following format
54+ * Determines whether caching should be skipped based on field-level conditions within specific argument objects. For each
55+ * item in 'params', the function inspects a corresponding argument at the specified 'index' in 'args'. It builds
56+ * a list of field-based skip conditions and checks if any of the fields in the input argument match any of the provided
57+ * values (supports multiple values via pipe '|' separators).
5258 *
53- * [{
54- * index: '0',
55- * fields: [{
56- * name: 'fromBlock', value: 'pending|safe'
57- * }, {
58- * name: 'toBlock', value: 'safe|finalized'
59- * }],
60- * }]
59+ * @param args - The function's arguments object (e.g., `IArguments`), where values are accessed by index.
60+ * @param params - An array of `CacheNamedParams` defining which arguments and which fields to inspect.
61+ * @returns `true` if any field value matches a skip condition; otherwise, `false`.
6162 *
62- * @param args
63- * @param params
63+ * @example
64+ * [{
65+ * index: '0',
66+ * fields: [{
67+ * name: 'fromBlock', value: 'pending|safe'
68+ * }, {
69+ * name: 'toBlock', value: 'safe|finalized'
70+ * }],
71+ * }]
6472 */
65- const shouldSkipCachingForNamedParams = ( args : any , params : any = [ ] ) => {
73+ const shouldSkipCachingForNamedParams = ( args : IArguments , params : CacheNamedParams [ ] = [ ] ) : boolean => {
6674 for ( const item of params ) {
6775 const input = args [ item . index ] ;
76+ // @ts -ignore
6877 const skipList = Object . assign ( { } , ...params . filter ( el => el . index == item . index ) [ 0 ] . fields . map ( el => {
6978 return { [ el . name ] : el . value } ;
7079 } ) ) ;
@@ -81,12 +90,21 @@ const shouldSkipCachingForNamedParams = (args: any, params: any = []) => {
8190} ;
8291
8392/**
84- * Generate cache key by method name and passed arguments
93+ * Generates a unique cache key string based on the method name and argument values. It serializes each argument (excluding
94+ * instances of `RequestDetails`) into a string format and appends them to the method name to form the final key.
8595 *
86- * @param methodName
87- * @param args
96+ * - If an argument is an object, each of its key-value pairs is added to the key.
97+ * - Primitive values are directly appended to the key.
98+ * - Arguments of type `RequestDetails` are ignored in the key generation.
99+ *
100+ * @param methodName - The name of the method being cached.
101+ * @param args - The arguments passed to the method (typically from `IArguments`).
102+ * @returns A string that uniquely identifies the method call for caching purposes.
103+ *
104+ * @example
105+ * generateCacheKey('getBlockByNumber', arguments); // should return getBlockByNumber_0x160c_false
88106 */
89- const generateCacheKey = ( methodName : string , args : any ) => {
107+ const generateCacheKey = ( methodName : string , args : IArguments ) => {
90108 let cacheKey : string = methodName ;
91109 for ( const [ , value ] of Object . entries ( args ) ) {
92110 if ( value ?. constructor ?. name != 'RequestDetails' ) {
@@ -105,24 +123,42 @@ const generateCacheKey = (methodName: string, args: any) => {
105123} ;
106124
107125/**
108- * Extract the RequestDetails field from the arguments
126+ * This utility is used to scan through the provided arguments (typically from `IArguments`)
127+ * and return the first value that is identified as an instance of `RequestDetails`.
109128 *
110- * @param args
129+ * If no such instance is found, it returns a new `RequestDetails` object with empty defaults.
130+ *
131+ * @param args - The arguments object from a function (typically `IArguments`).
132+ * @returns The first found `RequestDetails` instance, or a new one with default values if none is found.
111133 */
112- const extractRequestDetails = ( args : any ) : RequestDetails => {
113- let requestId , ipAddress , connectionId : string = '' ;
134+ const extractRequestDetails = ( args : IArguments ) : RequestDetails => {
114135 for ( const [ , value ] of Object . entries ( args ) ) {
115136 if ( value ?. constructor ?. name == 'RequestDetails' ) {
116- requestId = value [ 'requestId' ] ;
117- ipAddress = value [ 'ipAddress' ] ;
118- connectionId = value [ 'connectionId' ] ;
119- break ;
137+ // @ts -ignore
138+ return value ;
120139 }
121140 }
122141
123- return new RequestDetails ( { requestId, ipAddress, connectionId } ) ;
142+ return new RequestDetails ( { requestId : '' , ipAddress : '' } ) ;
124143} ;
125144
145+ /**
146+ * This decorator uses a `CacheService` to attempt to retrieve a cached result before executing the original method. If
147+ * no cached response exists, the method is executed and its result may be stored in the cache depending on configurable
148+ * options. Caching can be conditionally skipped based on runtime arguments via `skipParams` (for positional args)
149+ * and `skipNamedParams` (for object args).
150+ *
151+ * @param cacheService - The caching service used to store and retrieve cache entries.
152+ * @param options - Optional configuration for caching behavior.
153+ * @property skipParams - An array of rules for skipping caching based on specific argument values.
154+ * @property skipNamedParams - An array of rules for skipping caching based on fields within argument objects.
155+ * @property ttl - Optional time-to-live for the cache entry; falls back to global config if not provided.
156+ *
157+ * @returns A method decorator function that wraps the original method with caching logic.
158+ *
159+ * @example
160+ * @cache (CacheService, { skipParams: [...], skipNamesParams: [...], ttl: 300 })
161+ */
126162export function cache ( cacheService : CacheService , options : CacheOptions = { } ) {
127163 return function ( _target : any , _propertyKey : string , descriptor : PropertyDescriptor ) {
128164 const method = descriptor . value ;
0 commit comments