Mollitia

https://genesys.github.io/mollitia
Admin
Mollitia is a JavaScript resilience library that helps manage asynchronous operations with...
Tokens:12,962
Snippets:108
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Mollitia and Redis Addon

Source: https://genesys.github.io/mollitia/guide/customization/addons/redis

Install Mollitia and the Redis addon using npm. Ensure Redis is installed separately.

```bash
# Install mollitia
npm install mollitia --save
# Install Redis and the Redis addon
npm install @mollitia/redis redis --save
```

--------------------------------

### Install Mollitia and Prometheus Addon

Source: https://genesys.github.io/mollitia/guide/customization/addons/prometheus

Install the necessary packages for Mollitia and the Prometheus addon using npm.

```bash
# Install mollitia
npm install mollitia --save
# Install the prometheus addon
npm install @mollitia/prometheus --save
```

--------------------------------

### Create a Custom Mollitia Module

Source: https://genesys.github.io/mollitia/guide/customization/modules

Define a new class extending Mollitia.Module and implement the execute method to add custom logic. This example demonstrates logging a message during circuit execution.

```typescript
import * as Mollitia from 'mollitia';
// Creates a class
class UselessModule extends Mollitia.Module {
  // Should implement the constructor, and call super(options)
  constructor (options) {
    super(options);
    this.message = options.message;
  }
  // Should implement the execute method
  async execute (circuit, promise, ...params) {
    // circuit: Circuit being executed
    // promise: The Circuit Function being used
    // params[]: The list of parameters that needs to be passed to the promise
    // Uncomment the line below to get the parameters that have been passed to the execute() function
    // const _params = this.getExecParams(circuit, params);
    console.info(`${circuit.name} - ${this.message}`); // That's some useful stuff
    return promise(...params); // This just executes normally the method
  }
}

// Let's use our new module
const circuit = new Mollitia.Circuit({
  name: 'UselessCircuit',
  options: {
    modules: [
      new UselessModule({
        message: 'Hello World!'
      })
    ]
  }
});

// Execute the circuit
circuit.fn(() => { return; }).execute();

// Logs will be:
// UselessCircuit - Hello World!
```

--------------------------------

### Multiple Ratelimit Configurations

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Combine multiple Ratelimit modules to enforce different constraints. This example sets a limit of 3 requests per second and also ensures at least 200ms between each request.

```typescript
const ratelimit = new Mollitia.Ratelimit({
  limitPeriod: 1000,
  limitForPeriod: 3
});
const ratelimit2 = new Mollitia.Ratelimit({
  limitPeriod: 200,
  limitForPeriod: 1
});
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      ratelimit2,
      ratelimit
    ]
  }
});
```

--------------------------------

### Configure and Use Sliding Count Breaker

Source: https://genesys.github.io/mollitia/guide/api/modules/breaker/sliding-count

Demonstrates how to create a circuit with a Sliding Count Breaker module. It shows the configuration options for sliding window size, minimum calls, failure rate thresholds, slow call duration, slow call rate, permitted calls in half-open state, and open state delay. The example also illustrates how the circuit's state changes based on the number and outcome of executed functions.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  name: 'my-circuit',
  options: {
    modules: [
			// Creates Sliding Count Breaker Module
			new Mollitia.SlidingCountBreaker({
				name: 'my-sliding-count-breaker',
				slidingWindowSize: 6, // Failure Rate Calculation is done on the last 6 iterations
				minimumNumberOfCalls: 3, // 3 iterations are needed to start calculating the failure rate, and see if circuit should be opened or not
				failureRateThreshold: 50, // If half of the iterations or more are failing, the circuit is switched to Opened state.
				slowCallDurationThreshold: 1000, // An iteration is considered as being slow if the iteration lasts more than 1s
				slowCallRateThreshold: 80, // If at least 80% of the iterations are considered as being slow, the circuit is switched to Opened state.
				permittedNumberOfCallsInHalfOpenState: 2, // When the circuit is in Half Opened state, the circuit accepts 2 iterations in this state.
				// Once these 2 iterations are received, failure rate is calculated on these iterations.
				// If failure rate is lower than failureRateThreshold, the circuit is switched to Closed state.
				// If the failure rate is higher or equal to failureRateThreshold, the circuit is switched to Opened state.
				openStateDelay: 10000 // The circuit stays in Opened state for 10s
			})
		]
  }
});

