kimu-core 0.4.1

package/src/modules-repository/api-axios/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog - API Axios Module
+
+All notable changes to the api-axios module will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-11-01
+
+### Added
+- Initial release of api-axios module
+- Full Axios-based HTTP client implementation
+- Request/response interceptors support
+- Automatic retry logic with exponential backoff
+- Request cancellation support via cancel tokens
+- Upload/download progress tracking
+- Response caching with configurable TTL
+- Complete TypeScript type definitions
+- Comprehensive documentation and examples
+- Migration guide from api-core
+- Error transformation and standardized error handling
+- Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Query parameters and custom headers support
+- Timeout configuration per request
+- Credentials (cookies) support
+
+### Features Over api-core
+- **Interceptors**: Add custom logic before/after requests
+- **Retry Logic**: Automatic retry with exponential backoff
+- **Cancellation**: Cancel pending requests when needed
+- **Progress**: Track upload/download progress in real-time
+- **Caching**: Cache GET responses to reduce network calls
+- **Better Errors**: Enhanced error handling with original error preservation
+
+### Dependencies
+- axios: ^1.6.0 (external dependency)
+
+## [Unreleased]
+
+### Planned Features
+- Request deduplication (prevent duplicate concurrent requests)
+- Request queue management
+- Offline request queueing
+- Custom retry strategies
+- Response schema validation
+- Mock mode for testing
+- Request/response logging
+- Metrics and performance tracking

package/src/modules-repository/api-axios/QUICK-REFERENCE.md

