@edirect/rate-limit-module 11.0.62 → 11.0.63

package/dist/README.md

@@ -0,0 +1,584 @@
+# @edirect/rate-limit-module
+
+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**.
+
+## Installation
+
+```sh
+pnpm add @edirect/rate-limit-module
+# or
+npm install @edirect/rate-limit-module
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create a Global Database Connection Module
+
+**Important:** This module requires a MongoDB connection provider. Create a global module to provide it:
+
+```ts
+// db-provider.module.ts
+import { Global, Module } from '@nestjs/common';
+import { Connection } from 'mongoose';
+import { MongoDBConnection } from './mongodb-connection';
+
+export const dbProvider = [
+  {
+    provide: 'DATABASE_CONNECTION',
+    useFactory: async (): Promise<Connection> => {
+      return new MongoDBConnection().connect();
+    },
+  },
+];
+
+@Global()
+@Module({
+  providers: [...dbProvider],
+  exports: [...dbProvider],
+})
+export class DbProviderModule {}
+```
+
+### 2. Import Database Module in Root Module
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { DbProviderModule } from './db-provider.module';
+
+@Module({
+  imports: [
+    DbProviderModule, // Must be imported first
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Import RateLimitingModule in Feature Module
+
+```ts
+import {
+  RateLimitingModule,
+  RuleEngineModule,
+} from '@edirect/rate-limit-module';
+
+@Module({
+  imports: [
+    // Pass the token name of your existing MongoDB connection provider
+    // Default is 'DATABASE_CONNECTION'
+    RateLimitingModule.forRoot('DATABASE_CONNECTION'),
+
+    // Or use a custom token
+    RateLimitingModule.forRoot('MY_CUSTOM_DB_CONNECTION'),
+
+    // Or omit to use default
+    RateLimitingModule.forRoot(),
+
+    // Configure custom functions for rule evaluation
+    RuleEngineModule.forFeatureAsync({
+      imports: [YourFunctionsModule],
+      useFactory: async (useCase: YourInjectFunctionsUseCase) => {
+        return await useCase.getFunctions();
+      },
+      inject: [YourInjectFunctionsUseCase],
+    }),
+  ],
+})
+export class YourFeatureModule {}
+```
+
+### 2. Database Connection Requirement
+
+The module uses the global `DATABASE_CONNECTION` provider created in step 1. It references your connection using the token name, so it doesn't duplicate the connection.
+
+### 3. Apply Rate Limiting to Routes
+
+Use the `@RateLimitingRuleMetadata` decorator and `@UseGuards(RateLimitingRuleGuard)` to protect your endpoints:
+
+```ts
+import { RateLimitingRuleGuard, RateLimitingRuleMetadata } from '@edirect/rate-limit-module';
+
+@RateLimitingRuleMetadata({
+  action: 'create_quote',
+  partnerPath: 'partner.partnerId',
+  providerPath: 'provider',
+  productTypePath: 'productType',
+  marketPath: 'market',
+})
+@UseGuards(RateLimitingRuleGuard)
+@Post('quotes')
+createQuote(@Body() body: CreateQuoteDto) {
+  return this.quoteService.create(body);
+}
+```
+
+## ✨ Features
+
+- Define rate-limiting rules with custom expressions
+- Dynamically inject context-aware functions for rule evaluation
+- Easily integrate with any resource via decorators
+- Uses existing MongoDB connection (no separate connection required)
+- Global module - configure once, use everywhere
+- 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 at runtime using data injected from the request context
+3. If the expression is true, the action is blocked
+
+## 🛠 Architecture
+
+The module is designed to:
+
+- **Not create its own MongoDB connection** - it uses the application's existing connection
+- **Be a global module** - providers are available throughout the application
+- **Use custom model providers** - creates Mongoose models using the injected `DATABASE_CONNECTION`
+- **Export Reflector** - ensures guards have access to metadata
+
+## 📝 Configuration Details
+
+### Module Structure
+
+```ts
+RateLimitingModule.forRoot(dbProvider) // Global module, accepts DATABASE_CONNECTION provider
+  └─ RuleModule.register()           // Provides RuleService and RuleRepository
+      └─ Custom Model Provider         // Uses DATABASE_CONNECTION to create Mongoose models
+```
+
+### Required Providers
+
+The module requires:
+
+1. **DATABASE_CONNECTION**: Mongoose connection instance
+2. **Reflector**: For metadata reflection (provided by the module)
+3. **RuleService**: For accessing rate limiting rules (exported by RuleModule)
+
+````ts
+import { RateLimitingRuleMetadata } from 'path-to-rate-limiting-module';
+
+- `action`: Name of the action to be controlled.
+
+- `partnerPath`: Path to extract the partner ID from the request context.
+
+- `providerPath`: Path to extract the provider.
+
+- `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();
+
+    // 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"
+}
+```
+
+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`.
+
+### Supported Syntax
+
+```json
+{
+  "value": ":applicant.documents[0].value",
+  "label": "applicant.documents.value"
+}
+```
+
+Will extract the value from the context:
+
+```json
+{
+  "applicant": {
+    "documents": [{ "type": "NIF", "value": "ABCDE" }]
+  }
+}
+```
+
+Result: `"ABCDE"`
+
+You can also use dynamic dates:
+
+```json
+{
+  "value": "date(-7d)",
+  "label": "createdAt",
+  "op": "gte"
+}
+```
+
+Result: `"2025-07-10T00:00:00.000Z"` (7 days ago)
+
+### Supported Date Units
+
+- `d`: Days (default)
+- `M`: Months
+- `y`: Years
+
+Examples:
+
+- `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.
+
+## ⚙️ Supported Operators (`op`)
+
+You can optionally define an `op` (operation) field to specify how the value should be interpreted. The system currently supports:
+
+### `gte` — Greater Than or Equal (usually for dates)
+
+```json
+{
+  "value": "date(-7d)",
+  "label": "createdAt",
+  "op": "gte"
+}
+```
+
+🔍 This means: only include records created after **7 days ago**.
+
+```json
+{
+  "value": {
+    "from": 1,
+    "to": 10
+  },
+  "label": "createdAt",
+  "op": "range"
+}
+```
+
+🔍 This sets a static date or value range. Can be used for numbers, dates, or custom fields.
+
+### `rangeDate` — Dynamic Date Range
+
+```json
+{
+  "value": {
+    "from": "date(-30d)",
+    "to": "date(0)"
+  },
+  "label": "createdAt",
+  "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**.
+
+## 🧬 DSL Support and MongoDB Integration
+
+This module uses a lightweight **DSL (Domain-Specific Language)** to define rules and filters in a declarative and expressive way.
+
+### What is a DSL?
+
+A **DSL** is a simplified, pseudo-language designed for expressing business logic in a readable and configurable format. In this module, the DSL is used to define:
+
+- Conditional expressions (e.g., `count_quote() > 1`)
+- Filter structures using dynamic context variables and operators (`eq`, `range`, `gte`, etc.)
+
+These DSL expressions are **not executed as raw code**, but safely parsed and evaluated using resolvers and expression evaluators.
+
+---
+
+### DSL to MongoDB Filter Conversion
+
+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: {
+    $gte: new Date('2025-06-17T00:00:00.000Z'),
+    $lte: new Date('2025-07-17T00:00:00.000Z')
+  }
+}
+```
+
+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
+
+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.
+
+## 🧾 Dynamic Query Context with `variables.queries`
+
+The `variables` object is designed to allow structured dynamic query generation through an array of `queries`. Each query defines:
+
+- The **function(s)** where this context will be injected (`fnContext`)
+- The **parameters** to be resolved and passed (`query`)
+- **Optional operations** and **default values**
+
+### Structure of `variables.queries`
+
+```json
+{
+  "queries": [
+    {
+      "fnContext": ["countQuoteByParams"],
+      "query": [
+        {
+          "value": ":partner.partnerId",
+          "label": "partner.partnerId"
+        },
+        {
+          "value": ":productType",
+          "label": "productType"
+        },
+        {
+          "value": ":provider",
+          "label": "provider"
+        },
+        {
+          "value": ":applicant.documents[0].value",
+          "label": "applicant.documents.value"
+        },
+        {
+          "value": ":applicant.documents[0].type",
+          "label": "applicant.documents.type"
+        },
+        {
+          "label": "createdAt",
+          "op": "range",
+          "value": {
+            "to": "date(0)",
+            "from": "fn:getValueFromSale"
+          },
+          "defaultValue": {
+            "from": "date(-5d)",
+            "to": "date(0)"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 🔍 Explanation
+
+Field
+
+Description
+
+`fnContext`
+
+The name(s) of the function(s) that will receive this query as parameter input
+
+`query`
+
+Array of parameter definitions. Each will be resolved based on context or DSL expressions
+
+`label`
+
+The target field to be passed (e.g. used to generate a MongoDB query or as input to a service)
+
+`value`
+
+Can be a dynamic reference (e.g., `:context.path`), a static value, or a DSL expression
+
+`op`
+
+Optional. Defines the operator (`eq`, `range`, `rangeDate`, `gte`, etc.)
+
+`defaultValue`
+
+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
+
+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
+{
+  partner: { partnerId: "bolttech" },
+  productType: "car-insurance",
+  provider: "bolttech",
+  applicant: {
+    documents: [{ type: "NIF", value: "ABCDE" }]
+  },
+  createdAt: {
+    from: new Date("2025-07-25T00:00:00Z"), // resolved from fn:getValueFromSale
+    to: new Date("2025-07-30T00:00:00Z")    // resolved from date(0)
+  }
+}
+```
+
+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.
+
+---
+
+## 🧠 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.
+
+These functions can be executed **before query construction** to compute values that are **injected** dynamically into query fields.
+
+---
+
+### 🔧 Structure of `functions`
+
+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 |
+
+### 📌 Example
+
+```json
+{
+  "functions": [
+    {
+      "name": "getValueFromSale",
+      "fn": "getValueFromSale(queries, target)",
+      "variables": {
+        "target": "createdAt",
+        "queries": [
+          {
+            "value": ":productType",
+            "label": "products.productType"
+          },
+          {
+            "value": ":applicant.documents[0].value",
+            "label": "applicant.documents.value"
+          },
+          {
+            "value": ":applicant.documents[0].type",
+            "label": "applicant.documents.type"
+          },
+          {
+            "value": "date(-5d)",
+            "label": "createdAt",
+            "op": "gte"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### 🔄 Using the Function Output in Queries
+
+To use the result of a function, reference it in a `query.value` using the syntax: `fn:functionName`.
+
+json
+
+CopyEdit
+
+```json
+{
+  "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)`
+
+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
+
+---
+
+> 💡 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)
+
+- Custom service to inject context functions (like `RateLimitingInjectFunctionsUseCase`)
+
+## 📎 Notes
+
+- 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).
+
+- Ensure `getFunctions()` returns **async functions** that provide the required values for the expression.
+
+## 🧾 License
+
+MIT

package/dist/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@edirect/rate-limit-module",
+  "version": "11.0.63",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@edirect/auth": "^11.0.63",
+    "@edirect/logger": "^11.0.63",
+    "@nestjs/cache-manager": "^3.1.3",
+    "@nestjs/common": "^11.2.1",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.2.1",
+    "@nestjs/mongoose": "^11.0.4",
+    "@nestjs/swagger": "^11.4.7",
+    "cache-manager-redis-store": "^3.0.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "dayjs": "^1.11.23",
+    "ioredis": "^6.0.0",
+    "jexl": "^2.3.0",
+    "mongoose": "^9.9.3",
+    "tslib": "^2.8.1",
+    "uuid": "^14.0.1"
+  },
+  "devDependencies": {
+    "@types/jexl": "^2.3.4"
+  },
+  "type": "commonjs"
+}

package/dist/src/decorators/rate-limiting-rule.decorator.d.ts

@@ -0,0 +1,10 @@
+export declare const RULE_METADATA = "RATE_LIMITING_RULE_METADATA";
+export interface RateLimitingRuleMetadataOptions {
+    action: string;
+    partnerPath: string;
+    providerPath: string;
+    productTypePath: string;
+    marketPath: string;
+}
+export declare const RateLimitingRuleMetadata: (options: RateLimitingRuleMetadataOptions) => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=rate-limiting-rule.decorator.d.ts.map

package/dist/src/decorators/rate-limiting-rule.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiting-rule.decorator.d.ts","sourceRoot":"","sources":["../../../src/decorators/rate-limiting-rule.decorator.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,gCAAgC,CAAC;AAE3D,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,wBAAwB,GACnC,SAAS,+BAA+B,qDACF,CAAC"}

package/dist/src/decorators/rate-limiting-rule.decorator.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitingRuleMetadata = exports.RULE_METADATA = void 0;
+const common_1 = require("@nestjs/common");
+exports.RULE_METADATA = 'RATE_LIMITING_RULE_METADATA';
+const RateLimitingRuleMetadata = (options) => (0, common_1.SetMetadata)(exports.RULE_METADATA, options);
+exports.RateLimitingRuleMetadata = RateLimitingRuleMetadata;

package/dist/src/guards/rate-limiting.guard.d.ts

@@ -0,0 +1,21 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { RuleService } from '../rules/rule.service';
+import { RuleEngineService } from '../shared/rule-engine/rule-engine.service';
+export declare class RateLimitingRuleGuard implements CanActivate {
+    private readonly reflector;
+    private readonly ruleService;
+    private readonly ruleEngine;
+    private readonly logger;
+    constructor(reflector: Reflector, ruleService: RuleService, ruleEngine: RuleEngineService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private _getValueFromPathOrRoot;
+    private _resolveDateExpr;
+    private _resolveValue;
+    private _resolveVariables;
+    private _resolveParams;
+    private _getByPath;
+    private _injectFnsResults;
+    private _updateFnsResults;
+}
+//# sourceMappingURL=rate-limiting.guard.d.ts.map

package/dist/src/guards/rate-limiting.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiting.guard.d.ts","sourceRoot":"","sources":["../../../src/guards/rate-limiting.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,gBAAgB,EAMjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOzC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAiB9E,qBACa,qBAAsB,YAAW,WAAW;IAIrD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAE5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAN7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBAG9C,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,EAExB,UAAU,EAAE,iBAAiB;IAG1C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoH9D,OAAO,CAAC,uBAAuB;IAoB/B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,UAAU;YAWJ,iBAAiB;IAiB/B,OAAO,CAAC,iBAAiB;CA4C1B"}