await circuit.fn(myFunction).execute();
await circuit.fn(myFunction2).execute();
// When this 3rd iteration is received, failureRate and slowCallRate is calculated
// If the 3 iterations lasts less than 1s and are all success, then the circuit is still closed
// The circuit is opened if:
//   - at least 2 iterations failed (failure rate is 66% (2 iterations failing) or 100% (3 iterations failing), which is > 50 (failureRateThreshold))
//   - or all the iterations are slow (as slowCallRateThreshold is 80%)
await circuit.fn(myFunction3).execute();
// If
//   - circuit is still closed, then the failure rate and slow call rate threshold will be calculated when a new iteration is received
//   - circuit is opened, then the iterations are failing fast
// Here, 4th iteration received. Calculation will be done on the 4th iterations
await circuit.fn(myFunction4).execute();
// Here, 5th iteration received. Calculation will be done on the 4 iterations
await circuit.fn(myFunction5).execute();
// Here, 6th iteration received. Calculation will be done on the 6 iterations
await circuit.fn(myFunction6).execute();
// Here, number of iterations is 7. So, the 1st iteration is no longer taken into account and the calculation is done on iterations 2 to 7 
await circuit.fn(myFunction7).execute();
```

--------------------------------

### Configure Redis Addon and Module with Option Priority

Source: https://genesys.github.io/mollitia/guide/customization/addons/redis

Demonstrates how module-level Redis options override addon-level options. In this example, `getMaxDelay` is set to 500 at the module level, taking precedence over the addon's `getMaxDelay` of 1000.

```typescript
Mollitia.use(new RedisAddon({ host: <Redis hostName>, port: <Redis Port>, password: <Redis Password>, getMaxDelay: 1000, setMaxDelay: 1000 }));
const rateLimitModule = new Mollitia.Ratelimit({
  name: 'myRateLimitModule',
  limitForPeriod: 2,
  limitPeriod: 20000,
  redis: {
    use: true,
    getMaxDelay: 500
  }
};

```

--------------------------------

### Get Global Prometheus Metrics and Scrap

Source: https://genesys.github.io/mollitia/guide/customization/addons/prometheus

Access all collected Prometheus metrics and scrap data from all circuits and modules globally.

```typescript
const metrics = MollitiaPrometheus.metrics(); // Will return an object containing all metrics from all circuits and modules
const scrap = MollitiaPrometheus.scrap(); // Will return the Prometheus scrap
```

--------------------------------

### Create and Use Bulkhead Module

Source: https://genesys.github.io/mollitia/guide/api/modules/bulkhead

Demonstrates how to create a circuit with a Bulkhead module, configure its concurrent size, queue size, and maximum wait time, and handle potential errors like BulkheadOverloadError and BulkheadQueueWaitError.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a bulkhead module
      new Mollitia.Bulkhead({
        concurrentSize: 2, // Allows 2 concurrent requests, if reached, goes in a queue.
        queueSize: 2, // Allows 2 requests to be in queue, if reached, it will be rejected with a BulkheadOverloadError.
        maxQueueWait: 30000 // After 30 seconds waiting, a queued request will be rejected with a BulkheadQueueWaitError.
      })
    ]
  }
});

// Let's say this function is running multiple times in a relatively short amount of time
circuit.fn(myFunction).execute()
  .then(() => {
    // The succeed normally (directly, or has been in a queue)
  })
  .catch((err) => {
    if (err instanceof Mollitia.BulkheadOverloadError) {
      // When the function has been called, the concurrent methods are at maximum, and the queue is full.
    } else if (err instanceof Mollitia.BulkheadQueueWaitError) {
      // The function has been waiting too long in queue (more than 30 seconds).
    }
    // It failed normally (directly, or has been in a queue)
  });
```

--------------------------------

### Circuit Constructor

Source: https://genesys.github.io/mollitia/guide/api/circuit

Initializes a new Circuit instance. You can provide a name, a default function, and options.

```APIDOC
## Constructor 

### Parameters

#### Constructor Parameters
- **name** (string) - Optional - The Circuit name. Defaults to `Circuit{Index}` for logging purposes.
- **func** (Function) - Optional - The Circuit function. This can be changed later using the `fn()` method. Defaults to `undefined`.
- **options** (object) - Optional - The options for the circuit. Defaults to `undefined`.

#### Options Parameters
- **modules** (Array<Module>) - Optional - An array of modules to be applied to the circuit. Defaults to `[]`.
```

--------------------------------

### Create and Execute a Circuit

Source: https://genesys.github.io/mollitia/guide/api/circuit

Imports the library and creates a new Circuit instance for PostgreSQL operations. The `execute` method is then used to run the defined function with provided arguments.

```typescript
import * as Mollitia from 'mollitia';

const pgCircuit = new Mollitia.Circuit({
  name: 'PostgreSQL Operations',
	func: sqlRequest
});

const res = await pgCircuit.execute('SELECT * FROM Mollitia;');

```

--------------------------------

### Initialize Redis Addon in Mollitia

Source: https://genesys.github.io/mollitia/guide/customization/addons/redis

Import and use the RedisAddon by providing Redis connection details. This addon enables Redis support for compatible Mollitia modules.

```typescript
// Then add the addon
import * as Mollitia from 'mollitia';
import { RedisAddon } from '@mollitia/redis';
// Adds the Redis addon to Mollitia
Mollitia.use(
  new RedisAddon({
    host: <Redis hostName>,
    port: <Redis Port>,
    password: <Redis Password>
  })
);
```

--------------------------------

### Create Mollitia Circuits with Retry and Timeout Modules

Source: https://genesys.github.io/mollitia/guide/design

Demonstrates how to create two Circuits: one with Retry then Timeout, and another with Timeout then Retry. The order of modules affects the resilience behavior.

```typescript
import * as Mollitia from 'mollitia';
// Creates a Retry Module
const retry = new Mollitia.Retry({
  attempts: 2, // Will retry two times
});
const timeout = new Mollitia.Timeout({
  delay: 500, // Will timeout after 500ms
});
// Creates Circuits
const retryWithTimeout = new Mollitia.Circuit({
  options: {
    modules: [retry, timeout]
  }
});
const timeoutRetries = new Mollitia.Circuit({
  options: {
    modules: [timeout, retry]
  }
});
```

--------------------------------

### Create and Use Cache Module in Circuit

Source: https://genesys.github.io/mollitia/guide/api/modules/cache

Demonstrates how to initialize a Mollitia Circuit with a Cache module and execute functions. The cache is configured with a Time-To-Live (TTL) and a cache clear interval. Subsequent calls with the same function and parameters within the TTL will return cached results.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a cache module
      new Mollitia.Cache({
        ttl: 60000,  // A cached response will be considered as valid for 1 minute
        cacheClearInterval: 900000 // A cached response will be kept for 15 minutes
      })
    ]
  }
});

