360-mock-server 1.1.0 → 1.2.0

package/README.md

@@ -1,190 +1,267 @@
 # 🚀 360 Mock Server
 
-Zero-config dynamic mock REST API server. Perfect for frontend development when backend isn't ready.
+**360 Mock Server** is a zero-configuration mock REST API designed for frontend developers.
+It allows you to instantly create and manage RESTful APIs **without building a backend**, making it ideal for frontend development, testing, demos, and rapid prototyping.
 
-## Installation
+Now with **Faker.js integration** for automatic fake data generation!
+
+
+## ✨ Why 360 Mock Server?
+
+* No backend setup required
+* Works instantly with **any endpoint**
+* **Auto-generate fake data** with Faker.js
+* Interactive CLI + REST API
+* Persistent JSON-based storage
+* Ideal for React, React Native, Vue, Angular, Redux apps
+
+
+## 📦 Installation
+
+Install globally using npm:
 
 ```bash
-# Global installation (recommended)
 npm install -g 360-mock-server
+```
 
-# Or use npx (no install needed)
+Or run directly using `npx` (recommended):
+
+```bash
 npx 360-mock-server
 ```
 
-## Quick Start
+
+## ⚡ Quick Start
 
 ```bash
-# Just run one command - that's it!
 npx 360-mock-server
 ```
 
-This will:
-1. ✅ Create `mock-data.json` automatically
-2. ✅ Start the server on port 3000
-3. ✅ Open interactive mode for easy API requests
+That’s it! 🎉
+The mock server will start at:
 
----
+```
+http://localhost:3000
+```
 
-## Interactive Mode (Recommended!)
 
-After running `npx 360-mock-server`, you get an interactive prompt:
+## 🧠 Interactive CLI Mode
 
-```
+Once the server starts, you can interact with it directly from the terminal:
+
+```text
 360-mock> POST /users {"name": "Ali", "email": "ali@test.com"}
-📤 POST /users
 ✅ Status: 201
-{ "id": 1234567890, "name": "Ali", "email": "ali@test.com" }
+{"id": 1737745200000, "name": "Ali", "email": "ali@test.com"}
 
 360-mock> GET /users
-📤 GET /users
 ✅ Status: 200
-[{ "id": 1234567890, "name": "Ali", "email": "ali@test.com" }]
+[{"id": 1737745200000, "name": "Ali", "email": "ali@test.com"}]
 
-360-mock> POST /products {"name": "Laptop", "price": 999}
-360-mock> GET /products
-360-mock> DELETE /users/1234567890
-360-mock> exit
+360-mock> DELETE /users/1737745200000
+✅ Status: 200
 ```
 
-### Interactive Commands
 
-| Command | Example |
-|---------|---------|
-| GET | `GET /users` |
-| POST | `POST /users {"name": "Ali"}` |
-| PUT | `PUT /users/123 {"name": "Updated"}` |
-| PATCH | `PATCH /users/123 {"email": "new@test.com"}` |
-| DELETE | `DELETE /users/123` |
-| list | Show all resources |
-| clear | Clear screen |
-| help | Show help |
-| exit | Exit |
+## 📟 CLI Commands (Interactive Mode)
 
----
+| Command                                | Description                  |
+| -------------------------------------- | ---------------------------- |
+| `GET /users`                           | Fetch all users              |
+| `GET /users/123`                       | Fetch user by ID             |
+| `POST /users {"name":"Ali"}`           | Create a new user            |
+| `PUT /users/123 {"name":"New"}`        | Replace entire resource      |
+| `PATCH /users/123 {"email":"x@y.com"}` | Update specific fields       |
+| `DELETE /users/123`                    | Delete resource              |
+| `list`                                 | Show all available resources |
+| `clear`                                | Clear terminal screen        |
+| `help`                                 | Show help                    |
+| `exit`                                 | Exit interactive mode        |
 
-## CLI Commands
+## 🧪 Using with Postman / REST Clients
 
-| Command | Description |
-|---------|-------------|
-| `360-mock` | Start server + interactive mode |
-| `360-mock start` | Start server only |
-| `360-mock init` | Create mock-data.json |
-| `360-mock list` | Show available resources |
-| `360-mock reset` | Clear all data |
+**Base URL**
 
-### Options
+```
+http://localhost:3000
+```
 
-```bash
-360-mock --port 4000             # Custom port
-360-mock --file db.json          # Custom data file
-360-mock --help                  # Show help
-360-mock --version               # Show version
+### Example Endpoints
+
+| Method | Endpoint     | Body                          |
+| ------ | ------------ | ----------------------------- |
+| GET    | `/users`     | —                             |
+| GET    | `/users/123` | —                             |
+| POST   | `/users`     | `{ "name": "Ali" }`           |
+| PUT    | `/users/123` | `{ "name": "Updated" }`       |
+| PATCH  | `/users/123` | `{ "email": "new@test.com" }` |
+| DELETE | `/users/123` | —                             |
+
+**Required Headers**
+
+```
+Content-Type: application/json
 ```
 
