@indra211/httpease 1.0.0

package/src/utils/helpers.js

@@ -0,0 +1,86 @@
+/**
+ * Helper utility functions
+ */
+
+/**
+ * Deep merge two objects
+ */
+function mergeConfig(config1, config2) {
+    const merged = { ...config1 };
+
+    Object.keys(config2).forEach(key => {
+        if (key === 'headers') {
+            merged.headers = { ...config1.headers, ...config2.headers };
+        } else if (config2[key] !== undefined) {
+            merged[key] = config2[key];
+        }
+    });
+
+    return merged;
+}
+
+/**
+ * Build URL with query parameters
+ */
+function buildURL(url, params) {
+    if (!params) return url;
+
+    const searchParams = new URLSearchParams();
+
+    Object.keys(params).forEach(key => {
+        const value = params[key];
+        if (value === null || value === undefined) return;
+
+        if (Array.isArray(value)) {
+            value.forEach(v => searchParams.append(key, v));
+        } else {
+            searchParams.append(key, value);
+        }
+    });
+
+    const queryString = searchParams.toString();
+    if (!queryString) return url;
+
+    const separator = url.includes('?') ? '&' : '?';
+    return url + separator + queryString;
+}
+
+/**
+ * Check if value is an object
+ */
+function isObject(val) {
+    return val !== null && typeof val === 'object' && !Array.isArray(val);
+}
+
+/**
+ * Check if running in browser
+ */
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+/**
+ * Sleep/delay utility
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate exponential backoff delay
+ */
+function calculateBackoff(attempt, baseDelay = 1000, maxDelay = 30000) {
+    const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+    // Add jitter (randomness) to prevent thundering herd
+    const jitter = delay * 0.1 * Math.random();
+    return delay + jitter;
+}
+
+module.exports = {
+    mergeConfig,
+    buildURL,
+    isObject,
+    isBrowser,
+    sleep,
+    calculateBackoff
+};

package/src/utils/progress.js

