jsgui3-server 0.0.138 → 0.0.140

package/examples/json/README.md

@@ -0,0 +1,115 @@
+# JSON API Examples
+
+This directory contains examples of using JSGUI3 Server to create JSON APIs without HTML UI components.
+
+## Examples
+
+### 1. Basic JSON API (`basic-api/`)
+A simple JSON API server that demonstrates basic CRUD operations for a todo list.
+
+**Features:**
+- GET/POST endpoints for managing todos
+- In-memory data storage
+- Error handling
+- JSON request/response handling
+
+**Run:**
+```bash
+cd basic-api
+node server.js
+```
+
+**Test:**
+```bash
+# Get all todos
+curl http://localhost:3000/api/todos
+
+# Create a todo
+curl -X POST http://localhost:3000/api/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Learn JSGUI3","completed":false}'
+
+# Get specific todo
+curl http://localhost:3000/api/todo?id=1
+```
+
+### 2. Weather API (`weather-api/`)
+A weather API that simulates external service calls.
+
+**Features:**
+- Simulated weather data
+- Async operations
+- Error handling for invalid requests
+- Multiple endpoints for different data types
+
+### 3. User Management API (`user-api/`)
+A complete user management system with authentication simulation.
+
+**Features:**
+- User registration and login
+- JWT-like token simulation
+- Protected endpoints
+- Data validation
+
+## Architecture Notes
+
+These examples demonstrate how to use JSGUI3 Server for pure API development:
+
+1. **No UI Components**: Unlike other examples, these don't serve HTML/JS/CSS bundles
+2. **Function Publishers**: Uses the `api` configuration option for endpoint definition
+3. **Data Handling**: Demonstrates various patterns for data processing and storage
+4. **Error Handling**: Shows proper error responses and validation
+
+## Common Patterns
+
+### API Structure
+```javascript
+Server.serve({
+  api: {
+    // GET/POST /api/endpoint
+    'endpoint': (requestData) => {
+      // Process request
+      return responseData;
+    }
+  },
+  port: 3000
+});
+```
+
+### Data Validation
+```javascript
+'create-item': (data) => {
+  if (!data.name) {
+    throw new Error('Name is required');
+  }
+  // Process valid data
+  return { success: true, item: newItem };
+}
+```
+
+### Async Operations
+```javascript
+'async-endpoint': async (data) => {
+  const result = await someAsyncOperation(data);
+  return result;
+}
+```
+
+## Running Examples
+
+Each example follows the same pattern:
+
+1. `cd` into the example directory
+2. Run `node server.js`
+3. Test endpoints with curl or your preferred HTTP client
+4. Check the README.md in each directory for specific instructions
+
+## Development Notes
+
+These examples are designed to be:
+- **Simple**: Easy to understand and modify
+- **Complete**: Working end-to-end implementations
+- **Educational**: Demonstrating best practices
+- **Extensible**: Easy to add features or modify behavior
+
+For more advanced patterns, see the main documentation in `docs/`.

package/examples/json/basic-api/README.md