----
 
-## API Endpoints
+## 🎲 Auto-Generate Fake Data with Faker.js
 
-### Any endpoint works automatically!
+Generate realistic fake data instantly! Just send a POST request with `fields` array:
 
-Just POST to any endpoint - it creates the resource:
+### Generate 10 Users (default count)
 
 ```bash
-# These all work without configuration:
 POST /users
-POST /products  
-POST /orders
-POST /anything-you-want
+{
+  "fields": ["name", "email", "avatar", "phone"]
+}
+```
+
+### Generate 50 Products with custom count
+
+```bash
+POST /products
+{
+  "fields": ["productName", "price", "category", "description", "image"],
+  "count": 50
+}
 ```
 
-### Full CRUD Operations
+### Available Faker Fields
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/users` | Get all users |
-| GET | `/users/1` | Get user by ID |
-| POST | `/users` | Create user |
-| PUT | `/users/1` | Replace user |
-| PATCH | `/users/1` | Update user |
-| DELETE | `/users/1` | Delete user |
-| DELETE | `/users` | Delete all users |
+| Category    | Fields                                                                 |
+| ----------- | ---------------------------------------------------------------------- |
+| **Person**  | `name`, `firstName`, `lastName`, `username`, `email`, `phone`, `avatar`, `bio`, `jobTitle`, `gender` |
+| **Location**| `address`, `city`, `state`, `country`, `zipCode`, `latitude`, `longitude` |
+| **Company** | `company`, `companyName`, `department`                                 |
+| **Internet**| `website`, `url`, `ip`, `password`                                     |
+| **Content** | `title`, `description`, `body`, `text`, `sentence`, `paragraph`, `slug`|
+| **Commerce**| `price`, `product`, `productName`, `productDescription`, `category`    |
+| **Images**  | `image`, `imageUrl`                                                    |
+| **Dates**   | `date`, `pastDate`, `futureDate`, `birthDate`                          |
+| **Numbers** | `number`, `age`, `rating`, `quantity`                                  |
+| **Boolean** | `boolean`, `isActive`, `isVerified`                                    |
+| **Misc**    | `uuid`, `color`, `word`, `words`                                       |
 
-### Query Parameters
+### Get All Available Fields
 
 ```bash
-GET /users?name=john           # Filter by name
-GET /users?_sort=name          # Sort by field
-GET /users?_order=desc         # Sort order
-GET /users?_limit=10&_page=2   # Pagination
+GET /faker/fields
 ```
 
----
+> **Note:** If your POST body contains a `fields` array, it generates fake data. Otherwise, it creates a single item with your provided key-value pairs.
 
-## Frontend Examples
 
-### Fetch API
+## 🔌 Frontend Integration Examples
+
+<details open>
+<summary><strong>Fetch API</strong></summary>
 
 ```javascript
-// Create
-const user = await fetch('http://localhost:3000/users', {
+const API = 'http://localhost:3000';
+
+// CREATE
+await fetch(`${API}/users`, {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ name: 'Ali', email: 'ali@test.com' })
-}).then(r => r.json());
-
-// Read all
-const users = await fetch('http://localhost:3000/users').then(r => r.json());
+});
 
-// Read one
-const user = await fetch('http://localhost:3000/users/1').then(r => r.json());
+// READ
+const users = await fetch(`${API}/users`).then(res => res.json());
 
-// Update
-await fetch('http://localhost:3000/users/1', {
+// UPDATE
+await fetch(`${API}/users/123`, {
   method: 'PATCH',
   headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'Ali Updated' })
+  body: JSON.stringify({ name: 'Updated' })
 });
 
-// Delete
-await fetch('http://localhost:3000/users/1', { method: 'DELETE' });
+// DELETE
+await fetch(`${API}/users/123`, { method: 'DELETE' });
 ```
 
-### Axios
+</details>
+
+<details>
+<summary><strong>Axios</strong></summary>
 
 ```javascript
 import axios from 'axios';
-const api = axios.create({ baseURL: 'http://localhost:3000' });
 