// If the result is a success, it will be cached.
await circuit.fn(myFirstFunction).execute();
// ...
// If this function is called before 1 minute is elapsed, the cached response will be returned
await circuit.fn(myFirstFunction).execute();
// This is a simple object
const myObject = {
  myFirstParam: 'myFirstValue'
};
// Same as before, if that's a success, the result is cached. (The params are different, so it does not return the cache from before)
await circuit.fn(myFirstFunction).execute(myObject);
// The objects changes
myObject.myFirstParam = 'myFirstValuesModified';
// Nevermind, the cache works by reference, meaning the cached result is returned.
await circuit.fn(myFirstFunction).execute(myObject);
// That won't return the cached result, as the function is different
await circuit.fn(mySecondFunction).execute(myObject);
// ... After 1 minute, the function is called again.
circuit.fn(myFirstFunction).execute(myObject)
  .then(() => {
    // If the request succeeds, it returns the result normally
    // If not, the old cached response is returned
  });
// After 15 minutes, the cache is cleared.
```

--------------------------------

### Create a Mollitia Addon

Source: https://genesys.github.io/mollitia/guide/customization/addons

Implement the Mollitia.Addon interface to create a custom addon. You can override methods like onCircuitCreate and onModuleCreate to modify behavior. Use Mollitia.use() to register your addon.

```typescript
import * as Mollitia from 'mollitia';
// Creates a class
class UselessAddon implements Mollitia.Addon {
  // Called when a circuit is created
  onCircuitCreate (circuit, options) {
    // Feel free to modify the circuit behavior, and add properties to it
  }
  // Called when a module is created
  onModuleCreate (module, options) {
    // Feel free to modify the module behavior, and add properties to it
  }
}

// Usage:
Mollitia.use(new UselessAddon());
```

--------------------------------

### Ratelimit Module Usage

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Demonstrates how to use the Ratelimit module to limit requests to 3 per second.

```APIDOC
## Usage

If you don't want more than 3 requests per second, you should define a circuit like this:
```typescript
import * as Mollitia from 'mollitia';
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      new Mollitia.Ratelimit({
        limitPeriod: 1000,
        limitForPeriod: 3
      })
    ]
  }
});
```
```

--------------------------------

### Ratelimit API Reference - Methods

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Lists the methods available for the Ratelimit module.

```APIDOC
### Methods

Name| Description| Returns
---|---|---
`getExecParams()`| Returns the circuit function parameters.| `any[]` **params**
```

--------------------------------

### Bulkhead Module Usage

Source: https://genesys.github.io/mollitia/guide/api/modules/bulkhead

Demonstrates how to create a circuit with a Bulkhead module to limit concurrent requests and handle potential errors like overload or excessive queue wait times.

```APIDOC
## Usage

typescript
```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a bulkhead module
      new Mollitia.Bulkhead({
        concurrentSize: 2, // Allows 2 concurrent requests, if reached, goes in a queue.
        queueSize: 2, // Allows 2 requests to be in queue, if reached, it will be rejected with a BulkheadOverloadError.
        maxQueueWait: 30000 // After 30 seconds waiting, a queued request will be rejected with a BulkheadQueueWaitError.
      })
    ]
  }
});

// Let's say this function is running multiple times in a relatively short amount of time
circuit.fn(myFunction).execute()
  .then(() => {
    // The succeed normally (directly, or has been in a queue)
  })
  .catch((err) => {
    if (err instanceof Mollitia.BulkheadOverloadError) {
      // When the function has been called, the concurrent methods are at maximum, and the queue is full.
    } else if (err instanceof Mollitia.BulkheadQueueWaitError) {
      // The function has been waiting too long in queue (more than 30 seconds).
    }
    // It failed normally (directly, or has been in a queue)
  });
```
```

--------------------------------

### Cache Module Usage

Source: https://genesys.github.io/mollitia/guide/api/modules/cache

Demonstrates how to initialize and use the Cache module within a Mollitia Circuit. It shows caching of function results, cache invalidation after TTL, and how parameters affect caching.

```APIDOC
## Usage

