phantomback 1.0.2 → 1.0.3

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,47 @@ 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
+## CLI Reference
 
 ```bash
-# Start with auto-detected config file
-phantomback start
-
-# Start with zero-config (demo mode)
-phantomback start --zero
-
-# Custom port
-phantomback start --port 4000
-
-# Specific config file
+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
-
-# Generate starter config
-phantomback init
-
-# Show help
+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 +328,10 @@ export default {
   },
 };
 ```
+</details>
 
-### E-Commerce
+<details>
+<summary><strong>🛒 E-Commerce</strong></summary>
 
 ```js
 export default {
@@ -403,12 +357,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 +378,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 +389,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">
+
+[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)
 
-MIT © [Madhav Chaturvedi](https://github.com/madhavxchaturvedi)
+Made with ❤️ by [Madhav Chaturvedi](https://madhavxchaturvedi.vercel.app) · [LinkedIn](https://www.linkedin.com/in/madhavxchaturvedi/) · [Instagram](https://www.instagram.com/madhavxchaturvedi)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phantomback",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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",