jsgui3-server 0.0.150 → 0.0.152

package/docs/swagger.md

@@ -0,0 +1,316 @@
+# Swagger / OpenAPI Documentation
+
+jsgui3-server includes **built-in, zero-dependency** Swagger / OpenAPI 3.0.3 support.  Every API you define — whether through `Server.serve()` or `server.publish()` — is automatically documented and browsable via an interactive Swagger UI.
+
+## Quick Start
+
+```js
+const Server = require('jsgui3-server/server');
+
+Server.serve({
+    port: 8080,
+    api: {
+        'users/list': {
+            handler: listUsers,
+            method: 'POST',
+            summary: 'List all users',
+            tags: ['Users']
+        }
+    }
+});
+```
+
+Open your browser:
+
+| URL | Purpose |
+|-----|---------|
+| `http://localhost:8080/api/docs` | Interactive Swagger UI |
+| `http://localhost:8080/api/openapi.json` | Raw OpenAPI 3.0 spec (JSON) |
+
+---
+
+## Configuration
+
+The `swagger` option controls whether the routes are registered:
+
+```js
+Server.serve({
+    swagger: true,   // Always enable  (default in dev)
+    swagger: false,  // Always disable (default in production)
+    // swagger omitted → auto (enabled when NODE_ENV !== 'production')
+});
+```
+
+You can also pass an object for fine-grained control:
+
+```js
+Server.serve({
+    swagger: {
+        title: 'My Service API',
+        version: '2.0.0',
+        description: 'Custom description for the spec info block'
+    }
+});
+```
+
+### Environment-Based Defaults
+
+| `NODE_ENV`   | `swagger` omitted | `swagger: true` | `swagger: false` |
+|--------------|-------------------|-----------------|------------------|
+| development  | ✅ enabled        | ✅ enabled      | ❌ disabled      |
+| production   | ❌ disabled       | ✅ enabled      | ❌ disabled      |
+| *(unset)*    | ✅ enabled        | ✅ enabled      | ❌ disabled      |
+
+---
+
+## Defining API Metadata
+
+### Declarative API (recommended)
+
+Pass metadata directly in the `api` option of `Server.serve()`:
+
+```js
+Server.serve({
+    port: 8080,
+    api: {
+        'products/search': {
+            handler: searchProducts,
+            method: 'POST',
+            summary: 'Search products',
+            description: 'Full-text search across the product catalog.',
+            tags: ['Products', 'Search'],
+            params: {
+                query:     { type: 'string',  description: 'Search query',     required: true },
+                page:      { type: 'integer', description: 'Page number',      default: 1 },
+                page_size: { type: 'integer', description: 'Results per page', default: 25 },
+                sort:      { type: 'string',  description: 'Sort field',       enum: ['name', 'price', 'date'] }
+            },
+            returns: {
+                rows:        { type: 'array',   items: { type: 'object' } },
+                total_count: { type: 'integer', description: 'Total matching results' },
+                page:        { type: 'integer' }
+            }
+        }
+    }
+});
+```
+
+### Imperative API
+
+Use `server.publish()` with a `meta` object:
+
+```js
+const server = new Server({ website: false });
+
+server.publish('users/create', createUser, {
+    method: 'POST',
+    summary: 'Create a new user',
+    description: 'Creates a user account and returns the user object.',
+    tags: ['Users'],
+    params: {
+        name:  { type: 'string', required: true, description: 'Full name' },
+        email: { type: 'string', required: true, description: 'Email address' }
+    },
+    returns: {
+        id:    { type: 'integer', description: 'New user ID' },
+        name:  { type: 'string' },
+        email: { type: 'string' }
+    }
+});
+
+// Register swagger routes after all publish() calls:
+server._register_swagger_routes({ title: 'User Service' });
+```
+
+---
+
+## Metadata Reference
+
+All metadata fields are **optional**.  Endpoints without metadata still produce a valid (minimal) Swagger entry.
+
+### Endpoint Metadata Fields
+
+| Field                | Type     | Default         | Purpose |
+|----------------------|----------|-----------------|---------|
+| `method`             | string   | `'POST'`        | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
+| `summary`            | string   | —               | One-line summary shown in Swagger UI operation list |
+| `description`        | string   | —               | Multi-line Markdown description for expanded view |
+| `tags`               | string[] | auto-detected   | Grouping tags (auto-detected from route if omitted) |
+| `params`             | Object   | —               | Request body schema (see schema format below) |
+| `returns`            | Object   | —               | Response body schema (see schema format below) |
+| `deprecated`         | boolean  | `false`         | Strike-through in Swagger UI |
+| `operationId`        | string   | auto-generated  | Unique operation identifier |
+| `response_description`| string  | `'Successful response'` | Custom 200 response description |
+| `schema`             | Object   | —               | Alternative to `params` (from Function_Publisher) |
+
+### Schema Format
+
+The `params` and `returns` objects use a simple `{key: definition}` format:
+
+```js
+{
+    field_name: {
+        type: 'string',       // 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object'
+        description: '...',   // Human-readable description
+        default: 'value',     // Default value
+        required: true,       // Whether the field is required
+        enum: ['a', 'b'],     // Allowed values
+        items: { type: '...' } // For type: 'array' — describes each item
+    }
+}
+```
+
+This simple format is automatically converted to OpenAPI Schema Objects by the spec generator.
+
+You can also pass raw OpenAPI schemas if you need more control:
+
+```js
+{
+    type: 'object',
+    properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' }
+    },
+    required: ['name']
+}
+```
+
+### Tag Auto-Detection
+
+When an endpoint has no explicit `tags`, a tag is automatically derived from the route path:
+
+| Route | Auto-Tag |
+|-------|----------|
+| `/api/users/list` | `users` |
+| `/api/data/products` | `data` |
+| `/api/admin/v1/status` | `admin` |
+| `/health` | `health` |
+
+---
+
+## Architecture
+
+```
+Server.serve({ api: {...} })
+        │
+        ├── serve-factory.js          ─── normalises endpoints
+        │       │                          preserves summary, tags, params, returns
+        │       ▼
+        ├── server.publish(name, fn, meta)
+        │       │
+        │       ├── Function_Publisher  ─── stores api_meta
+        │       └── _api_registry[]    ─── indexed for OpenAPI
+        │
+        └── _register_swagger_routes()
+                │
+                └── Swagger_Publisher (extends HTTP_Publisher)
+                        │
+                        ├── /api/openapi.json  ─── openapi.js generates spec
+                        │                           walks _api_registry + function_publishers
+                        │                           converts params/returns → OpenAPI schemas
+                        │
+                        └── /api/docs          ─── swagger-ui.js generates HTML
+                                                    loads Swagger UI from CDN
+                                                    dark theme matching jsgui3
+```
+
+### Source Files
+
+| File | Purpose |
+|------|---------|
+| `publishers/swagger-publisher.js` | `Swagger_Publisher` class (extends `HTTP_Publisher`) |
+| `openapi.js` | OpenAPI 3.0.3 spec generator (zero dependencies) |
+| `publishers/swagger-ui.js` | HTML page generator (CDN-based Swagger UI) |
+| `publishers/http-function-publisher.js` | Stores `api_meta` on publisher instances |
+| `publishers/Publishers.js` | Registry — includes `'swagger'` entry |
+| `server.js` | `publish()` + `_register_swagger_routes()` |
+| `serve-factory.js` | Metadata flow + auto-registration |
+| `tests/openapi.test.js` | 14 tests across 5 suites |
+
+---
+
+## Customisation
+
+### Title and Version
+
+```js
+Server.serve({
+    swagger: { title: 'My API', version: '2.0.0' }
+});
+```
+
+### Manual Registration
+
+For servers created with `new Server(...)` directly:
+
+```js
+const server = new Server({ website: false });
+// ... server.publish() calls ...
+server._register_swagger_routes({
+    title: 'My API',
+    version: '3.0.0',
+    description: 'API for my service'
+});
+```
+
+### Standalone Publisher
+
+You can also create a `Swagger_Publisher` independently and attach it
+to any server with access to the router:
+
+```js
+const Swagger_Publisher = require('jsgui3-server/publishers/swagger-publisher');
+
+const swagger = new Swagger_Publisher({
+    server: my_server,
+    title: 'My API',
+    version: '3.0.0'
+});
+
+my_server.server_router.set_route('/api/openapi.json', swagger, swagger.handle_http.bind(swagger));
+my_server.server_router.set_route('/api/docs', swagger, swagger.handle_http.bind(swagger));
+```
+
+The publisher is also available in the `Publishers` registry:
+
+```js
+const Publishers = require('jsgui3-server/publishers/Publishers');
+const Swagger_Publisher = Publishers.swagger;
+```
+
+### Disabling in Production
+
+Swagger is automatically disabled when `NODE_ENV=production`.  To force it on:
+
+```js
+Server.serve({ swagger: true });
+```
+
+---
+
+## How It Works Internally
+
+1. **Endpoint registration** — `server.publish()` creates a `Function_Publisher` and adds an entry to `server._api_registry` with the full metadata.
+
+2. **Metadata normalisation** — `serve-factory.js` preserves `summary`, `tags`, `params`, `returns`, and `schema` from the declarative API definition and passes them through to `publish()`.
+
+3. **Spec generation** — When `/api/openapi.json` is requested, `openapi.js` walks the `_api_registry` and `function_publishers` arrays, converts the simple schema format to OpenAPI Schema Objects, and assembles a complete OpenAPI 3.0.3 document.
+
+4. **Swagger UI** — When `/api/docs` is requested, a pre-generated HTML page is served that loads Swagger UI from the unpkg CDN and points it at `/api/openapi.json`.
+
+---
+
+## Testing
+
+Run the test suite:
+
+```bash
+node --test tests/openapi.test.js
+```
+
+This runs 14 tests across 5 suites:
+- **simple_schema_to_openapi** — schema conversion edge cases
+- **generate_openapi_spec** — spec structure, minimal metadata, route filtering
+- **collect_api_entries** — deduplication across data sources
+- **generate_swagger_html** — HTML output and CDN links
+- **Swagger routes integration** — end-to-end HTTP tests with a real server