Once you call a **function** , with some **parameters** , it will check if it has been cached, if so, the function will not be called at all, and will directly resolve with the cached response.

> It is important to understand that the cache works by reference!
> That means that the cache is specifically referenced **for one function** , and **for the same parameters** .
>
Also, when a circuit fails and have an outdated cached response (ttl has been passed), the circuit will fire the request, and will respond with the new value if it succeeds, otherwise it will resolve with the cached response.
```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a cache module
      new Mollitia.Cache({
        ttl: 60000,  // A cached response will be considered as valid for 1 minute
        cacheClearInterval: 900000 // A cached response will be kept for 15 minutes
      })
    ]
  }
});

// If the result is a success, it will be cached.
await circuit.fn(myFirstFunction).execute();
// ...
// If this function is called before 1 minute is elapsed, the cached response will be returned
await circuit.fn(myFirstFunction).execute();
// This is a simple object
const myObject = {
  myFirstParam: 'myFirstValue'
};
// Same as before, if that's a success, the result is cached. (The params are different, so it does not return the cache from before)
await circuit.fn(myFirstFunction).execute(myObject);
// The objects changes
myObject.myFirstParam = 'myFirstValuesModified';
// Nevermind, the cache works by reference, meaning the cached result is returned.
await circuit.fn(myFirstFunction).execute(myObject);
// That won't return the cached result, as the function is different
await circuit.fn(mySecondFunction).execute(myObject);
// ... After 1 minute, the function is called again.
circuit.fn(myFirstFunction).execute(myObject)
  .then(() => {
    // If the request succeeds, it returns the result normally
    // If not, the old cached response is returned
  });
// After 15 minutes, the cache is cleared.
```
```

--------------------------------

### Ratelimit API Reference - Options

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Details the configuration options available for the Ratelimit module.

```APIDOC
## API Reference

### Options

Name| Description| Default
---|---|---
`limitPeriod`| Specifies the time period during which the ratelimit is calculated| `0`
`limitForPeriod`| Specifies the maximum number of requests during the period| `Infinity`
```

--------------------------------

### Basic Ratelimit Configuration

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Configure a circuit to allow no more than 3 requests per second. This sets a limit period of 1000ms (1 second) and allows 3 requests within that period.

```typescript
import * as Mollitia from 'mollitia';
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      new Mollitia.Ratelimit({
        limitPeriod: 1000,
        limitForPeriod: 3
      })
    ]
  }
});
```

--------------------------------

### Create and Configure Sliding Time Breaker

Source: https://genesys.github.io/mollitia/guide/api/modules/breaker/sliding-time

Demonstrates how to create a circuit with a Sliding Time Breaker module. Configure parameters like sliding window size, minimum calls for calculation, failure rate thresholds, slow call duration, slow call rate, permitted calls in half-open state, and open state delay.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  name: 'my-circuit',
  options: {
    modules: [
			// Creates Sliding Time Breaker Module
			new Mollitia.SlidingTimeBreaker({
				name: 'my-sliding-time-breaker',
				slidingWindowSize: 30000, // Failure Rate Calculation is done on the iterations received during the last 30s.
				minimumNumberOfCalls: 2, // 2 iterations are needed to start calculating the failure rate, and see if circuit should be opened or not
				failureRateThreshold: 60, // If at least 60% of the iterations are failing, the circuit is switched to Opened state.
				slowCallDurationThreshold: 500, // An iteration is considered as being slow if the iteration lasts more than 0.5s
				slowCallRateThreshold: 40, // If at least 40% of the iterations are considered as being slow, the circuit is switched to Opened state.
				permittedNumberOfCallsInHalfOpenState: 2, // When the circuit is in Half Opened state, the circuit accepts 2 iterations in this state.
				// Once these 2 iterations are received, failure rate is calculated on these iterations.
				// If failure rate is lower than failureRateThreshold, the circuit is switched to Closed.
				// If the failure rate is higher or equal to failureRateThreshold, the circuit is switched to Opened.
				openStateDelay: 10000 // The circuit stays in Opened state for 10s
			})
		]
  }
});
// Time is t0
await circuit.fn(myFunction).execute();
// 10s later (t0 + 10s)
// When this 2nd iteration is received, failureRate and slowCallRate is calculated
// If the 2 iterations lasts less than 500ms and are all success, then the circuit is still closed
// The circuit is opened if:
//   - the 2 iterations failed (as failureRateThreshold is 60%)
//   - at least 1 iteration is slow (as slowCallRateThreshold is 40%)
await circuit.fn(myFunction2).execute();
// 10s later (t0 + 20s)
// Elapsed time since 1st iteration is lower than 30s
// If circuit is still closed, the failureRate and slowCallRate threshold is calculated on the 3 iterations 
await circuit.fn(myFunction3).execute();
// 5s later (t0 + 25s)
// Elapsed time since 1st iteration is lower than 30s
// If circuit is still closed, the failureRate and slowCallRate threshold is calculated on the 4 iterations
await circuit.fn(myFunction4).execute();
// 10s later (t0 + 35s)
// Elapsed time since 1st iteration is greater than 30s. Elapsed time since 2nd iteration is lower than 30s
// If circuit is still closed, the failureRate and slowCallRate threshold is now calculated on iterations from 2 to 5, as iteration 1 is too old
await circuit.fn(myFunction5).execute();
```