-// Create
-const { data: user } = await api.post('/users', { name: 'Ali' });
+const API = 'http://localhost:3000';
+
+// CREATE
+await axios.post(`${API}/users`, {
+  name: 'Ali',
+  email: 'ali@test.com'
+});
+
+// READ
+const { data: users } = await axios.get(`${API}/users`);
+
+// UPDATE
+await axios.patch(`${API}/users/123`, {
+  name: 'Updated'
+});
+
+// DELETE
+await axios.delete(`${API}/users/123`);
+```
+
+</details>
 
-// Read
-const { data: users } = await api.get('/users');
 
-// Update
-await api.patch(`/users/${id}`, { name: 'Updated' });
+## ⚙️ CLI Options
 
-// Delete
-await api.delete(`/users/${id}`);
+| Option   | Description    | Default          |
+| -------- | -------------- | ---------------- |
+| `--port` | Server port    | `3000`           |
+| `--file` | Data file name | `mock-data.json` |
+
+### Examples
+
+```bash
+npx 360-mock-server --port 4000
+npx 360-mock-server --file db.json
 ```
 
----
 
-## Features
+## 🛠 Additional Commands
+
+| Command          | Description                             |
+| ---------------- | --------------------------------------- |
+| `360-mock start` | Start server only (no interactive mode) |
+| `360-mock init`  | Create an empty data file               |
+| `360-mock list`  | List all resources                      |
+| `360-mock reset` | Clear all stored data                   |
+
+
+## 🌟 Features
+
+* ✅ Zero-config setup
+* ✅ Supports **any REST endpoint**
+* ✅ Full CRUD operations
+* ✅ **Auto-generate fake data** with Faker.js
+* ✅ Auto-generated unique IDs
+* ✅ Automatic timestamps (`createdAt`, `updatedAt`)
+* ✅ Persistent JSON storage
+* ✅ CORS enabled
+* ✅ Works with Postman & frontend apps
+* ✅ Perfect for mock APIs & demos
 
-- ✅ **Zero config** - Works out of the box
-- ✅ **Any endpoint** - Auto-creates resources
-- ✅ **Full CRUD** - GET, POST, PUT, PATCH, DELETE
-- ✅ **Filtering** - Query parameter support
-- ✅ **Sorting** - `?_sort=field&_order=desc`
-- ✅ **Pagination** - `?_limit=10&_page=1`
-- ✅ **Auto IDs** - Generated automatically
-- ✅ **Timestamps** - createdAt, updatedAt
-- ✅ **CORS enabled** - Works with any frontend
 
----
+## 💾 Data Storage
 
-## License
+All data is stored locally in:
+
+```
+mock-data.json
+```
+
+This file is automatically created and updated in your project directory.
+
+## 📄 License
 
 MIT © [zahidrahimoon](https://github.com/zahidrahimoon)
+

package/lib/server.js

@@ -2,6 +2,7 @@ const express = require("express");
 const fs = require("fs");
 const path = require("path");
 const cors = require("cors");
+const { faker } = require("@faker-js/faker");
 
 const app = express();
 const PORT = process.env.PORT || 3000;
@@ -46,6 +47,99 @@ app.use((req, res, next) => {
   next();
 });
 
+// Faker field mappings for automatic data generation
+const fakerFieldMap = {
+  // Person
+  name: () => faker.person.fullName(),
+  firstName: () => faker.person.firstName(),
+  lastName: () => faker.person.lastName(),
+  username: () => faker.internet.username(),
+  email: () => faker.internet.email(),
+  phone: () => faker.phone.number(),
+  avatar: () => faker.image.avatar(),
+  bio: () => faker.person.bio(),
+  jobTitle: () => faker.person.jobTitle(),
+  gender: () => faker.person.sex(),
+  
+  // Location
+  address: () => faker.location.streetAddress(),
+  city: () => faker.location.city(),
+  state: () => faker.location.state(),
+  country: () => faker.location.country(),
+  zipCode: () => faker.location.zipCode(),
+  latitude: () => faker.location.latitude(),
+  longitude: () => faker.location.longitude(),
+  
+  // Company
+  company: () => faker.company.name(),
+  companyName: () => faker.company.name(),
+  department: () => faker.commerce.department(),
+  
+  // Internet
+  website: () => faker.internet.url(),
+  url: () => faker.internet.url(),
+  ip: () => faker.internet.ip(),
+  password: () => faker.internet.password(),
+  
+  // Content
+  title: () => faker.lorem.sentence(),
+  description: () => faker.lorem.paragraph(),
+  body: () => faker.lorem.paragraphs(3),
+  text: () => faker.lorem.text(),
+  sentence: () => faker.lorem.sentence(),
+  paragraph: () => faker.lorem.paragraph(),
+  slug: () => faker.lorem.slug(),
+  
+  // Commerce
+  price: () => parseFloat(faker.commerce.price()),
+  product: () => faker.commerce.productName(),
+  productName: () => faker.commerce.productName(),
+  productDescription: () => faker.commerce.productDescription(),
+  category: () => faker.commerce.department(),
+  
+  // Images
+  image: () => faker.image.url(),
+  imageUrl: () => faker.image.url(),
+  
+  // Date/Time
+  date: () => faker.date.recent().toISOString(),
+  pastDate: () => faker.date.past().toISOString(),
+  futureDate: () => faker.date.future().toISOString(),
+  birthDate: () => faker.date.birthdate().toISOString(),
+  
+  // Numbers
+  number: () => faker.number.int({ min: 1, max: 1000 }),
+  age: () => faker.number.int({ min: 18, max: 80 }),
+  rating: () => faker.number.int({ min: 1, max: 5 }),
+  quantity: () => faker.number.int({ min: 1, max: 100 }),
+  
+  // Boolean
+  boolean: () => faker.datatype.boolean(),
+  isActive: () => faker.datatype.boolean(),
+  isVerified: () => faker.datatype.boolean(),
+  
+  // Misc
+  uuid: () => faker.string.uuid(),
+  color: () => faker.color.human(),
+  word: () => faker.word.noun(),
+  words: () => faker.word.words(3),
+};
+
+// Get available faker fields
+app.get("/faker/fields", (req, res) => {
+  res.json({
+    message: "Available faker fields for auto-generation",
+    fields: Object.keys(fakerFieldMap),
+    usage: {
+      endpoint: "POST /:resource",
+      example: {
+        fields: ["name", "email", "avatar"],
+        count: 20
+      }
+    }
+  });
+});
+
 app.get("/", (req, res) => {
   const data = readData();
   const resources = Object.keys(data).filter(k => !k.startsWith("_"));
@@ -56,10 +150,11 @@ app.get("/", (req, res) => {
     endpoints: {
       "GET /:resource": "Get all items",
       "GET /:resource/:id": "Get single item",
-      "POST /:resource": "Create new item",
+      "POST /:resource": "Create new item OR generate fake data with { fields: [...], count: N }",
       "PUT /:resource/:id": "Replace item",
       "PATCH /:resource/:id": "Update item",
-      "DELETE /:resource/:id": "Delete item"
+      "DELETE /:resource/:id": "Delete item",
+      "GET /faker/fields": "List available faker fields"
     }
   });
 });
@@ -127,6 +222,43 @@ app.post("/:resource", (req, res) => {
     data[resource] = [];
     console.log(`           📁 Created new resource: ${resource}`);
   }
+  
+  // Check if this is a faker request (has 'fields' array)
+  if (Array.isArray(req.body.fields) && req.body.fields.length > 0) {
+    const { fields, count = 10 } = req.body;
+    
+    const generatedItems = [];
+    for (let i = 0; i < count; i++) {
+      const item = { 
+        id: faker.string.uuid(), 
+        createdAt: new Date().toISOString() 
+      };
+      
+      fields.forEach(field => {
+        if (fakerFieldMap[field]) {
+          item[field] = fakerFieldMap[field]();
+        } else {
+          // Default to random words if field not mapped
+          item[field] = faker.word.words(2);
+        }
+      });
+      
+      data[resource].push(item);
+      generatedItems.push(item);
+    }
+    
+    writeData(data);
+    console.log(`           ✅ Generated ${count} fake ${resource}`);
+    
+    return res.status(201).json({ 
+      message: `Successfully generated ${count} ${resource}`,
+      count: count,
+      sample: generatedItems.slice(0, 3),
+      total: data[resource].length
+    });
+  }
+  
+  // Normal POST - create single item with provided key-value pairs
   const newId = req.body.id || Date.now();
   if (data[resource].some(item => String(item.id) === String(newId))) {
     return res.status(409).json({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "360-mock-server",
-  "version": "1.1.0",
-  "description": "🚀 Zero-config dynamic mock REST API server for frontend developers",
+  "version": "1.2.0",
+  "description": "🚀 Zero-config dynamic mock REST API server with Faker.js auto-generation for frontend developers",
   "main": "lib/server.js",
   "bin": {
     "360-mock": "./bin/cli.js"
@@ -17,11 +17,13 @@
     "server",
     "json",
     "fake",
+    "faker",
     "backend",
     "frontend",
     "development",
     "testing",
-    "crud"
+    "crud",
+    "auto-generate"
   ],
   "author": "zahidrahimoon",
   "license": "MIT",
@@ -42,6 +44,7 @@
     "node": ">=14.0.0"
   },
   "dependencies": {
+    "@faker-js/faker": "^10.2.0",
     "commander": "^11.1.0",
     "cors": "^2.8.5",
     "express": "^4.18.2"