package/docs/system-architecture.md

@@ -32,29 +32,29 @@ JSGUI3 Server is a Node.js-based web framework that serves modern JavaScript GUI
 
 **Purpose:** Handles conversion of various content types to HTTP responses.
 
-**Key Publishers:**
-- `HTTP_Webpage_Publisher`: Serves bundled JSGUI3 controls as complete web pages
-- `HTTP_Website_Publisher`: Manages multi-page websites
-- `HTTP_Function_Publisher`: Exposes JavaScript functions as REST API endpoints
-- `HTTP_Observable_Publisher`: Streams observable-backed SSE
-- `HTTP_SSE_Publisher`: General-purpose SSE fan-out publisher
-- `HTTP_CSS_Publisher`: Serves CSS stylesheets
-- `HTTP_JS_Publisher`: Serves JavaScript bundles
-- `HTTP_Image_Publisher`: Handles image file serving
+**Key Publishers:**
+- `HTTP_Webpage_Publisher`: Serves bundled JSGUI3 controls as complete web pages
+- `HTTP_Website_Publisher`: Manages multi-page websites
+- `HTTP_Function_Publisher`: Exposes JavaScript functions as REST API endpoints
+- `HTTP_Observable_Publisher`: Streams observable-backed SSE
+- `HTTP_SSE_Publisher`: General-purpose SSE fan-out publisher
+- `HTTP_CSS_Publisher`: Serves CSS stylesheets
+- `HTTP_JS_Publisher`: Serves JavaScript bundles
+- `HTTP_Image_Publisher`: Handles image file serving
 
 ### 3. Resource Management Layer
 **Directory:** `resources/`
 
 **Purpose:** Provides abstractions for accessing different types of data and functionality.
 