@@ -0,0 +1,166 @@
+/**
+ * HttpEase Progress Tracking Utilities
+ *
+ * Zero-dependency upload and download progress using native
+ * ReadableStream / TransformStream APIs (Node.js 18+, modern browsers).
+ */
+
+/**
+ * Build a ProgressEvent-like object.
+ * @param {number} loaded
+ * @param {number} total
+ * @returns {{ loaded: number, total: number, percentage: number }}
+ */
+function makeProgressEvent(loaded, total) {
+    return {
+        loaded,
+        total,
+        percentage: total > 0 ? Math.min(100, (loaded / total) * 100) : 0
+    };
+}
+
+/**
+ * Convert a body value to a Uint8Array so we know its total byte size.
+ * Supports: string, Uint8Array/Buffer, ArrayBuffer.
+ * Returns null if the body type is not supported (e.g. FormData, ReadableStream).
+ *
+ * @param {unknown} body
+ * @returns {Uint8Array | null}
+ */
+function toUint8Array(body) {
+    if (body == null) return null;
+
+    if (body instanceof Uint8Array) return body;
+
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+
+    if (body instanceof ArrayBuffer) {
+        return new Uint8Array(body);
+    }
+
+    if (typeof body === 'string') {
+        return new TextEncoder().encode(body);
+    }
+
+    // FormData, Blob, ReadableStream — cannot easily track bytes
+    return null;
+}
+
+/**
+ * Wrap a request body as a ReadableStream that fires `onProgress` as bytes
+ * are consumed by the fetch engine.
+ *
+ * Falls back to the raw body (no progress) if:
+ * - The body type is unsupported (FormData, Blob, etc.)
+ * - TransformStream is not available in the environment
+ *
+ * @param {unknown} body  - The serialized request body
+ * @param {Function} onProgress - `(event: ProgressEvent) => void`
+ * @returns {{ body: unknown, duplex: string | undefined }}
+ *   Returns the (possibly wrapped) body and whether `duplex: 'half'` is needed.
+ */
+function wrapBodyWithProgress(body, onProgress) {
+    // Guard: requires TransformStream
+    if (typeof TransformStream === 'undefined') {
+        return { body, duplex: undefined };
+    }
+
+    const bytes = toUint8Array(body);
+
+    // Cannot determine size or not a byte-convertible type
+    if (bytes === null) {
+        return { body, duplex: undefined };
+    }
+
+    const total = bytes.byteLength;
+    let loaded = 0;
+
+    // Fire initial 0% event
+    onProgress(makeProgressEvent(0, total));
+
+    const { readable, writable } = new TransformStream({
+        transform(chunk, controller) {
+            controller.enqueue(chunk);
+            loaded += chunk.byteLength;
+            onProgress(makeProgressEvent(loaded, total));
+        }
+    });
+
+    // Pipe bytes into the transform stream
+    const writer = writable.getWriter();
+    // Write in chunks to allow progress events to fire incrementally
+    const CHUNK_SIZE = 16 * 1024; // 16 KB chunks
+    let offset = 0;
+
+    (async () => {
+        while (offset < bytes.byteLength) {
+            const end = Math.min(offset + CHUNK_SIZE, bytes.byteLength);
+            await writer.write(bytes.slice(offset, end));
+            offset = end;
+        }
+        await writer.close();
+    })().catch(() => writer.abort());
+
+    // Return ReadableStream — fetch needs duplex: 'half' for streaming bodies
+    return { body: readable, duplex: 'half' };
+}
+
+/**
+ * Read a Response body as a stream, firing `onProgress` for each chunk.
+ * Returns the full body text (already consumed for you).
+ *
+ * Falls back to `response.text()` if ReadableStream not supported.
+ *
+ * @param {Response} response  - The native fetch Response
+ * @param {Function} onProgress - `(event: ProgressEvent) => void`
+ * @returns {Promise<string>} The raw response text
+ */
+async function readBodyWithProgress(response, onProgress) {
+    // Guard: requires response.body ReadableStream
+    if (!response.body || typeof response.body.getReader !== 'function') {
+        const text = await response.text();
+        onProgress(makeProgressEvent(text.length, text.length));
+        return text;
+    }
+
+    const contentLength = response.headers.get('content-length');
+    const total = contentLength ? parseInt(contentLength, 10) : 0;
+
+    const reader = response.body.getReader();
+    const chunks = [];
+    let loaded = 0;
+
+    // Fire initial 0% event
+    onProgress(makeProgressEvent(0, total));
+
+    while (true) {
+        const { done, value } = await reader.read();
+
+        if (done) break;
+
+        chunks.push(value);
+        loaded += value.byteLength;
+        onProgress(makeProgressEvent(loaded, total));
+    }
+
+    // Ensure a final 100% event is fired
+    onProgress(makeProgressEvent(loaded, total > 0 ? total : loaded));
+
+    // Combine chunks and decode
+    const allBytes = new Uint8Array(loaded);
+    let position = 0;
+    for (const chunk of chunks) {
+        allBytes.set(chunk, position);
+        position += chunk.byteLength;
+    }
+
+    return new TextDecoder().decode(allBytes);
+}
+
+module.exports = {
+    wrapBodyWithProgress,
+    readBodyWithProgress,
+    makeProgressEvent
+};

package/src/utils/transformers.js

@@ -0,0 +1,45 @@
+const { isObject } = require('./helpers');
+
+/**
+ * Default request data transformers
+ */
+const transformRequest = [
+  function (data, headers) {
+    // Auto-set Content-Type for objects
+    if (isObject(data) && !headers['Content-Type']) {
+      headers['Content-Type'] = 'application/json';
+      return JSON.stringify(data);
+    }
+
+    // Handle FormData
+    if (typeof FormData !== 'undefined' && data instanceof FormData) {
+      // Let browser set Content-Type with boundary
+      delete headers['Content-Type'];
+      return data;
+    }
+
+    return data;
+  }
+];
+
+/**
+ * Default response data transformers
+ */
+const transformResponse = [
+  async function (response) {
+    const contentType = response.headers.get('content-type');
+
+    // Auto-parse JSON
+    if (contentType && contentType.includes('application/json')) {
+      return await response.json();
+    }
+
+    // Return text for other types
+    return await response.text();
+  }
+];
+
+module.exports = {
+  transformRequest,
+  transformResponse
+};