@zairakai/js-http-client 1.0.0

package/src/client.ts

@@ -0,0 +1,207 @@
+/**
+ * HTTP client factory with configurable options
+ */
+
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+import {
+  Logger,
+  ShouldRetryFunction,
+  TokenSource,
+  createAuthInterceptor,
+  createCSRFInterceptor,
+  createErrorLoggerInterceptor,
+  createRetryInterceptor,
+  createTimeoutInterceptor,
+  createTrackingInterceptors,
+} from './interceptors.js'
+import { RequestTracker, createRequestTracker } from './request-tracker.js'
+
+/**
+ * HTTP client configuration options
+ */
+export interface HttpClientOptions {
+  /** Base URL for requests */
+  baseURL?: string
+  /** Default headers */
+  headers?: Record<string, string>
+  /** Include credentials */
+  withCredentials?: boolean
+  /** Request timeout in milliseconds */
+  timeout?: number
+  /** Enable request tracking */
+  trackRequests?: boolean
+  /** CSRF token or getter function */
+  csrfToken?: TokenSource
+  /** Auth token or getter function */
+  authToken?: TokenSource
+  /** Auth token type (Bearer, Token, etc.) */
+  authType?: string
+  /** Enable error logging */
+  enableErrorLogging?: boolean
+  /** Custom logger function */
+  logger?: Logger
+  /** Number of retries for failed requests */
+  retries?: number
+  /** Delay between retries in milliseconds */
+  retryDelay?: number
+  /** Custom retry logic */
+  shouldRetry?: ShouldRetryFunction
+  /** Enable Laravel-specific features */
+  laravel?: boolean
+}
+
+/**
+ * HTTP client instance with convenience methods
+ */
+export interface HttpClient {
+  /** Axios instance */
+  readonly client: AxiosInstance
+  /** Request tracker instance (null if tracking disabled) */
+  readonly tracker: RequestTracker | null
+  /** Whether there are active requests */
+  readonly isLoading: boolean
+  /** Current number of active requests */
+  readonly requestCount: number
+
+  // Convenience HTTP methods
+  get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>
+  post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>
+  put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>
+  patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>
+  delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>
+}
+
+/**
+ * Default configuration for HTTP clients
+ */
+const DEFAULT_CONFIG: Required<Pick<HttpClientOptions, 'baseURL' | 'timeout' | 'withCredentials' | 'headers'>> = {
+  baseURL: '',
+  timeout: 10000,
+  withCredentials: false,
+  headers: {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  },
+}
+
+/**
+ * Creates a configured HTTP client with interceptors
+ * @param options - Configuration options
+ * @returns Configured axios instance with tracker
+ */
+export const createHttpClient = (options: HttpClientOptions = {}): HttpClient => {
+  const config = { ...DEFAULT_CONFIG, ...options }
+
+  // Create axios instance
+  const client = axios.create({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    withCredentials: config.withCredentials,
+    headers: { ...DEFAULT_CONFIG.headers, ...config.headers },
+  })
+
+  // Create request tracker if enabled
+  const tracker = false !== config.trackRequests ? createRequestTracker() : null
+
+  // Add request tracking interceptors
+  if (tracker) {
+    const trackingInterceptors = createTrackingInterceptors(tracker)
+    client.interceptors.request.use(trackingInterceptors.request, trackingInterceptors.requestError)
+    client.interceptors.response.use(trackingInterceptors.response, trackingInterceptors.responseError)
+  }
+
+  // Add CSRF interceptor
+  if (config.csrfToken) {
+    client.interceptors.request.use(createCSRFInterceptor(config.csrfToken))
+  }
+
+  // Add auth interceptor
+  if (config.authToken) {
+    client.interceptors.request.use(createAuthInterceptor(config.authToken, config.authType))
+  }
+
+  // Add timeout interceptor if different from default
+  if (config.timeout !== DEFAULT_CONFIG.timeout) {
+    client.interceptors.request.use(createTimeoutInterceptor(config.timeout))
+  }
+
+  // Add error logging interceptor
+  if (false !== config.enableErrorLogging) {
+    client.interceptors.response.use((response) => response, createErrorLoggerInterceptor(config.logger))
+  }
+
+  // Add retry interceptor
+  if (config.retries && 0 < config.retries) {
+    // Add the client instance to configs for retry handling
+    client.interceptors.request.use((reqConfig) => {
+      ;(reqConfig as any)._axios = client
+      return reqConfig
+    })
+
+    client.interceptors.response.use(
+      (response) => response,
+      createRetryInterceptor(config.retries, config.retryDelay, config.shouldRetry)
+    )
+  }
+
+  // Add Laravel-style headers if not disabled
+  if (false !== config.laravel) {
+    client.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest'
+  }
+
+  return {
+    client,
+    tracker,
+
+    // Convenience methods
+    get: <T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> =>
+      client.get<T>(url, config),
+    post: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> =>
+      client.post<T>(url, data, config),
+    put: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> =>
+      client.put<T>(url, data, config),
+    patch: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> =>
+      client.patch<T>(url, data, config),
+    delete: <T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>> =>
+      client.delete<T>(url, config),
+
+    // Request status
+    get isLoading(): boolean {
+      /* c8 ignore next */
+      return tracker ? tracker.isActive : false
+    },
+
+    get requestCount(): number {
+      /* c8 ignore next */
+      return tracker ? tracker.count : 0
+    },
+  }
+}
+
+/**
+ * Creates a Laravel-compatible HTTP client
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+export const createLaravelClient = (options: HttpClientOptions = {}): HttpClient => {
+  return createHttpClient({
+    withCredentials: true,
+    headers: {
+      'X-Requested-With': 'XMLHttpRequest',
+    },
+    ...options,
+  })
+}
+
+/**
+ * Creates an API client (typically for external APIs)
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+export const createApiClient = (options: HttpClientOptions = {}): HttpClient => {
+  return createHttpClient({
+    withCredentials: false,
+    laravel: false,
+    ...options,
+  })
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @zairakai/npm-http-client
+ * Configurable HTTP client built on axios with request tracking and Laravel support
+ */
+
+export {
+  createApiClient,
+  createHttpClient,
+  createLaravelClient,
+  type HttpClient,
+  type HttpClientOptions,
+} from './client.js'
+
+export { createRequestTracker, globalRequestTracker, type RequestTracker } from './request-tracker.js'
+
+export {
+  createAuthInterceptor,
+  createCSRFInterceptor,
+  createErrorLoggerInterceptor,
+  createRetryInterceptor,
+  createTimeoutInterceptor,
+  createTrackingInterceptors,
+  type Logger,
+  type ShouldRetryFunction,
+  type TokenSource,
+  type TrackingInterceptors,
+} from './interceptors.js'
+
+// Re-export axios for convenience
+export { default as axios } from 'axios'
+export type { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse, Method as HttpMethod } from 'axios'