-**Key Resources:**
-- `Server_Resource_Pool`: Manages collections of resources with lifecycle management
-- `Process_Resource`: Local process resource (`direct` default, optional `pm2`)
-- `Remote_Process_Resource`: HTTP-controlled remote process resource
-- `Website_Resource`: Wraps website objects for server integration
-- `File_System_Resource`: Provides file system access
-- `Data_Resource`: Handles data storage and retrieval
-- `Local_Server_Info_Resource`: Provides server environment information
+**Key Resources:**
+- `Server_Resource_Pool`: Manages collections of resources with lifecycle management
+- `Process_Resource`: Local process resource (`direct` default, optional `pm2`)
+- `Remote_Process_Resource`: HTTP-controlled remote process resource
+- `Website_Resource`: Wraps website objects for server integration
+- `File_System_Resource`: Provides file system access
+- `Data_Resource`: Handles data storage and retrieval
+- `Local_Server_Info_Resource`: Provides server environment information
 
 ### 4. Processing Layer
 **Directory:** `resources/processors/`
@@ -105,6 +105,8 @@ Client Request
     ↓
 HTTP Server (Node.js http/https)
     ↓
+Middleware Pipeline (server.use)     ← gzip/deflate/brotli, CORS, logging, etc.
+    ↓
 Server Router
     ↓
 Resource Pool
