ntropi 1.0.0-beta.1 → 1.0.0

package/README.md

@@ -2,35 +2,29 @@
 ![Ntropi Logo](https://github.com/Pushpender-18/DeLender/blob/main/ntropi-npm-bg.png?raw=true)
 
 <div align="center">
-	<div style="margin-top: 8px;">
-		<strong> 
-			<p>A live mock API generator that works without having any actual backend.
-			Perfect for frontend development, testing, and prototyping.</p>
-		</strong>
-	</div>	
+  <strong>
+    <p>
+      A live mock API generator for frontend development, testing, and prototyping,
+      with a built-in configuration website.
+    </p>
+  </strong>
 </div>
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Usage](#usage)
-  - [Basic Commands](#basic-commands)
-  - [Command Options](#command-options)
+- [CLI Usage](#cli-usage)
+  - [Commands](#commands)
+  - [Options](#options)
+  - [API Method Syntax](#api-method-syntax)
 - [Configuration File](#configuration-file)
+  - [Top-Level Properties](#top-level-properties)
   - [Endpoint Properties](#endpoint-properties)
+  - [Template and Data Behavior](#template-and-data-behavior)
+  - [Dynamic Token Reference](#dynamic-token-reference)
+- [Configuration Website](#configuration-website)
 - [Examples](#examples)
-  - [Example 1: Simple API for Frontend Development](#example-1-simple-api-for-frontend-development)
-  - [Example 2: Simulate Slow Network](#example-2-simulate-slow-network)
-  - [Example 3: Test Error Handling](#example-3-test-error-handling)
-  - [Example 4: Multiple Endpoints](#example-4-multiple-endpoints)
-  - [Example 5: Add Endpoints](#example-5-add-endpoints)
-  - [Example 6: Custom Config File](#example-6-custom-config-file)
-  - [Example 7: Complete Workflow](#example-7-complete-workflow)
-- [Advanced Usage](#advanced-usage)
-  - [Custom Response Data](#custom-response-data)
-  - [Testing Different Scenarios](#testing-different-scenarios)
-- [Tips](#tips)
 - [Troubleshooting](#troubleshooting)
 - [Authors](#authors)
 
@@ -42,247 +36,207 @@ npm install -g ntropi
 
 ## Quick Start
 
-Generate a config and run the server:
-
 ```bash
-ntropi --api users posts --delay 1000 --failure-rate 10
+# 1) Create config
+ntropi --api users posts --delay 500 --failure-rate 10
+
+# 2) Run server
 ntropi run
 ```
 
-## Usage
+By default, Ntropi starts at `http://localhost:8008`.
+If port `8008` is occupied, it automatically tries the next free port.
 
-### Basic Commands
+## CLI Usage
 
-#### Run the Mock Server
+### Commands
 
 ```bash
-# Run with default config (ntropi-config.json)
+# Generate or update config (default: ntropi-config.json)
+ntropi [options]
+
+# Run server using default config file
 ntropi run
 
-# Run with custom config file
-ntropi run --config my-config.json
+# Same as above using flag
+ntropi --run
 ```
 
-#### Generate Configuration
-
-```bash
-# Generate default config with default settings
-ntropi
+### Options
 
-# Generate config with specific APIs
-ntropi --api users posts products
+| Option | Shorthand | Description |
+| --- | --- | --- |
+| `--help` | - | Show help output |
+| `run` | - | Run the mock server |
+| `--run` | `-r` | Run the mock server |
+| `--api <values...>` | `-a` | Endpoints to generate/update |
+| `--delay <num>` | `-d` | Response delay in milliseconds (integer, `>= 0`) |
+| `--failure-rate <num>` | `-f` | Failure percentage (`0` to `100`) |
+| `--config <file>` | `-c` | Config file path |
+| `run --editor-only` | - | Start only the configuration website (no mock endpoints) |
 
-# Generate config with delay (in milliseconds)
-ntropi --api users --delay 2000
+### API Method Syntax
 
-# Generate config with failure rate (0-100%)
-ntropi --api users --failure-rate 50
+You can set endpoint methods directly in `--api` values:
 
-# Combine multiple options
-ntropi --api users posts --delay 1000 --failure-rate 25
-```
+```bash
+# Default method is GET
+ntropi --api users products
 
-### Command Options
+# Explicit method
+ntropi --api users:POST orders:DELETE
 
-| Option | Shorthand | Description | Example |
-|--------|-----------|-------------|---------|
-| `--help` | | Show help information | `ntropi --help` |
-| `run` |  | Run the mock server | `ntropi run` |
-| `--api` | `-a` | Specify API endpoints | `ntropi --api users posts` |
-| `--delay` | `-d` | Set response delay (ms) | `ntropi --delay 2000` |
-| `--failure-rate` | `-f` | Set failure rate (0-100%) | `ntropi --failure-rate 30` |
-| `--config` | `-c` | Specify config file | `ntropi --config custom.json` |
+# Shorthand methods
+# G=GET, P=POST, U=PUT, D=DELETE, H=PATCH
+ntropi --api users:G orders:P profile:U health:D patch-test:H
+```
 
 ## Configuration File
 
-The configuration file (`ntropi-config.json`) defines your mock API endpoints:
+Default file: `ntropi-config.json`
 
 ```json
 {
+  "localhost": true,
   "endpoints": [
     {
       "path": "/api/users",
       "method": "GET",
-      // If data is an array then one
-      // item is sent at random
       "data": [
-        {"id": 1, "name": "John Doe"},
-        {"id": 2, "name": "Jane Smith"}
+        { "id": 1, "name": "$name" },
+        { "id": 2, "name": "$name" }
       ],
-      "delay": 1000,
-      "failureRate": 10
-    },
-    {
-      "path": "/api/posts",
-      "method": "GET",
-      // If data is not an array then
-      // data is sent as it is
-      "data": 
-        {"id": 1, "title": "Hello World"},
-      "delay": 0,
-      "failureRate": 0
+      "delay": 300,
+      "failureRate": 5,
+      "cacheSize": 5
     }
   ]
 }
 ```
 
-**Note:** If data is an array then an item is choosen at random otherwise the data is sent as it is. 
+### Top-Level Properties
+
+- `endpoints` (required): array of endpoint definitions.
+- `localhost` (optional):
+  - `true` or omitted: bind to `127.0.0.1`.
+  - `false`: bind to `0.0.0.0` for LAN/network access.
 
 ### Endpoint Properties
 
-- **path**: API endpoint path (e.g., `/api/users`)
-- **method**: HTTP method (`GET`, `POST`, `PUT`, `DELETE`, etc.)
-- **data**: Response data (can be any valid JSON)
-- **delay**: Response delay in milliseconds
-- **failureRate**: Percentage chance of returning 500 error (0-100)
+- `path` (required): route path, must start with `/`.
+- `method` (required): one of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.
+- `data` (required): source data used for response generation.
+- `delay` (optional): non-negative number in milliseconds.
+- `failureRate` (optional): number in range `0..100`.
+- `cacheSize` (optional): positive integer response cache size.
+- `template` (optional): object template that maps placeholders to `data`.
 
-## Examples
+### Template and Data Behavior
 
-### Example 1: Simple API for Frontend Development
+- If `template` is not provided:
+  - array `data`: one top-level item is randomly selected (token resolved if present).
+  - object/string `data`: returned directly (after token resolution).
+- If `template` is provided:
+  - `data` must be a non-empty array.
+  - indexed placeholders like `$1`, `$2` refer to array positions.
+  - nested template objects/arrays are supported.
 
-```bash
-# Create a users API with no delay
-ntropi --api users --delay 0 --failure-rate 0
-ntropi run
+Template example:
+
+```json
+{
+  "endpoints": [
+    {
+      "path": "/api/profile",
+      "method": "GET",
+      "data": [
+        ["active", "inactive"],
+        { "name": "$name", "age": "$int(18-40)" }
+      ],
+      "template": {
+        "status": "$1",
+        "user": "$2"
+      },
+      "delay": 0,
+      "failureRate": 0
+    }
+  ]
+}
 ```
 
-Access at: `http://localhost:8008/api/users`
+### Custom Dataset Generator
 
-### Example 2: Simulate Slow Network
+We have built a powerful custom dataset generator designed to deliver instant, ready-to-use datasets tailored to your exact specifications. Simply define your parameters, set your desired values, and generate structured data on demand, no manual effort required.
 
-```bash
-# Create API with 3 second delay
-ntropi --api products --delay 3000
-ntropi run
-```
+### Dynamic Token Reference
 
-### Example 3: Test Error Handling
+Supported value generators in `data` strings:
 
-```bash
-# Create API with 50% failure rate
-ntropi --api orders --failure-rate 50
-ntropi run
-```
+- `$name`
+- `$string(min-max)` or `$string(n)`
+- `$int(min-max)` or `$int(n)`
+- `$float(min-max,decimals)`
+- `$bool`
+- `$date(format)` (or `$date` for ISO timestamp)
+- `$uuid`
 
-### Example 4: Multiple Endpoints
+Escape tokens with `\\$` to keep them as literal text.
 
-```bash
-# Create multiple APIs with different configurations
-ntropi --api users posts comments products
-ntropi run
-```
+## Configuration Website
 
-Then manually edit `ntropi-config.json` to customize each endpoint.
-
-### Example 5: Add Endpoints
+When you run Ntropi, it also serves a configuration website at the server root.
 
 ```bash
-# Add APIs to existing configuratoin
-ntropi --api users 
-ntropi --api posts 
-ntropi --api comments 
-ntropi --api products
 ntropi run
 ```
 
+Then open:
 
-### Example 6: Custom Config File
+- `http://localhost:8008/` (or the printed port)
 
-```bash
-# Use a specific config file
-ntropi run --config staging-api.json
-```
-
-### Example 7: Complete Workflow
+Editor-only mode:
 
 ```bash
-# 1. Generate config with 3 APIs
-ntropi --api users posts comments --delay 500 --failure-rate 5
-
-# 2. Edit ntropi-config.json to customize responses
+ntropi run --editor-only
+```
 
-# 3. Run the server
-ntropi run
+This starts only the configuration website and management APIs, without generating mock API endpoints.
 
-# 4. Access your mock APIs
-# GET http://localhost:8008/api/users
-# GET http://localhost:8008/api/posts
-# GET http://localhost:8008/api/comments
-```
+## Examples
 
-## Advanced Usage
+```bash
+# Basic endpoints
+ntropi --api users posts comments
 
-### Custom Response Data
+# With delay and failures
+ntropi --api orders payments --delay 1200 --failure-rate 25
 
-Edit `ntropi-config.json` to add custom response data:
+# Mixed methods
+ntropi --api users:G users:POST users:PUT users:D
 
-```json
-{
-  "endpoints": [
-    {
-      "path": "/api/users/1",
-      "method": "GET",
-      "data": {
-        "id": 1,
-        "name": "Alice Johnson",
-        "email": "alice@example.com",
-        "role": "admin"
-      },
-      "delay": 500,
-      "failureRate": 0
-    }
-  ]
-}
+# Custom config file
+ntropi --api products --config staging.json
+ntropi run --config staging.json
 ```
 
-### Testing Different Scenarios
+## Troubleshooting
 
-```json
-{
-  "endpoints": [
-    {
-      "path": "/api/fast-endpoint",
-      "method": "GET",
-      "data": {"message": "Lightning fast!"},
-      "delay": 0,
-      "failureRate": 0
-    },
-    {
-      "path": "/api/slow-endpoint",
-      "method": "GET",
-      "data": {"message": "Taking my time..."},
-      "delay": 5000,
-      "failureRate": 0
-    },
-    {
-      "path": "/api/unreliable-endpoint",
-      "method": "GET",
-      "data": {"message": "Hope I work!"},
-      "delay": 1000,
-      "failureRate": 80
-    }
-  ]
-}
-```
+### Config validation error
 
-## Tips
+Check that:
 
-1. **Start Simple**: Begin with basic endpoints and add complexity as needed
-2. **Test Error States**: Use `failureRate` to ensure your app handles errors gracefully
-3. **Realistic Delays**: Use delays to simulate real-world network conditions
-4. **Version Control**: Commit your config files to share API mocks with your team
-5. **Multiple Configs**: Use different config files for different testing scenarios
+- each endpoint has `path`, `method`, `data`
+- `path` starts with `/`
+- `method` is valid
+- `delay >= 0` and `failureRate` is in `0..100`
 
-## Troubleshooting
+### Port already in use
 
-### Port Already in Use
-If port 8008 is busy, Ntropi will automatically try the next available port.
+Ntropi automatically increments the port until it finds a free one.
 
-### Config File Not Found
-Make sure you've generated a config file first or specify the correct path with `--config`.
+### Endpoint not changing after edit
 
-### Syntax Error in Config
-Validate your JSON file using a JSON validator or linter.
+Ntropi hot-reloads config file changes. If you changed endpoint `path`/`method`, the server restarts automatically. For value-only changes (like `delay`, `failureRate`, `data`), endpoints keep running and use new values on next request.
 
 ## Authors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntropi",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0",
   "description": "A live mock api generator that works without having any actual backend.",
   "author": "Amitrajeet Konch, Pushpender Singh",
   "type": "module",
@@ -9,14 +9,15 @@
     "ntropi": "src/app.js"
   },
   "scripts": {
-    "test": "vitest"
+    "test": "vitest",
+    "frontend:build": "cd src/frontend && npm run build"
   },
   "dependencies": {
-    "dotenv": "^17.2.3",
+    "@fastify/static": "^9.0.0",
     "fastify": "^5.7.4"
   },
   "devDependencies": {
-    "verdaccio": "^6.2.5",
+    "@fastify/cors": "^11.2.0",
     "vitest": "^4.0.18"
   }
 }

package/src/app.js

@@ -7,13 +7,11 @@ import { updateConfig } from './libs/config_updater.js';
 const args = process.argv.slice(2);
 const CONFIG = parseArgs(args);
 
-// Error Handling
 if (CONFIG.error) {
 	console.log(`Error: ${CONFIG.error}`);
 	process.exit(1);
 }
 
-// Help
 if (CONFIG.help) {
 	console.log(`
 Usage: node app.js [options]
@@ -30,9 +28,8 @@ Options:
 }
 
 if (CONFIG.run) {
-	// Run Server
 	const configPath = CONFIG.config || 'ntropi-config.json';
-	await run_server(configPath);
+	await run_server(configPath, CONFIG.configOnly);
 } else {
 	updateConfig(CONFIG);
 }

package/src/frontend/README.md

@@ -0,0 +1,16 @@
+# React + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.

package/src/frontend/eslint.config.js

@@ -0,0 +1,29 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{js,jsx}'],
+    extends: [
+      js.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+    },
+  },
+])

package/src/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Ntropi Engine</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/src/frontend/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.2.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.36.0",
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "vite": "^7.3.1"
+  }
+}