@@ -0,0 +1,345 @@
+# Basic JSON API Example
+
+This example demonstrates a complete JSON API server using JSGUI3 Server for managing a todo list. Unlike other examples, this serves **only JSON APIs** with no HTML UI components.
+
+## Features
+
+- ✅ **Pure JSON API**: No HTML, CSS, or JavaScript UI bundles
+- ✅ **Complete CRUD**: Create, Read, Update, Delete operations
+- ✅ **Data Validation**: Input validation with meaningful error messages
+- ✅ **Statistics**: Analytics endpoints for todo data
+- ✅ **Error Handling**: Proper HTTP error responses
+- ✅ **In-Memory Storage**: Simple data persistence (replace with database for production)
+
+## API Endpoints
+
+### Todos Management
+
+#### `GET /api/todos`
+Get all todos with summary statistics.
+
+**Response:**
+```json
+{
+  "todos": [
+    {
+      "id": 1,
+      "title": "Learn JSGUI3 Server",
+      "completed": false,
+      "createdAt": "2025-11-02T01:00:00.000Z"
+    }
+  ],
+  "total": 1,
+  "completed": 0
+}
+```
+
+#### `GET /api/todo?id={id}`
+Get a specific todo by ID.
+
+**Parameters:**
+- `id` (required): Todo ID number
+
+**Response:**
+```json
+{
+  "id": 1,
+  "title": "Learn JSGUI3 Server",
+  "completed": false,
+  "createdAt": "2025-11-02T01:00:00.000Z"
+}
+```
+
+#### `POST /api/create-todo`
+Create a new todo item.
+
+**Request Body:**
+```json
+{
+  "title": "New todo item",
+  "completed": false
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "todo": {
+    "id": 3,
+    "title": "New todo item",
+    "completed": false,
+    "createdAt": "2025-11-02T01:00:00.000Z",
+    "updatedAt": "2025-11-02T01:00:00.000Z"
+  },
+  "message": "Todo created successfully"
+}
+```
+
+#### `POST /api/update-todo`
+Update an existing todo.
+
+**Request Body:**
+```json
+{
+  "id": 1,
+  "title": "Updated title",
+  "completed": true
+}
+```
+
+#### `POST /api/delete-todo`
+Delete a todo item.
+
+**Request Body:**
+```json
+{
+  "id": 1
+}
+```
+
+#### `POST /api/toggle-todo`
+Toggle the completion status of a todo.
+
+**Request Body:**
+```json
+{
+  "id": 1
+}
+```
+
+### Analytics
+
+#### `GET /api/stats`
+Get todo statistics.
+
+**Response:**
+```json
+{
+  "total": 2,
+  "completed": 1,
+  "pending": 1,
+  "completionRate": "50.0%"
+}
+```
+
+#### `POST /api/clear-completed`
+Remove all completed todos.
+
+**Response:**
+```json
+{
+  "success": true,
+  "deletedCount": 1,
+  "remainingCount": 1,
+  "message": "Deleted 1 completed todos"
+}
+```
+
+## Running the Example
+
+1. **Start the server:**
+   ```bash
+   cd examples/json/basic-api
+   node server.js
+   ```
+
+2. **Test the API:**
+   ```bash
+   # Get all todos
+   curl http://localhost:3000/api/todos
+
+   # Create a new todo
+   curl -X POST http://localhost:3000/api/create-todo \
+     -H "Content-Type: application/json" \
+     -d '{"title":"Test todo","completed":false}'
+
+   # Get statistics
+   curl http://localhost:3000/api/stats
+
+   # Update a todo
+   curl -X POST http://localhost:3000/api/update-todo \
+     -H "Content-Type: application/json" \
+     -d '{"id":1,"completed":true}'
+
+   # Delete a todo
+   curl -X POST http://localhost:3000/api/delete-todo \
+     -H "Content-Type: application/json" \
+     -d '{"id":1}'
+   ```
+
+## Code Structure
+
+### Server Configuration
+
+```javascript
+Server.serve({
+  // No UI control - pure API server
+  // ctrl: undefined,
+
+  api: {
+    // Define your endpoints here
+    'todos': () => { /* ... */ },
+    'create-todo': (data) => { /* ... */ },
+    // ...
+  },
+
+  port: 3000
+});
+```
+
+### Data Validation
+
+```javascript
+'create-todo': (data) => {
+  if (!data.title || typeof data.title !== 'string') {
+    throw new Error('Title is required and must be a string');
+  }
+
+  if (data.title.length > 200) {
+    throw new Error('Title must be 200 characters or less');
+  }
+
+  // Process valid data...
+}
+```
+
+### Error Handling
+
+All thrown errors are automatically converted to JSON error responses:
+
+```json
+{
+  "error": "Title is required and must be a string"
+}
+```
+
+## Key Differences from UI Examples
+
+1. **No Control**: Unlike other examples, this doesn't specify a `ctrl` property
+2. **No Bundling**: No JavaScript/CSS bundling occurs since there's no UI
+3. **Pure API**: Only serves JSON responses to API endpoints
+4. **No HTML**: No web pages are served - only API endpoints
+
+## Production Considerations
+
+This example uses in-memory storage. For production, consider:
+
+- **Database Integration**: Replace the in-memory `todos` array with a database
+- **Authentication**: Add user authentication and authorization
+- **Rate Limiting**: Implement rate limiting to prevent abuse
+- **Input Sanitization**: Add more comprehensive input validation
+- **Logging**: Add request logging and monitoring
+- **CORS**: Configure CORS policies for web clients
+
+## Extending the Example
+
+### Adding a Database
+
+```javascript
+// Replace in-memory storage with database
+const db = require('some-database-library');
+
+const api = {
+  'todos': async () => {
+    const todos = await db.query('SELECT * FROM todos');
+    return { todos, total: todos.length };
+  },
+
+  'create-todo': async (data) => {
+    const result = await db.query('INSERT INTO todos (title, completed) VALUES (?, ?)',
+                                  [data.title, data.completed]);
+    return { success: true, id: result.insertId };
+  }
+  // ...
+};
+```
+
+### Adding Authentication
+
+```javascript
+// Add authentication middleware (conceptual)
+const authenticate = (req) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) throw new Error('No token provided');
+  // Verify token and return user info
+  return verifyToken(token);
+};
+
+const api = {
+  'protected-endpoint': (data, req) => {
+    const user = authenticate(req);
+    // Only authenticated users can access this
+    return { user, data };
+  }
+};
+```
+
+## Testing
+
+### Manual Testing
+
+Use curl or Postman to test all endpoints:
+
+```bash
+# Create test data
+curl -X POST http://localhost:3000/api/create-todo \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Test API","completed":false}'
+
+# Verify creation
+curl http://localhost:3000/api/todos
+
+# Test error handling
+curl -X POST http://localhost:3000/api/create-todo \
+  -H "Content-Type: application/json" \
+  -d '{"title":"","completed":false}'
+```
+
+### Automated Testing
+
+```javascript
+// test-api.js
+const assert = require('assert');
+
+async function testAPI() {
+  const baseUrl = 'http://localhost:3000/api';
+
+  // Test GET todos
+  const todosResponse = await fetch(`${baseUrl}/todos`);
+  const todosData = await todosResponse.json();
+  assert(Array.isArray(todosData.todos), 'Todos should be an array');
+
+  // Test POST create todo
+  const createResponse = await fetch(`${baseUrl}/create-todo`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: 'Test Todo', completed: false })
+  });
+  const createData = await createResponse.json();
+  assert(createData.success, 'Create should succeed');
+
+  console.log('✅ All API tests passed!');
+}
+
+testAPI().catch(console.error);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Route not found"**: Make sure the server is running and endpoints are correctly defined
+2. **"Unexpected token"**: Check that Content-Type header is set to `application/json`
+3. **"Title is required"**: Ensure request body includes required fields
+4. **Server won't start**: Check that port 3000 is not already in use
+
+### Debug Mode
+
+Run with debug logging:
+
+```bash
+DEBUG=* node server.js
+```
+
+This will show detailed request/response logging.

package/examples/json/basic-api/server.js

@@ -0,0 +1,199 @@
+// Basic JSON API Example - Todo List API
+// This example demonstrates a complete JSON API server with no HTML UI
+
+const Server = require('../../../server');
+
+// In-memory data store (in production, use a database)
+let todos = [
+  { id: 1, title: 'Learn JSGUI3 Server', completed: false, createdAt: new Date() },
+  { id: 2, title: 'Build JSON API', completed: true, createdAt: new Date() }
+];
+
+let nextId = 3;
+
+Server.serve({
+  // No UI control - pure API server
+  // ctrl: undefined,
+
+  api: {
+    // GET /api/todos - Get all todos
+    'todos': () => {
+      return {
+        todos: todos,
+        total: todos.length,
+        completed: todos.filter(t => t.completed).length
+      };
+    },
+
+    // GET /api/todo?id=1 - Get specific todo
+    'todo': (data) => {
+      const id = parseInt(data.id);
+      if (!id) {
+        throw new Error('Todo ID is required');
+      }
+
+      const todo = todos.find(t => t.id === id);
+      if (!todo) {
+        throw new Error('Todo not found');
+      }
+
+      return todo;
+    },
+
+    // POST /api/create-todo - Create new todo
+    'create-todo': (data) => {
+      if (!data.title || typeof data.title !== 'string') {
+        throw new Error('Title is required and must be a string');
+      }
+
+      if (data.title.length > 200) {
+        throw new Error('Title must be 200 characters or less');
+      }
+
+      const newTodo = {
+        id: nextId++,
+        title: data.title.trim(),
+        completed: Boolean(data.completed),
+        createdAt: new Date(),
+        updatedAt: new Date()
+      };
+
+      todos.push(newTodo);
+
+      return {
+        success: true,
+        todo: newTodo,
+        message: 'Todo created successfully'
+      };
+    },
+
+    // POST /api/update-todo - Update existing todo
+    'update-todo': (data) => {
+      const id = parseInt(data.id);
+      if (!id) {
+        throw new Error('Todo ID is required');
+      }
+
+      const todoIndex = todos.findIndex(t => t.id === id);
+      if (todoIndex === -1) {
+        throw new Error('Todo not found');
+      }
+
+      const todo = todos[todoIndex];
+
+      // Update allowed fields
+      if (data.title !== undefined) {
+        if (typeof data.title !== 'string' || data.title.length > 200) {
+          throw new Error('Title must be a string of 200 characters or less');
+        }
+        todo.title = data.title.trim();
+      }
+
+      if (data.completed !== undefined) {
+        todo.completed = Boolean(data.completed);
+      }
+
+      todo.updatedAt = new Date();
+
+      return {
+        success: true,
+        todo: todo,
+        message: 'Todo updated successfully'
+      };
+    },
+
+    // POST /api/delete-todo - Delete todo
+    'delete-todo': (data) => {
+      const id = parseInt(data.id);
+      if (!id) {
+        throw new Error('Todo ID is required');
+      }
+
+      const todoIndex = todos.findIndex(t => t.id === id);
+      if (todoIndex === -1) {
+        throw new Error('Todo not found');
+      }
+
+      const deletedTodo = todos.splice(todoIndex, 1)[0];
+
+      return {
+        success: true,
+        deletedTodo: deletedTodo,
+        message: 'Todo deleted successfully'
+      };
+    },
+
+    // POST /api/toggle-todo - Toggle completion status
+    'toggle-todo': (data) => {
+      const id = parseInt(data.id);
+      if (!id) {
+        throw new Error('Todo ID is required');
+      }
+
+      const todo = todos.find(t => t.id === id);
+      if (!todo) {
+        throw new Error('Todo not found');
+      }
+
+      todo.completed = !todo.completed;
+      todo.updatedAt = new Date();
+
+      return {
+        success: true,
+        todo: todo,
+        message: `Todo ${todo.completed ? 'completed' : 'marked incomplete'}`
+      };
+    },
+
+    // GET /api/stats - Get todo statistics
+    'stats': () => {
+      const total = todos.length;
+      const completed = todos.filter(t => t.completed).length;
+      const pending = total - completed;
+
+      return {
+        total: total,
+        completed: completed,
+        pending: pending,
+        completionRate: total > 0 ? (completed / total * 100).toFixed(1) + '%' : '0%'
+      };
+    },
+
+    // POST /api/clear-completed - Remove all completed todos
+    'clear-completed': () => {
+      const initialCount = todos.length;
+      todos = todos.filter(t => !t.completed);
+      const deletedCount = initialCount - todos.length;
+
+      return {
+        success: true,
+        deletedCount: deletedCount,
+        remainingCount: todos.length,
+        message: `Deleted ${deletedCount} completed todos`
+      };
+    }
+  },
+
+  port: 3000
+}).then(server => {
+  console.log('🚀 JSON API Server started successfully!');
+  console.log(`📡 Server running at: http://localhost:${server.port}`);
+  console.log('\n📋 Available endpoints:');
+  console.log('  GET  /api/todos           - Get all todos');
+  console.log('  GET  /api/todo?id=1       - Get specific todo');
+  console.log('  POST /api/create-todo     - Create new todo');
+  console.log('  POST /api/update-todo     - Update existing todo');
+  console.log('  POST /api/delete-todo     - Delete todo');
+  console.log('  POST /api/toggle-todo     - Toggle completion status');
+  console.log('  GET  /api/stats           - Get statistics');
+  console.log('  POST /api/clear-completed - Remove completed todos');
+  console.log('\n🧪 Test with:');
+  console.log('  curl http://localhost:3000/api/todos');
+  console.log('  curl -X POST http://localhost:3000/api/create-todo \\');
+  console.log('    -H "Content-Type: application/json" \\');
+  console.log('    -d \'{"title":"Test todo","completed":false}\'');
+
+}).catch(err => {
+  console.error('❌ Failed to start server:', err.message);
+  process.exit(1);
+});