@edirect/rate-limit-module 2.0.10 → 11.0.41

package/README.md

@@ -1,15 +1,9 @@
 # 📈 Rate Limiting Module
 
-  
-
 This module provides a flexible **rate-limiting system** where access to operations can be restricted based on dynamic **rule expressions** such as `count_quote( ) > 1`. If the condition evaluates to `true`, access is **blocked**.
 
-  
-
 ## ✨ Features
 
-  
-
 - Define rate-limiting rules with custom expressions.
 
 - Dynamically inject context-aware functions for rule evaluation.
@@ -18,71 +12,44 @@ This module provides a flexible **rate-limiting system** where access to operati
 
 - Built with extensibility and modularity in mind.
 
-  
-
 ## 🧱 How It Works
 
-  
-
 1. You define a rule using a simple expression (e.g., `count_quote( ) > 1`).
 
 2. The rule is evaluated in runtime using data injected from the request context.
 
 3. If the expression is true, the action is blocked.
 
-  
-
 ## 🧩 Usage
 
-  
-
 ### 1. Install the Module
 
-  
-
 ```ts
-
 @Module({
+  imports: [
+    RateLimitingModule,
 
-imports: [
-
-RateLimitingModule,
-
-RuleEngineModule.forFeatureAsync({
-
-useFactory: async (quoteService:  QuoteService) => {
-
-return  await quoteService.countQuote();
-
-},
-
-inject: [QuoteService],
-
-}),
-
-],
+    RuleEngineModule.forFeatureAsync({
+      useFactory: async (quoteService: QuoteService) => {
+        return await quoteService.countQuote();
+      },
 
+      inject: [QuoteService],
+    }),
+  ],
 })
-
-export  class  YourFeatureModule {}
-
+export class YourFeatureModule {}
 ```
 
-  
-
 ## 2. Decorate Your Handlers
 
-  
-
 Use the `@RateLimitingRuleMetadata` decorator to attach metadata used during rule evaluation.
 
-  
-
 ```ts
 
 import { RateLimitingRuleMetadata } from  'path-to-rate-limiting-module';
 
-  
+
 
 @RateLimitingRuleMetadata({
 
@@ -108,82 +75,57 @@ return  this.quoteService.create(body);
 
 ```
 
-  
+- `action`: Name of the action to be controlled.
 
-*  `action`: Name of the action to be controlled.
+- `partnerPath`: Path to extract the partner ID from the request context.
 
-*  `partnerPath`: Path to extract the partner ID from the request context.
+- `providerPath`: Path to extract the provider.
 
-*  `providerPath`: Path to extract the provider.
-
-*  `productTypePath`: Path to extract the product type.
-
-  
+- `productTypePath`: Path to extract the product type.
 
 ## 🛠 Rule Engine Integration
 
-  
-
 This module depends on an underlying rule engine to evaluate expressions. You must provide the functions used in expressions through:
 
-  
-
 ```ts
-
 RuleEngineModule.forFeatureAsync({
+  useFactory: async (useCase: RateLimitingInjectFunctionsUseCase) => {
+    return await useCase.getFunctions();
 
-useFactory: async (useCase:  RateLimitingInjectFunctionsUseCase) => {
-
-return  await useCase.getFunctions();
-
-// returns an object like { count_quote: async () => number }
-
-},
-
-inject: [RateLimitingInjectFunctionsUseCase],
+    // returns an object like { count_quote: async () => number }
+  },
 
+  inject: [RateLimitingInjectFunctionsUseCase],
 });
-
 ```
 
-  
-
 ## 🧪 Example Rule
 
-  
 A rule stored in your system might look like:
 
-
 ```json
-
 {
-	"expression": "count_quote() > 1",
-	"action": "create_quote"
+  "expression": "count_quote() > 1",
+  "action": "create_quote"
 }
-
 ```
 
-  
-
 If the expression returns `true`, the rate limiter will block further `create_quote` actions for the user based on the context values.
 
-  
 ## 🧠 Dynamic Parameter Resolution
 
 When building queries based on request context, it's possible to reference nested values using paths. This system supports:
 
--   Resolving values using variable placeholders like `:applicant.documents[0].value`.
-    
--   Interpreting date expressions safely, like `date(-5d)` (5 days ago), without using `eval`.
+- Resolving values using variable placeholders like `:applicant.documents[0].value`.
+- Interpreting date expressions safely, like `date(-5d)` (5 days ago), without using `eval`.
 
 ### Supported Syntax
-```json
 
+```json
 {
   "value": ":applicant.documents[0].value",
   "label": "applicant.documents.value"
 }
