phantomback 1.0.2 → 2.0.0

package/README.md

@@ -1,85 +1,76 @@
 <div align="center">
 
+<br />
+
 # 👻 PhantomBack
 
-### Instant Fake Backend Generator with Smart Responses
+**Instant Fake Backend Generator with Smart Responses**
 
 [![npm version](https://img.shields.io/npm/v/phantomback.svg?style=flat-square&color=a78bfa)](https://www.npmjs.com/package/phantomback)
+[![downloads](https://img.shields.io/npm/dm/phantomback.svg?style=flat-square&color=a78bfa)](https://www.npmjs.com/package/phantomback)
 [![license](https://img.shields.io/npm/l/phantomback.svg?style=flat-square)](LICENSE)
 [![node](https://img.shields.io/node/v/phantomback.svg?style=flat-square)](package.json)
-[![docs](https://img.shields.io/badge/docs-phantomback-a78bfa?style=flat-square)](https://phantombackxdocs.vercel.app)
-
-**Stop waiting for the backend. Start building now.**
-
-Drop in your API schema → get a fully functional REST server with realistic data,
-JWT auth, pagination, filtering, sorting, search, and nested routes — in seconds.
 
-[Getting Started](https://phantombackxdocs.vercel.app/getting-started) · [Config Guide](https://phantombackxdocs.vercel.app/configuration) · [API Reference](https://phantombackxdocs.vercel.app/api-reference) · [Examples](https://phantombackxdocs.vercel.app/examples)
+Stop waiting for the backend. Drop in your API schema → get a fully functional REST server with
+realistic data, JWT auth, pagination, filtering, sorting, search, and nested routes — in seconds.
 
-[Documentation](https://phantombackxdocs.vercel.app) · [npm](https://www.npmjs.com/package/phantomback) · [GitHub](https://github.com/madhavxchaturvedi/npm-phantomback)
+[Documentation](https://phantombackxdocs.vercel.app) ·
+[Getting Started](https://phantombackxdocs.vercel.app/docs/getting-started) ·
+[API Reference](https://phantombackxdocs.vercel.app/docs/api-reference) ·
+[Playground](https://phantombackxdocs.vercel.app/docs/playground) ·
+[GitHub](https://github.com/madhavxchaturvedi/npm-phantomback)
 
-Made by [Madhav Chaturvedi](https://madhavxchaturvedi.vercel.app) · [LinkedIn](https://www.linkedin.com/in/madhavxchaturvedi/) · [Instagram](https://www.instagram.com/madhavxchaturvedi)
+<br />
 
 </div>
 
 ---
 
-## ✨ Features
-
-- 🚀 **Zero-config mode** — one command, full working API
-- 📦 **Auto CRUD** — GET, POST, PUT, PATCH, DELETE for every resource
-- 🎭 **Realistic data** — powered by Faker.js (names, emails, prices, avatars...)
-- 📄 **Pagination** — `?page=1&limit=10` with total counts & page metadata
-- 🔍 **Search** — `?q=term` full-text search across all fields
-- 🎯 **Filtering** — `?role=admin`, `?age_gte=18`, `?price_lte=100`, `?name_like=john`
-- ↕️ **Sorting** — `?sort=-price`, `?sort=name,createdAt`
-- 🔗 **Relations & Nested Routes** — `GET /users/:id/posts` auto-detected from foreign keys
-- 🔒 **JWT Auth** — register, login, protected routes with Bearer tokens
-- ⏱️ **Response Delay** — simulate slow networks with fixed or random latency
-- ✅ **Validation** — required fields, type checks, unique constraints, email format
-- 🖥️ **CLI + Library** — use as a CLI tool or import in your code
-- 🧠 **Smart Defaults** — sensible conventions, override only what you need
+## Why PhantomBack?
+
+| Pain point | PhantomBack fix |
+|---|---|
+| Backend not ready yet | Full REST API in one command |
+| Static JSON mocks feel fake | Stateful CRUD with realistic Faker data |
+| No pagination / filtering in mocks | Full query support out of the box |
+| Auth testing is painful | JWT auth simulation built-in |
+| Mock server setup takes time | One command or one line of code |
 
 ---
 
-## 📦 Installation
+## Quick Start
 
-```bash
-# Global install (recommended for CLI)
-npm install -g phantomback
+### Install
 
-# Or as a dev dependency in your project
-npm install --save-dev phantomback
+```bash
+npm install -g phantomback        # CLI (global)
+npm install --save-dev phantomback # Library (project)
 ```
 
----
-
-## 🚀 Quick Start
-
-### One command — full API:
+### Zero-config — one command, full API
 
 ```bash
 phantomback start --zero
 ```
 
-That's it. You now have a REST API running at `http://localhost:3777` with:
-- 👤 25 Users (protected with auth)
-- 📝 50 Posts
-- 💬 100 Comments
-- 📦 30 Products
-- ✅ 40 Todos
+You now have a REST API at **`http://localhost:3777`** with:
 
-### Or with your own config:
+| Resource | Count | Auth |
+|---|---|---|
+| `/api/users` | 25 records | 🔒 Protected |
+| `/api/posts` | 50 records | — |
+| `/api/comments` | 100 records | — |
+| `/api/products` | 30 records | — |
+| `/api/todos` | 40 records | — |
 
-```bash
-# Generate a starter config
-phantomback init
+### Or bring your own schema
 
-# Edit phantom.config.js to your needs, then:
-phantomback start
+```bash
+phantomback init          # generates phantom.config.js
+phantomback start         # reads config and starts server
 ```
 
-### Or as a library:
+### Or use as a library
 
 ```js
 import { createPhantom } from 'phantomback';
@@ -100,10 +91,10 @@ const server = await createPhantom({
 
 // server.stop()      — shut down
 // server.reset()     — re-seed all data
-// server.getStore()  — export current state as JSON
+// server.getStore()  — export current state
 ```
 
-One line for zero-config:
+One-liner for zero-config:
 
 ```js
 import { createPhantomZero } from 'phantomback';
@@ -112,18 +103,16 @@ await createPhantomZero(); // Full demo API on port 3777
 
 ---
 
-## ⚙️ Configuration
+## Configuration
 
-Create a `phantom.config.js` in your project root:
+Create **`phantom.config.js`** in your project root:
 
 ```js
 export default {
   port: 3777,
   prefix: '/api',
-
-  // Global response latency (ms)
-  // latency: 500,
-  // latency: [200, 800],  // random range
+  // latency: 500,          // fixed delay (ms)
+  // latency: [200, 800],   // random range
 
   auth: {
     secret: 'my-secret-key',
@@ -133,23 +122,23 @@ export default {
   resources: {
     users: {
       fields: {
-        name: { type: 'name', required: true },
-        email: { type: 'email', unique: true },
-        age: { type: 'number', min: 18, max: 65 },
-        role: { type: 'enum', values: ['admin', 'user', 'moderator'] },
-        avatar: { type: 'avatar' },
+        name:     { type: 'name', required: true },
+        email:    { type: 'email', unique: true },
+        age:      { type: 'number', min: 18, max: 65 },
+        role:     { type: 'enum', values: ['admin', 'user', 'moderator'] },
+        avatar:   { type: 'avatar' },
         isActive: { type: 'boolean' },
       },
-      seed: 25,     // auto-generate 25 records
+      seed: 25,
       auth: true,   // protect with JWT
     },
 
     posts: {
       fields: {
-        title: { type: 'title', required: true },
-        body: { type: 'paragraphs', count: 3 },
+        title:  { type: 'title', required: true },
+        body:   { type: 'paragraphs', count: 3 },
         userId: { type: 'relation', resource: 'users' },
-        views: { type: 'number', min: 0, max: 10000 },
+        views:  { type: 'number', min: 0, max: 10000 },
       },
       seed: 50,
     },
@@ -157,43 +146,29 @@ export default {
 };
 ```
 
-### Supported Field Types
+> **Full config reference →** [phantombackxdocs.vercel.app/docs/configuration](https://phantombackxdocs.vercel.app/docs/configuration)
+
+---
+
+## Supported Field Types
 
 | Type | Generates | Options |
-|------|-----------|---------|
-| `name` | Full name | — |
-| `firstName` | First name | — |
-| `lastName` | Last name | — |
-| `username` | Username | — |
-| `email` | Email address | `unique: true` |
-| `avatar` | Avatar URL | — |
+|---|---|---|
+| `name` `firstName` `lastName` `username` | Names | — |
+| `email` | Email | `unique` |
 | `phone` | Phone number | — |
-| `bio` | Short bio | — |
-| `jobTitle` | Job title | — |
-| `sentence` | One sentence | — |
-| `paragraph` | One paragraph | — |
-| `paragraphs` | Multiple paragraphs | `count: 3` |
-| `title` | Short title | — |
-| `description` | 2-4 sentences | — |
-| `slug` | URL slug | — |
-| `number` | Integer | `min`, `max` |
-| `float` | Decimal | `min`, `max`, `precision` |
-| `price` | Price string | — |
-| `rating` | 1.0 – 5.0 | — |
-| `boolean` | true/false | — |
-| `date` | ISO date | — |
-| `pastDate` | Past date | — |
-| `futureDate` | Future date | — |
-| `url` | URL | — |
-| `image` | Image URL | — |
-| `color` | Color name | — |
-| `address` | Street address | — |
-| `city` | City name | — |
-| `country` | Country name | — |
-| `product` | Product name | — |
-| `company` | Company name | — |
+| `avatar` | Avatar URL | — |
+| `bio` `jobTitle` | Profile text | — |
+| `sentence` `paragraph` `paragraphs` | Text blocks | `count` |
+| `title` `description` `slug` | Content | — |
+| `number` `float` `price` `rating` | Numbers | `min` `max` `precision` |
+| `boolean` | true / false | — |
+| `date` `pastDate` `futureDate` | ISO dates | — |
+| `url` `image` `color` | Misc | — |
+| `address` `city` `country` | Location | — |
+| `product` `company` | Business | — |
 | `enum` | Random from list | `values: [...]` |
-| `relation` | Foreign key | `resource: 'users'` |
+| `relation` | Foreign key | `resource: '...'` |
 | `uuid` | UUID string | — |
 
 ### Field Options
@@ -201,60 +176,81 @@ export default {
 ```js
 {
   type: 'email',
-  required: true,   // validation: must be present
-  unique: true,     // validation: no duplicates
-  min: 0,           // for numbers: minimum value
-  max: 100,         // for numbers: maximum value
+  required: true,   // must be present on create
+  unique: true,     // no duplicates allowed
+  min: 0,           // number minimum
+  max: 100,         // number maximum
 }
 ```
 
 ---
 
-## 🛣️ Auto-Generated Routes
+## Auto-Generated Routes
 
-For each resource (e.g., `users`), PhantomBack generates:
+Every resource gets full CRUD automatically:
 
 | Method | Endpoint | Description |
-|--------|----------|-------------|
+|---|---|---|
 | `GET` | `/api/users` | List all (paginated) |
-| `GET` | `/api/users/:id` | Get one by ID |
-| `POST` | `/api/users` | Create new |
+| `GET` | `/api/users/:id` | Get one |
+| `POST` | `/api/users` | Create |
 | `PUT` | `/api/users/:id` | Full update |
 | `PATCH` | `/api/users/:id` | Partial update |
 | `DELETE` | `/api/users/:id` | Delete |
 
-### Nested Routes (auto-detected from relations)
+### Nested Routes
 
-If `posts` has `userId: { type: 'relation', resource: 'users' }`, you get:
+If `posts` has `userId: { type: 'relation', resource: 'users' }`, you automatically get:
 
 ```
-GET /api/users/:id/posts    → all posts by this user
+GET /api/users/:id/posts   → all posts by this user
 ```
 
 ### Special Routes
 
 | Method | Endpoint | Description |
-|--------|----------|-------------|
+|---|---|---|
 | `GET` | `/api` | List all endpoints |
-| `GET` | `/api/_health` | Server health check |
-| `POST` | `/api/auth/register` | Register (email + password) |
-| `POST` | `/api/auth/login` | Login (returns JWT) |
-| `GET` | `/api/auth/me` | Current user (requires token) |
+| `GET` | `/api/_health` | Health check |
+| `POST` | `/api/auth/register` | Register |
+| `POST` | `/api/auth/login` | Login → JWT |
+| `GET` | `/api/auth/me` | Current user (token required) |
 
 ---
 
-## 🔍 Query Parameters
-
-### Pagination
+## Query Parameters
 
 ```bash
+# Pagination
 GET /api/users?page=2&limit=10
 GET /api/users?offset=20&limit=10
+
+# Filtering
+GET /api/users?role=admin                # exact match
+GET /api/users?age_gte=18                # ≥
+GET /api/users?age_lte=30                # ≤
+GET /api/users?age_gt=18&age_lt=30       # range
+GET /api/users?role_ne=admin             # not equal
+GET /api/users?name_like=john            # contains
+
+# Sorting
+GET /api/users?sort=name                 # ascending
+GET /api/users?sort=-name                # descending
+GET /api/users?sort=role,-age            # multi-field
+
+# Search
+GET /api/users?q=john                    # full-text across all fields
+
+# Field Selection
+GET /api/users?fields=name,email,role
 ```
 
-Response includes:
+Response includes pagination metadata:
+
 ```json
 {
+  "success": true,
+  "data": [ ... ],
   "meta": {
     "page": 2,
     "limit": 10,
@@ -266,91 +262,92 @@ Response includes:
 }
 ```
 
-### Filtering
-
-```bash
-GET /api/users?role=admin              # exact match
-GET /api/users?age_gte=18              # greater than or equal
-GET /api/users?age_lte=30              # less than or equal
-GET /api/users?age_gt=18               # greater than
-GET /api/users?age_lt=30               # less than
-GET /api/users?role_ne=admin           # not equal
-GET /api/users?name_like=john          # contains (case-insensitive)
-```
-
-### Sorting
-
-```bash
-GET /api/users?sort=name               # ascending
-GET /api/users?sort=-name              # descending
-GET /api/users?sort=role,-age          # multi-field
-```
-
-### Search
-
-```bash
-GET /api/users?q=john                  # search across all fields
-```
-
-### Field Selection
-
-```bash
-GET /api/users?fields=name,email,role  # only return these fields
-```
-
 ---
 
-## 🔒 Authentication
+## Authentication
 
-1. **Register:**
 ```bash
+# 1. Register
 curl -X POST http://localhost:3777/api/auth/register \
   -H "Content-Type: application/json" \
-  -d '{"email": "user@example.com", "password": "secret123", "name": "John"}'
-```
+  -d '{"email": "user@test.com", "password": "secret123", "name": "John"}'
 
-2. **Login:**
-```bash
+# 2. Login
 curl -X POST http://localhost:3777/api/auth/login \
   -H "Content-Type: application/json" \
-  -d '{"email": "user@example.com", "password": "secret123"}'
-```
+  -d '{"email": "user@test.com", "password": "secret123"}'
 
-3. **Access protected routes:**
-```bash
+# 3. Use the token
 curl http://localhost:3777/api/users \
   -H "Authorization: Bearer <your-token>"
 ```
 
 ---
 
-## 💻 CLI Reference
+## Reality Mode — Chaos Engineering
+
+Test your frontend's resilience by simulating real-world production failures.
+
+Enable in `phantom.config.js`:
+
+```js
+export default {
+  // ...
+  chaos: {
+    enabled: true,
+    latency:            { min: 200, max: 5000 }, // latency jitter range (ms)
+    failureRate:        0.1,                      // 10% random 5xx responses
+    errorCodes:         [500, 502, 503, 504],
+    connectionDropRate: 0.02,                     // 2% abrupt connection drops
+    corruptionRate:     0.02,                     // 2% malformed JSON
+    timeoutRate:        0.03,                     // 3% hanging responses
+    scenarios:          ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+  },
+};
+```
+
+Or enable instantly from the CLI:
 
 ```bash
-# Start with auto-detected config file
-phantomback start
+phantomback start --chaos                           # enable with defaults
+phantomback start --chaos --chaos-failure 0.2      # 20% failure rate
+phantomback start --chaos --chaos-latency 500,3000 # 500–3000 ms jitter
+```
 
-# Start with zero-config (demo mode)
-phantomback start --zero
+| Scenario | Config Key | Description |
+|---|---|---|
+| `latency` | `latency` | Injects random delay on ~30% of requests |
+| `failure` | `failureRate` | Returns a random 5xx error |
+| `drop` | `connectionDropRate` | Abruptly closes the TCP connection |
+| `corruption` | `corruptionRate` | Sends malformed / partial JSON |
+| `timeout` | `timeoutRate` | Hangs the response for ~30 seconds |
 
-# Custom port
-phantomback start --port 4000
+> **Full guide →** [phantombackxdocs.vercel.app/docs/reality-mode](https://phantombackxdocs.vercel.app/docs/reality-mode)
 
-# Specific config file
-phantomback start --config ./my-api.config.js
+---
 
-# Generate starter config
-phantomback init
+## CLI Reference
 
-# Show help
+```bash
+phantomback start                              # start with phantom.config.js
+phantomback start --zero                       # zero-config demo mode
+phantomback start --port 4000                  # custom port
+phantomback start --config ./my-api.config.js  # custom config path
+phantomback start --chaos                      # enable Reality Mode
+phantomback start --chaos --chaos-failure 0.2  # 20% failure rate
+phantomback start --chaos --chaos-latency 200,5000  # latency jitter range
+phantomback init                               # generate starter config
 phantomback --help
 ```
 
+> **Full CLI docs →** [phantombackxdocs.vercel.app/docs/cli](https://phantombackxdocs.vercel.app/docs/cli)
+
 ---
 
-## 🏗️ Real-World Examples
+## Real-World Examples
 
-### Hospital Management
+<details>
+<summary><strong>🏥 Hospital Management</strong></summary>
 
 ```js
 export default {
@@ -376,8 +373,10 @@ export default {
   },
 };
 ```
+</details>
 
-### E-Commerce
+<details>
+<summary><strong>🛒 E-Commerce</strong></summary>
 
 ```js
 export default {
@@ -403,12 +402,13 @@ export default {
   },
 };
 ```
+</details>
 
----
+> **More examples →** [phantombackxdocs.vercel.app/docs/examples](https://phantombackxdocs.vercel.app/docs/examples)
 
-## 📜 Response Format
+---
 
-All responses follow a consistent format:
+## Response Format
 
 **Success:**
 ```json
@@ -423,10 +423,7 @@ All responses follow a consistent format:
 ```json
 {
   "success": false,
-  "error": {
-    "status": 404,
-    "message": "users with id \"abc\" not found"
-  }
+  "error": { "status": 404, "message": "users with id \"abc\" not found" }
 }
 ```
 
@@ -437,28 +434,27 @@ All responses follow a consistent format:
   "error": {
     "status": 400,
     "message": "Validation failed",
-    "details": [
-      { "field": "email", "message": "\"email\" is required" }
-    ]
+    "details": [{ "field": "email", "message": "\"email\" is required" }]
   }
 }
 ```
 
 ---
 
-## 🌟 Why PhantomBack?
+## License
 
-| Problem | PhantomBack Solution |
-|---------|---------------------|
-| Backend not ready yet | Start frontend dev instantly |
-| Static JSON mocks are unrealistic | Stateful CRUD with realistic Faker data |
-| No pagination/filtering in mocks | Full query support out of the box |
-| Auth testing is painful | JWT auth simulation built-in |
-| Setting up mock servers takes time | One command / one line of code |
-| Different projects need different schemas | Define any resource with a config file |
+MIT © [Madhav Chaturvedi](https://github.com/madhavxchaturvedi)
 
 ---
 
-## 📄 License
+<div align="center">
 
-MIT © [Madhav Chaturvedi](https://github.com/madhavxchaturvedi)
+[Documentation](https://phantombackxdocs.vercel.app) ·
+[npm](https://www.npmjs.com/package/phantomback) ·
+[GitHub](https://github.com/madhavxchaturvedi/npm-phantomback) ·
+[CLI Reference](https://phantombackxdocs.vercel.app/docs/cli) ·
+[Playground](https://phantombackxdocs.vercel.app/docs/playground)
+
+Made with ❤️ by [Madhav Chaturvedi](https://madhavxchaturvedi.vercel.app) · [LinkedIn](https://www.linkedin.com/in/madhavxchaturvedi/) · [Instagram](https://www.instagram.com/madhavxchaturvedi)
+
+</div>

package/bin/phantomback.js

@@ -23,6 +23,9 @@ program
   .option('--prefix <prefix>', 'API route prefix', '/api')
   .option('-c, --config <path>', 'Path to config file')
   .option('-z, --zero', 'Zero-config mode: generate a full demo backend')
+  .option('--chaos', 'Enable Reality Mode (chaos engineering)')
+  .option('--chaos-failure <rate>', 'Failure rate for Reality Mode (0-1)', parseFloat)
+  .option('--chaos-latency <range>', 'Latency range in ms (e.g. "200,5000")')
   .action(async (options) => {
     const { startCommand } = await import('../src/cli/commands.js');
     await startCommand(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phantomback",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Instant fake backend generator with smart responses & chaos engineering. Drop in your API schema → get a fully functional, stateful REST server with realistic data, auth, pagination, filtering, and Reality Mode for chaos testing.",
   "type": "module",
   "main": "./src/index.js",
@@ -27,6 +27,10 @@
     "development",
     "prototyping",
     "chaos-engineering",
+    "reality-mode",
+    "chaos-testing",
+    "fault-injection",
+    "resilience",
     "testing",
     "frontend",
     "faker",

package/src/cli/commands.js

@@ -69,14 +69,24 @@ export default {
     },
   },
 
-  // Chaos Engineering (Reality Mode) — Phase 2
-  // chaos: {
-  //   enabled: true,
-  //   jitter: { min: 100, max: 3000 },
-  //   failureRate: 0.1,
-  //   duplicateRate: 0.05,
-  //   connectionDropRate: 0.02,
-  // },
+  // Chaos Engineering (Reality Mode)
+  chaos: {
+    enabled: false,
+    // Latency jitter range (ms) — random delays injected on ~30% of requests
+    latency: { min: 200, max: 5000 },
+    // Probability (0-1) of returning a random 5xx error
+    failureRate: 0.1,
+    // HTTP error codes used for random failures
+    errorCodes: [500, 502, 503, 504],
+    // Probability of abruptly dropping the connection
+    connectionDropRate: 0.02,
+    // Probability of sending malformed/partial JSON
+    corruptionRate: 0.02,
+    // Probability of request hanging (30s timeout)
+    timeoutRate: 0.03,
+    // Which chaos scenarios to activate
+    scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+  },
 };
 `;
 
@@ -114,6 +124,31 @@ export async function startCommand(options) {
   if (options.port) config.port = parseInt(options.port, 10);
   if (options.prefix) config.prefix = options.prefix;
 
+  // Reality Mode (Chaos) CLI overrides
+  if (options.chaos) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+  }
+  if (options.chaosFailure !== undefined) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+    const rate = options.chaosFailure;
+    if (rate < 0 || rate > 1) {
+      logger.warn('--chaos-failure must be between 0 and 1. Clamping to valid range.');
+    }
+    config.chaos.failureRate = Math.max(0, Math.min(1, rate));
+  }
+  if (options.chaosLatency) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+    const parts = options.chaosLatency.split(',').map(Number);
+    if (parts.length === 2 && !isNaN(parts[0]) && !isNaN(parts[1]) && parts[0] >= 0 && parts[1] >= parts[0]) {
+      config.chaos.latency = { min: parts[0], max: parts[1] };
+    } else {
+      logger.warn('Invalid --chaos-latency format. Expected "min,max" (e.g. "200,5000"). Using defaults.');
+    }
+  }
+
   // Check if using defaults (no config found and no resources)
   if (Object.keys(config.resources).length === 0) {
     logger.warn('No config found and no resources defined. Using zero-config defaults.');

package/src/features/chaos.js

@@ -0,0 +1,468 @@
+/**
+ * Reality Mode — Chaos Engineering Middleware for PhantomBack
+ *
+ * Simulates real-world production instability during development:
+ *   • Latency spikes (jitter)
+ *   • Random HTTP failures (5xx errors)
+ *   • Connection drops (socket destruction)
+ *   • Response corruption (malformed JSON)
+ *   • Request timeouts (hanging responses)
+ *   • Out-of-order response delays
+ *
+ * Configuration:
+ *   chaos: {
+ *     enabled: true,
+ *     latency:            { min: 200, max: 5000 },
+ *     failureRate:        0.1,
+ *     errorCodes:         [500, 502, 503, 504],
+ *     connectionDropRate: 0.02,
+ *     corruptionRate:     0.02,
+ *     timeoutRate:        0.03,
+ *     scenarios:          ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+ *   }
+ */
+
+import { logger } from '../utils/logger.js';
+
+// ─── Default Chaos Configuration ─────────────────────────────────────────────
+
+const DEFAULT_CHAOS_CONFIG = {
+  enabled: false,
+  latency: { min: 200, max: 5000 },
+  failureRate: 0.1,
+  errorCodes: [500, 502, 503, 504],
+  connectionDropRate: 0.02,
+  corruptionRate: 0.02,
+  timeoutRate: 0.03,
+  scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+};
+
+// ─── Chaos Engine ────────────────────────────────────────────────────────────
+
+export class ChaosEngine {
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_CHAOS_CONFIG,
+      ...config,
+      latency: {
+        ...DEFAULT_CHAOS_CONFIG.latency,
+        ...(config.latency || {}),
+      },
+      errorCodes: config.errorCodes || DEFAULT_CHAOS_CONFIG.errorCodes,
+      scenarios: config.scenarios || DEFAULT_CHAOS_CONFIG.scenarios,
+    };
+    this.stats = {
+      totalRequests: 0,
+      chaosApplied: 0,
+      latencySpikes: 0,
+      failures: 0,
+      drops: 0,
+      corruptions: 0,
+      timeouts: 0,
+      startedAt: new Date().toISOString(),
+    };
+    this.paused = false;
+  }
+
+  /** Check if a specific scenario is enabled */
+  isScenarioEnabled(name) {
+    return this.config.enabled && !this.paused && this.config.scenarios.includes(name);
+  }
+
+  /** Roll the dice — returns true with the given probability (0-1) */
+  shouldTrigger(rate) {
+    return Math.random() < rate;
+  }
+
+  /** Generate a random latency value within the configured jitter range */
+  getJitter() {
+    const { min, max } = this.config.latency;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+
+  /** Pick a random error code from the configured list */
+  getRandomErrorCode() {
+    const codes = this.config.errorCodes;
+    return codes[Math.floor(Math.random() * codes.length)];
+  }
+
+  /** Enable chaos at runtime */
+  enable() {
+    this.config.enabled = true;
+    this.paused = false;
+    logger.chaos('Reality Mode ENABLED');
+  }
+
+  /** Disable chaos at runtime */
+  disable() {
+    this.config.enabled = false;
+    logger.chaos('Reality Mode DISABLED');
+  }
+
+  /** Pause chaos temporarily */
+  pause() {
+    this.paused = true;
+    logger.chaos('Reality Mode PAUSED');
+  }
+
+  /** Resume chaos after pause */
+  resume() {
+    this.paused = false;
+    logger.chaos('Reality Mode RESUMED');
+  }
+
+  /** Update chaos configuration at runtime */
+  configure(newConfig) {
+    this.config = { ...this.config, ...newConfig };
+    logger.chaos('Configuration updated');
+  }
+
+  /** Get current status and stats */
+  getStatus() {
+    return {
+      enabled: this.config.enabled,
+      paused: this.paused,
+      active: this.config.enabled && !this.paused,
+      config: this.config,
+      stats: { ...this.stats },
+    };
+  }
+
+  /** Reset stats counters */
+  resetStats() {
+    this.stats = {
+      totalRequests: 0,
+      chaosApplied: 0,
+      latencySpikes: 0,
+      failures: 0,
+      drops: 0,
+      corruptions: 0,
+      timeouts: 0,
+      startedAt: new Date().toISOString(),
+    };
+  }
+}
+
+// ─── Chaos Scenarios ─────────────────────────────────────────────────────────
+
+const ERROR_MESSAGES = {
+  500: 'Internal Server Error — [Reality Mode] Simulated server crash',
+  502: 'Bad Gateway — [Reality Mode] Upstream service unavailable',
+  503: 'Service Unavailable — [Reality Mode] Server overloaded',
+  504: 'Gateway Timeout — [Reality Mode] Upstream request timed out',
+};
+
+/**
+ * Scenario: Latency Spike
+ * Adds a random delay to simulate network jitter or slow backends
+ */
+function applyLatencySpike(engine, _req, _res) {
+  if (!engine.isScenarioEnabled('latency')) return null;
+  if (!engine.shouldTrigger(0.3)) return null; // 30% of requests get jitter
+
+  const delay = engine.getJitter();
+  engine.stats.latencySpikes++;
+
+  return new Promise((resolve) => {
+    logger.chaos(`Latency spike: +${delay}ms`);
+    setTimeout(resolve, delay);
+  });
+}
+
+/**
+ * Scenario: Random Failure
+ * Returns a random 5xx error response
+ */
+function applyFailure(engine, _req, res) {
+  if (!engine.isScenarioEnabled('failure')) return false;
+  if (!engine.shouldTrigger(engine.config.failureRate)) return false;
+
+  const code = engine.getRandomErrorCode();
+  engine.stats.failures++;
+
+  logger.chaos(`Random failure: HTTP ${code}`);
+  res.status(code).json({
+    success: false,
+    error: {
+      status: code,
+      message: ERROR_MESSAGES[code] || `HTTP ${code} — [Reality Mode] Simulated failure`,
+      chaos: true,
+    },
+  });
+
+  return true;
+}
+
+/**
+ * Scenario: Connection Drop
+ * Destroys the socket mid-request to simulate network issues
+ */
+function applyConnectionDrop(engine, req, _res) {
+  if (!engine.isScenarioEnabled('drop')) return false;
+  if (!engine.shouldTrigger(engine.config.connectionDropRate)) return false;
+
+  engine.stats.drops++;
+  logger.chaos(`Connection drop: ${req.method} ${req.originalUrl}`);
+
+  // Destroy the underlying socket
+  if (req.socket) {
+    req.socket.destroy();
+  }
+
+  return true;
+}
+
+/**
+ * Scenario: Response Corruption
+ * Sends back malformed/partial JSON to test error handling
+ */
+function applyCorruption(engine, req, res) {
+  if (!engine.isScenarioEnabled('corruption')) return false;
+  if (!engine.shouldTrigger(engine.config.corruptionRate)) return false;
+
+  engine.stats.corruptions++;
+  logger.chaos(`Response corruption: ${req.method} ${req.originalUrl}`);
+
+  // Pick a random corruption type
+  const corruptions = [
+    // Truncated JSON
+    () => {
+      res.setHeader('Content-Type', 'application/json');
+      res.status(200).end('{"success":true,"data":[{"id":"abc","na');
+    },
+    // Invalid JSON
+    () => {
+      res.setHeader('Content-Type', 'application/json');
+      res.status(200).end('{success: true, data: undefined}');
+    },
+    // Empty body with 200
+    () => {
+      res.status(200).end('');
+    },
+    // Wrong content type
+    () => {
+      res.setHeader('Content-Type', 'text/html');
+      res.status(200).end('<html><body>Unexpected HTML response</body></html>');
+    },
+    // Partial response with wrong status
+    () => {
+      res.status(206).json({
+        success: true,
+        data: null,
+        error: { message: '[Reality Mode] Partial response — data truncated' },
+        chaos: true,
+      });
+    },
+  ];
+
+  const corrupt = corruptions[Math.floor(Math.random() * corruptions.length)];
+  corrupt();
+  return true;
+}
+
+/**
+ * Scenario: Request Timeout
+ * Holds the connection open without responding (simulates hung backend)
+ */
+function applyTimeout(engine, req, _res) {
+  if (!engine.isScenarioEnabled('timeout')) return false;
+  if (!engine.shouldTrigger(engine.config.timeoutRate)) return false;
+
+  engine.stats.timeouts++;
+  logger.chaos(`Request timeout: ${req.method} ${req.originalUrl} (hanging for 30s)`);
+
+  // Return a promise that resolves after 30s (or until client gives up)
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, 30000);
+
+    // Clean up if client disconnects
+    req.on('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+// ─── Main Chaos Middleware ───────────────────────────────────────────────────
+
+/**
+ * Create the Reality Mode middleware.
+ * This is the main entry point — attach to Express before resource routes.
+ *
+ * @param {ChaosEngine} engine - Chaos engine instance
+ * @returns {Function} Express middleware
+ */
+export function chaosMiddleware(engine) {
+  return async (req, res, next) => {
+    engine.stats.totalRequests++;
+
+    // Skip if chaos is disabled or paused
+    if (!engine.config.enabled || engine.paused) {
+      return next();
+    }
+
+    // Skip chaos control endpoints
+    if (req.path.includes('/_chaos')) {
+      return next();
+    }
+
+    // Skip health check
+    if (req.path.includes('/_health')) {
+      return next();
+    }
+
+    // Add chaos header so clients know Reality Mode is active
+    res.setHeader('X-PhantomBack-Chaos', 'active');
+
+    // ── Execute scenarios in priority order ──
+
+    // 1. Connection Drop (highest priority — immediate termination)
+    if (applyConnectionDrop(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return; // Socket destroyed, nothing more to do
+    }
+
+    // 2. Request Timeout (holds connection)
+    const timeoutResult = applyTimeout(engine, req, res);
+    if (timeoutResult instanceof Promise) {
+      engine.stats.chaosApplied++;
+      await timeoutResult;
+      // After timeout, destroy the socket (client likely already disconnected)
+      if (req.socket && !req.socket.destroyed) {
+        req.socket.destroy();
+      }
+      return;
+    }
+
+    // 3. Random Failure (returns error response)
+    if (applyFailure(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return;
+    }
+
+    // 4. Response Corruption (sends malformed data)
+    if (applyCorruption(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return;
+    }
+
+    // 5. Latency Spike (adds delay, then continues to real handler)
+    const latencyResult = applyLatencySpike(engine, req, res);
+    if (latencyResult instanceof Promise) {
+      engine.stats.chaosApplied++;
+      await latencyResult;
+    }
+
+    // If no chaos blocked the request, proceed normally
+    next();
+  };
+}
+
+// ─── Chaos Control Routes ────────────────────────────────────────────────────
+
+/**
+ * Register chaos control endpoints on the Express app.
+ * These allow runtime control of Reality Mode.
+ *
+ * Routes:
+ *   GET  {prefix}/_chaos            — Status & stats
+ *   POST {prefix}/_chaos/enable     — Enable chaos
+ *   POST {prefix}/_chaos/disable    — Disable chaos
+ *   POST {prefix}/_chaos/pause      — Pause chaos
+ *   POST {prefix}/_chaos/resume     — Resume chaos
+ *   POST {prefix}/_chaos/configure  — Update config
+ *   POST {prefix}/_chaos/reset      — Reset stats
+ */
+export function createChaosRoutes(app, engine, config) {
+  const prefix = config.prefix || '/api';
+
+  // GET /_chaos — status dashboard
+  app.get(`${prefix}/_chaos`, (_req, res) => {
+    const status = engine.getStatus();
+    res.json({
+      success: true,
+      message: status.active
+        ? '🔥 Reality Mode is ACTIVE — chaos is being injected!'
+        : '😴 Reality Mode is inactive',
+      ...status,
+    });
+  });
+
+  // POST /_chaos/enable
+  app.post(`${prefix}/_chaos/enable`, (_req, res) => {
+    engine.enable();
+    res.json({
+      success: true,
+      message: '🔥 Reality Mode ENABLED — brace yourself!',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/disable
+  app.post(`${prefix}/_chaos/disable`, (_req, res) => {
+    engine.disable();
+    res.json({
+      success: true,
+      message: '😴 Reality Mode DISABLED — back to calm waters',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/pause
+  app.post(`${prefix}/_chaos/pause`, (_req, res) => {
+    engine.pause();
+    res.json({
+      success: true,
+      message: '⏸️  Reality Mode PAUSED',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/resume
+  app.post(`${prefix}/_chaos/resume`, (_req, res) => {
+    engine.resume();
+    res.json({
+      success: true,
+      message: '▶️  Reality Mode RESUMED',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/configure — update chaos config at runtime
+  app.post(`${prefix}/_chaos/configure`, (req, res) => {
+    const updates = req.body;
+    if (!updates || typeof updates !== 'object') {
+      return res.status(400).json({
+        success: false,
+        error: { status: 400, message: 'Request body must be a JSON object with chaos config' },
+      });
+    }
+
+    engine.configure(updates);
+    res.json({
+      success: true,
+      message: '⚙️  Chaos configuration updated',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/reset — reset stats
+  app.post(`${prefix}/_chaos/reset`, (_req, res) => {
+    engine.resetStats();
+    res.json({
+      success: true,
+      message: '📊 Chaos stats reset',
+      ...engine.getStatus(),
+    });
+  });
+
+  // Log registered chaos routes
+  logger.chaos('Control endpoints registered:');
+  logger.route('GET', `${prefix}/_chaos`);
+  logger.route('POST', `${prefix}/_chaos/enable`);
+  logger.route('POST', `${prefix}/_chaos/disable`);
+  logger.route('POST', `${prefix}/_chaos/pause`);
+  logger.route('POST', `${prefix}/_chaos/resume`);
+  logger.route('POST', `${prefix}/_chaos/configure`);
+  logger.route('POST', `${prefix}/_chaos/reset`);
+}

package/src/index.js

@@ -64,4 +64,5 @@ export { createServer } from './server/createServer.js';
 export { parseConfig } from './schema/parser.js';
 export { DEFAULT_RESOURCES } from './schema/defaults.js';
 export { DataStore } from './data/store.js';
+export { ChaosEngine, chaosMiddleware, createChaosRoutes } from './features/chaos.js';
 export { logger } from './utils/logger.js';

package/src/schema/parser.js

@@ -16,6 +16,13 @@ export const DEFAULT_CONFIG = {
   },
   chaos: {
     enabled: false,
+    latency: { min: 200, max: 5000 },
+    failureRate: 0.1,
+    errorCodes: [500, 502, 503, 504],
+    connectionDropRate: 0.02,
+    corruptionRate: 0.02,
+    timeoutRate: 0.03,
+    scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
   },
   resources: {},
   snapshot: false,
@@ -79,6 +86,8 @@ async function findConfigFile() {
  * Merge user config with defaults
  */
 function mergeConfig(userConfig) {
+  const userChaos = userConfig.chaos || {};
+
   return {
     ...DEFAULT_CONFIG,
     ...userConfig,
@@ -88,7 +97,13 @@ function mergeConfig(userConfig) {
     },
     chaos: {
       ...DEFAULT_CONFIG.chaos,
-      ...(userConfig.chaos || {}),
+      ...userChaos,
+      latency: {
+        ...DEFAULT_CONFIG.chaos.latency,
+        ...(userChaos.latency || {}),
+      },
+      errorCodes: userChaos.errorCodes || DEFAULT_CONFIG.chaos.errorCodes,
+      scenarios: userChaos.scenarios || DEFAULT_CONFIG.chaos.scenarios,
     },
   };
 }

package/src/server/createServer.js

@@ -1,6 +1,7 @@
 import { createExpressApp, addErrorHandling } from './middleware.js';
 import { createRouter } from './router.js';
 import { createAuthRoutes } from '../features/auth.js';
+import { ChaosEngine, chaosMiddleware, createChaosRoutes } from '../features/chaos.js';
 import { seedAll } from '../data/seeder.js';
 import { DataStore } from '../data/store.js';
 import { logger } from '../utils/logger.js';
@@ -15,6 +16,22 @@ export async function createServer(config) {
   const store = new DataStore();
   const app = createExpressApp(config);
 
+  // Initialize Reality Mode (Chaos Engine)
+  const chaosConfig = config.chaos || {};
+  const chaos = new ChaosEngine(chaosConfig);
+
+  // Register chaos control endpoints (before chaos middleware so they're never affected)
+  createChaosRoutes(app, chaos, config);
+
+  // Always mount chaos middleware so runtime toggling via /_chaos/enable works
+  // The middleware itself checks engine.config.enabled internally
+  app.use(chaosMiddleware(chaos));
+
+  // Print chaos banner if enabled at startup
+  if (chaosConfig.enabled) {
+    logger.chaosBanner(chaosConfig);
+  }
+
   // Seed data
   seedAll(config.resources, store);
 
@@ -43,6 +60,7 @@ export async function createServer(config) {
     app,
     server,
     store,
+    chaos,
     stop: () =>
       new Promise((resolve) => {
         server.close(resolve);
@@ -53,5 +71,6 @@ export async function createServer(config) {
       logger.info('Store has been reset and re-seeded');
     },
     getStore: () => store.toJSON(),
+    getChaos: () => chaos.getStatus(),
   };
 }

package/src/utils/logger.js

@@ -29,7 +29,7 @@ export const logger = {
     console.log(chalk.hex('#a78bfa').bold('  ╔═══════════════════════════════════════╗'));
     console.log(
       chalk.hex('#a78bfa').bold('  ║         ') +
-        chalk.white.bold('PhantomBack v1.0.0') +
+        chalk.white.bold('PhantomBack v2.0.0') +
         chalk.hex('#a78bfa').bold('         ║'),
     );
     console.log(
@@ -55,4 +55,70 @@ export const logger = {
     }
     console.log('');
   },
+
+  // ── Reality Mode (Chaos) Logging ──
+  chaos: (...args) =>
+    console.log(PREFIX, chalk.hex('#ff6b6b').bold('⚡CHAOS'), ...args),
+
+  chaosBanner: (config) => {
+    console.log('');
+    console.log(chalk.hex('#ff6b6b').bold('  ┌───────────────────────────────────────┐'));
+    console.log(
+      chalk.hex('#ff6b6b').bold('  │    ') +
+        chalk.white.bold('⚡ Reality Mode ACTIVE ⚡') +
+        chalk.hex('#ff6b6b').bold('        │'),
+    );
+    console.log(
+      chalk.hex('#ff6b6b').bold('  │  ') +
+        chalk.dim('Chaos is being injected into your API') +
+        chalk.hex('#ff6b6b').bold(' │'),
+    );
+    console.log(chalk.hex('#ff6b6b').bold('  └───────────────────────────────────────┘'));
+    console.log('');
+    if (config) {
+      const scenarios = config.scenarios || [];
+      console.log(PREFIX, chalk.hex('#ff6b6b').bold('Active Scenarios:'));
+      if (scenarios.includes('latency')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.yellow('⏱  Latency Spikes'),
+          chalk.dim(`(${config.latency?.min || 200}–${config.latency?.max || 5000}ms)`),
+        );
+      }
+      if (scenarios.includes('failure')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.red('💥 Random Failures'),
+          chalk.dim(`(${(config.failureRate || 0.1) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('drop')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.magenta('🔌 Connection Drops'),
+          chalk.dim(`(${(config.connectionDropRate || 0.02) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('corruption')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.hex('#ff9f43')('🧩 Response Corruption'),
+          chalk.dim(`(${(config.corruptionRate || 0.02) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('timeout')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.hex('#ee5a24')('⏳ Request Timeouts'),
+          chalk.dim(`(${(config.timeoutRate || 0.03) * 100}% rate)`),
+        );
+      }
+      console.log('');
+    }
+  },
 };