--------------------------------

### Create and Use Timeout Module in Circuit

Source: https://genesys.github.io/mollitia/guide/api/modules/timeout

Demonstrates how to create a Mollitia Circuit with a Timeout module. The timeout is set to reject if the function takes longer than 2 minutes. It also shows how to handle the TimeoutError when the operation exceeds the delay.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a timeout module
      new Mollitia.Timeout({
        delay: 120000  // Will get rejected with a TimeoutError if it takes more than 2 minutes
      })
    ]
  }
});

// Let's see what happens if we run a long function
circuit.fn(myLongFunction).execute()
  .then(() => {
    // It took less than 2 minutes, and succeed.
  })
  .catch((err) => {
    if (err instanceof Mollitia.TimeoutError) {
      // It took more than 2 minutes.
    }
    // It took less than 2 minutes, and failed.
  });
```

--------------------------------

### Circuit.execute

Source: https://genesys.github.io/mollitia/guide/api/circuit

Executes the circuit, running the configured resilience logic.

```APIDOC
## Methods 

### execute(...args: any[])

#### Description
Executes the circuit.

#### Parameters
- **args** (any[]) - Any arguments to pass to the circuit's function.
```

--------------------------------

### Timeout Module Usage

Source: https://genesys.github.io/mollitia/guide/api/modules/timeout

Demonstrates how to create and use the Timeout module within a Mollitia Circuit to handle long-running asynchronous functions.

```APIDOC
## Usage

```typescript
import * as Mollitia from 'mollitia';

// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a timeout module
      new Mollitia.Timeout({
        delay: 120000  // Will get rejected with a TimeoutError if it takes more than 2 minutes
      })
    ]
  }
});

// Let's see what happens if we run a long function
circuit.fn(myLongFunction).execute()
  .then(() => {
    // It took less than 2 minutes, and succeed.
  })
  .catch((err) => {
    if (err instanceof Mollitia.TimeoutError) {
      // It took more than 2 minutes.
    }
    // It took less than 2 minutes, and failed.
  });
```
```

--------------------------------

### Create and Configure Retry Module

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Demonstrates how to create a Circuit with a Retry module. Configure the number of attempts, initial interval, retry mode, and a custom onRejection handler to control retry behavior based on specific errors.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a retry module
      new Mollitia.Retry({
        attempts: 2, // Will retry two times
        interval: 500,
        mode: RetryMode.LINEAR,
        factor: 1 // With interval=500, mode=LINEAR and factor 1, the interval between attempts will grow linearly (500ms before 1st retry, then 1000ms before 2nd retry)
        onRejection: (err, attempt) => { // Can help filtering error and modifying the retry behavior
          // Second parameter represent the current attempt
          // In this example, onRejection will be called 3 times
          // attempt = 0: first failure
          // attempt = 1: first retry failure
          // attempt = 2: second retry failure
          if (err instanceof BrokenError) {
            return false; // Returning false will cancel the retry attempt
          } else if (err instanceof BusyError) {
            return 1000; // Returning a number will modify the interval time, and wait for that time before retry
          } else {
            return true; // Returning true will retry, using the configured interval value
          }
        }
      })
    ]
  }
});

```

--------------------------------

### Bulkhead Module API Reference

Source: https://genesys.github.io/mollitia/guide/api/modules/bulkhead

Details the configuration options, methods, and events available for the Bulkhead module.

```APIDOC
## API Reference

### Options

Name| Description| Default  
---|---|---
`concurrentSize`| The number of concurrent requests that can be running in parallel.| `10`  
`queueSize`| The number of requests that can be queued.| `10`  
`maxQueueWait`| The amount of time before a queued request is rejected.| `60000`  

### Methods

Name| Description| Returns  
---|---|---
`getExecParams()`| Returns the circuit function parameters.| `any[]` **params**  

### Events

Name| Description| Params  
---|---|---
`execute`| Called when the module is executed.| `Mollitia.Circuit` **circuit** , `Promise<T>` **promise** , `any[]` **params**  
`update-concurrent-buffer`|  Called when the concurrent buffer is updated.| `Mollitia.Circuit` **circuit** , `BufferedPromise[]` **buffer**  
`update-queue-buffer`|  Called when the queue buffer is updated.| `Mollitia.Circuit` **circuit** , `BufferedPromise[]` **buffer**
```

--------------------------------

### Ratelimit Module with Multiple Limits

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Shows how to combine multiple Ratelimit modules for more complex rate limiting, such as limiting to 3 requests per second and ensuring at least 200ms between requests.

```APIDOC
## Usage

If you don't want more than 3 requests per second, and also at least 200ms between each request, you should define a circuit like this:
```typescript
const ratelimit = new Mollitia.Ratelimit({
  limitPeriod: 1000,
  limitForPeriod: 3
});
const ratelimit2 = new Mollitia.Ratelimit({
  limitPeriod: 200,
  limitForPeriod: 1
});
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      ratelimit2,
      ratelimit
    ]
  }
});
```
```