@@ -118,6 +120,10 @@ Content Processing/Bundling
 HTTP Response
 ```
 
+Middleware functions registered via `server.use(fn)` execute in order before
+the router. If no middleware is registered, the router is called directly
+with zero overhead. See [Middleware Guide](middleware-guide.md) for details.
+
 ### Component Serving Flow
 
 ```
@@ -276,4 +282,4 @@ Add new processing pipelines for assets and data.
 
 ---
 
-This architecture document provides the foundation for understanding how JSGUI3 Server components work together. For detailed implementation of specific components, refer to their individual documentation files.
+This architecture document provides the foundation for understanding how JSGUI3 Server components work together. For detailed implementation of specific components, refer to their individual documentation files.

package/examples/controls/1) window/server.js

@@ -105,9 +105,14 @@ if (require.main === module) {
                 throw err;
             } else {
                 // Should have build it by now...
-    
+
                 console.log('server started');
+                server.print_endpoints({
+                    prefix: 'active endpoint'
+                });
             }
+        }, {
+            on_port_conflict: 'auto-loopback'
         });
     })
 

package/examples/controls/21) mvvm and declarative api/check.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const jsgui = require('./client');
+const { UserProfileEditor } = jsgui.controls;
+
+let pass = 0, fail = 0;
+function check(label, ok) {
+    if (ok) { console.log(`  ✅ ${label}`); pass++; }
+    else { console.log(`  ❌ ${label}`); fail++; }
+}
+
+console.log('\n═══ MVVM & Declarative API Check ═══\n');
+
+// ── 1. Construction & Model Initialisation ──────────────────────────
+const editor = new UserProfileEditor({
+    first_name: 'John',
+    last_name: 'Smith',
+    is_active: true
+});
+
+check('Control instantiated', !!editor);
+check('Has data.model layer', !!editor.data && !!editor.data.model);
+check('Has view.data.model layer', !!editor.view && !!editor.view.data && !!editor.view.data.model);
+
+// ── 2. Raw Model Values ─────────────────────────────────────────────
+check('first_name stored correctly', editor.data.model.get('first_name').value === 'John');
+check('last_name stored correctly', editor.data.model.get('last_name').value === 'Smith');
+check('is_active stored correctly', editor.data.model.get('is_active').value === true);
+
+// ── 3. Computed Properties ──────────────────────────────────────────
+const fullName = editor.data.model.get('full_name').value;
+check('Computed full_name = "John Smith"', fullName === 'John Smith');
+
+const statusText = editor.data.model.get('status_text').value;
+check('Computed status_text = "Active Account"', statusText === 'Active Account');
+
+// ── 4. Server-Side HTML Rendering ───────────────────────────────────
+const html = editor.all_html_render();
+check('HTML renders without throwing', typeof html === 'string' && html.length > 0);
+check('HTML has .profile-card wrapper', html.includes('profile-card'));
+check('HTML has active-state class', html.includes('active-state'));
+check('HTML has profile-header section', html.includes('profile-header'));
+check('HTML has profile-body section', html.includes('profile-body'));
+check('HTML has profile-footer section', html.includes('profile-footer'));
+check('HTML has Toggle Status button', html.includes('Toggle Status'));
+check('HTML has Save Profile button', html.includes('Save Profile'));
+check('HTML has input elements for bind-value', html.includes('<input'));
+check('HTML has First Name label', html.includes('First Name:'));
+check('HTML has Last Name label', html.includes('Last Name:'));
+// Note: bind-text content (e.g. "John Smith") is injected client-side
+// during activation. SSR renders the structure; bind-text populates at runtime.
+
+// ── 5. Model Mutation: Update first_name ─────────────────────────────
+editor.data.model.set('first_name', 'Alice');
+const updatedFullName = editor.data.model.get('full_name').value;
+check('Computed full_name updates to "Alice Smith"', updatedFullName === 'Alice Smith');
+
+// ── 6. Model Mutation: toggleStatus() ────────────────────────────────
+editor.toggleStatus();
+check('is_active toggled to false', editor.data.model.get('is_active').value === false);
+check('Computed status_text = "Suspended Account"', editor.data.model.get('status_text').value === 'Suspended Account');
+
+// ── 7. Toggle back ──────────────────────────────────────────────────
+editor.toggleStatus();
+check('is_active toggled back to true', editor.data.model.get('is_active').value === true);
+check('Computed status_text back to "Active Account"', editor.data.model.get('status_text').value === 'Active Account');
+
+// ── 8. Edge cases ───────────────────────────────────────────────────
+editor.data.model.set('first_name', '');
+check('Computed full_name with empty first = "Smith"', editor.data.model.get('full_name').value === 'Smith');
+
+editor.data.model.set('last_name', '');
+check('Computed full_name with both empty = ""', editor.data.model.get('full_name').value === '');
+
+editor.data.model.set('first_name', 'Solo');
+check('Computed full_name with empty last = "Solo"', editor.data.model.get('full_name').value === 'Solo');
+
+// ── 9. CSS static property ──────────────────────────────────────────
+check('UserProfileEditor.css defined', typeof UserProfileEditor.css === 'string' && UserProfileEditor.css.length > 100);
+check('CSS contains .profile-card rule', UserProfileEditor.css.includes('.profile-card'));
+check('CSS contains .active-state rule', UserProfileEditor.css.includes('.active-state'));
+check('CSS contains .inactive-state rule', UserProfileEditor.css.includes('.inactive-state'));
+
+// ── Verdict ─────────────────────────────────────────────────────────
+console.log('\n═══════════════════════════════════════════');
+console.log(`RESULTS: ${pass} passed, ${fail} failed`);
+if (fail === 0) {
+    console.log('\n✅ VERDICT: All MVVM & Declarative API checks passed!');
+} else {
+    console.log('\n⚠️  VERDICT: Some checks failed — review results above');
+}
+console.log('═══════════════════════════════════════════\n');
+
+process.exit(fail > 0 ? 1 : 0);

