@vicaniddouglas/js_aide 1.15.3 → 1.16.0

package/README.md

@@ -5,6 +5,7 @@
 **JS Aide** is a high-performance, modular utility collection designed for modern web applications. Whether you're building a native SPA or an enterprise-grade MPA, JS Aide provides the orchestrated power you need.
 
 ## 🕹️ Live Playground
+
 Explore all library features—including the new Asynchronous Handshaking system—directly in our **[Interactive Sandbox](https://vicaniddouglas.gitlab.io/js_aide)**.
 
 ### `Router`
@@ -71,11 +72,11 @@ You can import specific modules or all of them:
 
 ```javascript
 // Import specific modules for best tree-shaking
-import { 
-    Router, 
-    sendRequest, 
-    validatePhoneNumber, 
-    humanizeDate 
+import {
+  Router,
+  sendRequest,
+  validatePhoneNumber,
+  humanizeDate,
 } from "@vicaniddouglas/js_aide";
 ```
 
@@ -158,12 +159,12 @@ const ws = new WebSocketClient("ws://localhost:8000");
 
 // Listen for connection events
 ws.on("open", () => {
-    console.log("Connected to server!");
+  console.log("Connected to server!");
 });
 
 // Register a handler for a specific event
 ws.onMessage("user_update", (data) => {
-    console.log("Profile updated:", data);
+  console.log("Profile updated:", data);
 });
 
 ws.connect();
@@ -177,10 +178,10 @@ ws.connect();
 ```javascript
 // Critical action with Acknowledgement
 try {
-    const response = await ws.sendWithAck("save_profile", { bio: "Hello world" });
-    console.log("Profile saved successfully:", response);
+  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);
+  console.error("Failed to save profile (timed out):", error.message);
 }
 ```
 
@@ -190,12 +191,13 @@ To support `sendWithAck()`, your backend (e.g., Python/FastAPI, Node.js, Go) mus
 
 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.
+    - `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",
@@ -210,7 +212,9 @@ To support `sendWithAck()`, your backend (e.g., Python/FastAPI, Node.js, Go) mus
 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)
@@ -221,63 +225,68 @@ Every call returns a Promise that always resolves to this structure:
 ```
 
 #### New Proactive Options
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. **Strictly awaited.** |
-| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. **Strictly awaited.** |
-| `showLoading` | `Function` | `null` | Called with `true`/`false`. **Strictly awaited.** |
-| `silent` | `Boolean` | `false` | If `true`, disables the automatic Red Popup on error. |
+
+| Option        | Type       | Default | Description                                                      |
+| :------------ | :--------- | :------ | :--------------------------------------------------------------- |
+| `onSuccess`   | `Function` | `null`  | Runs automatically if `status` is `true`. **Strictly awaited.**  |
+| `onError`     | `Function` | `null`  | Runs automatically if `status` is `false`. **Strictly awaited.** |
+| `showLoading` | `Function` | `null`  | Called with `true`/`false`. **Strictly awaited.**                |
+| `silent`      | `Boolean`  | `false` | If `true`, disables the automatic Red Popup on error.            |
 
 #### Usage Patterns
 
 **1. The "Sequential Async Flow" (Awaiting Callbacks)**
 Because `sendRequest` **strictly awaits** your callbacks, you can safely use `async/await` inside them without worrying about race conditions or premature page reloads.
+
 ```javascript
 import { sendRequest, popup } from "@vicaniddouglas/js_aide";
 
 await sendRequest({
-  endpoint: '/api/save',
+  endpoint: "/api/save",
   onSuccess: async (data) => {
     // This popup is BEAUTIFUL and BLOCKING.
     // sendRequest will NOT finish until the user clicks OK.
-    await popup.success("Settings Saved!"); 
-  }
+    await popup.success("Settings Saved!");
+  },
 });
 
 // This reload is GUARANTEED to happen only after the popup is closed.
-window.location.reload(); 
+window.location.reload();
 ```
 
 **2. 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)
+  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' });
+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);
+  // 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',
+  endpoint: "/api/poll-notifications",
   silent: true,
-  onSuccess: (count) => updateBadge(count)
+  onSuccess: (count) => updateBadge(count),
 });
 ```
 
@@ -286,6 +295,7 @@ sendRequest({
 The `FileUploader` module provides standardized utilities for validating and uploading files. It supports both traditional binary (`Multipart/Form-Data`) and JSON-based Base64 uploads.
 
 #### Base64 File Conversions (For Previews)
+
 The `toBase64` utility converts a raw `File` object into a Base64 string. It follows the "Always Resolve" pattern.
 
 ```javascript