--------------------------------

### Access Circuit Metrics and Scrap

Source: https://genesys.github.io/mollitia/guide/customization/addons/prometheus

Retrieve metrics and Prometheus scrap data directly from a circuit instance.

```typescript
// ...

const myCircuitMetrics = myCircuit.prometheus.metrics; // Will return an object containing all metrics from this circuit
const myCircuitScrap = myCircuit.prometheus.scrap(); // Will return the Prometheus scrap from this circuit
```

--------------------------------

### Add Prometheus Addon to Mollitia

Source: https://genesys.github.io/mollitia/guide/customization/addons/prometheus

Import and use the PrometheusAddon with Mollitia to enable metrics collection.

```typescript
// Then add the addon
import * as Mollitia from 'mollitia';
import * as MollitiaPrometheus from '@mollitia/prometheus';

Mollitia.use(new MollitiaPrometheus.PrometheusAddon());
```

--------------------------------

### Configure Prometheus Options for Circuits and Modules

Source: https://genesys.github.io/mollitia/guide/customization/addons/prometheus

Add Prometheus-specific options when creating Mollitia circuits or modules to name them and assign labels.

```typescript
const myModule = new Mollitia.Timeout({
	prometheus: {
		name: 'my-module'
	}
});
const myCircuit = new Mollitia.Circuit({
  options: {
    prometheus: {
      name: 'my-circuit',
      labels: {
        tag2: 'val2',
        tag3: 'val3'
      }
    }
  }
});
```

--------------------------------

### Cache Module Methods

Source: https://genesys.github.io/mollitia/guide/api/modules/cache

Lists the available methods for the Cache module, such as retrieving execution parameters.

```APIDOC
### Methods

Name| Description| Returns  
---|---|---
`getExecParams()`| Returns the circuit function parameters.| `any[]` **params**  
```

--------------------------------

### Configure Ratelimit Module with Redis

Source: https://genesys.github.io/mollitia/guide/customization/addons/redis

Configure a Ratelimit module to use Redis by setting `redis.use` to true. This allows the rate limiting state to be stored and shared via Redis.

```typescript
const rateLimitModule = new Mollitia.Ratelimit({
  name: 'myRateLimitModule',
  limitForPeriod: 2,
  limitPeriod: 20000,
  redis: {
    // Setting redis.use to true indicates Redis should be used
    use: true
  }
};
// Creates a circuit
const myCircuit = new Mollitia.Circuit({
  // Initializes a circuit with a handler
  func: yourFunction,
  options: {
    modules: [
      rateLimit: rateLimitModule
    ]
  }
});
// This will execute yourFunction('dummy')
await myCircuit.execute('dummy');
```

--------------------------------

### LINEAR Retry Mode Calculation

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Illustrates the formula for calculating retry delays in LINEAR mode. The delay increases linearly with each attempt, capped by maxInterval.

```text
min(interval + (iteration * factor * interval), maxInterval)
```

--------------------------------

### Cache Module Options

Source: https://genesys.github.io/mollitia/guide/api/modules/cache

Details the configurable options for the Cache module, including Time-To-Live (TTL), cache clearing interval, and cache information retrieval.

```APIDOC
## API Reference

### Options

Name| Description| Default  
---|---|---
`ttl`| The amount of time during which a cached result is considered valid.| `6000`  
`cacheClearInterval`| The amount of time before the cache cleans itself up.| `900000`  
`getInformationFromCache`| Specifies if the async response is retrieved from Cache (`res._mollitiaIsFromCache` is `true`)| `false`  
`adjustCacheParams`| A filtering callback, to modify the parameters used for Cache Key.| `none`  
```

--------------------------------

### EXPONENTIAL Retry Mode Calculation

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Shows the formula for retry delay calculation in EXPONENTIAL mode. The delay grows exponentially with each attempt, also respecting maxInterval.

```text
min(interval * (factor ** iteration), maxInterval)
```

--------------------------------

### Timeout Module API Reference

Source: https://genesys.github.io/mollitia/guide/api/modules/timeout

Details the configuration options, methods, and events available for the Timeout module.

```APIDOC
## API Reference

### Options

Name| Description| Default
---|---|---
`delay`| The amount of time before a the promise is rejected.| `60000`

### Methods

Name| Description| Returns
---|---|---
`getExecParams()`| Returns the circuit function parameters.| `any[]` **params**

### Events

Name| Description| Params
---|---|---
`execute`| Called when the module is executed.| `Mollitia.Circuit` **circuit** , `Promise<T>` **promise** , `any[]` **params**
`timeout`| Called when the module times out.| `Mollitia.Circuit` **circuit**
```

--------------------------------

### Fallback Module API Reference

Source: https://genesys.github.io/mollitia/guide/api/modules/fallback

Reference for the Fallback module's options, methods, and events.