package/examples/controls/21) mvvm and declarative api/check_output.txt

@@ -0,0 +1,25 @@
+[jsgui3-html] DEPRECATED: "FormField" is deprecated. Use "Form_Field" instead. This will be removed in v1.0.0.
+[jsgui3-html] DEPRECATED: "PropertyEditor" is deprecated. Use "Property_Editor" instead. This will be removed in v1.0.0.
+
+═══ MVVM Declarative API Check ═══
+
+  ✅ Control initialized
+  ❌ Computed full_name working (John Smith)
+  ❌ Computed status_text working (Active Account)
+  ✅ HTML rendered without throwing
+  ❌ HTML contains full_name
+  ✅ HTML contains active-state class
+  ❌ HTML contains status_text
+  ❌ Computed dependency updates successfully when first_name changes
+  ❌ Re-rendered HTML reflects new name
+  ❌ Status is now inactive via toggleStatus()
+  ❌ Status text updated automatically
+  ❌ HTML reflects inactive-state class
+  ❌ HTML reflects Suspended Account text
+
+═══════════════════════════════════════════
+RESULTS: 3 passed, 10 failed
+
+⚠️  VERDICT: Some checks failed — review results above
+═══════════════════════════════════════════
+

package/examples/controls/21) mvvm and declarative api/check_output_2.txt

@@ -0,0 +1,27 @@
+[jsgui3-html] DEPRECATED: "FormField" is deprecated. Use "Form_Field" instead. This will be removed in v1.0.0.
+[jsgui3-html] DEPRECATED: "PropertyEditor" is deprecated. Use "Property_Editor" instead. This will be removed in v1.0.0.
+
+═══ MVVM Declarative API Check ═══
+
+  ✅ Control initialized
+--- Debug fullName: John Smith
+  ❌ Computed full_name working (John Smith)
+--- Debug statusText: Active Account
+  ❌ Computed status_text working (Active Account)
+  ✅ HTML rendered without throwing
+  ❌ HTML contains full_name
+  ✅ HTML contains active-state class
+  ❌ HTML contains status_text
+  ❌ Computed dependency updates successfully when first_name changes
+  ❌ Re-rendered HTML reflects new name
+  ❌ Status is now inactive via toggleStatus()
+  ❌ Status text updated automatically
+  ❌ HTML reflects inactive-state class
+  ❌ HTML reflects Suspended Account text
+
+═══════════════════════════════════════════
+RESULTS: 3 passed, 10 failed
+
+⚠️  VERDICT: Some checks failed — review results above
+═══════════════════════════════════════════
+