package/src/interceptors.ts

@@ -0,0 +1,167 @@
+/**
+ * Common interceptors for HTTP clients
+ */
+
+import axios, { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios'
+import { RequestTracker } from './request-tracker.js'
+
+/**
+ * Token source type - either a string or a function that returns a string
+ */
+export type TokenSource = string | (() => string)
+
+/**
+ * Logger function type
+ */
+export type Logger = (message: string, data?: unknown) => void
+
+/**
+ * Retry condition function type
+ */
+export type ShouldRetryFunction = (error: AxiosError) => boolean
+
+/**
+ * Tracking interceptors interface
+ */
+export interface TrackingInterceptors {
+  request: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig
+  requestError: (error: Error) => Promise<never>
+  response: (response: AxiosResponse) => AxiosResponse
+  responseError: (error: Error) => Promise<never>
+}
+
+/**
+ * Creates request tracking interceptors
+ * @param tracker - Request tracker instance
+ * @returns Request and response interceptors
+ */
+export const createTrackingInterceptors = (tracker: RequestTracker): TrackingInterceptors => ({
+  request: (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
+    tracker.increment()
+    return config
+  },
+
+  requestError: (error: Error): Promise<never> => {
+    return Promise.reject(error)
+  },
+
+  response: (response: AxiosResponse): AxiosResponse => {
+    tracker.decrement()
+    return response
+  },
+
+  responseError: (error: Error): Promise<never> => {
+    tracker.decrement()
+    return Promise.reject(error)
+  },
+})
+
+/**
+ * Creates Laravel CSRF token interceptor
+ * @param tokenSource - CSRF token or function that returns token
+ * @returns Request interceptor
+ */
+export const createCSRFInterceptor =
+  (tokenSource: TokenSource) =>
+  (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
+    const token = 'function' === typeof tokenSource ? tokenSource() : tokenSource
+
+    if (token) {
+      config.headers = config.headers ?? {}
+      config.headers['X-CSRF-TOKEN'] = token
+    }
+
+    return config
+  }
+
+/**
+ * Creates authentication interceptor
+ * @param tokenSource - Auth token or function that returns token
+ * @param type - Token type ('Bearer', 'Token', etc.)
+ * @returns Request interceptor
+ */
+export const createAuthInterceptor =
+  (tokenSource: TokenSource, type: string = 'Bearer') =>
+  (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
+    const token = 'function' === typeof tokenSource ? tokenSource() : tokenSource
+
+    if (token) {
+      config.headers = config.headers ?? {}
+      config.headers['Authorization'] = `${type} ${token}`
+    }
+
+    return config
+  }
+
+/**
+ * Creates error logging interceptor
+ * @param logger - Logging function
+ * @returns Response error interceptor
+ */
+export const createErrorLoggerInterceptor =
+  (logger: Logger = console.error) =>
+  (error: AxiosError): Promise<never> => {
+    const logData = {
+      message: error.message,
+      status: error.response?.status,
+      statusText: error.response?.statusText,
+      url: error.config?.url,
+      method: error.config?.method?.toUpperCase(),
+    }
+
+    logger('HTTP Error:', logData)
+    return Promise.reject(error)
+  }
+
+/**
+ * Creates timeout interceptor
+ * @param timeout - Default timeout in milliseconds
+ * @returns Request interceptor
+ */
+export const createTimeoutInterceptor =
+  (timeout: number) =>
+  (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
+    config.timeout = timeout
+    return config
+  }
+
+/**
+ * Interface for retry configuration in request config
+ */
+interface RetryConfig extends InternalAxiosRequestConfig {
+  __retryCount?: number
+}
+
+/**
+ * Creates retry interceptor
+ * @param retries - Number of retries
+ * @param delay - Delay between retries in milliseconds
+ * @param shouldRetry - Function to determine if request should be retried
+ * @returns Response error interceptor
+ */
+export const createRetryInterceptor = (
+  retries: number = 3,
+  delay: number = 1000,
+  shouldRetry: ShouldRetryFunction = () => true
+) => {
+  return async (error: AxiosError): Promise<any> => {
+    const config = error.config as RetryConfig | undefined
+
+    if (!config || (config.__retryCount ?? 0) >= retries) {
+      return Promise.reject(error)
+    }
+
+    if (!shouldRetry(error)) {
+      return Promise.reject(error)
+    }
+
+    config.__retryCount = (config.__retryCount ?? 0) + 1
+
+    await new Promise((resolve) => setTimeout(resolve, delay))
+
+    // Try to use the instance from the error, otherwise fall back to axios
+    /* c8 ignore next */
+    const axiosInstance = (config as any)._axios ?? axios
+    return axiosInstance.request(config)
+  }
+}

package/src/request-tracker.ts

@@ -0,0 +1,56 @@
+/**
+ * Request tracking utility for monitoring ongoing HTTP requests
+ */
+
+/**
+ * Interface for request tracker instance
+ */
+export interface RequestTracker {
+  /** Current number of active requests */
+  readonly count: number
+  /** Whether there are any active requests */
+  readonly isActive: boolean
+  /** Increment the request counter */
+  increment(): void
+  /** Decrement the request counter */
+  decrement(): void
+  /** Reset the counter to zero */
+  reset(): void
+}
+
+/**
+ * Creates a request tracker instance
+ * @returns Request tracker with counter and methods
+ */
+export const createRequestTracker = (): RequestTracker => {
+  let nbrInternal = 0
+
+  return {
+    get count(): number {
+      return nbrInternal
+    },
+
+    set count(val: number) {
+      nbrInternal = Math.max(0, val)
+    },
+
+    get isActive(): boolean {
+      return 0 < nbrInternal
+    },
+
+    increment(): void {
+      nbrInternal++
+    },
+
+    decrement(): void {
+      nbrInternal = Math.max(0, nbrInternal - 1)
+    },
+
+    reset(): void {
+      nbrInternal = 0
+    },
+  }
+}
+
+// Global shared instance for backward compatibility
+export const globalRequestTracker: RequestTracker = createRequestTracker()