@n1k1t/mock-server 0.3.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 <div align='center'>
   <h1>Mock server</h1>
-  <p>Mock, match, modify and manipulate a HTTP request/response payload using flexible expectations with types</p>
+  <p>The ultimate toolkit to <b>intercept, transform, and simulate</b> HTTP/WS traffic with type-safe expectations</p>
 
   <img src="https://raw.githubusercontent.com/n1k1t/mock-server/refs/heads/master/images/preview.png?raw=true" />
 
@@ -12,1244 +12,814 @@
   ![Dynamic XML Badge](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fgithub.com%2Fn1k1t%2Fmock-server%2Fblob%2Fmaster%2Fcoverage%2Fcobertura-coverage.xml%3Fraw%3Dtrue&query=round(%2Fcoverage%2F%40line-rate%20*%201000)%20div%201000&label=coverage)
 </div>
 
-# Navigation
-
-- [Basics](#basics)
-    - [How it works](#how-it-works)
-    - [Install](#install)
-    - [Start](#start)
-    - [GUI](#gui)
-    - [Mock](#mock)
-- [Expectations](#expectations)
-	- [Schema](#schema)
-	- [Forwarding](#forwarding)
-	- [Context](#context)
-	- [Utils](#utils)
-	- [Operators](#operators)
-	- [Typings](#typings)
-	- [Storage](#storage)
-	- [Containers](#containers)
-	- [Cache](#cache)
-	- [State](#state)
-	- [Seeds](#seeds)
-	- [XML](#xml)
-- [API](#api)
-	- [Ping](#ping)
-	- [Create expectation](#create-expectation)
-	- [Update expectation](#update-expectation)
-	- [Delete expectation](#delete-expectation)
-- [Additional](#additional)
-    - [Configuration](#configuration)
-    - [Logger](#logger)
-    - [Meta](#meta)
-
-# Basics
-
-## Install
+This mock server provides complete control over your network layer. It allows you to simulate missing APIs, modify real backend responses on the fly, and proxy traffic with advanced caching. Designed for flexibility, it handles complex scenarios with ease while maintaining strict type safety across all your expectations.
+
+- [Features](#features)
+- [Installation](#installation)
+- [Simple Example](#simple-example)
+- [Overview](#overview)
+  - [GUI](#gui)
+  - [Storage & Containers](#storage--containers)
+  - [Cache](#cache)
+  - [State & Seeds](#state--seeds)
+- [Mock Server Utilities](#mock-server-utilities)
+  - [Expectation Operators ($)](#expectation-operators-)
+  - [Operator Locations](#operator-locations)
+  - [Operator Context](#operator-context)
+  - [Container Methods](#container-methods)
+- [Usage](#usage)
+  - [Complex Expectations with $and](#complex-expectations-with-and)
+  - [Custom Logic with $exec](#custom-logic-with-exec)
+  - [Dynamic Response Manipulation](#dynamic-response-manipulation)
+  - [Binary Data and Files](#binary-data-and-files)
+  - [XML Support](#xml-support)
+  - [Simulating Network Errors](#simulating-network-errors)
+  - [Disabled By Default](#disabled-by-default)
+  - [Type Safety](#type-safety)
+  - [WebSocket Support](#websocket-support)
+  - [Request Forwarding](#request-forwarding)
+  - [Using Relative Paths with baseUrl](#using-relative-paths-with-baseurl)
+  - [Transforming Request Data Before Forwarding](#transforming-request-data-before-forwarding)
+  - [WebSocket Forwarding and Manipulation](#websocket-forwarding-and-manipulation)
+  - [Conditional Caching](#conditional-caching)
+  - [Custom Cache Key](#custom-cache-key)
+  - [Request State](#request-state)
+  - [Storage and Containers](#storage-and-containers)
+  - [Cross-Expectation Sync](#cross-expectation-sync)
+- [Extensions](#extensions)
+  - [Redis Configuration](#redis-configuration)
+  - [Remote Expectations with RemoteClient](#remote-expectations-with-remoteclient)
+  - [Grouping with Providers](#grouping-with-providers)
+  - [Logger](#logger)
+- [License](#license)
+
+## Features
+
+- **Multi-protocol Support**: Full support for both **HTTP** and **WebSocket** protocols.
+- **Flexible Matching**: Match requests by path, method, headers, and data using regex, minimatch, or custom functions.
+- **Payload Manipulation**: Modify request or response payloads on the fly.
+- **Request Forwarding**: Proxy requests to real services with optional caching.
+- **Built-in GUI**: Monitor traffic and manage expectations through a web interface.
+- **Typed Expectations**: First-class support for TypeScript to keep your mocks type-safe.
+- **Advanced State Management**: Store data across requests using Containers or Request State.
+- **XML Support**: Native parsing and serialization for XML payloads.
+
+## Installation
 
 ```bash
 npm i @n1k1t/mock-server
 ```
 
-## How it works
-
-![screenshot](https://raw.githubusercontent.com/n1k1t/mock-server/refs/heads/master/images/strategy.png?raw=true)
-
-According on the picture above, main idea is to generate or modify response from some backend service. The mock server provides many scenarios to do that
-
-**In case of mocking without request forwarding:**
-
-1. Start mock server (for example on `localhost:8080`)
-2. Register expectation using CLI (cURL) or application lib
-3. Make request to `localhost:8080/...`
-    1. The mock server matches a request payload with registered expectations
-    2. Build a response using an expectation configuration
-
-**In case of mocking with request forwarding:**
-
-0. Lets imagine that you have a service that hosts on `localhost:8081`
-1. Start mock server (for example on `localhost:8080`)
-2. Register expectation using CLI (cURL) or application lib
-3. Make request to `localhost:8080/...`
-    1. The mock server matches a request payload with registered expectations
-    2. Next is forwarding a request payload to `localhost:8081/...`
-    3. Using response fetched from `localhost:8081/...` the mock server builds a response
-
-## Start
-
-### CLI
-
-```bash
-npx mock -h localhost -p 8080
-```
-
-### JavaScript
-
-```js
-const { MockServer } = require('@n1k1t/mock-server');
-MockServer.start({ host: 'localhost', port: 8080 });
-```
-
-### TypeScript
+## Simple Example
 
 ```ts
 import { MockServer } from '@n1k1t/mock-server';
-MockServer.start({ host: 'localhost', port: 8080 });
-```
 
-## GUI
+const server = await MockServer.start({ host: 'localhost', port: 8080 });
 
-The mock server provides built-in web panel to track everything that is going through. There are two tabs `Expectations` and `History`
+// Create a type-safe expectation using the operator compiler ($)
+await server.client.createExpectation(({ $ }) => ({
+  schema: {
+    request: $.has('incoming.path', { $value: '/api/hello' }),
+    response: $.set('outgoing.data', { $value: { message: 'world' } }),
+  },
+}));
+```
 
-By default it can be found on `/_system/gui` of a host of mock server. Example: `localhost:8080/_system/gui`
+## Overview
 
-Also it provides convenient util to navigate through payload of expectations and requests payload
+### GUI
 
-## Mock
+The mock server provides a built-in web panel to track everything that is going through. By default, it can be found on `/_system/gui`. Example: `localhost:8080/_system/gui`.
 
-Simple examples can be found in [expectation creation API](#create-expectation)
+### Storage & Containers
 
-# Expectations
+Storage provides access to read/write **Containers**—temporary cells used to sync expectations or store data between requests. Containers have a configurable TTL (Time to Live) and can be merged or assigned new payloads.
 
-## Schema
+### Cache
 
-An expectation schema can contain some rules to handle `request`, `response` and `forward`
+Cache is used to store payloads of forwarded requests, powered by [ioredis](https://www.npmjs.com/package/ioredis). It allows for long-term persistence of mocked responses from real backends.
 
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| request | [Operators](#operators) | `object` | * | Describes a way to catch by request and how to manipulate it |
-| response | [Operators](#operators) | `object` | * | Describes how to manipulate response. Also can be used to catch response in case of forwarding |
-| forward | [Forwarding](#forwarding) | `object` | * | Describes configuration to forward a request to another host |
+### State & Seeds
 
-**Example**
+- **State**: A unique storage for each individual request, typically extracted from headers. By default, it's extracted from the `X-Use-Mock-State` header (JSON in Base64).
+- **Seeds**: Help generate consistent random data using [faker](https://www.npmjs.com/package/@faker-js/faker). By default, the seed value is extracted from the `X-Use-Mock-Seed` header. You can also manually set the seed within an expectation using the `seed` location:
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $and: [],
-    },
-    response: {
-      $or: [],
-    },
-    forward: {
-      baseUrl: 'https://example.com',
-      url: '/some/path',
-    },
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/faker' }),
+      // Manually set seed from query parameter or any other logic
+      $.set('seed', { $exec: (seed, { context }) => context.incoming.query.seed ?? context.seed ?? 12345 }),
+    ]),
+    response: $.set('outgoing.data', {
+      $exec: (payload, { faker }) => ({
+        id: faker.number.int(), // Will be consistent for the same seed
+        name: faker.person.fullName(),
+      }),
+    }),
   },
-});
+}));
 ```
 
-## Forwarding
-
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| url | | `string` | * | Absolute URL to target |
-| baseUrl | | `string` | * | Base URL to target. The path will be provided from request |
-| options | | `string` | * | Forwarding options |
-| | host | `origin` | * | Provides `Host` header as same as mock server host (if not specified). If specified to `origin` then value for `Host` header will be taken from url |
-| cache | | `object` | * | [Cache](#cache) configuration for a payload of forwarded requests |
-| | storage | `redis` | * | Storage to read/write a cache |
-| | key | `string` | * | Key to get read/write access of cached payload |
-| | prefix | `string` | * | Prefix of the `key` of cache |
-| | ttl | `number` | * | Time to live of cache in seconds |
-
-## Context
-
-| Property | Nested | `$location` | Type | Optional | Description |
-|--|--|--|--|--|--|
-| storage | [Storage](#storage) | | `object` | | A storage of `container` entities |
-| container | [Container](#containers) | `container` | `object` | * | A temporary cell in `storage`. Should be useful to sync expectations between each other or store and use any data each request |
-| state | | `state` | `object` | | An [object](#state) with custom data |
-| seed | | `seed` | `string` | * | Incoming request [seed](#seeds) |
-| cache | | `cache` | `object` | | [Cache](#cache) configuration |
-| | isEnabled | | `boolean` | | Toggle of cache usage |
-| | key | | `string ∣ object` | * | Key to get read/write access of cached payload. Value provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm  |
-| | prefix | | `string` | * | Prefix of the `key` of cache |
-| | ttl | | `number` | * | Time to live of cache in seconds |
-| incoming | | | `object` | | Payload with data of incoming request |
-| | path | `path` | `string` | | Incoming request path |
-| | method | `method` | `string` | | Incoming request method in **uppercase** |
-| | headers | `incoming.headers` | `object` | | Incoming request headers with keys in **lowercase** |
-| | dataRaw | `incoming.dataRaw` | `string` | | Incoming request source data |
-| | data | `incoming.data` | `object` | * | Incoming request parsed data |
-| | query | `incoming.query` | `object` | * | Incoming request query search parameters |
-| | delay | `delay` | `number` | * | Delay that can be applied with [operators](#operators) |
-| | error | `error` | `string` | * | Error that can be applied with [operators](#operators) |
-| outgoing | | | `object` | | Payload with data of response |
-| | status | `outgoing.status` | `number` | | Response status code |
-| | headers | `outgoing.headers` | `number` | | Response headers |
-| | dataRaw | `outgoing.dataRaw` | `string` | | Response source data |
-| | data | `outgoing.data` | `any` | * | Response data |
-
-## Utils
-
-Additional utils in `$exec` operator
-
-| Property | Description |
-|--|--|
-| `context` | A request [context](#context) |
-| `logger` | [Logger](#logger) of mock server |
-| `mode` | A mode of expectation execution. Has `match` on catching request or `manipulate` on manipulation over [context](#context) |
-| `meta` | A [meta](#meta) of a request |
-| `_` | [Lodash](https://www.npmjs.com/package/lodash) |
-| `d` | [DayJS](https://www.npmjs.com/package/dayjs) |
-| `faker` | [Faker](https://www.npmjs.com/package/@faker-js/faker). Uses [seed](#seeds) if it was provided |
-
-## Operators
-
-> **!NOTE** Each schema that using operators can have only one nested operator. To use more than one operator use `$and` or `$or` operators
-
-| Operator | Optional | Description |
-|--|--|--|
-| [$has](#has) | * | Catches a request/response or checks a payload in [context](#context) |
-| [$set](#set) | * | Sets payload in [context](#context) |
-| [$merge](#merge) | * | Merges object payload in [context](#context) with provided `$value` |
-| [$remove](#remove) | * | Removes payload in [context](#context) |
-| [$exec](#exec) | * | Function to catch a request/response or check/manipulate payload in [context](#context) |
-| [$and](#and) | * | Logical `and` |
-| [$or](#or) | * | Logical `or` |
-| [$not](#not) | * | Logical `not` |
-| [$if](#if) | * | Logical `if` |
-| [$switch](#switch) | * | Logical `switch/case` |
-
-**Example**
-
-```ts
-await server.client.createExpectation({
+## Mock Server Utilities
+
+### Expectation Operators ($)
+
+Expectations are built using operators that define how to match requests and transform responses.
+
+- `$.has(location, { $path, ... })`: Checks if a value exists at the specified path. Supports `$value`, `$match` (minimatch), `$regExp`, and `$exec`.
+- `$.set(location, { $value, ... })`: Sets a value at the specified path.
+- `$.merge(location, { $value, ... })`: Merges an object into the value at the specified path.
+- `$.remove(location, { $path, ... })`: Removes the value at the specified path.
+- `$.and([...operators])`: Logical AND of multiple operators.
+- `$.or([...operators])`: Logical OR of multiple operators.
+- `$.not(operator)`: Logical NOT of an operator.
+- `$.if({ $condition, $then, $else })`: Conditional execution of operators.
+- `$.switch({ $cases, $default })`: Switch-case execution based on the value at the path.
+- `$.exec(fn)`: Executes custom logic. In `match` mode, it must return a boolean. In `manipulate` mode, it can modify the context.
+
+### Operator Locations
+
+Many operators (like `$.has`, `$.set`, `$.merge`) accept a `location` as their first argument. This defines where the operation should be performed:
+
+- `'incoming.path'`: The URL path of the request.
+- `'incoming.method'`: The HTTP method.
+- `'incoming.query'`: The query parameters object.
+- `'incoming.headers'`: The request headers object.
+- `'incoming.data'`: The request body (parsed JSON or XML).
+- `'outgoing.status'`: The response status code.
+- `'outgoing.headers'`: The response headers object.
+- `'outgoing.data'`: The response body object.
+- `'container'`: Access to a [Container](#container-methods).
+- `'state'`: Access to [Request State](#request-state).
+- `'cache'`: Access to [Forward Cache](#conditional-caching) configuration.
+- `'seed'`: Access to the [Seed](#state--seeds) value.
+- `'error'`: For [Simulating Network Errors](#simulating-network-errors).
+
+When targeting an object (like `headers` or `data`), you can use `$path` as the second argument to target a nested value:
+`$.has('incoming.headers', '$path', 'content-type', { $value: 'application/json' })`
+
+### Operator Context
+
+When using `$exec`, the second argument provides a context with useful utilities and data:
+
+- **`context`**: The full request/response context.
+  - `incoming`: Input data (immutable in match mode).
+    - `path`: The request URL path.
+    - `method`: HTTP method (GET, POST, etc.).
+    - `query`: Object containing query parameters.
+    - `headers`: Object containing request headers.
+    - `data`: Parsed JSON/XML request body.
+  - `outgoing`: Output data (target for manipulation).
+    - `status`: HTTP status code.
+    - `headers`: Response headers.
+    - `data`: Response body object (serialized to JSON/XML).
+    - `dataRaw`: Buffer for binary data.
+    - `stream`: Observable for WebSocket messages.
+  - `storage`: Interface to manage [Containers](#container-methods).
+  - `container`: The currently bound container (if any).
+  - `cache`: Configuration for forwarding cache.
+    - `isEnabled`: Whether caching is enabled for this request.
+    - `prefix`: Redis key prefix.
+    - `key`: Custom cache key (string or object).
+    - `ttl`: Time to live in seconds.
+    - `hasRead`: (Internal) Whether cache was read.
+    - `hasWritten`: (Internal) Whether cache was written.
+- **`state`**: The unique [Request State](#state--seeds). Persistent only for the duration of the current request.
+- **`mode`**: The execution phase: `'match'` (deciding if expectation applies) or `'manipulate'` (preparing the response).
+- **`logger`**: A scoped logger for debugging (`info`, `error`, `warn`).
+- **`faker`**: Full `@faker-js/faker` instance for generating mock data.
+- **`_`**: Lodash utility library.
+- **`d`**: Dayjs instance for date/time manipulation.
+- **`rx`**: RxJS exports for advanced WebSocket stream control.
+
+### Container Methods
+
+Containers (accessible via `context.storage`) provide several methods for managing data:
+
+- `storage.provide({ key, payload, ttl })`: Retrieves an existing container by key or creates a new one with the provided payload and TTL.
+- `storage.register({ key, payload, ttl })`: Forcefully creates and registers a new container, overwriting any existing one with the same key.
+- `storage.find(key)`: Finds an existing container by key. Returns `undefined` if not found.
+- `container.assign(payload | fn)`: Shallows merges the given payload into the current container state. If a function is provided, it receives the current payload and returns the new one.
+- `container.merge(payload | fn)`: Deeply merges the given payload into the current container state.
+- `container.bind(key)`: Binds the container to an additional key.
+- `container.unbind()`: Removes the container from the storage.
+
+## Usage
+
+### Complex Expectations with `$and`
+
+You can group multiple conditions using logical operators like `$.and`, `$.or`, and `$.not` to create sophisticated matching rules.
+
+```ts
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $and: [
-        {
-          $has: {
-            $location: 'path',
-            $value: '/foo',
-          },
-        },
-        {
-          $has: {
-            $location: 'method',
-            $value: 'GET',
-          },
-        },
-      ],
-    },
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/user' }),
+      $.has('incoming.method', { $value: 'POST' }),
+      // Checks if 'content-type' header equals 'application/json' using selection with $path = content-type
+      $.has('incoming.headers', '$path', 'content-type', { $value: 'application/json' }),
+    ]),
+    response: $.set('outgoing.data', { $value: { status: 'success' } }),
   },
-});
+}));
 ```
 
-### $has
+### Custom Logic with `$exec`
 
-> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
-
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
-| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
-| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
-| $value | `any` | `any` | * | Checks by value equality in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $valueAnyOf | `any[]` | `any[]` | * | Checks by any of value equality in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $regExp | `RegExp` | `{ source: string, flags?: string }` | * | Checks by regular expression in context using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $regExpAnyOf | `RegExp[]` | `{ source: string, flags?: string }[]` | * | Checks by any of regular expression in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $match | `string ∣ object` | `string ∣ object` | * | Checks by minimatch for `string` and `number` (example `/foo/*/bar` or `2**`) or similar `object` by passing object payload in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $matchAnyOf | `(string ∣ object)[]` | `(string ∣ object)[]` | * | Checks by any of minimatch for `string` and `number` (example `/foo/*/bar` or `2**`) or similar `object` by passing object payload in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $exec | `(payload, utils) => boolean` | `string` | * | Checks payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
-
-**Example using application**
+For scenarios that require dynamic calculations or external utilities, use the `$exec` operator.
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $has: {
-        $location: 'path',
-        $regExp: /^\/foo/,
-      },
-    },
+    request: $.has('incoming.path', {
+      // Custom matching logic: checks if path starts with '/api/data'
+      $exec: (path) => path.startsWith('/api/data')
+    }),
+    response: $.set('outgoing.data', {
+      // Use built-in utils like lodash (_), dayjs (d), or faker
+      $exec: (payload, { _, d, faker }) => ({
+        id: faker.string.uuid(),
+        timestamp: d().format(),
+        values: _.range(3).map(() => _.random(1, 100)),
+      }),
+    }),
   },
-});
-```
-
-**Example using cURL**
+}));
 
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$has": {
-        "\$location": "method",
-        "\$regExp": { "source": "^\/foo" }
+// Use $.exec for full control over the expectation execution
+await server.client.createExpectation(({ $ }) => ({
+  schema: {
+    request: $.exec(({ context, logger, mode }) => {
+      // mode can be 'match' (on catching request) or 'manipulate' (on manipulation)
+      if (mode === 'match') {
+        logger.info('Checking request path', context.incoming.path);
+        return context.incoming.path === '/api/custom';
       }
-    }
-  }
-}
-EOF
+    }),
+    response: $.set('outgoing.data', { $value: { status: 'custom' } }),
+  },
+}));
 ```
 
-### $set
+### Dynamic Response Manipulation
 
-> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
-
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
-| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
-| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
-| $value | `any` | `any` | * | Sets value to [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $exec | `(payload, utils) => any` | `string` | * | Sets payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
-
-**Example using application**
+You can dynamically adjust the response payload based on incoming request parameters (query, body, headers, etc.).
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $set: {
-        $location: 'incoming.data',
-        $path: 'foo',
-        $exec: (payload, { _ }) => _.clamp(payload, 0, 10),
-      },
-    },
+    request: $.has('incoming.path', { $value: '/api/profile' }),
+    response: $.set('outgoing.data', {
+      $exec: (payload, { context }) => ({
+        id: context.incoming.query.userId,
+        // Conditionally include data based on request headers
+        debug: context.incoming.headers['x-debug'] === 'true'
+          ? { timestamp: Date.now() }
+          : undefined
+      })
+    }),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$set": {
-        "\$location": "incoming.data",
-        "\$path": "foo",
-        "\$exec": "_.clamp(payload, 0, 10)"
-      }
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $merge
+### Binary Data and Files
 
-> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
-
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
-| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
-| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
-| $value | `object` | `object` | * | Merges value in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
-| $exec | `(payload, utils) => any` | `string` | * | Merges payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
-
-**Example using application**
+You can return binary data (Buffers) as a response body. This is useful for mocking file downloads or image responses.
 
 ```ts
-await server.client.createExpectation({
+import { readFile } from 'fs/promises';
+
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $merge: {
-        $location: 'incoming.data',
-        $value: { has_mocked: true },
-      },
-    },
+    request: $.has('incoming.path', { $value: '/api/download' }),
+    response: $.and([
+      $.set('outgoing.headers', '$path', 'content-type', { $value: 'application/pdf' }),
+      $.set('outgoing.dataRaw', {
+        $exec: async () => await readFile('./path/to/document.pdf')
+      }),
+    ]),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$merge": {
-        "\$location": "incoming.data",
-        "\$value": {"has_mocked": true}
-      }
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $remove
+### XML Support
 
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
-| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
-| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
-
-**Example using application**
+The mock server provides native support for XML payloads via [fast-xml-parser](https://www.npmjs.com/package/fast-xml-parser) with `ignoreAttributes: false`. It automatically parses incoming XML and can serialize objects back to XML in the response.
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $remove: { $location: 'outgoing.data' },
-    },
+    request: $.and([
+      $.has('incoming.path', { $matchAnyOf: ['/api/user*'] }),
+      $.exec(({ context }) => context.incoming.headers['content-type'] === 'application/xml'),
+    ]),
+    response: $.and([
+      $.set('outgoing.headers', '$path', 'content-type', { $value: 'application/xml' }),
+      $.set('outgoing.data', {
+        $value: {
+          user: {
+            info: {
+              '#text': 'John Doe',
+              '@_type': 'mocked',
+              '@_id': 123
+            }
+          },
+        },
+      }),
+    ]),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$remove": {"\$location": "outgoing.data"}
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $exec
+### Simulating Network Errors
 
-> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
-
-| Type (application) | Type (cURL) | Description |
-|--|--|--|
-| `(utils) => boolean ∣ unknown` | `string` | Does something you want or catch request/response payload in [context](#context) by function with arguments where `utils` is [utils](#utils) |
-
-**Example using application**
+You can simulate connection drops or network errors by setting the `error` property.
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $exec: ({ context, logger }) => {
-        logger.info(context);
-        return context.incoming.path === '/foo';
-      },
-    },
+    request: $.has('incoming.path', { $value: '/api/error' }),
+    response: $.set('error', {
+      // Common error codes: ECONNRESET, ECONNABORTED, etc.
+      $value: 'ECONNRESET'
+    }),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$exec": "{ logger.info(context); return context.incoming.path === '/foo' }"
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $and
-
-| Type (application) | Type (cURL) | Description |
-|--|--|--|
-| `object[]` | `object[]` | Provides [operators](#operators) schemas |
+### Disabled by Default
 
-**Example using application**
+You can create expectations that are disabled by default by setting `isEnabled: false`. These can be manually enabled later via the [GUI](#gui).
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $ }) => ({
+  isEnabled: false,
   schema: {
-    request: {
-      $and: [
-        { $has: { $location: 'path', $match: 'foo/*' } },
-        { $has: { $location: 'method', $valueAnyOf: ['GET', 'POST'] } },
-      ],
-    },
+    request: $.has('incoming.path', { $value: '/api/hidden' }),
+    response: $.set('outgoing.data', { $value: { message: 'Activate me in GUI' } }),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$and": [
-        {"\$has": {"\$location": "path", "\$match": "foo/*"}},
-        {"\$has": {"\$location": "method", "\$valueAnyOf": ["GET", "POST"]}}
-      ]
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $or
-
-| Type (application) | Type (cURL) | Description |
-|--|--|--|
-| `object[]` | `object[]` | Provides [operators](#operators) schemas |
+### Type Safety
 
-**Example using application**
+You can provide generic types to `createExpectation` to ensure your schemas and `$exec` functions are fully typed.
 
 ```ts
-await server.client.createExpectation({
-  schema: {
-    request: {
-      $or: [
-        { $has: { $location: 'path', $match: 'foo/*' } },
-        { $has: { $location: 'method', $valueAnyOf: ['GET', 'POST'] } },
-      ],
-    },
-  },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$or": [
-        {"\$has": {"\$location": "path", "\$match": "foo/*"}},
-        {"\$has": {"\$location": "method", "\$valueAnyOf": ["GET", "POST"]}}
-      ]
-    }
-  }
+interface MyContext {
+  incoming: {
+    query: {
+      userId: string;
+      expand?: boolean;
+    };
+  };
+  outgoing: {
+    data: {
+      id: string;
+      name: string;
+    };
+  };
 }
-EOF
-```
-
-### $not
 
-| Type (application) | Type (cURL) | Description |
-|--|--|--|
-| `object` | `object` | Provides an [operators](#operators) schema |
-
-**Example using application**
-
-```ts
-await server.client.createExpectation({
+await server.client.createExpectation<MyContext>(({ $ }) => ({
   schema: {
-    request: {
-      $not: { $has: { $location: 'path', $match: 'foo/*' } },
-    },
+    request: $.has('incoming.query', {
+      $exec: (query) => query.userId === '123'
+    }),
+    response: $.set('outgoing.data', {
+      $exec: (payload, { faker }) => ({
+        id: '123',
+        name: faker.person.fullName()
+      })
+    }),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$not": {"\$has": {"\$location": "path", "\$match": "foo/*"}}
-    }
-  }
-}
-EOF
+}));
 ```
 
-### $if
+### WebSocket Support
 
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $condition | `object` | `object` | | Condition to check. Should contain one of `$and`, `$exec`, `$has`, `$or` or `$not` [operators](#operators) schema |
-| $then | `object` | `object` | * | Logical `then`. Should contain an [operators](#operators) schema |
-| $else | `object` | `object` | * | Logical `else`. Should contain an [operators](#operators) schema |
-
-**Example using application**
+The mock server provides first-class support for WebSockets, allowing you to intercept and mock streaming data using [RxJS](https://rxjs.dev/).
 
 ```ts
-await server.client.createExpectation({
+await server.client.createExpectation(({ $, utils }) => ({
+  // 1. Specify 'ws' transport
+  transports: utils.transports(['ws']),
+
   schema: {
-    request: {
-      $if: {
-        $condition: { $has: { $location: 'path', $match: 'foo/*' } },
-        $then: { $set: { $location: 'delay', $value: 5000 } },
-        $else: { $set: { $location: 'error', $value: 'ECONNABORTED' } },
-      },
-    },
+    request: $.has('incoming.path', { $value: '/ws/updates' }),
+    response: $.and([
+      // 2. Set custom WS status code if needed
+      $.set('outgoing.status', { $value: 1000 }),
+      // 3. Define the outgoing stream
+      $.set('outgoing.stream', {
+        $exec: (stream, { rx }) => {
+          // Return an Observable of messages
+          return rx.from([
+            { event: 'connected' },
+            { event: 'data', value: 1 },
+            { event: 'data', value: 2 },
+          ]);
+        },
+      }),
+    ]),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$if": {
-        "\$condition": {"\$has": {"\$location": "path", "\$match": "foo/*"}},
-        "\$then": {"\$set": {"\$location": "delay", "\$value": 5000}},
-        "\$else": {"\$set": {"\$location": "error", "\$value": "ECONNABORTED"}}
-      }
-    }
-  }
-}
-EOF
+}));
 ```
 
- ### $switch
-
-> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
-
-| Property | Type (application) | Type (cURL) | Optional | Description |
-|--|--|--|--|--|
-| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
-| $cases | `Record<string ∣ number, object>` | `Record<string ∣ number, object>` | | An object where `key` is an extracted value from [enum](#context) using `$location` (and `$path`, `$exec` if it was specified) and `value` is an [operators](#operators) schema |
-| $default | `object` | `object` | * | Default behavior as an [operators](#operators) schema |
-| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
-| $exec | `(payload, utils) => any` | `string` | * | Sets payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` and `utils` is [utils](#utils) |
+### Request Forwarding
 
-**Example using application**
+You can forward requests to an external API and manipulate the response before it's returned to the client.
 
- ```ts
-await server.client.createExpectation({
+```ts
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: {
-      $switch: {
-        $location: 'method',
-        $cases: {
-          'GET': { $set: { $location: 'delay', $value: 2000 } },
-          'POST': { $set: { $location: 'delay', $value: 5000 } },
-        },
-        $default: {
-          $set: { $location: 'error', $value: 'ECONNABORTED' }
-        },
-      },
+    request: $.has('incoming.path', { $value: '/api/proxy' }),
+    // Forward the request to an external service
+    forward: {
+      url: 'https://api.external-service.com/data',
     },
+    // Manipulate the response from the external service
+    response: $.set('outgoing.data', {
+      $exec: (data) => ({
+        ...data,
+        source: 'mock-server',
+        timestamp: new Date().toISOString(),
+      }),
+    }),
   },
-});
-```
-
-**Example using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$switch": {
-        "\$location": "method",
-        "\$cases": {
-          "GET": {"\$set": {"\$location": "delay", "\$value": 2000}},
-          "POST": {"\$set": {"\$location": "delay", "\$value": 5000}}
-        },
-        "\$default": {
-          "\$set": {"\$location": "error", "\$value": "ECONNABORTED"}
-        }
-      }
-    }
-  }
-}
-EOF
+}));
 ```
 
-## Typings
-
-The application client lib provides approach to keep typings using function predicate to `create` or `update` expectation with a generic argument. The generic type should have the same schema like [context](#context)
+### Using Relative Paths with `baseUrl`
 
-The function predicate provides an object argument with `$` that contains simplified API to build typed expectation schemas. Some operators have `using` predicate that can contain `$path`, `$jsonPath` or `$exec` selectors
-
-**Examples**
+When using `baseUrl`, the original request path is appended to the target URL.
 
 ```ts
-await client.createExpectation<{
-  incoming: {
-    query: {
-      foo: 'a' | 'b' | 'c';
-      bar?: string;
-    };
-  };
-}>(({ $ }) => ({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    request: $.or([
-      $.has('incoming.query', '$path', 'foo', { $value: 'a' }),
-      $.has('incoming.query', { $match: { foo: 'b' } }),
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/v1/*' }),
+      // Rewrite the path from v1 to v2 before forwarding
+      $.set('incoming.path', {
+        $exec: (path) => path.replace('/v1/', '/v2/'),
+      }),
     ]),
+    forward: {
+      // If request is '/api/v1/users', it forwards to 'https://legacy-api.com/api/v2/users'
+      baseUrl: 'https://legacy-api.com',
+    },
+    response: $.set('outgoing.headers', '$path', 'x-proxied-by', { $value: 'mock-server' }),
   },
 }));
 ```
 
+### Transforming Request Data Before Forwarding
+
+You can also modify the request body or headers before they are sent to the target API.
+
 ```ts
-await client.createExpectation<{
+interface SearchRequest {
   incoming: {
-    query: {
-      foo: 'a' | 'b' | 'c';
-      bar?: string;
-    };
-  };
-  outgoing: {
     data: {
-      foo: 'a' | 'b' | 'c';
-      bar?: {
-        baz: 'a' | 'b' | 'c';
-      };
+      query: string;
+      limit?: number;
     };
   };
-}>(({ $ }) => ({
-  schema: {
-    response: $.and([
-      $.switch('incoming.query', '$exec', (payload) => payload.foo, {
-        $cases: {
-          'a': $.set('outgoing.data', '$path', 'bar.baz', { $value: 'a' }),
-          'b': $.set('outgoing.data', '$path', 'bar.baz', { $value: 'b' }),
-        },
-      }),
+}
 
-      $.switch('incoming.query', '$path', 'bar', {
-        $cases: {
-          'something': $.set('outgoing.data', '$path', 'bar.baz', { $value: 'c' }),
-        },
+await server.client.createExpectation<SearchRequest>(({ $ }) => ({
+  schema: {
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/search' }),
+      // Inject API key and transform data before forwarding
+      $.merge('incoming.headers', { $value: { 'X-API-Key': 'secret-token' } }),
+      $.set('incoming.data', {
+        $exec: (data) => ({
+          ...data,
+          limit: data.limit ?? 20,
+          q: data.query, // Rename 'query' to 'q' for the external API
+        })
       }),
     ]),
+    forward: {
+      url: 'https://external-search-service.com/v1/query',
+    },
   },
 }));
 ```
 
-## Storage
-
-Storage is a temporary storage that provides an access to read/write [containers](#containers)
-
-| Property | Type | Description |
-|--|--|--|
-| find | `(key: string ∣ object) => Container ∣ null` | Finds a container in storage. Every `key` provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm |
-| delete | `(key: string ∣ object) => Container ∣ null` | Deletes a container in storage. Every `key` provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm |
-| register | `(configuration: Container) => Container` | Registers a container in storage (overrides if existent) |
-| provide | `(configuration: Container) => Container` | Finds or registers a container in storage |
-
-As a temporary storage it has a job to garbage an expired containers. Use `containers.expiredCleaningInterval` to setup an interval of clearance in [configuration](#configuration)
-
-> **!NOTE** See example of usage in [containers](#containers) section below
-
-## Containers
-
-| Property | Type | Description |
-|--|--|--|
-| key | `string` | A key of container |
-| prefix | `string` | A prefix of container |
-| payload | `object` | An object with custom data |
-| ttl | `number` | Time to live of container in seconds **(default: 1h)** |
-| expiresAt | `number` | An expiration date/time as unix timestamp with milliseconds |
-| bind | `(key: string ∣ object) => Container` | Binds a container to one more key. Every `key` provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm |
-| unbind | `(key: string ∣ object) => Container` | Unbinds a container from key. Every `key` provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm |
-| assign | `(payload: object ∣ (payload: object) => object) => Container` | Uses as payload predicate to assign payload values to existent |
-| merge | `(payload: object ∣ (payload: object) => object) => Container` | Uses as payload predicate to deep merge of payload values with existent |
+### WebSocket Forwarding and Manipulation
 
-
-**Example**
+You can forward WebSocket connections to a real server and manipulate the message stream on the fly.
 
 ```ts
-await client.createExpectation<{
-  container: {
-    counter: number;
-  };
-}>(({ $ }) => ({
-  schema: {
-    request: $.set('container', {
-      $exec: (container, { context }) => context.storage
-        .provide({ key: 'foo', payload: { counter: 0 } })
-        .assign((payload) => ({ counter: payload.counter + 1 }))
-    }),
+await server.client.createExpectation(({ $, utils }) => ({
+  transports: utils.transports(['ws']),
 
-    response: $.set('outgoing.data', {
-      $exec: (payload, { context }) => ({
-        count: context.container!.payload.counter,
-      }),
+  schema: {
+    request: $.has('incoming.path', { $value: '/ws/proxy' }),
+    forward: {
+      baseUrl: 'wss://real-server.com',
+    },
+    response: $.set('outgoing.stream', {
+      $exec: (stream, { rx }) => {
+        // 'stream' is the Observable from the real server
+        return stream?.pipe(
+          // Inject extra message at the beginning
+          rx.startWith({ event: 'proxy-init', timestamp: Date.now() }),
+          // Transform real messages
+          rx.map((message) => ({ ...message, intercepted: true }))
+        );
+      },
     }),
   },
 }));
 ```
 
-## Cache
-
-> **!NOTE** Cache is usable **only** to store a payload of forwarded requests
+### Conditional Caching
 
-To work with cache the mock server uses [ioredis](https://www.npmjs.com/package/ioredis) package
-
-To configure it use `database.redis` configuration on the mock server start options
-
-**Example**
+You can control when the mock server should cache a forwarded response. For example, only cache responses with a `200 OK` status.
 
 ```ts
-const server = await MockServer.start({
-  host: 'localhost',
-  port: 8080,
-
-  databases: {
-    redis: {
-      host: 'localhost',
-      port: 6379,
+await server.client.createExpectation(({ $ }) => ({
+  schema: {
+    request: $.has('incoming.path', { $value: '/api/cacheable' }),
+    forward: {
+      baseUrl: 'https://api.service.com',
+      cache: {
+        ttl: 3600, // 1 hour
+      },
     },
+    response: $.set('cache', '$path', 'isEnabled', {
+      $exec: (value, { context }) => context.outgoing.status === 200,
+    }),
   },
-});
+}));
 ```
 
-**How it works in steps?**
+### Custom Cache Key
 
-0. [Expectation schema](#schema) should have `forward` configuration specified
-1. Preparing incoming request...
-2. Preparing [request schema](#schema) in expectation...
-3. Setting up cache configuration from [context](#context) or [forward.cache](#forwarding)...
-4. If `cache.isEnabled` is equals `true` the mock server checks a cache using provided configuration
-5. If `key` was not provided a key for cache will calculated with `path`, `method`, `data` and `query` property values using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm
-6. If cache was found then step `7` is skipping
-7. Forwarding a request....
-8. Preparing [response schema](#schema) in expectation...
-9. Setting up cache configuration from [context](#context)...
-10. If `cache.isEnabled` is equals `true` the mock server will write a cache over provided `ttl`
-11. Replying...
-
-**Example**
+By default, the cache key is a hash generated from the `incoming` object (path, method, data, query). You can override this with a custom key.
 
 ```ts
-await client.createExpectation(({ $ }) => ({
+await server.client.createExpectation(({ $ }) => ({
   schema: {
-    response: $.set('cache', '$path', 'isEnabled', {
-      $exec: (payload, { context }) => context.outgoing.status < 400,
-    }),
-
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/cache-custom' }),
+      $.set('cache', '$path', 'key', {
+        // Use a specific header as the cache key
+        $exec: (key, { context }) => context.incoming.headers['x-user-id'],
+      }),
+    ]),
     forward: {
-      baseUrl: 'https://example.com',
-
+      baseUrl: 'https://api.service.com',
       cache: {
-        ttl: 30 * 24 * 60 * 60,
+        isEnabled: true,
+        ttl: 600,
       },
     },
   },
 }));
-```
-
-## State
-
-State is a unique storage of each request. It can be used to handle complex expectations
 
-By default an object of state extracts from `X-Use-Mock-State` in `incoming.headers` (as serialized json in **base64 encoding**) or creates an empty object
-
-**Example**
-
-```ts
-await client.createExpectation<{
-  state: {
-    id?: number;
-  };
-  incoming: {
-    query: {
-      foo: 'a' | 'b' | 'c';
-    };
-  };
-  outgoing: {
-    data: {
-      id: number;
-    };
-  };
-}>(({ $ }) => ({
+// You can also provide an object as a key; it will be automatically hashed
+await server.client.createExpectation(({ $ }) => ({
   schema: {
     request: $.and([
-      $.switch('incoming.query', '$exec', (payload) => payload.foo, {
-        $cases: {
-          'a': $.set('state', '$path', 'id', { $value: 1 }),
-          'b': $.set('state', '$path', 'id', { $value: 2 }),
-        },
+      $.has('incoming.path', { $value: '/api/cache-object' }),
+      $.set('cache', '$path', 'key', {
+        // Cache depends on specific properties of the incoming data
+        $exec: (key, { context }) => ({
+          id: context.incoming.data.id,
+          type: context.incoming.data.type,
+        }),
       }),
     ]),
-    response: $.set('outgoing.data', {
-      $exec: (payload, { state }) => ({ id: state.id ?? 0 }),
-    }),
+    forward: {
+      baseUrl: 'https://api.service.com',
+      cache: { isEnabled: true },
+    },
   },
 }));
 ```
 
-## Seeds
+### Request State
 
-Seeds can help to generate content with the same values each request using [faker](https://www.npmjs.com/package/@faker-js/faker)
-
-By default a number of seed takes from `X-Use-Mock-Seed` in `incoming.headers`
-
-**Example**
+State is a unique storage for each request. It can be used to pass data between operators or expectations. By default, it's extracted from the `X-Use-Mock-State` header (JSON in Base64).
 
 ```ts
-await client.createExpectation(({ $ }) => ({
+interface MyState {
+  state: {
+    internalId: number;
+  };
+}
+
+await server.client.createExpectation<MyState>(({ $ }) => ({
   schema: {
     request: $.and([
-      $.set('seed', { $exec: (seed) => seed ?? 123 }),
+      $.has('incoming.path', { $value: '/api/stateful' }),
+      $.set('state', {
+        // Compute and store data in state for later use
+        $exec: (state) => ({ internalId: state.internalId ?? Math.random() }),
+      }),
     ]),
     response: $.set('outgoing.data', {
-      $exec: (payload, { faker }) => ({
-        id: faker.number.int({ max: 1000, min: 500 }),
-        first_name: faker.person.firstName('male'),
-        last_name: faker.person.lastName('male'),
+      // Use the stored state in response building
+      $exec: (payload, { state }) => ({
+        id: state.internalId,
       }),
     }),
   },
 }));
 ```
 
-## XML
+### Storage and Containers
 
-The mock server uses the [fast-xml-parser](https://www.npmjs.com/package/fast-xml-parser) package to parse and serialize XML payload with options:
+Storage provides access to **Containers**—temporary cells used to store data between requests or sync multiple expectations. Unlike `state`, which is request-scoped, Containers are persistent until they expire (TTL).
 
 ```ts
-{
-  ignoreAttributes: false,
-}
-```
-
-To define a `incoming.data` as XML in incoming request `incoming.headers` should have `Content-Type: application/xml`.
-
-The same with `outgoing.data` and `outgoing.headers`
-
-**Example of serialized XML**
-
-```xml
-<tag type="default">
-    <nested type="nested">456</nested>
-    123
-</tag>
-```
-
-**Example of parsed XML**
-
-```json
-{
-  "tag":{
-    "nested":{
-      "#text":456,
-      "@_type":"nested"
-    },
-    "#text":123,
-    "@_type":"default"
-  }
+interface CounterContainer {
+  container: {
+    count: number;
+  };
 }
-```
-
-To parse an XML manually the application lib provides utils:
-
-```ts
-import { parsePayload, serializePayload } from '@n1k1t/mock-server';
-
-const parsed = parsePayload('xml', '<tag>123</tag>'); // { tag: 123 }
-const serialized = serializePayload('xml', parsed); // '<tag>123</tag>'
-```
-
-# API
-
-The mock server provides 3 different ways to work with. There are: `HTTP API` (eg using cURL), `RemoteClient` provided by application lib to connect and work with existent mock server on another host and `MockServer.client` on the same host (application script)
-
-The `HTTP API` and `RemoteClient` have some usage restrictions like:
-- Every `$exec` operator **cannot have an access to variables outside the function**. If you need to use some extra variables or modules that implemented in outer scope you have to use the `MockServer.client` to setup everything on the mock server side host
-- Plugins are not supported
-
-## Ping
-
-`INPUT` → `GET /_system/ping`
-
-`OUTPUT`
-
-| Type | Description |
-|--|--|
-| `string` | A `pong` message |
 
-**Using cURL**
-
-```bash
-curl -H "Content-type: application/json" --location "localhost:8080/_system/ping"
+await server.client.createExpectation<CounterContainer>(({ $ }) => ({
+  schema: {
+    request: $.set('container', {
+      $exec: (container, { context }) => context.storage
+        // provide() finds an existing container by key or creates a new one with the given payload
+        .provide({ key: 'my-counter', payload: { count: 0 } })
+        .assign((payload) => ({ count: payload.count + 1 })),
+    }),
+    response: $.set('outgoing.data', {
+      $exec: (payload, { context }) => ({
+        // Access the incremented value from the container
+        currentCount: context.container!.payload.count,
+      }),
+    }),
+  },
+}));
 ```
 
-**Using application lib on server side**
-
-```ts
-import { MockServer } from '@n1k1t/mock-server';
-
-const server = await MockServer.start({ host: 'localhost', port: 8080 });
-await server.client.ping();
-```
+### Cross-Expectation Sync
 
-**Using application lib on remotely**
+You can use Containers to synchronize data between different endpoints. For example, one endpoint increments a counter, and another retrieves its current value.
 
 ```ts
-import { RemoteClient } from '@n1k1t/mock-server';
-
-const client = await RemoteClient.connect({ host: 'localhost', port: 8080 });
-await client.ping();
-```
-
-## Create expectation
-
-`INPUT` → `POST /_system/expectations`
-
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| schema | [Schema](#schema) | `object` | | An expectation schema |
-| name | | `string` | * | A preferred name for an expectation |
-
-`OUTPUT`
-
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| id | | `string` | | An expectation ID |
-| name | | `string` | | An expectation name |
-| schema | [Schema](#schema) | `object` | | Provided schema |
-
-**Using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "schema": {
-    "request": {
-      "\$has": {
-        "\$location": "method",
-        "\$value": "GET"
-      }
-    }
-  }
+interface SyncContainer {
+  container: {
+    count: number;
+  };
 }
-EOF
-```
 
-**Using application lib on server side**
-
-```ts
-import { MockServer } from '@n1k1t/mock-server';
-
-const server = await MockServer.start({ host: 'localhost', port: 8080 });
-const expectation = await server.client.createExpectation({
+// Expectation 1: Increments the counter
+await server.client.createExpectation<SyncContainer>(({ $ }) => ({
+  name: 'Incrementer',
   schema: {
-    request: {
-      $has: {
-        $location: 'method',
-        $value: 'GET',
-      },
-    },
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/increment' }),
+      $.set('container', {
+        $exec: (container, { context }) => context.storage
+          .provide({ key: 'shared-counter', payload: { count: 0 } })
+          .assign((payload) => ({ count: payload.count + 1 })),
+      }),
+    ]),
+    response: $.set('outgoing.data', { $value: { status: 'incremented' } }),
   },
-});
-
-console.log('Mock expectation has created', expectation.id);
-```
-
-**Using application lib on remotely**
-
-```ts
-import { RemoteClient } from '@n1k1t/mock-server';
+}));
 
-const client = await RemoteClient.connect({ host: 'localhost', port: 8080 });
-const expectation = await client.createExpectation({
+// Expectation 2: Retrieves the current value
+await server.client.createExpectation<SyncContainer>(({ $ }) => ({
+  name: 'Getter',
   schema: {
-    request: {
-      $has: {
-        $location: 'method',
-        $value: 'GET',
-      },
-    },
+    request: $.and([
+      $.has('incoming.path', { $value: '/api/count' }),
+      $.set('container', {
+        $exec: (container, { context }) => context.storage
+          .provide({ key: 'shared-counter', payload: { count: 0 } }),
+      }),
+    ]),
+    response: $.set('outgoing.data', {
+      $exec: (payload, { context }) => ({
+        total: context.container!.payload.count,
+      }),
+    }),
   },
-});
-
-console.log('Mock expectation has created', expectation.id);
+}));
 ```
 
-## Update expectation
-
-`INPUT` → `PUT /_system/expectations`
-
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| id | | `string` | | ID of a registered expectation |
-| set | | `object` | | A payload to set |
-| | name | `string` | * | A preferred name for an expectation |
-| | schema | [Schema](#schema) | * | An expectation schema |
+## Extensions
 
-`OUTPUT`
+### Redis Configuration
 
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| id | | `string` | | An expectation ID |
-| name | | `string` | | An expectation name |
-| schema | [Schema](#schema) | `object` | | Provided schema |
-
-**Using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X PUT --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "id": "...",
-  "set": {"name": "The expectation"}
-}
-EOF
-```
-
-**Using application lib on server side**
+The mock server uses Redis for caching forwarded responses and persistent storage. You can configure the connection details during server startup.
 
 ```ts
 import { MockServer } from '@n1k1t/mock-server';
 
-const server = await MockServer.start({ host: 'localhost', port: 8080 });
-const expectation = await server.client.updateExpectation({
-  id: '...',
-  set: { name: 'The expectation' }
+const server = await MockServer.start({
+  host: 'localhost',
+  port: 8080,
+  databases: {
+    redis: {
+      host: 'localhost',
+      port: 6379,
+      // Optional: password, keyPrefix, etc.
+      keyPrefix: 'my-mock-server:',
+    },
+  },
 });
-
-console.log('Mock expectation has updated', expectation);
 ```
 
-**Using application lib on remotely**
+### Remote Expectations with `RemoteClient`
+
+The `RemoteClient` allows you to manage expectations on a running mock server instance from a remote application or a separate test suite.
 
 ```ts
 import { RemoteClient } from '@n1k1t/mock-server';
 
-const client = await RemoteClient.connect({ host: 'localhost', port: 8080 });
-const expectation = await client.updateExpectation({
-  id: '...',
-  set: { name: 'The expectation' }
-});
-
-console.log('Mock expectation has updated', expectation);
-```
-
-## Delete expectation
+// 1. Connect to a running mock server
+const client = await RemoteClient.connect({ baseUrl: 'http://localhost:8080' });
 
-`INPUT` → `DELETE /_system/expectations`
+// 2. Create expectations remotely
+await client.createExpectation(({ $, utils }) => ({
+  // Specify allowed transports (http, ws)
+  transports: utils.transports(['http']),
 
-| Property | Nested | Type | Optional | Description |
-|--|--|--|--|--|
-| ids | | `string[]` | * | An expectation IDs list to delete. Or **delete all expectations** if not provided |
-
-**Using cURL**
-
-```bash
-curl -H "Content-type: application/json" -X DELETE --location "localhost:8080/_system/expectations" --data-binary @- << EOF
-{
-  "ids": ["..."]
-}
-EOF
+  schema: {
+    request: $.has('path', { $value: '/api/remote-mock' }),
+    response: $.set('outgoing.data', { $value: { success: true, source: 'remote-client' } }),
+  },
+}));
 ```
 
-**Using application lib on server side**
+### Grouping with Providers
 
-```ts
-import { MockServer } from '@n1k1t/mock-server';
-
-const server = await MockServer.start({ host: 'localhost', port: 8080 });
-await server.client.deleteExpectations({
-  ids: ['...'],
-});
-```
-
-**Using application lib on remotely**
+Providers allow grouping expectations and isolating them from each other. They are also used to route requests to specific sets of expectations based on path patterns.
 
 ```ts
-import { RemoteClient } from '@n1k1t/mock-server';
-
-const client = await RemoteClient.connect({ host: 'localhost', port: 8080 });
-await client.deleteExpectations({
-  ids: ['...'],
-});
-```
+import { MockServer, Provider } from '@n1k1t/mock-server';
 
-# Additional
+// 1. Define providers for different modules
+const authProvider = Provider.build({ group: 'auth' });
+const userProvider = Provider.build({ group: 'users' });
 
-## Configuration
-
-> **!NOTE** Configuration must be provided in the same script like mock server
-
-```ts
-import { config } from '@n1k1t/mock-server';
+// 2. Setup server
+const server = await MockServer.start({ port: 13000 });
 
-config.merge({
-  logger: {
-    level: 'D', // Logger level (default: D)
+// 3. Add expectations to specific providers
+await authProvider.client.createExpectation(({ $ }) => ({
+  schema: {
+    request: $.has('path', { $value: '/api/auth/login' }),
+    response: $.set('outgoing.data', { $value: { token: 'secret-token' } }),
   },
+}));
 
-  history: {
-    limit: 100, // Limit for history of requests (default: 100)
+await userProvider.client.createExpectation(({ $ }) => ({
+  schema: {
+    request: $.has('path', { $value: '/api/users/me' }),
+    response: $.set('outgoing.data', { $value: { id: 1, name: 'John' } }),
   },
+}));
 
-  containers: {
-    expiredCleaningInterval: 60 * 60, // Expired containers cleaning interval in seconds (default: 1h)
-  },
-});
+// 4. Setup routing
+server.router
+  .register('/api/auth/**', { provider: authProvider })
+  .register('/api/users/**', { provider: userProvider });
 ```
 
-## Logger
+### Logger
 
-> **!NOTE** Configuration must be provided in the same script like mock server
+You can customize how the mock server logs information by using serializers or by redirecting logs to an external logger (e.g., Sentry, Winston).
 
 ```ts
 import { Logger } from '@n1k1t/mock-server';
 
-// It defines your own logger methods
 Logger.useExternal({
-  debug: (...messages: string[]) => console.debug(...messages),
-  info: (...messages: string[]) => console.log(...messages),
-  warn: (...messages: string[]) => console.warn(...messages),
-  error: (...messages: string[]) => console.error(...messages),
-  fatal: (...messages: string[]) => console.error(...messages),
-});
-
-// It defines a JSON serializers to mask some private data by keys on objects
-Logger.useSerializers({
-  cvv: () => '***',
-  card: (payload: string) => payload.slice(0, 8) + 'xxxx',
+  info: (title, ...messages) => {
+    // Send to your logging service
+    console.log(`[${title}]`, ...messages);
+  },
+  error: (title, ...messages) => {
+    // Handle errors specifically
+  },
 });
 ```
 
-## Meta
-
-Some loggers (like `banyan` and etc) provide a meta context for logs with some data. To keep a meta contexts between requests the mock server provides a `metaStorage` using native node `AsyncLocalStorage`.
-
-The `metaStorage.provide()` returns an instance of `meta` that contains basic data like:
-
-| Property | Type | Optional | Description |
-|--|--|--|--|
-| operationId | `string` | | UUID v4 |
-| requestId | `string` | * | `X-Request-Id` from `incoming.headers` |
-
-**Setup**
+Serializers allow you to mask sensitive data (like passwords or credit card numbers) before they are logged.
 
 ```ts
-import { Logger, metaStorage } from '@n1k1t/mock-server';
-
-// Some external logger with meta context support
-const external = {...};
+import { Logger } from '@n1k1t/mock-server';
 
-// It defines your own logger methods
-Logger.useExternal({
-  debug: (...messages: string[]) => external.debug(metaStorage.provide(), ...messages),
-  info: (...messages: string[]) => external.log(metaStorage.provide(), ...messages),
-  warn: (...messages: string[]) => external.warn(metaStorage.provide(), ...messages),
-  error: (...messages: string[]) => external.error(metaStorage.provide(), ...messages),
-  fatal: (...messages: string[]) => external.error(metaStorage.provide(), ...messages),
+Logger.useSerializers({
+  password: () => '***',
+  token: (val: string) => `${val.slice(0, 4)}...`,
 });
 ```
 
-**Usage**
+## License
 
-```ts
-await server.client.createExpectation({
-  schema: {
-    request: {
-      $exec: ({ context, logger }) => {
-        // Here logger should have a meta context like { operationId: '...' }
-        logger.info('Before')
-      },
-      $exec: ({ context, logger, meta }) => {
-        // It enriches meta context for further logs of request
-        meta.merge({ foo: 'bar' });
-      },
-      $exec: ({ context, logger, meta }) => {
-        // Now logger should have a meta context like { foo: 'bar', operationId: '...' }
-        logger.info('After')
-      },
-    },
-  },
-});
-```
+MIT