houser-js-utils/dist/NetworkUtils.d.ts

A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.

/**
 * @module NetworkUtils
 * @description Utility functions for network operations in the browser, including fetch helpers with authentication, caching, progress, retry, and timeout; network status listeners; and network information utilities. Designed to simplify robust HTTP requests and network state management in web applications.
 * @example
 * ```typescript
 * import { NetworkUtils } from 'houser-js-utils';
 *
 * // Add a network status listener
 * const remove = NetworkUtils.addNetworkStatusListener((online) => console.log('Online:', online));
 * // ...later
 * remove();
 *
 * // Fetch with authentication
 * const res = await NetworkUtils.fetchWithAuth('/api', 'token123');
 *
 * // Fetch with cache
 * const cachedRes = await NetworkUtils.fetchWithCache('/api/data');
 *
 * // Fetch JSON with error handling
 * const data = await NetworkUtils.fetchJson<{foo: string}>('/api/data');
 *
 * // Fetch with progress
 * await NetworkUtils.fetchWithProgress('/file', {}, (progress) => console.log('Progress:', progress));
 *
 * // Fetch with retry and timeout
 * const retryRes = await NetworkUtils.fetchWithRetry('/api', {}, 5, 500);
 * const timeoutRes = await NetworkUtils.fetchWithTimeout('/api', {}, 2000);
 *
 * // Get network speed and type
 * const speed = NetworkUtils.getNetworkSpeed();
 * const type = NetworkUtils.getNetworkType();
 *
 * // Check if online
 * if (NetworkUtils.isOnline()) {
 *   // Do something when online
 * }
 * ```
 */
export declare const NetworkUtils: {
    /**
     * Adds a listener for network status changes (online/offline).
     * @param callback - Callback invoked with `true` if online, `false` if offline.
     * @returns Function to remove the listener.
     * @example
     * ```typescript
     * const remove = NetworkUtils.addNetworkStatusListener((online) => console.log('Online:', online));
     * // ...later
     * remove();
     * ```
     */
    addNetworkStatusListener: (callback: (online: boolean) => void) => (() => void);
    /**
     * Makes a fetch request with Bearer token authentication.
     * @param url - The URL to fetch.
     * @param token - The authentication token.
     * @param options - Additional fetch options.
     * @returns The fetch response.
     * @example
     * ```typescript
     * const res = await NetworkUtils.fetchWithAuth('/api', 'token123');
     * ```
     */
    fetchWithAuth: (url: string, token: string, options?: RequestInit) => Promise<Response>;
    /**
     * Makes a fetch request with caching in localStorage.
     * @param url - The URL to fetch.
     * @param options - Fetch options.
     * @param cacheTime - Cache time in milliseconds (default 5 minutes).
     * @returns The fetch response (from cache or network).
     * @example
     * ```typescript
     * const res = await NetworkUtils.fetchWithCache('/api/data');
     * ```
     */
    fetchWithCache: (url: string, options?: RequestInit, cacheTime?: number) => Promise<Response>;
    /**
     * Makes a fetch request and parses the response as JSON, with error handling.
     * @template T
     * @param url - The URL to fetch.
     * @param options - Fetch options.
     * @returns The parsed response data.
     * @throws {Error} If the response is not OK.
     * @example
     * ```typescript
     * const data = await NetworkUtils.fetchJson<{foo: string}>('/api/data');
     * ```
     */
    fetchJson: <T>(url: string, options?: RequestInit) => Promise<T>;
    /**
     * Makes a fetch request and tracks download progress.
     * @param url - The URL to fetch.
     * @param options - Fetch options.
     * @param onProgress - Progress callback (0-100).
     * @returns The fetch response.
     * @example
     * ```typescript
     * await NetworkUtils.fetchWithProgress('/file', {}, (progress) => console.log('Progress:', progress));
     * ```
     */
    fetchWithProgress: (url: string, options?: RequestInit, onProgress?: (progress: number) => void) => Promise<Response>;
    /**
     * Makes a fetch request with retry logic on failure.
     * @param url - The URL to fetch.
     * @param options - Fetch options.
     * @param retries - Number of retries (default 3).
     * @param delay - Delay between retries in milliseconds (default 1000).
     * @returns The fetch response.
     * @throws {Error} If all retries fail.
     * @example
     * ```typescript
     * const res = await NetworkUtils.fetchWithRetry('/api', {}, 5, 500);
     * ```
     */
    fetchWithRetry: (url: string, options?: RequestInit, retries?: number, delay?: number) => Promise<Response>;
    /**
     * Makes a fetch request with a timeout.
     * @param url - The URL to fetch.
     * @param options - Fetch options.
     * @param timeout - Request timeout in milliseconds (default 5000).
     * @returns The fetch response.
     * @throws {Error} If the request times out.
     * @example
     * ```typescript
     * const res = await NetworkUtils.fetchWithTimeout('/api', {}, 2000);
     * ```
     */
    fetchWithTimeout: (url: string, options?: RequestInit, timeout?: number) => Promise<Response>;
    /**
     * Gets the current network speed (downlink) in Mbps, if available.
     * @returns The network speed in Mbps, or null if not available.
     * @example
     * ```typescript
     * const speed = NetworkUtils.getNetworkSpeed();
     * console.log('Speed:', speed);
     * ```
     */
    getNetworkSpeed: () => string | null;
    /**
     * Gets the current network type (e.g., 'wifi', '4g'), if available.
     * @returns The network type, or null if not available.
     * @example
     * ```typescript
     * const type = NetworkUtils.getNetworkType();
     * console.log('Type:', type);
     * ```
     */
    getNetworkType: () => string | null;
    /**
     * Checks if the network is currently online.
     * @returns True if the network is online, false otherwise.
     * @example
     * ```typescript
     * if (NetworkUtils.isOnline()) {
     *   // Do something when online
     * }
     * ```
     */
    isOnline: () => boolean;
};