JSGUI3 Client

ES6 JSGUI Client library for delivery to the browser. This module provides client-side functionality for building web applications with the JSGUI framework.

Overview

The jsgui3-client package extends the base jsgui3-html framework with browser-specific functionality, including HTTP communication, client resource management, page context handling, and UI controls optimized for client-side execution.

Features

HTTP Communication

• GET, POST, DELETE requests: Built-in HTTP methods with Promise/callback support
• Automatic JSON handling: Serialization and parsing of JSON data
• Timeout support: Configurable request timeouts (default: 2500ms, override via jsgui.timeout in ms)
• Error handling: Comprehensive status code and error response handling

Resource Management

• Client Resource Pool: Manages client-side resources with HTTP endpoint connectivity
• Data Resources: HTTP-based data resources with GET/POST/DELETE operations
• Resource Registration: Server resource registration and management

Page Context

• Client Page Context: Extended page context class with browser-specific features
• Modal Support: Built-in modal dialog functionality
• Element Management: DOM element mapping and control
• Control Integration: Seamless integration with JSGUI controls

Controls

• Active HTML Document: Enhanced HTML document control with automatic activation
• Standard Control Updates: Automatic control registration and updates

Installation

npm install jsgui3-client

Dependencies

• jsgui3-html: ^0.0.172 - Core JSGUI HTML framework
• fnl: 0.0.37 - Functional library utilities

Requirements

• Node.js >= 15.0.0

Main Components

client.js

Main entry point that sets up the global jsgui object with client-specific functionality including HTTP methods and resource management.

resource.js

Defines client-side resources that can communicate with server endpoints via HTTP.

client-resource-pool.js

Manages pools of client resources, extending the base resource pool with client-specific capabilities. Includes a default data_resource used to attach server-exposed resource functions during activation. Client_Resource_Pool.start() starts resources that meet requirements and rejects if requirements can’t be satisfied.

page-context.js

Provides Client_Page_Context class that extends the base page context with browser-specific features like modals and DOM management. Client_Page_Context.overlay.place(...) supports below, above, right, and left placements.

data-get-post-delete-http-resource.js

Implements HTTP-based data resources supporting standard CRUD operations over HTTP.

Controls

This package builds on the control set provided by jsgui3-html (for example Control and Modal) and focuses on client/browser runtime integration (page context, HTTP helpers, client resources).

Usage

// The library automatically extends the global jsgui object when loaded
const jsgui = require('jsgui3-client');

// HTTP requests
jsgui.http('/api/data').then(data => {
    console.log('Retrieved data:', data);
});

// POST data
jsgui.http_post('/api/data', {name: 'example'}).then(response => {
    console.log('Posted successfully:', response);
});

// Create page context
const context = new jsgui.Client_Page_Context({
    document: document
});

// Use modal
context.modal.show('Hello World!');

Architecture

This module is designed to work in browser environments and provides the client-side counterpart to jsgui3-server. It handles:

• Browser-specific DOM operations
• HTTP communication with server resources
• Client-side resource pooling and management
• UI controls optimized for browser execution

Documentation

• See docs/README.md for a comprehensive guide covering how jsgui3-client layers on top of jsgui3-html and how it integrates with jsgui3-server (bundling, serving, and API interaction).

Testing

npm test

E2E (Puppeteer):

npm run test:e2e

Notes:

• Tests use Node’s built-in node:test runner (Node.js >= 18 recommended for running the test suite).
• Browser-only behavior is tested by stubbing window, document, and XMLHttpRequest in Node (see test/fixtures/).

Security Notes / Further Review Areas

• Server resource names registered via register_server_resources(...) should be treated as untrusted; client.js blocks __proto__, constructor, and prototype to avoid prototype-pollution style issues.
• HTTP helpers assume JSON responses on HTTP 200 and reject with { status, responseText, parse_error: true } on invalid JSON.
• XHR timeouts reject with { status: 0, timeout: true }; network errors reject with { status: 0, network_error: true }.
• CSRF/auth headers/CORS settings are application concerns and are not handled by this package.

License

MIT

Author

James Vickers james@metabench.com

Repository

https://github.com/metabench/jsgui3-client.git