@@ -294,42 +304,44 @@ import { toBase64 } from "@vicaniddouglas/js_aide";
 const res = await toBase64(myFile);
 
 if (res.status) {
-    // res.data is the full data URL (e.g. data:image/png;base64,...)
-    myImagePreview.src = res.data;
+  // res.data is the full data URL (e.g. data:image/png;base64,...)
+  myImagePreview.src = res.data;
 } else {
-    console.error("Conversion failed:", res.log);
+  console.error("Conversion failed:", res.log);
 }
 ```
 
 #### Standard Binary Upload
+
 By default, `uploadFile` sends files as a binary `Multipart/Form-Data` stream.
 
 ```javascript
 import { uploadFile, popup } from "@vicaniddouglas/js_aide";
 
 await uploadFile({
-    files: document.getElementById('myFileInput').files[0],
-    endpoint: '/api/upload-avatar',
-    fieldName: 'avatar',
-    onSuccess: () => popup.success("Avatar uploaded!")
+  files: document.getElementById("myFileInput").files[0],
+  endpoint: "/api/upload-avatar",
+  fieldName: "avatar",
+  onSuccess: () => popup.success("Avatar uploaded!"),
 });
 ```
 
 #### Base64 JSON Upload
+
 For APIs that require images to be embedded in a JSON payload, simply toggle the `asBase64` flag.
 
 ```javascript
 import { uploadFile } from "@vicaniddouglas/js_aide";
 
 await uploadFile({
-    files: selectedFiles,
-    endpoint: '/api/upload-as-json',
-    asBase64: true, // Automically converts to Base64 strings
-    stripPrefix: true, // Only send the raw Base64 data (no "data:image/..." prefix)
-    payload: {
-        userId: 123,
-        description: "Holiday photo"
-    }
+  files: selectedFiles,
+  endpoint: "/api/upload-as-json",
+  asBase64: true, // Automically converts to Base64 strings
+  stripPrefix: true, // Only send the raw Base64 data (no "data:image/..." prefix)
+  payload: {
+    userId: 123,
+    description: "Holiday photo",
+  },
 });
 ```
 
@@ -345,25 +357,28 @@ 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. |
+| 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 });
@@ -375,18 +390,21 @@ await popup.success("Account deleted.");
 
 **3. Custom Branding**
 Override the icon and color to match specific visual needs.
+
 ```javascript
-popup.success("Photo Uploaded!", { 
+popup.success("Photo Uploaded!", {
   icon: icons.cameraIcon(),
-  color: "#3b82f6" 
+  color: "#3b82f6",
 });
 ```
 
 #### 4. Asynchronous Handshaking (Zero-Alert)
+
 The popup system provides replacements for native `confirm()` and `prompt()` that are fully asynchronous, themeable, and non-blocking in the developer's logic (via `await`).
 
 **Confirmation Dialogs**
 Returns `true` on confirm, `false` on cancel/close.
+
 ```javascript
 const confirmed = await popup.confirm("Are you sure you want to delete this?");
 
@@ -398,10 +416,11 @@ if (confirmed) {
 
 **Data-Entry Prompts**
 Returns the input value as a **string** on submit, or `null` if cancelled.
+
 ```javascript
 const name = await popup.prompt("Enter your display name:", {
   placeholder: "e.g., Douglas",
-  inputType: "text" // Options: text, number, currency, password
+  inputType: "text", // Options: text, number, currency, password
 });
 
 if (name) {
@@ -409,12 +428,12 @@ if (name) {
 }
 ```
 
-| Prompt Option | Description |
-| :--- | :--- |
-| `inputType` | Controls input behavior (`text`, `number`, `currency`, `password`). |
-| `defaultValue`| Initial text inside the input. |
-| `submitText` | Text for the action button (default: "Submit"). |
-| `cancelText` | Text for the dismiss button (default: "Cancel"). |
+| Prompt Option  | Description                                                         |
+| :------------- | :------------------------------------------------------------------ |
+| `inputType`    | Controls input behavior (`text`, `number`, `currency`, `password`). |
+| `defaultValue` | Initial text inside the input.                                      |
+| `submitText`   | Text for the action button (default: "Submit").                     |
+| `cancelText`   | Text for the dismiss button (default: "Cancel").                    |
 
 ## Development
 

package/declarations.d.ts

@@ -547,7 +547,9 @@ declare module "@vicaniddouglas/js_aide" {
     options?: toBase64Options,
   ): Promise<Base64Result>;
 
-  export function uploadFile(options: UploadOptions): Promise<StandardizedResponse>;
+  export function uploadFile(
+    options: UploadOptions,
+  ): Promise<StandardizedResponse>;
 
   export function uploadDataUrl(
     dataUrl: string,