@@ -0,0 +1,178 @@
+# API Axios - Quick Reference
+
+## Import
+
+```typescript
+import { apiAxiosService } from '../../modules/api-axios/api-axios-service';
+```
+
+## Basic Methods
+
+```typescript
+// GET request
+const response = await apiAxiosService.get(url, config);
+
+// POST request
+const response = await apiAxiosService.post(url, data, config);
+
+// PUT request
+const response = await apiAxiosService.put(url, data, config);
+
+// PATCH request
+const response = await apiAxiosService.patch(url, data, config);
+
+// DELETE request
+const response = await apiAxiosService.delete(url, config);
+
+// Generic request with method
+const response = await apiAxiosService.request(method, url, data, config);
+```
+
+## Common Use Cases
+
+### With Query Parameters
+```typescript
+const response = await apiAxiosService.get('https://api.example.com/users', {
+  params: { page: 1, limit: 10 }
+});
+// Calls: https://api.example.com/users?page=1&limit=10
+```
+
+### With Custom Headers
+```typescript
+const response = await apiAxiosService.get('https://api.example.com/data', {
+  headers: {
+    'Authorization': 'Bearer token123',
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+### With Timeout
+```typescript
+const response = await apiAxiosService.get('https://api.example.com/data', {
+  timeout: 5000 // 5 seconds
+});
+```
+
+### With Retry
+```typescript
+const response = await apiAxiosService.request('GET', 'https://api.example.com/data', null, {
+  retries: 3,
+  retryDelay: 1000
+});
+```
+
+### With Cache
+```typescript
+const response = await apiAxiosService.get('https://api.example.com/data', {
+  useCache: true
+});
+
+// Configure cache TTL
+apiAxiosService.setCacheTTL(10 * 60 * 1000); // 10 minutes
+
+// Clear cache
+apiAxiosService.clearCache();
+```
+
+### With Progress Tracking
+```typescript
+const response = await apiAxiosService.post('https://api.example.com/upload', formData, {
+  onUploadProgress: (event) => {
+    const percent = Math.round((event.loaded * 100) / event.total);
+    console.log(`Upload: ${percent}%`);
+  }
+});
+```
+
+### With Cancellation
+```typescript
+const cancelToken = apiAxiosService.createCancelToken();
+
+const promise = apiAxiosService.get('https://api.example.com/data', {
+  axiosConfig: { cancelToken: cancelToken.token }
+});
+
+// Cancel if needed
+cancelToken.cancel('User cancelled');
+```
+
+## Interceptors
+
+### Request Interceptor
+```typescript
+apiAxiosService.addRequestInterceptor(async (config) => {
+  config.headers = config.headers || {};
+  config.headers['Authorization'] = 'Bearer token';
+  return config;
+});
+```
+
+### Response Interceptor
+```typescript
+apiAxiosService.addResponseInterceptor(async (response) => {
+  console.log('Response:', response.status);
+  return response;
+});
+```
+
+### Error Interceptor
+```typescript
+apiAxiosService.addErrorInterceptor(async (error) => {
+  if (error.status === 401) {
+    // Handle unauthorized
+  }
+});
+```
+
+## TypeScript Types
+
+```typescript
+import type { ApiResponse, ApiError, ApiRequestConfig } from '../../modules/api-axios';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+const response = await apiAxiosService.get<User>('https://api.example.com/user/1');
+// response.data is typed as User
+```
+
+## Error Handling
+
+```typescript
+try {
+  const response = await apiAxiosService.get('https://api.example.com/data');
+  console.log(response.data);
+} catch (error: any) {
+  console.error('Status:', error.status);
+  console.error('Message:', error.message);
+  console.error('Data:', error.data);
+}
+```
+
+## Response Format
+
+```typescript
+{
+  data: any,           // Response data
+  status: number,      // HTTP status code
+  statusText: string,  // HTTP status text
+  headers: {},         // Response headers
+  config: {}           // Original request config
+}
+```
+
+## Migration from api-core
+
+```typescript
+// Simply replace the import
+// From:
+import { apiCoreService } from '../../modules/api-core/api-core-service';
+// To:
+import { apiAxiosService } from '../../modules/api-axios/api-axios-service';
+
+// All basic methods work the same!
+```

package/src/modules-repository/api-axios/README.md

@@ -0,0 +1,304 @@
+# API Axios Module
+
+Advanced HTTP client module for KIMU Framework based on the **Axios** library.
+
+## Overview
+
+The `api-axios` module provides an enhanced HTTP client with advanced features like interceptors, automatic retries, request cancellation, progress tracking, and response caching.
+
+## Key Features
+
+### ✨ Advanced Features Over api-core
+
+1. **Request/Response Interceptors**
+   - Modify requests before they are sent
+   - Transform responses before they reach your code
+   - Handle errors globally
+
+2. **Automatic Retry Logic**
+   - Configurable retry attempts
+   - Exponential backoff strategy
+   - Retry only on specific error conditions
+
+3. **Request Cancellation**
+   - Cancel pending requests
+   - Avoid memory leaks from unmounted components
+   - Manage concurrent requests
+
+4. **Progress Tracking**
+   - Upload progress callbacks
+   - Download progress callbacks
+   - Real-time feedback for large transfers
+
+5. **Response Caching**
+   - Cache GET requests
+   - Configurable TTL (Time To Live)
+   - Reduce network traffic and improve performance
+
+6. **Better Error Handling**
+   - Standardized error format
+   - Original error preservation
+   - Error interceptors for global handling
+
+#### 📋 Feature Comparison: api-core vs api-axios
+
+| Funzione                      | api-core | api-axios |
+|-------------------------------|:--------:|:---------:|
+| HTTP Methods                  |    ✅    |    ✅     |
+| Query Parameters              |    ✅    |    ✅     |
+| Custom Headers                |    ✅    |    ✅     |
+| Timeout                       |    ✅    |    ✅     |
+| Request Interceptors          |    ❌    |    ✅     |
+| Response Interceptors         |    ❌    |    ✅     |
+| Error Interceptors            |    ❌    |    ✅     |
+| Automatic Retry               |    ❌    |    ✅     |
+| Request Cancellation          |    ❌    |    ✅     |
+| Progress Tracking             |    ❌    |    ✅     |
+| Response Caching              |    ❌    |    ✅     |
+| Bundle Size                   |  ~2KB    |  ~15KB    |
+| Dependencies                  |    0     |  axios    |
+
+**Legenda:** ✅ = supportato, ❌ = non supportato
+
+## Installation
+
+The module is already part of KIMU-Core. To use it:
+
+```bash
+npm install axios
+```
+
+## Basic Usage
+
+### Import the Service
+
+```typescript
+import { apiAxiosService } from '../../modules/api-axios/api-axios-service';
+```
+
+### Simple GET Request
+
+```typescript
+const response = await apiAxiosService.get('https://api.example.com/data');
+console.log(response.data);
+```
+
+### POST Request with Data
+
+```typescript
+const response = await apiAxiosService.post(
+  'https://api.example.com/users',
+  { name: 'John', email: 'john@example.com' }
+);
+console.log(response.data);
+```
+
+## Advanced Features
+
+### Request with Retry
+
+```typescript
+const response = await apiAxiosService.request(
+  'GET',
+  'https://api.example.com/data',
+  null,
+  {
+    retries: 3,           // Retry up to 3 times
+    retryDelay: 1000      // Start with 1 second delay (exponential backoff)
+  }
+);
+```
+
+### Cached GET Request
+
+```typescript
+// First call - fetches from server
+const response1 = await apiAxiosService.get(
+  'https://api.example.com/data',
+  { useCache: true }
+);
+
+// Second call - returns cached data (if within TTL)
+const response2 = await apiAxiosService.get(
+  'https://api.example.com/data',
+  { useCache: true }
+);
+```
+
+### Configure Cache TTL
+
+```typescript
+// Set cache to expire after 10 minutes
+apiAxiosService.setCacheTTL(10 * 60 * 1000);
+
+// Clear all cached data
+apiAxiosService.clearCache();
+```
+
+### Request with Progress Tracking
+
+```typescript
+const response = await apiAxiosService.post(
+  'https://api.example.com/upload',
+  formData,
+  {
+    onUploadProgress: (event) => {
+      const percentComplete = Math.round((event.loaded * 100) / event.total);
+      console.log(`Upload: ${percentComplete}%`);
+    },
+    onDownloadProgress: (event) => {
+      const percentComplete = Math.round((event.loaded * 100) / event.total);
+      console.log(`Download: ${percentComplete}%`);
+    }
+  }
+);
+```
+
+### Request Cancellation
+
+```typescript
+// Create a cancel token
+const cancelToken = apiAxiosService.createCancelToken();
+
+// Make a request with the cancel token
+const requestPromise = apiAxiosService.get(
+  'https://api.example.com/large-data',
+  {
+    axiosConfig: {
+      cancelToken: cancelToken.token
+    }
+  }
+);
+
+// Cancel the request if needed
+cancelToken.cancel('User cancelled the request');
+```
+
+### Request Interceptor
+
+```typescript
+// Add authentication token to all requests
+apiAxiosService.addRequestInterceptor(async (config) => {
+  const token = await getAuthToken();
+  config.headers = config.headers || {};
+  config.headers['Authorization'] = `Bearer ${token}`;
+  return config;
+});
+```
+
+### Response Interceptor
+
+```typescript
+// Transform all responses
+apiAxiosService.addResponseInterceptor(async (response) => {
+  console.log('Response received:', response.status);
+  // You can modify the response here
+  return response;
+});
+```
+
+### Error Interceptor
+
+```typescript
+// Handle errors globally
+apiAxiosService.addErrorInterceptor(async (error) => {
+  if (error.status === 401) {
+    console.log('Unauthorized - redirecting to login');
+    // Redirect to login page
+  }
+});
+```
+
+## Migration from api-core
+
+The `api-axios` module maintains the same interface as `api-core` for basic operations, making migration simple:
+
+```typescript
+// Before (api-core)
+import { apiCoreService } from '../../modules/api-core/api-core-service';
+const response = await apiCoreService.get('https://api.example.com/data');
+
+// After (api-axios) - same interface!
+import { apiAxiosService } from '../../modules/api-axios/api-axios-service';
+const response = await apiAxiosService.get('https://api.example.com/data');
+```
+
+## When to Use api-axios vs api-core
+
+### Use **api-core** when:
+- You need a minimal, zero-dependency solution
+- Your requests are simple and don't need advanced features
+- Bundle size is critical
+- You want maximum control over the HTTP implementation
+
+### Use **api-axios** when:
+- You need request/response interceptors
+- You want automatic retry logic
+- You need request cancellation
+- You want upload/download progress tracking
+- Response caching would improve performance
+- You're building a complex application with many API calls
+
+## Performance Considerations
+
+- **Bundle Size**: Axios adds ~13KB (minified + gzipped) to your bundle
+- **Memory**: Caching consumes memory - use `clearCache()` periodically
+- **Network**: Retries increase network traffic - use wisely
+
+## Error Handling
+
+All errors are transformed to the standard `ApiError` format:
+
+```typescript
+try {
+  const response = await apiAxiosService.get('https://api.example.com/data');
+} catch (error: ApiError) {
+  console.error('Status:', error.status);
+  console.error('Message:', error.message);
+  console.error('Data:', error.data);
+  console.error('Original:', error.originalError);
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with generic types:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const response = await apiAxiosService.get<User>('https://api.example.com/user/1');
+// response.data is typed as User
+console.log(response.data.name);
+```
+
+## Best Practices
+
+1. **Use interceptors for cross-cutting concerns** (auth, logging, error handling)
+2. **Enable caching for static or slowly-changing data**
+3. **Use retry logic for non-critical requests**
+4. **Cancel requests when components unmount**
+5. **Track progress for large file uploads/downloads**
+6. **Set appropriate timeouts** for different types of requests
+7. **Clear cache periodically** to manage memory
+
+## Dependencies
+
+- `axios`: ^1.6.0 (peer dependency)
+
+## License
+
+This module is part of KIMU Framework and follows the same license (MPL-2.0).
+
+## Author
+
+**UnicòVerso** - Marco Di Pasquale
+
+## Related
+
+- [api-core](../api-core/README.md) - Minimal native HTTP client
+- [KIMU Framework](https://github.com/UnicoVerso/kimu-core)