@vicaniddouglas/js_aide 1.9.0 → 1.10.0

package/README.md

@@ -52,6 +52,10 @@ Utilities for number formatting, currency (including UGX defaults), and percenta
 
 A robust manager for dynamically loading CDN-based libraries (like SheetJS or jsPDF) with retry logic and dependency tracking.
 
+### `WebSocketClient`
+
+A professional-grade WebSocket client featuring automatic reconnection, heartbeat/health monitoring, and a built-in instance registry to prevent duplicate connections. Supports namespaces, rooms, and message acknowledgements.
+
 ## Installation
 
 Install the package via npm:
@@ -149,6 +153,171 @@ if (productDetailView) {
 router.navigate("/products/123?utm_source=email#overview");
 ```
 
+### Example: Using the WebSocket Client
+
+The `WebSocketClient` is designed to be "Zero-Touch," handling connection lifecycles and resource management automatically.
+
+```javascript
+import { WebSocketClient, ConnectionEvent } from "@vicaniddouglas/js_aide";
+
+// The constructor automatically reuses instances for the same URL (Registry Pattern)
+const ws = new WebSocketClient("ws://localhost:8000");
+
+// Listen for connection events
+ws.on("open", () => {
+    console.log("Connected to server!");
+});
+
+// Register a handler for a specific event
+ws.onMessage("user_update", (data) => {
+    console.log("Profile updated:", data);
+});
+
+ws.connect();
+```
+
+#### `ws.send(event, data)` vs `ws.sendWithAck(event, data)`
+
+1.  **`ws.send()`**: A "fire and forget" method. It sends the data and returns immediately. Use this for non-critical updates like typing indicators.
+2.  **`ws.sendWithAck()`**: Returns a **Promise** that resolves when the server confirms receipt. Use this for critical actions like saving a profile or processing a payment.
+
+```javascript
+// Critical action with Acknowledgement
+try {
+    const response = await ws.sendWithAck("save_profile", { bio: "Hello world" });
+    console.log("Profile saved successfully:", response);
+} catch (error) {
+    console.error("Failed to save profile (timed out):", error.message);
+}
+```
+
+#### The Backend Contract (Implementing Acknowledgements)
+
+To support `sendWithAck()`, your backend (e.g., Python/FastAPI, Node.js, Go) must follow the `@vicaniddouglas` framework standard:
+
+1.  The client sends a message containing an `id` and `ack: true`.
+2.  The server **must** respond with a message containing:
+    *   `event: "ack"`
+    *   `id`: The *exact* same ID sent by the client.
+    *   `success`: `true` or `false`.
+    *   `data` (optional): Any response data to return to the client.
+
+**Example Server Response (JSON):**
+```json
+{
+  "event": "ack",
+  "id": "1712065432123-0",
+  "success": true,
+  "data": { "status": "saved" }
+}
+```
+
+### Example: Using the Requests Module
+
+The `sendRequest` function is a proactive HTTP client that standardizes all responses into a single dictionary format. It automatically handles error popups and callbacks, eliminating the need for `try-catch` blocks.
+
+#### Standardized Response
+Every call returns a Promise that always resolves to this structure:
+```javascript
+{
+  status: boolean, // true if Success, false if Error (Network or Business)
+  log: string,    // Error message on failure, or "" on success
+  data: any,       // The actual payload from the server
+  httpCode: number // The raw HTTP status code
+}
+```
+
+#### New Proactive Options
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. |
+| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. |
+| `silent` | `Boolean` | `false` | If `true`, disables the automatic Red Popup on error. |
+
+#### Usage Patterns
+
+**1. The "Fire and Forget" (Proactive Success)**
+No need to check status if you only care about success. If it fails, the user gets a popup automatically.
+```javascript
+import { sendRequest } from "@vicaniddouglas/js_aide";
+
+sendRequest({
+  endpoint: '/api/settings',
+  onSuccess: (data) => console.log("Profile updated!", data)
+});
+```
+
+**2. The "Sequential Chain" (Linear Await)**
+Since the promise **never rejects**, you can write linear logic without `try-catch`.
+```javascript
+const res = await sendRequest({ endpoint: '/profile' });
+
+if (res.status) {
+   // Since status is true, we know data is safe to use
+   const stats = await sendRequest({ endpoint: `/stats/${res.data.id}` });
+   if (stats.status) render(stats.data);
+}
+```
+
+**3. Silent Background Tasks**
+Use `silent: true` for background checks where a popup would be annoying.
+```javascript
+sendRequest({
+  endpoint: '/api/poll-notifications',
+  silent: true,
+  onSuccess: (count) => updateBadge(count)
+});
+```
+
+### Example: Using the Popup System
+
+The `popup` module provides a Promise-based modal system for showing professional alerts. It is fully accessible (supports the `Escape` key) and highly customizable.
+
+```javascript
+import { popup, icons } from "@vicaniddouglas/js_aide";
+
+// Basic success alert (auto-closes in 2.5s)
+await popup.success("Profile saved!");
+```
+
+#### Configuration Reference
+Every popup method (`.success()`, `.error()`, `.info()`) accepts an optional **`options`** object as the second argument.
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `duration` | `Number` | `2500ms - 4000ms` | Time before the modal closes automatically. |
+| `persistent`| `Boolean`| `false` | If `true`, the modal will stay on screen until manually closed. |
+| `closable` | `Boolean`| `true` | If `false`, hides the close button and disables `Esc`/backdrop clicks. |
+| `icon` | `String` | Theme default | A custom SVG string to override the default icon. |
+| `color` | `String` | Theme default | A custom hex or CSS color for the icon and background tint. |
+
+#### Common Usage Patterns
+
+**1. Sticky Info (Requires Acknowledgment)**
+```javascript
+await popup.info("Maintenance scheduled for midnight.", { persistent: true });
+```
+
+**2. Process Lock (Interaction Block)**
+Use this to prevent users from navigating away during critical operations.
+```javascript
+// Shows a modal with no close buttons
+popup.info("Deleting account data...", { persistent: true, closable: false });
+
+await api.deleteAccount();
+popup.close(); // Programmatically remove the modal
+await popup.success("Account deleted.");
+```
+
+**3. Custom Branding**
+Override the icon and color to match specific visual needs.
+```javascript
+popup.success("Photo Uploaded!", { 
+  icon: icons.cameraIcon(),
+  color: "#3b82f6" 
+});
+```
+
 ## Development
 
 ### Running Tests