kimu-core 0.4.1

package/src/modules-repository/api-axios/api-axios-service.ts

@@ -0,0 +1,355 @@
+/**
+ * API Axios Service
+ * 
+ * Advanced HTTP client based on Axios library.
+ * Provides additional features over api-core:
+ * - Request/response interceptors
+ * - Automatic retries with exponential backoff
+ * - Request cancellation
+ * - Upload/download progress tracking
+ * - Better error handling and transformation
+ * - Request/response caching
+ * 
+ * @module api-axios
+ * @author UnicòVerso
+ * @version 1.0.0
+ */
+
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse, CancelTokenSource, InternalAxiosRequestConfig } from 'axios';
+import {
+  ApiRequestConfig,
+  ApiResponse,
+  ApiError,
+  HttpMethod,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor
+} from './interfaces';
+
+/**
+ * ApiAxiosService - Advanced HTTP client with Axios
+ * 
+ * Features:
+ * - Interceptors for requests and responses
+ * - Automatic retry logic with exponential backoff
+ * - Request cancellation support
+ * - Progress tracking for uploads/downloads
+ * - Response caching
+ * - Better error handling
+ */
+export class ApiAxiosService {
+  private axiosInstance: AxiosInstance;
+  private requestInterceptors: RequestInterceptor[] = [];
+  private responseInterceptors: ResponseInterceptor[] = [];
+  private errorInterceptors: ErrorInterceptor[] = [];
+  private cache: Map<string, { data: any; timestamp: number }> = new Map();
+  private cacheTTL: number = 5 * 60 * 1000; // 5 minutes default
+
+  constructor() {
+    this.axiosInstance = axios.create({
+      timeout: 30000,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+
+    this.setupInterceptors();
+  }
+
+  /**
+   * Setup default Axios interceptors
+   */
+  private setupInterceptors(): void {
+    // Request interceptor
+    this.axiosInstance.interceptors.request.use(
+      async (config: InternalAxiosRequestConfig) => {
+        // Apply custom request interceptors
+        for (const interceptor of this.requestInterceptors) {
+          const modifiedConfig = await interceptor(config as any);
+          Object.assign(config, modifiedConfig);
+        }
+        return config;
+      },
+      (error: any) => Promise.reject(error)
+    );
+
+    // Response interceptor
+    this.axiosInstance.interceptors.response.use(
+      async (response: AxiosResponse) => {
+        const apiResponse = this.transformResponse(response);
+        
+        // Apply custom response interceptors
+        for (const interceptor of this.responseInterceptors) {
+          await interceptor(apiResponse);
+        }
+        
+        return response;
+      },
+      async (error: any) => {
+        const apiError = this.transformError(error);
+        
+        // Apply custom error interceptors
+        for (const interceptor of this.errorInterceptors) {
+          await interceptor(apiError);
+        }
+        
+        return Promise.reject(apiError);
+      }
+    );
+  }
+
+  /**
+   * Add a request interceptor
+   */
+  addRequestInterceptor(interceptor: RequestInterceptor): void {
+    this.requestInterceptors.push(interceptor);
+  }
+
+  /**
+   * Add a response interceptor
+   */
+  addResponseInterceptor(interceptor: ResponseInterceptor): void {
+    this.responseInterceptors.push(interceptor);
+  }
+
+  /**
+   * Add an error interceptor
+   */
+  addErrorInterceptor(interceptor: ErrorInterceptor): void {
+    this.errorInterceptors.push(interceptor);
+  }
+
+  /**
+   * Transform Axios response to ApiResponse format
+   */
+  private transformResponse(response: AxiosResponse): ApiResponse {
+    return {
+      data: response.data,
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers as Record<string, string>,
+      config: response.config as ApiRequestConfig
+    };
+  }
+
+  /**
+   * Transform Axios error to ApiError format
+   */
+  private transformError(error: any): ApiError {
+    if (error.response) {
+      return {
+        message: error.message || 'Request failed',
+        status: error.response.status,
+        data: error.response.data,
+        originalError: error
+      };
+    }
+    
+    return {
+      message: error.message || 'Network error',
+      originalError: error
+    };
+  }
+
+  /**
+   * Generate cache key from URL and config
+   */
+  private getCacheKey(url: string, config?: ApiRequestConfig): string {
+    const params = config?.params ? JSON.stringify(config.params) : '';
+    return `${url}${params}`;
+  }
+
+  /**
+   * Check if cached response is still valid
+   */
+  private isCacheValid(timestamp: number): boolean {
+    return Date.now() - timestamp < this.cacheTTL;
+  }
+
+  /**
+   * Set cache TTL (time-to-live) in milliseconds
+   */
+  setCacheTTL(ttl: number): void {
+    this.cacheTTL = ttl;
+  }
+
+  /**
+   * Clear all cached responses
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Create a cancel token for request cancellation
+   */
+  createCancelToken(): CancelTokenSource {
+    return axios.CancelToken.source();
+  }
+
+  /**
+   * Perform HTTP GET request
+   */
+  async get<T = any>(url: string, config?: ApiRequestConfig & { useCache?: boolean }): Promise<ApiResponse<T>> {
+    const useCache = config?.useCache ?? false;
+    const cacheKey = this.getCacheKey(url, config);
+
+    // Check cache
+    if (useCache && this.cache.has(cacheKey)) {
+      const cached = this.cache.get(cacheKey)!;
+      if (this.isCacheValid(cached.timestamp)) {
+        return {
+          data: cached.data,
+          status: 200,
+          statusText: 'OK (cached)',
+          headers: {},
+          config: config || {}
+        };
+      }
+    }
+
+    const axiosConfig: AxiosRequestConfig = {
+      ...config?.axiosConfig,
+      headers: config?.headers,
+      params: config?.params,
+      timeout: config?.timeout,
+      withCredentials: config?.withCredentials,
+      responseType: config?.responseType,
+      onUploadProgress: config?.onUploadProgress,
+      onDownloadProgress: config?.onDownloadProgress
+    };
+
+    const response = await this.axiosInstance.get<T>(url, axiosConfig);
+    const apiResponse = this.transformResponse(response);
+
+    // Store in cache if enabled
+    if (useCache) {
+      this.cache.set(cacheKey, {
+        data: apiResponse.data,
+        timestamp: Date.now()
+      });
+    }
+
+    return apiResponse;
+  }
+
+  /**
+   * Perform HTTP POST request
+   */
+  async post<T = any>(url: string, data?: any, config?: ApiRequestConfig): Promise<ApiResponse<T>> {
+    const axiosConfig: AxiosRequestConfig = {
+      ...config?.axiosConfig,
+      headers: config?.headers,
+      params: config?.params,
+      timeout: config?.timeout,
+      withCredentials: config?.withCredentials,
+      responseType: config?.responseType,
+      onUploadProgress: config?.onUploadProgress,
+      onDownloadProgress: config?.onDownloadProgress
+    };
+
+    const response = await this.axiosInstance.post<T>(url, data, axiosConfig);
+    return this.transformResponse(response);
+  }
+
+  /**
+   * Perform HTTP PUT request
+   */
+  async put<T = any>(url: string, data?: any, config?: ApiRequestConfig): Promise<ApiResponse<T>> {
+    const axiosConfig: AxiosRequestConfig = {
+      ...config?.axiosConfig,
+      headers: config?.headers,
+      params: config?.params,
+      timeout: config?.timeout,
+      withCredentials: config?.withCredentials,
+      responseType: config?.responseType,
+      onUploadProgress: config?.onUploadProgress,
+      onDownloadProgress: config?.onDownloadProgress
+    };
+
+    const response = await this.axiosInstance.put<T>(url, data, axiosConfig);
+    return this.transformResponse(response);
+  }
+
+  /**
+   * Perform HTTP PATCH request
+   */
+  async patch<T = any>(url: string, data?: any, config?: ApiRequestConfig): Promise<ApiResponse<T>> {
+    const axiosConfig: AxiosRequestConfig = {
+      ...config?.axiosConfig,
+      headers: config?.headers,
+      params: config?.params,
+      timeout: config?.timeout,
+      withCredentials: config?.withCredentials,
+      responseType: config?.responseType,
+      onUploadProgress: config?.onUploadProgress,
+      onDownloadProgress: config?.onDownloadProgress
+    };
+
+    const response = await this.axiosInstance.patch<T>(url, data, axiosConfig);
+    return this.transformResponse(response);
+  }
+
+  /**
+   * Perform HTTP DELETE request
+   */
+  async delete<T = any>(url: string, config?: ApiRequestConfig): Promise<ApiResponse<T>> {
+    const axiosConfig: AxiosRequestConfig = {
+      ...config?.axiosConfig,
+      headers: config?.headers,
+      params: config?.params,
+      timeout: config?.timeout,
+      withCredentials: config?.withCredentials,
+      responseType: config?.responseType
+    };
+
+    const response = await this.axiosInstance.delete<T>(url, axiosConfig);
+    return this.transformResponse(response);
+  }
+
+  /**
+   * Perform a generic HTTP request with automatic retry
+   */
+  async request<T = any>(
+    method: HttpMethod,
+    url: string,
+    data?: any,
+    config?: ApiRequestConfig & { retries?: number; retryDelay?: number }
+  ): Promise<ApiResponse<T>> {
+    const retries = config?.retries ?? 0;
+    const retryDelay = config?.retryDelay ?? 1000;
+
+    let lastError: ApiError | null = null;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        switch (method) {
+          case 'GET':
+            return await this.get<T>(url, config);
+          case 'POST':
+            return await this.post<T>(url, data, config);
+          case 'PUT':
+            return await this.put<T>(url, data, config);
+          case 'PATCH':
+            return await this.patch<T>(url, data, config);
+          case 'DELETE':
+            return await this.delete<T>(url, config);
+          default:
+            throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+      } catch (error: any) {
+        lastError = error as ApiError;
+        
+        if (attempt < retries) {
+          // Exponential backoff
+          await new Promise(resolve => setTimeout(resolve, retryDelay * Math.pow(2, attempt)));
+        }
+      }
+    }
+
+    throw lastError;
+  }
+}
+
+// Singleton instance
+export const apiAxiosService = new ApiAxiosService();

package/src/modules-repository/api-axios/examples.ts

@@ -0,0 +1,293 @@
+/**
+ * API Axios Service - Usage Examples
+ * 
+ * Collection of practical examples demonstrating various features
+ * of the api-axios module.
+ */
+
+import { apiAxiosService } from './api-axios-service';
+import type { ApiError } from './interfaces';
+
+/**
+ * Example 1: Simple GET request
+ */
+export async function exampleSimpleGet() {
+  try {
+    const response = await apiAxiosService.get('https://api.ipify.org?format=json');
+    console.log('Your IP:', response.data.ip);
+    return response.data;
+  } catch (error: any) {
+    console.error('Error fetching IP:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 2: GET with query parameters
+ */
+export async function exampleGetWithParams() {
+  try {
+    const response = await apiAxiosService.get('https://api.github.com/search/repositories', {
+      params: {
+        q: 'kimu',
+        sort: 'stars',
+        order: 'desc'
+      }
+    });
+    console.log('Repositories found:', response.data.total_count);
+    return response.data;
+  } catch (error: any) {
+    console.error('Error searching repositories:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 3: POST request with data
+ */
+export async function examplePost() {
+  try {
+    const response = await apiAxiosService.post('https://jsonplaceholder.typicode.com/posts', {
+      title: 'My Post',
+      body: 'This is the content',
+      userId: 1
+    });
+    console.log('Post created:', response.data);
+    return response.data;
+  } catch (error: any) {
+    console.error('Error creating post:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 4: Request with retry logic
+ */
+export async function exampleWithRetry() {
+  try {
+    const response = await apiAxiosService.request(
+      'GET',
+      'https://api.ipify.org?format=json',
+      null,
+      {
+        retries: 3,
+        retryDelay: 1000
+      }
+    );
+    console.log('IP (with retry):', response.data.ip);
+    return response.data;
+  } catch (error: any) {
+    console.error('Failed after retries:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 5: Cached GET request
+ */
+export async function exampleWithCache() {
+  // First call - fetches from server
+  console.log('First call (from server)...');
+  const response1 = await apiAxiosService.get('https://api.ipify.org?format=json', {
+    useCache: true
+  });
+  console.log('IP:', response1.data.ip);
+
+  // Second call - returns cached data
+  console.log('Second call (from cache)...');
+  const response2 = await apiAxiosService.get('https://api.ipify.org?format=json', {
+    useCache: true
+  });
+  console.log('IP:', response2.data.ip);
+
+  return response2.data;
+}
+
+/**
+ * Example 6: Request with custom headers
+ */
+export async function exampleWithHeaders() {
+  try {
+    const response = await apiAxiosService.get('https://api.github.com/user', {
+      headers: {
+        'Authorization': 'Bearer YOUR_TOKEN_HERE',
+        'Accept': 'application/vnd.github.v3+json'
+      }
+    });
+    console.log('User:', response.data.login);
+    return response.data;
+  } catch (error: any) {
+    console.error('Error fetching user:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 7: Request with timeout
+ */
+export async function exampleWithTimeout() {
+  try {
+    const response = await apiAxiosService.get('https://api.ipify.org?format=json', {
+      timeout: 5000 // 5 seconds
+    });
+    console.log('IP:', response.data.ip);
+    return response.data;
+  } catch (error: any) {
+    if (error.message.includes('timeout')) {
+      console.error('Request timed out!');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Example 8: Upload with progress tracking
+ */
+export async function exampleUploadProgress() {
+  const formData = new FormData();
+  formData.append('file', new Blob(['test content'], { type: 'text/plain' }));
+
+  try {
+    const response = await apiAxiosService.post(
+      'https://httpbin.org/post',
+      formData,
+      {
+        onUploadProgress: (event) => {
+          const percentComplete = Math.round((event.loaded * 100) / (event.total || 1));
+          console.log(`Upload progress: ${percentComplete}%`);
+        }
+      }
+    );
+    console.log('Upload complete:', response.status);
+    return response.data;
+  } catch (error: any) {
+    console.error('Upload failed:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 9: Request cancellation
+ */
+export async function exampleCancellation() {
+  const cancelToken = apiAxiosService.createCancelToken();
+
+  // Start the request
+  const requestPromise = apiAxiosService.get('https://api.github.com/users/torvalds', {
+    axiosConfig: {
+      cancelToken: cancelToken.token
+    }
+  });
+
+  // Cancel after 100ms
+  setTimeout(() => {
+    console.log('Cancelling request...');
+    cancelToken.cancel('User cancelled the request');
+  }, 100);
+
+  try {
+    const response = await requestPromise;
+    console.log('Request completed:', response.data.login);
+    return response.data;
+  } catch (error: any) {
+    if (error.message.includes('cancel')) {
+      console.log('Request was cancelled');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Example 10: Using interceptors
+ */
+export function exampleInterceptors() {
+  // Add request interceptor to add auth token
+  apiAxiosService.addRequestInterceptor(async (config) => {
+    console.log('Request interceptor: Adding auth token');
+    config.headers = config.headers || {};
+    config.headers['X-Custom-Token'] = 'my-token-123';
+    return config;
+  });
+
+  // Add response interceptor to log responses
+  apiAxiosService.addResponseInterceptor(async (response) => {
+    console.log('Response interceptor: Status', response.status);
+    return response;
+  });
+
+  // Add error interceptor to handle errors globally
+  apiAxiosService.addErrorInterceptor(async (error) => {
+    console.error('Error interceptor:', error.message);
+    if (error.status === 401) {
+      console.log('Unauthorized - redirecting to login');
+    }
+  });
+
+  console.log('Interceptors configured');
+}
+
+/**
+ * Example 11: TypeScript with generic types
+ */
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+export async function exampleWithTypes() {
+  try {
+    const response = await apiAxiosService.get<User>('https://jsonplaceholder.typicode.com/users/1');
+    // response.data is typed as User
+    console.log('User name:', response.data.name);
+    console.log('User email:', response.data.email);
+    return response.data;
+  } catch (error: any) {
+    console.error('Error fetching user:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Example 12: Error handling with detailed information
+ */
+export async function exampleErrorHandling() {
+  try {
+    const response = await apiAxiosService.get('https://api.github.com/nonexistent');
+    return response.data;
+  } catch (error: any) {
+    const apiError = error as ApiError;
+    
+    console.error('Error details:');
+    console.error('- Message:', apiError.message);
+    console.error('- Status:', apiError.status);
+    console.error('- Response data:', apiError.data);
+    console.error('- Original error:', apiError.originalError);
+    
+    throw error;
+  }
+}
+
+/**
+ * Example 13: Cache management
+ */
+export async function exampleCacheManagement() {
+  // Set cache TTL to 10 minutes
+  apiAxiosService.setCacheTTL(10 * 60 * 1000);
+
+  // Make cached request
+  const response1 = await apiAxiosService.get('https://api.ipify.org?format=json', {
+    useCache: true
+  });
+  console.log('First call:', response1.data.ip);
+
+  // Clear cache
+  apiAxiosService.clearCache();
+  console.log('Cache cleared');
+
+  // This will fetch from server again
+  const response2 = await apiAxiosService.get('https://api.ipify.org?format=json', {
+    useCache: true
+  });
+  console.log('Second call (after clear):', response2.data.ip);
+}

package/src/modules-repository/api-axios/index.ts

@@ -0,0 +1,19 @@
+/**
+ * API Axios Module - Public API
+ * 
+ * Main entry point for the api-axios module.
+ * 
+ * @module api-axios
+ */
+
+export { ApiAxiosService, apiAxiosService } from './api-axios-service';
+export type {
+  ApiRequestConfig,
+  ApiResponse,
+  ApiError,
+  HttpMethod,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor
+} from './interfaces';
+export { default as ApiAxiosModule } from './module';