-
 ```
 
 Will extract the value from the context:
@@ -191,14 +133,12 @@ Will extract the value from the context:
 ```json
 {
   "applicant": {
-    "documents": [
-      { "type": "NIF", "value": "ABCDE" }
-    ]
+    "documents": [{ "type": "NIF", "value": "ABCDE" }]
   }
 }
 ```
-Result: `"ABCDE"`
 
+Result: `"ABCDE"`
 
 You can also use dynamic dates:
 
@@ -214,19 +154,15 @@ Result: `"2025-07-10T00:00:00.000Z"` (7 days ago)
 
 ### Supported Date Units
 
--   `d`: Days (default)
-    
--   `M`: Months
-    
--   `y`: Years
+- `d`: Days (default)
+- `M`: Months
+- `y`: Years
 
 Examples:
 
--   `date(-5d)` → 5 days ago
-    
--   `date(-1M)` → 1 month ago
-    
--   `date(0)` → Today
+- `date(-5d)` → 5 days ago
+- `date(-1M)` → 1 month ago
+- `date(0)` → Today
 
 No dynamic code execution (`eval`, `new Function`) is used — expressions are parsed securely.
 
@@ -243,6 +179,7 @@ You can optionally define an `op` (operation) field to specify how the value sho
   "op": "gte"
 }
 ```
+
 🔍 This means: only include records created after **7 days ago**.
 
 ```json
@@ -255,6 +192,7 @@ You can optionally define an `op` (operation) field to specify how the value sho
   "op": "range"
 }
 ```
+
 🔍 This sets a static date or value range. Can be used for numbers, dates, or custom fields.
 
 ### `rangeDate` — Dynamic Date Range
@@ -269,8 +207,8 @@ You can optionally define an `op` (operation) field to specify how the value sho
   "op": "rangeDate"
 }
 ```
-🔍 This automatically resolves both `from` and `to` values as dates. For example, this would generate a date range from **30 days ago** to **now**.
 
+🔍 This automatically resolves both `from` and `to` values as dates. For example, this would generate a date range from **30 days ago** to **now**.
 
 ## 🧬 DSL Support and MongoDB Integration
 
@@ -292,6 +230,7 @@ These DSL expressions are **not executed as raw code**, but safely parsed and ev
 One powerful feature of this module is the ability to **transform DSL filters into MongoDB-compatible query objects**.
 
 For example, the following DSL input:
+
 ```json
 {
   createdAt: {
@@ -300,17 +239,15 @@ For example, the following DSL input:
   }
 }
 ```
+
 This is handled by utility functions like `buildDlsOp`, which map DSL constructs to database query.
 
 ### ✅ Benefits of Using DSL
 
--   **Separation of logic from code:** Business rules can be stored in DB or configs
-    
--   **Extensibility:** Easy to support new operators or DB backends (e.g., SQL, Elasticsearch)
-    
--   **Security:** No raw `eval` or dynamic JS execution
-    
--   **Readability:** DSL is expressive for non-technical stakeholders
+- **Separation of logic from code:** Business rules can be stored in DB or configs
+- **Extensibility:** Easy to support new operators or DB backends (e.g., SQL, Elasticsearch)
+- **Security:** No raw `eval` or dynamic JS execution
+- **Readability:** DSL is expressive for non-technical stakeholders
 
 By combining DSL definitions with path-based context extraction and safe runtime resolution, this module provides a highly flexible and secure rate-limiting engine ready for dynamic environments.
 
@@ -398,32 +335,27 @@ Optional. Defines the operator (`eq`, `range`, `rangeDate`, `gte`, etc.)
 
 Fallback value(s) to be used if dynamic resolution fails (e.g., missing path or function)
 
-----------
+---
 
 ### 🧠 Special Value Formats
 
--   `:path.to.value` — Dynamically extracted from the context object
-    
--   `date(-7d)` — Resolved as a safe date expression
-    
--   `fn:getValueFromSale` — Calls a predefined function to resolve the value dynamically
-    
--   Static values like `"moneyhero"` are passed as-is
-    
-    ### 🧪 Use Case Example
+- `:path.to.value` — Dynamically extracted from the context object
+- `date(-7d)` — Resolved as a safe date expression
+- `fn:getValueFromSale` — Calls a predefined function to resolve the value dynamically
+- Static values like `"moneyhero"` are passed as-is
+
+  ### 🧪 Use Case Example
 
 Imagine your service defines a method like:
 
-    
     async countQuoteByParams(filters: Record<string, any>): Promise<number>
 
 At runtime, the module will:
 
 1.  Resolve each `value` in the `query` array using context and supported expressions.
-    
 2.  Construct a query object:
 
-```json 
+```json
 {
   partner: { partnerId: "bolttech" },
   productType: "car-insurance",
@@ -439,9 +371,10 @@ At runtime, the module will:
 ```
 
 3.  Inject this into `countQuoteByParams(...)`
