@zze/mock-server 0.2.4

package/README.md

@@ -0,0 +1,643 @@
+# @zze/mock-server
+
+A reusable Node.js mock server for simulating backend APIs during local microfrontend development.
+
+## Features
+
+- 🚀 **Zero-config TypeScript support** - Write configs in JSON, JS, or TS
+- 🔄 **Hot reload** - Automatic config reloading on file changes
+- 🎭 **Scenarios** - Define multiple response scenarios per endpoint
+- 🌊 **Flows** - Activate groups of scenarios to simulate user journeys
+- 🎨 **Admin UI** - Visual dashboard at `/mock-admin` to control the server
+- 🔌 **REST API** - Programmatic control via admin endpoints
+- 📦 **Single package** - Everything bundled, no external dependencies needed
+
+## Installation
+
+```bash
+npm install --save-dev @zze/mock-server
+```
+
+## Quick Start
+
+### 1. Create your config directory structure
+
+```
+your-project/
+├── mock-config/
+│   ├── endpoints/
+│   │   └── users.json
+│   └── flows/
+│       └── error-flow.json
+└── package.json
+```
+
+### 2. Define an endpoint
+
+**mock-config/endpoints/users.json**
+```json
+{
+  "id": "get-users",
+  "path": "/users",
+  "method": "GET",
+  "defaultScenarioId": "success",
+  "scenarios": [
+    {
+      "id": "success",
+      "name": "Success Response",
+      "status": 200,
+      "body": [
+        { "id": 1, "name": "Alice" },
+        { "id": 2, "name": "Bob" }
+      ]
+    },
+    {
+      "id": "empty",
+      "name": "Empty List",
+      "status": 200,
+      "body": []
+    },
+    {
+      "id": "error",
+      "name": "Server Error",
+      "status": 500,
+      "body": { "error": "Internal server error" }
+    }
+  ]
+}
+```
+
+### 3. Start the server
+
+**Option A: Programmatic (recommended)**
+
+```typescript
+// scripts/mock-server.ts
+import { MockServer } from '@zze/mock-server';
+
+const server = new MockServer({
+  configPath: './mock-config',
+  port: 3001,
+  apiPrefix: '/api',
+  hotReload: true
+});
+
+await server.start();
+console.log('🎭 Mock server running at http://localhost:3001');
+console.log('📊 Admin UI at http://localhost:3001/mock-admin');
+```
+
+Run with:
+```bash
+npx tsx scripts/mock-server.ts
+```
+
+**Option B: Simple script in package.json**
+
+```json
+{
+  "scripts": {
+    "mock": "tsx scripts/mock-server.ts"
+  }
+}
+```
+
+### 4. Make requests
+
+```bash
+# Default scenario
+curl http://localhost:3001/api/users
+# → [{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]
+
+# Open admin UI to switch scenarios
+open http://localhost:3001/mock-admin
+```
+
+---
+
+## Configuration
+
+### Endpoint Config
+
+Each endpoint file defines an API endpoint with multiple response scenarios.
+
+```typescript
+interface EndpointConfig {
+  id: string;                    // Unique identifier
+  path: string;                  // URL path (supports Express patterns)
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  defaultScenarioId: string;     // ID of the default scenario
+  scenarios: ScenarioConfig[];   // Available response scenarios
+}
+```
+
+### Scenario Config
+
+```typescript
+interface ScenarioConfig {
+  id: string;                    // Unique within endpoint
+  name: string;                  // Display name in admin UI
+  status: number;                // HTTP status code (100-599)
+  body?: any;                    // Response body (JSON or function)
+  headers?: Record<string, string>;  // Custom response headers
+  delay?: number;                // Response delay in ms
+}
+```
+
+### Flow Config
+
+Flows activate multiple scenarios at once to simulate complex user journeys.
+
+```typescript
+interface FlowConfig {
+  id: string;                    // Unique identifier
+  name: string;                  // Display name
+  description?: string;          // Optional description
+  category?: string;             // Optional category for grouping in UI
+  endpointScenarios: {           // Map of endpointId → scenarioId
+    [endpointId: string]: string;
+  };
+}
+```
+
+**Example: mock-config/flows/error-flow.json**
+```json
+{
+  "id": "all-errors",
+  "name": "All Errors Flow",
+  "description": "Returns errors for all endpoints",
+  "category": "Error States",
+  "endpointScenarios": {
+    "get-users": "error",
+    "get-products": "error",
+    "create-order": "validation-error"
+  }
+}
+```
+
+---
+
+## TypeScript Configs
+
+You can write configs in TypeScript for type safety and dynamic responses:
+
+**mock-config/endpoints/users.ts**
+```typescript
+import type { EndpointConfig } from '@zze/mock-server';
+
+const endpoint: EndpointConfig = {
+  id: 'get-users',
+  path: '/users',
+  method: 'GET',
+  defaultScenarioId: 'success',
+  scenarios: [
+    {
+      id: 'success',
+      name: 'Success',
+      status: 200,
+      body: (req) => {
+        // Dynamic response based on request
+        const limit = parseInt(req.query.limit as string) || 10;
+        return Array.from({ length: limit }, (_, i) => ({
+          id: i + 1,
+          name: `User ${i + 1}`,
+          timestamp: new Date().toISOString()
+        }));
+      }
+    }
+  ]
+};
+
+export default endpoint;
+```
+
+---
+
+## Admin UI
+
+The built-in admin UI is available at `/mock-admin` and provides:
+
+- **Endpoints Panel**: View all endpoints, expand to see scenarios, click to activate
+  - Create new endpoints with the JSON editor
+  - Edit existing endpoint configurations
+  - Delete endpoints with confirmation
+- **Flows Panel**: View and activate user flows with category grouping
+  - Create new flows with the endpoint/scenario picker
+  - Edit or duplicate existing flows
+  - Delete flows with confirmation
+  - Collapsible category groups for organization
+  - Search/filter flows by name
+- **State Panel**: See current active flow and scenario count
+- **Controls**: Refresh data, reset to defaults
+
+![Admin UI Screenshot](./docs/admin-ui.png)
+
+---
+
+## Admin REST API
+
+Control the mock server programmatically:
+
+### State & Config
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/mock-admin/api/config` | Get all endpoints and flows |
+| GET | `/mock-admin/api/state` | Get current active state |
+| POST | `/mock-admin/api/scenarios/activate` | Activate a scenario |
+| POST | `/mock-admin/api/flows/activate` | Activate/deactivate a flow |
+| POST | `/mock-admin/api/reset` | Reset to default state |
+
+### Endpoint CRUD
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/mock-admin/api/endpoints` | Create a new endpoint |
+| PUT | `/mock-admin/api/endpoints/:id` | Update an existing endpoint |
+| DELETE | `/mock-admin/api/endpoints/:id` | Delete an endpoint |
+
+### Flow CRUD
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/mock-admin/api/flows` | Create a new flow |
+| PUT | `/mock-admin/api/flows/:id` | Update an existing flow |
+| DELETE | `/mock-admin/api/flows/:id` | Delete a flow |
+| POST | `/mock-admin/api/flows/:id/duplicate` | Duplicate an existing flow |
+
+### Examples
+
+```bash
+# Get current config
+curl http://localhost:3001/mock-admin/api/config
+
+# Activate a scenario
+curl -X POST http://localhost:3001/mock-admin/api/scenarios/activate \
+  -H "Content-Type: application/json" \
+  -d '{"endpointId": "get-users", "scenarioId": "error"}'
+
+# Activate a flow
+curl -X POST http://localhost:3001/mock-admin/api/flows/activate \
+  -H "Content-Type: application/json" \
+  -d '{"flowId": "all-errors"}'
+
+# Deactivate flow
+curl -X POST http://localhost:3001/mock-admin/api/flows/activate \
+  -H "Content-Type: application/json" \
+  -d '{"flowId": null}'
+
+# Reset to defaults
+curl -X POST http://localhost:3001/mock-admin/api/reset
+
+# Create a new endpoint
+curl -X POST http://localhost:3001/mock-admin/api/endpoints \
+  -H "Content-Type: application/json" \
+  -d '{"endpoint": {"id": "new-endpoint", "method": "GET", "path": "/api/test", "scenarios": [{"id": "default", "name": "Default", "response": {"status": 200, "body": {}}}]}}'
+
+# Update an endpoint
+curl -X PUT http://localhost:3001/mock-admin/api/endpoints/new-endpoint \
+  -H "Content-Type: application/json" \
+  -d '{"endpoint": {"id": "new-endpoint", "method": "GET", "path": "/api/test-updated", "scenarios": [{"id": "default", "name": "Default", "response": {"status": 200, "body": {"updated": true}}}]}}'
+
+# Delete an endpoint
+curl -X DELETE http://localhost:3001/mock-admin/api/endpoints/new-endpoint
+
+# Create a new flow
+curl -X POST http://localhost:3001/mock-admin/api/flows \
+  -H "Content-Type: application/json" \
+  -d '{"flow": {"id": "my-flow", "name": "My Flow", "category": "Testing", "endpointScenarios": {"get-users": "error"}}}'
+
+# Update a flow
+curl -X PUT http://localhost:3001/mock-admin/api/flows/my-flow \
+  -H "Content-Type: application/json" \
+  -d '{"flow": {"id": "my-flow", "name": "My Updated Flow", "category": "Testing", "endpointScenarios": {"get-users": "success"}}}'
+
+# Duplicate a flow
+curl -X POST http://localhost:3001/mock-admin/api/flows/my-flow/duplicate \
+  -H "Content-Type: application/json" \
+  -d '{"newId": "my-flow-copy"}'
+
+# Delete a flow
+curl -X DELETE http://localhost:3001/mock-admin/api/flows/my-flow
+```
+
+---
+
+## Programmatic API
+
+### MockServer Class
+
+```typescript
+import { MockServer } from '@zze/mock-server';
+
+const server = new MockServer({
+  configPath: './mock-config',  // Required
+  port: 3001,                   // Default: 3001
+  apiPrefix: '/api',            // Default: '/api'
+  hotReload: true               // Default: true
+});
+```
+
+### Lifecycle Methods
+
+```typescript
+// Start the server
+await server.start();
+
+// Stop the server
+await server.stop();
+
+// Restart (stop + start)
+await server.restart();
+
+// Manually reload config
+await server.reload();
+```
+
+### State & Info
+
+```typescript
+// Get server state
+const state = server.getState();
+// {
+//   running: true,
+//   port: 3001,
+//   endpointCount: 5,
+//   flowCount: 2,
+//   hotReloadActive: true,
+//   activeFlowId: null,
+//   activeScenarios: { 'get-users': 'error' }
+// }
+
+// Get loaded endpoints
+const endpoints = server.getEndpoints();
+
+// Get loaded flows
+const flows = server.getFlows();
+
+// Get config path
+const configPath = server.getConfigPath();
+```
+
+### Control Methods
+
+```typescript
+// Activate a specific scenario
+server.activateScenario('get-users', 'error');
+
+// Activate a flow
+server.activateFlow('all-errors');
+
+// Deactivate flow
+server.activateFlow(null);
+
+// Reset to defaults
+server.reset();
+```
+
+### Event Handlers
+
+```typescript
+// Listen for config reloads
+const unsubscribe = server.onReload((event) => {
+  console.log('Config reloaded:', event.changedFiles);
+});
+
+// Listen for errors
+server.onError((error) => {
+  console.error('Server error:', error);
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+### Advanced: Access Express App
+
+```typescript
+// Get the Express app instance (for custom middleware)
+const app = server.getApp();
+if (app) {
+  app.use('/custom', customMiddleware);
+}
+
+// Get the HTTP server (for WebSocket, etc.)
+const httpServer = server.getHttpServer();
+```
+
+---
+
+## Path Parameters & Patterns
+
+Endpoints support Express-style path patterns:
+
+```json
+{
+  "id": "get-user-by-id",
+  "path": "/users/:id",
+  "method": "GET",
+  "defaultScenarioId": "success",
+  "scenarios": [
+    {
+      "id": "success",
+      "name": "User Found",
+      "status": 200,
+      "body": { "id": 1, "name": "Alice" }
+    },
+    {
+      "id": "not-found",
+      "name": "Not Found",
+      "status": 404,
+      "body": { "error": "User not found" }
+    }
+  ]
+}
+```
+
+Dynamic response using path params (TypeScript):
+```typescript
+{
+  id: 'success',
+  name: 'User Found',
+  status: 200,
+  body: (req) => ({
+    id: parseInt(req.params.id),
+    name: `User ${req.params.id}`
+  })
+}
+```
+
+---
+
+## Response Delays
+
+Simulate network latency:
+
+```json
+{
+  "id": "slow-response",
+  "name": "Slow Response",
+  "status": 200,
+  "body": { "data": "loaded" },
+  "delay": 2000
+}
+```
+
+---
+
+## Custom Headers
+
+Add custom response headers:
+
+```json
+{
+  "id": "with-headers",
+  "name": "With Custom Headers",
+  "status": 200,
+  "headers": {
+    "X-Custom-Header": "custom-value",
+    "Cache-Control": "no-cache"
+  },
+  "body": { "data": "ok" }
+}
+```
+
+---
+
+## Hot Reload
+
+When `hotReload: true` (default), the server watches your config directory and automatically reloads when files change:
+
+- Add/remove endpoint files
+- Modify scenarios
+- Add/remove flows
+
+Changes take effect immediately without restarting the server. A 300ms debounce prevents rapid reloads during saves.
+
+---
+
+## Integration with Tests
+
+Use the mock server in your test setup:
+
+```typescript
+// test/setup.ts
+import { MockServer } from '@zze/mock-server';
+
+let server: MockServer;
+
+beforeAll(async () => {
+  server = new MockServer({
+    configPath: './test/mock-config',
+    port: 3099,
+    hotReload: false
+  });
+  await server.start();
+});
+
+afterAll(async () => {
+  await server.stop();
+});
+
+beforeEach(() => {
+  server.reset();
+});
+
+// In tests
+it('handles error response', async () => {
+  server.activateScenario('get-users', 'error');
+  
+  const response = await fetch('http://localhost:3099/api/users');
+  expect(response.status).toBe(500);
+});
+```
+
+---
+
+## Troubleshooting
+
+### Port already in use
+
+```
+Error: listen EADDRINUSE: address already in use :::3001
+```
+
+Change the port or kill the existing process:
+```bash
+lsof -i :3001 | grep LISTEN | awk '{print $2}' | xargs kill
+```
+
+### Config not loading
+
+- Ensure `configPath` points to a directory with `endpoints/` and `flows/` subdirectories
+- Check file extensions: `.json`, `.js`, or `.ts`
+- Validate JSON syntax
+- Check for required fields: `id`, `path`, `method`, `defaultScenarioId`, `scenarios`
+
+### TypeScript configs not working
+
+Ensure you have `typescript` installed. The package uses `jiti` for zero-config TS loading.
+
+---
+
+## API Reference
+
+### Types
+
+```typescript
+// Main options
+interface MockServerOptions {
+  configPath: string;
+  port?: number;
+  apiPrefix?: string;
+  hotReload?: boolean;
+  watcherOptions?: WatcherOptions;
+}
+
+// Server state
+interface MockServerState {
+  running: boolean;
+  port: number | null;
+  endpointCount: number;
+  flowCount: number;
+  hotReloadActive: boolean;
+  activeFlowId: string | null;
+  activeScenarios: Record<string, string | null>;
+}
+
+// Reload event
+interface ReloadEvent {
+  changedFiles: WatcherEvent[];
+  timestamp: Date;
+}
+```
+
+### Exports
+
+```typescript
+// Main class
+export { MockServer, createMockServer };
+
+// Types
+export type {
+  MockServerOptions,
+  MockServerState,
+  EndpointConfig,
+  ScenarioConfig,
+  FlowConfig,
+  HttpMethod,
+  ResponseBody,
+  ServerOptions,
+  ReloadEvent,
+  WatcherOptions
+};
+
+// Constants
+export { ADMIN_UI_PATH }; // '/mock-admin'
+```
+
+---
+
+## License
+
+MIT

package/dist/__tests__/mock-server.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for MockServer - the public API
+ */
+export {};
+//# sourceMappingURL=mock-server.test.d.ts.map

package/dist/__tests__/mock-server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-server.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mock-server.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}