aziosxjs 0.4.1 → 1.0.0

package/src/plugins/pluginManager.ts

@@ -0,0 +1,143 @@
+import type { AziosPlugin, PluginRegistry } from '../types/plugin'
+import type { AziosInstance } from '../types/request'
+import type { AziosRequestConfig } from '../types/config'
+import type { AziosResponse } from '../types/response'
+
+/**
+ * PluginManager handles plugin lifecycle and hook execution
+ * Production-grade plugin system with error handling and validation
+ */
+export default class PluginManager {
+  private plugins: PluginRegistry = {}
+
+  /**
+   * Install a plugin and trigger its onInstall hook
+   * @throws Error if plugin name is already registered
+   */
+  async install(plugin: AziosPlugin, instance: AziosInstance): Promise<void> {
+    if (this.plugins[plugin.name]) {
+      throw new Error(`Plugin "${plugin.name}" is already installed`)
+    }
+
+    this.plugins[plugin.name] = plugin
+
+    try {
+      if (plugin.hooks.onInstall) {
+        await plugin.hooks.onInstall(instance)
+      }
+    } catch (err) {
+      // Rollback on error
+      delete this.plugins[plugin.name]
+      throw err
+    }
+  }
+
+  /**
+   * Uninstall a plugin and trigger its onUninstall hook
+   */
+  async uninstall(pluginName: string, instance: AziosInstance): Promise<void> {
+    const plugin = this.plugins[pluginName]
+
+    if (!plugin) {
+      throw new Error(`Plugin "${pluginName}" is not installed`)
+    }
+
+    try {
+      if (plugin.hooks.onUninstall) {
+        await plugin.hooks.onUninstall(instance)
+      }
+    } finally {
+      delete this.plugins[pluginName]
+    }
+  }
+
+  /**
+   * Execute beforeRequest hooks from all plugins
+   */
+  async executeBeforeRequestHooks(
+    config: AziosRequestConfig
+  ): Promise<AziosRequestConfig> {
+    let result = config
+
+    for (const plugin of Object.values(this.plugins)) {
+      if (plugin.hooks.beforeRequest) {
+        try {
+          result = await plugin.hooks.beforeRequest(result)
+        } catch (err) {
+          throw new Error(
+            `Plugin "${plugin.name}" beforeRequest hook failed: ${err instanceof Error ? err.message : String(err)}`
+          )
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Execute afterResponse hooks from all plugins
+   */
+  async executeAfterResponseHooks(
+    response: AziosResponse
+  ): Promise<AziosResponse> {
+    let result = response
+
+    for (const plugin of Object.values(this.plugins)) {
+      if (plugin.hooks.afterResponse) {
+        try {
+          result = await plugin.hooks.afterResponse(result)
+        } catch (err) {
+          throw new Error(
+            `Plugin "${plugin.name}" afterResponse hook failed: ${err instanceof Error ? err.message : String(err)}`
+          )
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Execute onError hooks from all plugins
+   */
+  async executeOnErrorHooks(error: Error): Promise<Error> {
+    let result = error
+
+    for (const plugin of Object.values(this.plugins)) {
+      if (plugin.hooks.onError) {
+        try {
+          result = await plugin.hooks.onError(result)
+        } catch (err) {
+          // Log but don't throw - error handlers should not crash
+          console.warn(
+            `Plugin "${plugin.name}" onError hook failed:`,
+            err instanceof Error ? err.message : String(err)
+          )
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Get all currently installed plugins
+   */
+  getInstalledPlugins(): AziosPlugin[] {
+    return Object.values(this.plugins)
+  }
+
+  /**
+   * Check if a plugin is installed
+   */
+  isPluginInstalled(name: string): boolean {
+    return name in this.plugins
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    this.plugins = {}
+  }
+}

package/src/rateLimiter/rateLimiter.ts

@@ -0,0 +1,36 @@
+let queue: Function[] = [];
+let activeRequests = 0;
+
+export function schedule(task: Function, limit: number) {
+
+  return new Promise((resolve, reject) => {
+
+    const run = async () => {
+
+      activeRequests++;
+
+      try {
+        const result = await task();
+        resolve(result);
+      } catch (err) {
+        reject(err);
+      }
+
+      activeRequests--;
+
+      if (queue.length) {
+        const next = queue.shift();
+        next && next();
+      }
+
+    };
+
+    if (activeRequests < limit) {
+      run();
+    } else {
+      queue.push(run);
+    }
+
+  });
+
+}

package/src/runtimes/AdapterFactory.ts

@@ -0,0 +1,46 @@
+import type { HttpAdapter } from './HttpAdapter'
+import { currentRuntime, RuntimeType } from './detectRuntime'
+import UniversalHttpAdapter from './UniversalHttpAdapter'
+
+/**
+ * Adapter factory for selecting the appropriate HTTP adapter
+ * Uses universal Fetch API when available with fallbacks for specific runtimes
+ */
+export class AdapterFactory {
+  private static adapters: Map<RuntimeType, HttpAdapter> = new Map()
+
+  /**
+   * Get or create adapter for current runtime
+   */
+  static getAdapter(): HttpAdapter {
+    if (!this.adapters.has(currentRuntime)) {
+      this.adapters.set(currentRuntime, new UniversalHttpAdapter())
+    }
+
+    const adapter = this.adapters.get(currentRuntime)!
+
+    if (!adapter.isSupported()) {
+      throw new Error(
+        `No supported HTTP adapter found for runtime: ${currentRuntime}`
+      )
+    }
+
+    return adapter
+  }
+
+  /**
+   * Register custom adapter for specific runtime
+   */
+  static registerAdapter(runtime: RuntimeType, adapter: HttpAdapter): void {
+    this.adapters.set(runtime, adapter)
+  }
+
+  /**
+   * Clear adapter cache
+   */
+  static clearCache(): void {
+    this.adapters.clear()
+  }
+}
+
+export default AdapterFactory

package/src/runtimes/HttpAdapter.ts

@@ -0,0 +1,26 @@
+import type { AziosRequestConfig } from '../types/config'
+import type { AziosResponse } from '../types/response'
+
+/**
+ * Universal HTTP adapter interface
+ * Abstracts HTTP functionality across different runtimes
+ */
+export interface HttpAdapter {
+  /**
+   * Execute an HTTP request
+   */
+  request(config: AziosRequestConfig): Promise<AziosResponse>
+
+  /**
+   * Method to check if adapter supports the current runtime
+   */
+  isSupported(): boolean
+}
+
+/**
+ * Base adapter class with common logic
+ */
+export abstract class BaseAdapter implements HttpAdapter {
+  abstract request(config: AziosRequestConfig): Promise<AziosResponse>
+  abstract isSupported(): boolean
+}

package/src/runtimes/UniversalHttpAdapter.ts

@@ -0,0 +1,136 @@
+import type { AziosRequestConfig } from '../types/config'
+import type { AziosResponse } from '../types/response'
+import { BaseAdapter } from './HttpAdapter'
+import AziosError from '../errors/AziosError'
+import { isRuntime, RuntimeType } from './detectRuntime'
+
+/**
+ * Unified HTTP adapter using Fetch API
+ * Works across Node 18+, browsers, Bun, Deno, and edge runtimes
+ * Falls back to runtime-specific implementations if needed
+ */
+export class UniversalHttpAdapter extends BaseAdapter {
+  /**
+   * Check if Fetch API is available
+   */
+  isSupported(): boolean {
+    return typeof fetch !== 'undefined'
+  }
+
+  /**
+   * Execute HTTP request using Fetch API
+   */
+  async request(config: AziosRequestConfig): Promise<AziosResponse> {
+    if (!this.isSupported()) {
+      throw new AziosError(
+        'Fetch API is not available in this runtime',
+        'UNSUPPORTED_RUNTIME',
+        config
+      )
+    }
+
+    try {
+      const { url, method = 'GET', headers, data, timeout, signal } = config
+
+      const baseURL = config.baseURL ? config.baseURL : ''
+      const fullURL = new URL(baseURL + url)
+
+      // Add query parameters
+      if (config.params) {
+        Object.entries(config.params).forEach(([key, value]) => {
+          if (value !== null && value !== undefined) {
+            if (Array.isArray(value)) {
+              value.forEach(v => fullURL.searchParams.append(key, String(v)))
+            } else {
+              fullURL.searchParams.set(key, String(value))
+            }
+          }
+        })
+      }
+
+      // Prepare request body
+      let body: string | null = null
+      if (data) {
+        body = typeof data === 'string' ? data : JSON.stringify(data)
+      }
+
+      // Set up timeout if specified (using AbortController)
+      let timeoutId: NodeJS.Timeout | undefined
+      const controller = new AbortController()
+      const finalSignal = signal || controller.signal
+
+      if (timeout) {
+        timeoutId = setTimeout(() => {
+          controller.abort()
+        }, timeout)
+      }
+
+      // Execute fetch
+      const response = await fetch(fullURL.toString(), {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...headers
+        },
+        body,
+        signal: finalSignal as any
+      })
+
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+
+      // Parse response body
+      let responseData: any
+
+      if (response.status === 204) {
+        // No content
+        responseData = null
+      } else {
+        const contentType = response.headers.get('content-type')
+
+        if (contentType?.includes('application/json')) {
+          try {
+            responseData = await response.json()
+          } catch {
+            responseData = await response.text()
+          }
+        } else {
+          responseData = await response.text()
+        }
+      }
+
+      const aziosResponse: AziosResponse = {
+        data: responseData,
+        status: response.status,
+        statusText: response.statusText,
+        headers: Object.fromEntries(response.headers.entries()),
+        config
+      }
+
+      return aziosResponse
+    } catch (err) {
+      if (err instanceof TypeError && err.message.includes('aborted')) {
+        throw new AziosError(
+          'Request aborted',
+          'ABORTED',
+          config
+        )
+      }
+
+      if (err instanceof AziosError) {
+        throw err
+      }
+
+      throw new AziosError(
+        err instanceof Error ? err.message : 'Network request failed',
+        'NETWORK_ERROR',
+        config,
+        undefined,
+        err instanceof Error ? err : new Error(String(err))
+      )
+    }
+  }
+}
+
+export default UniversalHttpAdapter

package/src/runtimes/detectRuntime.ts

@@ -0,0 +1,85 @@
+/**
+ * Runtime detection utilities
+ * Identifies the current JavaScript runtime environment
+ * Supports: Node.js, Browser, Bun, Deno, Cloudflare Workers/Edge
+ */
+
+export enum RuntimeType {
+  Node = 'node',
+  Browser = 'browser',
+  Bun = 'bun',
+  Deno = 'deno',
+  Edge = 'edge',
+  Unknown = 'unknown'
+}
+
+/**
+ * Detects the current runtime environment
+ * Production-grade detection with reliable environment checks
+ */
+export function detectRuntime(): RuntimeType {
+  // Check for Deno
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return RuntimeType.Deno
+  }
+
+  // Check for Bun
+  if (typeof (globalThis as any).Bun !== 'undefined') {
+    return RuntimeType.Bun
+  }
+
+  // Check for Cloudflare Workers / Edge
+  if (
+    typeof (globalThis as any).caches !== 'undefined' &&
+    typeof (globalThis as any).ENVIRONMENT !== 'undefined'
+  ) {
+    return RuntimeType.Edge
+  }
+
+  // Check for Node.js
+  if (
+    typeof process !== 'undefined' &&
+    process.versions &&
+    process.versions.node
+  ) {
+    return RuntimeType.Node
+  }
+
+  // Check for Browser
+  if (typeof (globalThis as any).window !== 'undefined' && typeof (globalThis as any).document !== 'undefined') {
+    return RuntimeType.Browser
+  }
+
+  return RuntimeType.Unknown
+}
+
+/**
+ * Get current runtime for use in adapters
+ */
+export const currentRuntime = detectRuntime()
+
+/**
+ * Check if running in a specific runtime
+ */
+export function isRuntime(runtime: RuntimeType): boolean {
+  return currentRuntime === runtime
+}
+
+/**
+ * Check if running in server-side runtime
+ */
+export function isServerRuntime(): boolean {
+  return (
+    currentRuntime === RuntimeType.Node ||
+    currentRuntime === RuntimeType.Bun ||
+    currentRuntime === RuntimeType.Deno ||
+    currentRuntime === RuntimeType.Edge
+  )
+}
+
+/**
+ * Check if running in browser runtime
+ */
+export function isBrowserRuntime(): boolean {
+  return currentRuntime === RuntimeType.Browser
+}

package/src/types/config.ts

@@ -0,0 +1,30 @@
+export interface AziosRequestConfig {
+
+  url?: string
+  method?: string
+
+  baseURL?: string
+
+  headers?: Record<string, any>
+
+  params?: Record<string, any>
+
+  data?: any
+
+  timeout?: number
+
+  responseType?: string
+
+  signal?: AbortSignal
+
+  // Sprint 3
+  retry?: number
+  retryDelay?: number
+
+  // Sprint 4
+  cache?: boolean
+  cacheTTL?: number
+
+  rateLimit?: number
+
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from './config'
+export * from './request'
+export * from './response'
+export * from './plugin'
+export * from './middleware'

package/src/types/middleware.ts

@@ -0,0 +1,21 @@
+import { AziosRequestConfig } from './config'
+import { AziosResponse } from './response'
+
+/**
+ * Middleware function type for request/response processing
+ * Koa-style middleware pattern that receives context and next function
+ */
+export type AziosMiddleware = (
+  config: AziosRequestConfig,
+  next: (cfg?: AziosRequestConfig) => Promise<AziosResponse>
+) => Promise<AziosResponse>
+
+/**
+ * Middleware context for tracking state across pipeline
+ */
+export interface MiddlewareContext {
+  startTime?: number
+  endTime?: number
+  config: AziosRequestConfig
+  metadata?: Record<string, any>
+}

package/src/types/plugin.ts

@@ -0,0 +1,50 @@
+import { AziosRequestConfig } from './config'
+import { AziosResponse } from './response'
+import type { AziosInstance } from './request'
+
+/**
+ * Plugin lifecycle hooks
+ * Allows plugins to inject behavior at various stages of the request/response pipeline
+ */
+export interface PluginHooks {
+  /**
+   * Called when plugin is installed
+   */
+  onInstall?(instance: AziosInstance): void | Promise<void>
+
+  /**
+   * Called before request is sent
+   */
+  beforeRequest?(config: AziosRequestConfig): AziosRequestConfig | Promise<AziosRequestConfig>
+
+  /**
+   * Called after response is received
+   */
+  afterResponse?(response: AziosResponse): AziosResponse | Promise<AziosResponse>
+
+  /**
+   * Called when an error occurs
+   */
+  onError?(error: Error): Error | Promise<Error>
+
+  /**
+   * Called when plugin is uninstalled
+   */
+  onUninstall?(instance: AziosInstance): void | Promise<void>
+}
+
+/**
+ * Plugin definition with metadata
+ */
+export interface AziosPlugin {
+  name: string
+  version?: string
+  hooks: PluginHooks
+}
+
+/**
+ * Plugin registry to track installed plugins
+ */
+export interface PluginRegistry {
+  [key: string]: AziosPlugin
+}

package/src/types/request.ts

@@ -0,0 +1,39 @@
+import { AziosRequestConfig } from "./config"
+import { AziosResponse } from "./response"
+import InterceptorManager from "../interceptors/InterceptorManager"
+import type { AziosPlugin } from "./plugin"
+import type { AziosMiddleware } from "./middleware"
+
+export interface AziosInstance {
+
+  (config: AziosRequestConfig): Promise<AziosResponse>
+
+  request(config: AziosRequestConfig): Promise<AziosResponse>
+
+  get(url: string, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  post(url: string, data?: any, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  put(url: string, data?: any, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  patch(url: string, data?: any, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  delete(url: string, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  head(url: string, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  options(url: string, config?: AziosRequestConfig): Promise<AziosResponse>
+
+  interceptors: {
+    request: InterceptorManager<AziosRequestConfig>
+    response: InterceptorManager<AziosResponse>
+  }
+
+  // Plugin system
+  installPlugin(plugin: AziosPlugin): Promise<void>
+  uninstallPlugin(name: string): Promise<void>
+
+  // Middleware system
+  use(middleware: AziosMiddleware): void
+
+}

package/src/types/response.ts

@@ -0,0 +1,37 @@
+import { AziosRequestConfig } from "./config"
+
+/**
+ * Azios HTTP response object
+ * Returned by all request methods
+ */
+export interface AziosResponse<T = any> {
+  /**
+   * Response data (parsed if JSON)
+   */
+  data: T
+
+  /**
+   * HTTP status code
+   */
+  status: number
+
+  /**
+   * HTTP status text
+   */
+  statusText: string
+
+  /**
+   * Response headers
+   */
+  headers: Record<string, any>
+
+  /**
+   * Original request config
+   */
+  config: AziosRequestConfig
+
+  /**
+   * Native request object (if available)
+   */
+  request?: any
+}