```APIDOC
## Fallback Module

### Options

Name| Description| Default  
---|---|---  
`callback`| The callback, called when the circuit rejects.| `Function(Error)`  

### Methods

Name| Description| Returns  
---|---|---  
`getExecParams()`| Returns the circuit function parameters.| `any[]` **params**  

### Events

Name| Description| Params  
---|---|---  
`execute`| Called when the module is executed.| `Mollitia.Circuit` **circuit** , `Promise<T>` **promise** , `any[]` **params**
```

--------------------------------

### Ratelimit API Reference - Events

Source: https://genesys.github.io/mollitia/guide/api/modules/ratelimit

Describes the events emitted by the Ratelimit module.

```APIDOC
### Events

Name| Description| Params
---|---|---
`execute`| Called when the module is executed.| `Mollitia.Circuit` **circuit** , `Promise<T>` **promise** , `any[]` **params**
```

--------------------------------

### Sliding Time Window Breaker Options

Source: https://genesys.github.io/mollitia/guide/api/modules/breaker/sliding-time

Configuration options for the Sliding Time Window Breaker.

```APIDOC
## Options

### `state`

- **Description**: Specifies the circuit state.
- **Default**: `CLOSED`

### `failureRateThreshold`

- **Description**: Specifies the failure rate threshold in percentage.
- **Default**: `50`

### `slowCallRateThreshold`

- **Description**: Specifies the slow duration threshold. A call is considered **slow** when duration `>=` than `slowCallDurationThreshold`.
- **Default**: `100`

### `slowCallDurationThreshold`

- **Description**: Specifies the duration (in ms) threshold above which calls are considered as slow.
- **Default**: `60000`

### `permittedNumberOfCallsInHalfOpenState`

- **Description**: Specifies the number of permitted calls when the circuit is half open.
- **Default**: `2`

### `halfOpenStateMaxDelay`

- **Description**: Specifies the maximum wait (in ms) in Half Open State, before switching back to open. 0 deactivates this.
- **Default**: `0`

### `slidingWindowSize`

- **Description**: Specifies the sliding duration (in ms) used to calculate failure and slow call rate percentages.
- **Default**: `60`

### `minimumNumberOfCalls`

- **Description**: Specifies the minimum number of calls used to calculate failure and slow call rate percentages.
- **Default**: `10`

### `openStateDelay`

- **Description**: Specifies the time (in ms) the circuit stay opened before switching to half-open.
- **Default**: `60000`

### `onError`

- **Description**: Allows filtering of the error to report as a failure or not.
- **Default**: `None`
```

--------------------------------

### Handling 'this' Context in Circuit Functions

Source: https://genesys.github.io/mollitia/guide/api/circuit

Demonstrates how to correctly bind the `this` context when using methods from an object as circuit functions. Without binding, `this` will be lost, causing errors. Binding ensures the correct context is maintained.

```typescript
const serviceController = {
  getUsers: function () {
    return this.request('/get-users');
  },
  request: function (url) {
    // Actual HTTP request call
  }
};
const serviceCircuit = new Mollitia.Circuit({
  name: 'Service - Get Users'
});

// This binding sets the "this" reference to "serviceController", resolving the above issue
await serviceCircuit.fn(serviceController.getUsers.bind(serviceController)).execute();

```

--------------------------------

### Retry Options

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Configuration options for customizing retry behavior.

```APIDOC
## Retry Options

### Description
Configuration options for customizing retry behavior.

### Options

- **`attempts`** (number) - The number of retry attempts (the function will be called attempts + 1 times). Default: `2`
- **`interval`** (number) - The amount of time to wait before retrying. Default: `0`
- **`fastFirst`** (boolean) - The first retry is done without delay if set to true. Default: `false`
- **`mode`** (string) - The mode for retry. Default: `CONSTANT`
- **`factor`** (number) - The factor to be used for retry (used only if `mode` is LINEAR, EXPONENTIAL OR JITTER). Default: LINEAR=`1`, `2` otherwise
- **`maxInterval`** (number) - The maximum interval between each retry. Default: `INFINITY`
- **`jitterAdjustment`** (number) - The percentage to adjust delay randomly based on jitter retry duration. Default: `0.1` (clamps from `0` to `1`)
- **`onRejection`** (callback) - A filtering callback, to modify the retry behavior. Default: `none`
```

--------------------------------

### Retry Methods

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Available methods for interacting with the retry module.

```APIDOC
## Retry Methods

### Description
Available methods for interacting with the retry module.

### Methods

- **`getExecParams()`** - Returns the circuit function parameters. Returns: `any[]` **params**
```

--------------------------------

### Sliding Time Window Breaker Methods

Source: https://genesys.github.io/mollitia/guide/api/modules/breaker/sliding-time

Available methods for the Sliding Time Window Breaker.

```APIDOC
## Methods

### `getExecParams()`

- **Description**: Returns the circuit function parameters.
- **Returns**: `any[]` **params**
```

--------------------------------

### Execute Operation with Retry then Timeout Circuit

Source: https://genesys.github.io/mollitia/guide/design

Illustrates the execution flow when using a Circuit configured with Retry followed by Timeout. The operation times out on each attempt, leading to a final TimeoutError.

