webrequest/ts/webrequest.function.ts

/**
 * Main webrequest function - fetch-compatible API
 */

import type { IWebrequestOptions } from './webrequest.types.js';
import { WebrequestClient } from './webrequest.client.js';

// Global default client
const defaultClient = new WebrequestClient();

/**
 * Fetch-compatible webrequest function
 * Drop-in replacement for fetch() with caching, retry, and fault tolerance
 *
 * @param input - URL or Request object
 * @param init - Request options (standard RequestInit + webrequest extensions)
 * @returns Promise<Response>
 *
 * @example
 * ```typescript
 * // Simple GET request
 * const response = await webrequest('https://api.example.com/data');
 * const data = await response.json();
 *
 * // With caching
 * const response = await webrequest('https://api.example.com/data', {
 *   cacheStrategy: 'cache-first',
 *   cacheMaxAge: 60000
 * });
 *
 * // With retry
 * const response = await webrequest('https://api.example.com/data', {
 *   retry: {
 *     maxAttempts: 3,
 *     backoff: 'exponential'
 *   }
 * });
 *
 * // With fallback URLs
 * const response = await webrequest('https://api.example.com/data', {
 *   fallbackUrls: ['https://backup.example.com/data'],
 *   retry: true
 * });
 * ```
 */
export async function webrequest(
  input: string | Request | URL,
  init?: IWebrequestOptions,
): Promise<Response> {
  const url = input instanceof Request ? input.url : String(input);
  const request = input instanceof Request ? input : new Request(url, init);

  return await defaultClient.request(request, init);
}

/**
 * Convenience method: GET request returning JSON
 */
webrequest.getJson = async function <T = any>(
  url: string,
  options?: IWebrequestOptions,
): Promise<T> {
  return await defaultClient.getJson<T>(url, options);
};

/**
 * Convenience method: POST request with JSON body
 */
webrequest.postJson = async function <T = any>(
  url: string,
  data: any,
  options?: IWebrequestOptions,
): Promise<T> {
  return await defaultClient.postJson<T>(url, data, options);
};

/**
 * Convenience method: PUT request with JSON body
 */
webrequest.putJson = async function <T = any>(
  url: string,
  data: any,
  options?: IWebrequestOptions,
): Promise<T> {
  return await defaultClient.putJson<T>(url, data, options);
};

/**
 * Convenience method: DELETE request
 */
webrequest.deleteJson = async function <T = any>(
  url: string,
  options?: IWebrequestOptions,
): Promise<T> {
  return await defaultClient.deleteJson<T>(url, options);
};

/**
 * Add a global request interceptor
 */
webrequest.addRequestInterceptor = function (interceptor) {
  defaultClient.addRequestInterceptor(interceptor);
};

/**
 * Add a global response interceptor
 */
webrequest.addResponseInterceptor = function (interceptor) {
  defaultClient.addResponseInterceptor(interceptor);
};

/**
 * Add a global error interceptor
 */
webrequest.addErrorInterceptor = function (interceptor) {
  defaultClient.addErrorInterceptor(interceptor);
};

/**
 * Clear all global interceptors
 */
webrequest.clearInterceptors = function () {
  defaultClient.clearInterceptors();
};

/**
 * Clear the cache
 */
webrequest.clearCache = async function () {
  await defaultClient.clearCache();
};

/**
 * Create a new WebrequestClient with custom configuration
 */
webrequest.createClient = function (
  options?: Partial<IWebrequestOptions>,
): WebrequestClient {
  return new WebrequestClient(options);
};

/**
 * Get the default client
 */
webrequest.getDefaultClient = function (): WebrequestClient {
  return defaultClient;
};