@vicaniddouglas/js_aide 1.13.4 → 1.15.0

package/README.md

@@ -281,6 +281,58 @@ sendRequest({
 });
 ```
 
+### Example: Using the FileUploader
+
+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
+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;
+} else {
+    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!")
+});
+```
+
+#### 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"
+    }
+});
+```
+
 ### 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.

package/declarations.d.ts

@@ -499,6 +499,61 @@ declare module "@vicaniddouglas/js_aide" {
     escapeCsvValue(value: any, delimiter: string): string;
   }
 
+  // =========================================================
+  // fileUploader (from fileUploader.js)
+  // =========================================================
+  interface FileUploaderValidationResult {
+    isValid: boolean;
+    error: string | null;
+  }
+
+  interface ValidateFileOptions {
+    allowedTypes?: string[];
+    maxSize?: number;
+  }
+
+  interface toBase64Options {
+    stripPrefix?: boolean;
+  }
+
+  interface Base64Result {
+    status: boolean;
+    data: string | null;
+    log: string | null;
+  }
+
+  interface UploadOptions {
+    files: File | File[];
+    endpoint: string;
+    fieldName?: string;
+    payload?: object;
+    maxSize?: number;
+    allowedTypes?: string[];
+    onProgress?: (percent: number) => void;
+    showLoading?: (isLoading: boolean) => void | Promise<void>;
+    silent?: boolean;
+    asBase64?: boolean;
+    stripPrefix?: boolean;
+  }
+
+  export function validateFile(
+    file: File,
+    options?: ValidateFileOptions,
+  ): FileUploaderValidationResult;
+
+  export function toBase64(
+    file: File,
+    options?: toBase64Options,
+  ): Promise<Base64Result>;
+
+  export function uploadFile(options: UploadOptions): Promise<StandardizedResponse>;
+
+  export function uploadDataUrl(
+    dataUrl: string,
+    fileName: string,
+    options?: UploadOptions,
+  ): Promise<StandardizedResponse>;
+
   // =========================================================
   // camera (from camera.js)
   // =========================================================