-This approach gives you a highly flexible, configurable system for controlling dynamic function parameters via context-based DSLs and runtime evaluation.
+    This approach gives you a highly flexible, configurable system for controlling dynamic function parameters via context-based DSLs and runtime evaluation.
+
+---
 
-----------
 ## 🧠 Custom Runtime Functions with `variables.functions`
 
 In addition to defining query parameters in `variables.queries`, the system also supports **custom runtime functions** through the `variables.functions` array.
@@ -454,11 +387,11 @@ These functions can be executed **before query construction** to compute values
 
 Each function definition includes:
 
-| Field      | Description                                                                 |
-|------------|-----------------------------------------------------------------------------|
-| `name`     | Unique function identifier                                                  |
-| `fn`       | The function to execute, in the format `functionName(args...)`             |
-| `variables`| Parameters passed to the function, which can include subqueries and values |
+| Field       | Description                                                                |
+| ----------- | -------------------------------------------------------------------------- |
+| `name`      | Unique function identifier                                                 |
+| `fn`        | The function to execute, in the format `functionName(args...)`             |
+| `variables` | Parameters passed to the function, which can include subqueries and values |
 
 ### 📌 Example
 
@@ -494,6 +427,7 @@ Each function definition includes:
   ]
 }
 ```
+
 ### 🔄 Using the Function Output in Queries
 
 To use the result of a function, reference it in a `query.value` using the syntax: `fn:functionName`.
@@ -504,80 +438,62 @@ CopyEdit
 
 ```json
 {
-   "label":"createdAt",
-   "op":"range",
-   "value":{
-      "from":"fn:getValueFromSale",
-      "to":"date(0)"
-   },
-   "defaultValue":{
-      "from":"date(-5d)",
-      "to":"date(0)"
-   }
+  "label": "createdAt",
+  "op": "range",
+  "value": {
+    "from": "fn:getValueFromSale",
+    "to": "date(0)"
+  },
+  "defaultValue": {
+    "from": "date(-5d)",
+    "to": "date(0)"
+  }
 }
-``` 
+```
 
 🔍 In this case, `getValueFromSale(...)` will run **before** the query is constructed, and the result will be injected into the `from` field.
 
-----------
+---
 
 ### 🧩 How It Works
 
 1.  The engine scans all `functions` in `variables.functions`.
-    
 2.  For each `query` entry in `variables.queries`, if `value` (or `from`, `to`) starts with `fn:`, it:
-    
-    -   Finds the corresponding `function` by name
-        
-    -   Resolves its `variables` (supporting nested `:context.paths`)
-        
-    -   Executes the declared function like `getValueFromSale(queries, target)`
-        
+    - Finds the corresponding `function` by name
+    - Resolves its `variables` (supporting nested `:context.paths`)
+    - Executes the declared function like `getValueFromSale(queries, target)`
+
 3.  The return value of the function replaces the `fn:` reference.
-    
 
-----------
+---
 
 ### ✅ Benefits
 
--   Enables **pre-processing logic** in a declarative way
-    
--   Keeps rule/query definitions **clean and context-aware**
-    
--   Promotes **reuse** of custom logic across different rules or queries
-    
--   Provides **defaultValue** fallback in case of failure
-    
+- Enables **pre-processing logic** in a declarative way
+- Keeps rule/query definitions **clean and context-aware**
+- Promotes **reuse** of custom logic across different rules or queries
+- Provides **defaultValue** fallback in case of failure
 
-----------
+---
 
 > 💡 Tip: Functions must be registered and resolvable at runtime by your system. The evaluation engine must be able to map the function name (`getValueFromSale`) to a real implementation.
 
-
-
 ## 🧰 Requirements
 
-  
-* NestJS
-
-* RuleEngineModule (compatible expression parser/executor)
+- NestJS
 
-* Custom service to inject context functions (like `RateLimitingInjectFunctionsUseCase`)
+- RuleEngineModule (compatible expression parser/executor)
 
+- Custom service to inject context functions (like `RateLimitingInjectFunctionsUseCase`)
 
 ## 📎 Notes
-  
 
-* Rules should be defined and stored externally (e.g., DB, config).
+- Rules should be defined and stored externally (e.g., DB, config).
 
-* The context extractor paths must match the structure of your handler inputs (e.g., body, params).
+- The context extractor paths must match the structure of your handler inputs (e.g., body, params).
 
-* Ensure `getFunctions()` returns **async functions** that provide the required values for the expression.
-
-  
+- Ensure `getFunctions()` returns **async functions** that provide the required values for the expression.
 
 ## 🧾 License
 
-  
-
-MIT
+MIT