```typescript
retryWithTimeout.fn(failureAsync).execute('dummy', 1000) // Launches the failureAsync method, that will return "dummy", and will take 1000ms to complete
// Attempt #1: The function times out (1000 > 500) - Launches First Retry
// Attempt #2: The function times out (1000 > 500) - Launches Second Retry
// Attempt #3: The function times out (1000 > 500) - Fails with TimeoutError
```

--------------------------------

### Cache Module Events

Source: https://genesys.github.io/mollitia/guide/api/modules/cache

Describes the events emitted by the Cache module, including execution, cache hits, and cache hits with old data.

```APIDOC
### Events

Name| Description| Params  
---|---|---
`execute`| Called when the module is executed.| `Mollitia.Circuit` **circuit** , `Promise<T>` **promise** , `any[]` **params**  
`cache-hit`|  Called when the module returns a cached result.| `Mollitia.Circuit` **circuit** , `any[]` **cacheKeys**  
`cache-hit-old`|  Called when the module returns an old cached result on failure.| `Mollitia.Circuit` **circuit** , `any[]` **cacheKeys** 
```

--------------------------------

### JITTER Retry Mode Calculation

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Details the calculation for retry delays in JITTER mode. It's based on exponential backoff with a random variation determined by jitterAdjustment, respecting maxInterval.

```text
minValue = Math.min((interval x factor^iteration), maxInterval) * ( 1 - jitterAdjustment)
maxValue = Math.min((interval x factor^iteration), maxInterval) * ( 1 + jitterAdjustment)
waitDelay = Math.random(0, (maxValue - minValue)) + minValue
```

--------------------------------

### Circuit Events

Source: https://genesys.github.io/mollitia/guide/api/circuit

Information about events emitted by the Circuit.

```APIDOC
## Events 

### execute

#### Description
Called when the module is executed.

#### Parameters
- **circuit** (Mollitia.Circuit) - The circuit instance.
- **promise** (Promise<T>) - The promise representing the execution.
- **params** (any[]) - The parameters passed to the execute method.
```

--------------------------------

### Execute Operation with Timeout then Retry Circuit

Source: https://genesys.github.io/mollitia/guide/design

Shows the execution flow when a Timeout module precedes a Retry module. The operation times out before any retries can occur, resulting in an immediate TimeoutError.

```typescript
timeoutRetries.fn(failureAsync).execute('dummy', 1000) // Exactly like before
// Attempt #1: The function times out (1000 > 500) - Fails with TimeoutError
```

--------------------------------

### Implement Fallback Module in Circuit

Source: https://genesys.github.io/mollitia/guide/api/modules/fallback

Use the Fallback module to filter errors rejected by a circuit. The callback function can inspect the error and return a specific error or a generic one.

```typescript
import * as Mollitia from 'mollitia';
// Creates a circuit
const circuit = new Mollitia.Circuit({
  options: {
    modules: [
      // Creates a fallback module
      new Mollitia.Fallback({
        callback (err) {
          // Every time the method rejects, You can filter here
          if (err instanceof MyError) {
            // I know this error
            return err; 
          }
          return new UnknownError();
        }
      })
    ]
  }
});

// The rejected errors are filtered, meaning you always know what is returned here
circuit.fn(myFunction).execute()
  .catch((err) => {
    if (err instanceof MyError) {
      // It's a MyError error
    } else {
      // It's an UnknownError error
    }
  });
```

--------------------------------

### Sliding Time Window Breaker Events

Source: https://genesys.github.io/mollitia/guide/api/modules/breaker/sliding-time

Events emitted by the Sliding Time Window Breaker.

```APIDOC
## Events

### `execute`

- **Description**: Called when the module is executed.
- **Params**: `Mollitia.Circuit` **circuit**, `Promise<T>` **promise**, `any[]` **params**

### `state-changed`

- **Description**: Called when the breaker state changes.
- **Params**: `Mollitia.BreakerState` **state**
```

--------------------------------

### Retry Events

Source: https://genesys.github.io/mollitia/guide/api/modules/retry

Events emitted by the retry module to signal different stages of execution.

```APIDOC
## Retry Events

### Description
Events emitted by the retry module to signal different stages of execution.

### Events

- **`execute`** - Called when the module is executed. Params: `Mollitia.Circuit` **circuit**, `Promise<T>` **promise**, `any[]` **params**
- **`retry`** - Called when retrying. Params: `Mollitia.Circuit` **circuit**, `number` **currentAttempt**
- **`success-without-retry`** - Called the module execution succeeds without retrying. Params: `Mollitia.Circuit` **circuit**
- **`success-with-retry`** - Called the module execution succeeds after retrying. Params: `Mollitia.Circuit` **circuit**, `number` **attempts**
- **`failure-without-retry`** - Called the module execution fails without retrying. Params: `Mollitia.Circuit` **circuit**
- **`failure-with-retry`** - Called the module execution fails after retrying. Params: `Mollitia.Circuit` **circuit**, `number` **attempts**
- **`delay-before-next-retry`** - Called when the delay before next retry starts. Params: `Mollitia.Circuit` **circuit**, `number` **waitDuration**
```
Tokens:
Raw