kimu-core 0.4.1 → 0.5.0

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

@@ -1,192 +1,192 @@
-# KIMU API Core Module - Quick Reference
-
-## Installation
-```bash
-# Using kimu-cli (when available)
-kimu install module api-core
-
-# Manual installation
-# Copy src/modules/api-core to your project
-```
-
-## Quick Start
-
-```typescript
-import { apiCoreService } from './modules/api-core/api-core-service';
-
-// Configure
-apiCoreService.configure({
-  baseURL: 'https://api.example.com',
-  timeout: 10000,
-  headers: {
-    'Authorization': 'Bearer YOUR_TOKEN'
-  }
-});
-
-// Make requests
-const users = await apiCoreService.get('/users');
-const newUser = await apiCoreService.post('/users', { name: 'Mario' });
-const updated = await apiCoreService.patch('/users/1', { age: 30 });
-await apiCoreService.delete('/users/1');
-```
-
-## Key Features
-- ✅ **Zero dependencies** - Based on native fetch
-- ✅ **Lightweight** - ~2KB minified
-- ✅ **TypeScript-first** - Complete type safety
-- ✅ **Interceptors** - Request/Response/Error hooks
-- ✅ **Timeout** - Configurable request timeout
-- ✅ **Cancellation** - AbortController support
-- ✅ **Query params** - Automatic serialization
-- ✅ **Multiple formats** - JSON, text, blob, arraybuffer
-
-## API Methods
-- `get<T>(url, options?)` - GET request
-- `post<T>(url, data, options?)` - POST request
-- `put<T>(url, data, options?)` - PUT request
-- `patch<T>(url, data, options?)` - PATCH request
-- `delete<T>(url, options?)` - DELETE request
-- `request<T>(url, options)` - Generic request
-
-## Configuration Options
-```typescript
-interface ApiConfig {
-  baseURL?: string;
-  timeout?: number;
-  headers?: Record<string, string>;
-  requestInterceptor?: (config) => config;
-  responseInterceptor?: (response) => response;
-  errorInterceptor?: (error) => error;
-}
-```
-
-## Request Options
-```typescript
-interface ApiRequestOptions {
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  headers?: Record<string, string>;
-  body?: any;
-  params?: Record<string, string | number | boolean>;
-  timeout?: number;
-  responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
-  credentials?: RequestCredentials;
-  cache?: RequestCache;
-  signal?: AbortSignal;
-}
-```
-
-## Response Structure
-```typescript
-interface ApiResponse<T> {
-  data: T;
-  status: number;
-  statusText: string;
-  headers: Headers;
-  raw: Response;
-}
-```
-
-## Error Structure
-```typescript
-interface ApiError {
-  message: string;
-  status?: number;
-  statusText?: string;
-  data?: any;
-  originalError: Error;
-}
-```
-
-## Common Patterns
-
-### Authentication
-```typescript
-apiCoreService.configure({
-  requestInterceptor: (config) => {
-    const token = getToken();
-    config.headers = {
-      ...config.headers,
-      'Authorization': `Bearer ${token}`
-    };
-    return config;
-  }
-});
-```
-
-### Error Handling
-```typescript
-try {
-  const response = await apiCoreService.get('/data');
-} catch (error) {
-  if (error.status === 401) {
-    // Handle unauthorized
-  } else if (error.status >= 500) {
-    // Handle server error
-  }
-}
-```
-
-### Timeout & Cancellation
-```typescript
-// With timeout
-await apiCoreService.get('/data', { timeout: 3000 });
-
-// With AbortController
-const controller = new AbortController();
-apiCoreService.get('/data', { signal: controller.signal });
-setTimeout(() => controller.abort(), 2000);
-```
-
-## Integration with KIMU
-
-```typescript
-import { KimuComponentElement } from '@kimu/core';
-import { KimuModuleManager } from '@kimu/core';
-
-export class MyComponent extends KimuComponentElement {
-  private api: any;
-
-  async onInit() {
-    this.api = KimuModuleManager.getInstance().getService('api-core');
-    await this.loadData();
-  }
-
-  async loadData() {
-    const response = await this.api.get('/data');
-    this.data = response.data;
-    this.onRender();
-  }
-}
-```
-
-## Files Structure
-```
-api-core/
-├── api-core-service.ts   # Main service implementation
-├── interfaces.ts          # TypeScript type definitions
-├── module.ts              # Module class and exports
-├── index.ts               # Main entry point
-├── examples.ts            # Usage examples
-├── README.md              # Complete documentation
-├── CHANGELOG.md           # Version history
-└── QUICK-REFERENCE.md     # This file
-```
-
-## Performance
-- Bundle size: ~2KB minified
-- First request: ~5ms (after DNS)
-- Subsequent requests: ~2ms (with HTTP/2)
-- Zero overhead compared to native fetch
-
-## Browser Support
-- Chrome/Edge: ✅ 90+
-- Firefox: ✅ 88+
-- Safari: ✅ 14+
-- Opera: ✅ 76+
-
-## License
-MPL-2.0 (part of KIMU-Core)
-
-## Support
-- GitHub: [kimu-core/issues](https://github.com/UnicoVerso/kimu-core/issues)
-- Docs: [kimu-docs](https://github.com/UnicoVerso/kimu-docs)
+# KIMU API Core Module - Quick Reference
+
+## Installation
+```bash
+# Using kimu-cli (when available)
+kimu install module api-core
+
+# Manual installation
+# Copy src/modules/api-core to your project
+```
+
+## Quick Start
+
+```typescript
+import { apiCoreService } from './modules/api-core/api-core-service';
+
+// Configure
+apiCoreService.configure({
+  baseURL: 'https://api.example.com',
+  timeout: 10000,
+  headers: {
+    'Authorization': 'Bearer YOUR_TOKEN'
+  }
+});
+
+// Make requests
+const users = await apiCoreService.get('/users');
+const newUser = await apiCoreService.post('/users', { name: 'Mario' });
+const updated = await apiCoreService.patch('/users/1', { age: 30 });
+await apiCoreService.delete('/users/1');
+```
+
+## Key Features
+- ✅ **Zero dependencies** - Based on native fetch
+- ✅ **Lightweight** - ~2KB minified
+- ✅ **TypeScript-first** - Complete type safety
+- ✅ **Interceptors** - Request/Response/Error hooks
+- ✅ **Timeout** - Configurable request timeout
+- ✅ **Cancellation** - AbortController support
+- ✅ **Query params** - Automatic serialization
+- ✅ **Multiple formats** - JSON, text, blob, arraybuffer
+
+## API Methods
+- `get<T>(url, options?)` - GET request
+- `post<T>(url, data, options?)` - POST request
+- `put<T>(url, data, options?)` - PUT request
+- `patch<T>(url, data, options?)` - PATCH request
+- `delete<T>(url, options?)` - DELETE request
+- `request<T>(url, options)` - Generic request
+
+## Configuration Options
+```typescript
+interface ApiConfig {
+  baseURL?: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+  requestInterceptor?: (config) => config;
+  responseInterceptor?: (response) => response;
+  errorInterceptor?: (error) => error;
+}
+```
+
+## Request Options
+```typescript
+interface ApiRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  headers?: Record<string, string>;
+  body?: any;
+  params?: Record<string, string | number | boolean>;
+  timeout?: number;
+  responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+  credentials?: RequestCredentials;
+  cache?: RequestCache;
+  signal?: AbortSignal;
+}
+```
+
+## Response Structure
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  raw: Response;
+}
+```
+
+## Error Structure
+```typescript
+interface ApiError {
+  message: string;
+  status?: number;
+  statusText?: string;
+  data?: any;
+  originalError: Error;
+}
+```
+
+## Common Patterns
+
+### Authentication
+```typescript
+apiCoreService.configure({
+  requestInterceptor: (config) => {
+    const token = getToken();
+    config.headers = {
+      ...config.headers,
+      'Authorization': `Bearer ${token}`
+    };
+    return config;
+  }
+});
+```
+
+### Error Handling
+```typescript
+try {
+  const response = await apiCoreService.get('/data');
+} catch (error) {
+  if (error.status === 401) {
+    // Handle unauthorized
+  } else if (error.status >= 500) {
+    // Handle server error
+  }
+}
+```
+
+### Timeout & Cancellation
+```typescript
+// With timeout
+await apiCoreService.get('/data', { timeout: 3000 });
+
+// With AbortController
+const controller = new AbortController();
+apiCoreService.get('/data', { signal: controller.signal });
+setTimeout(() => controller.abort(), 2000);
+```
+
+## Integration with KIMU
+
+```typescript
+import { KimuComponentElement } from '@kimu/core';
+import { KimuModuleManager } from '@kimu/core';
+
+export class MyComponent extends KimuComponentElement {
+  private api: any;
+
+  async onInit() {
+    this.api = KimuModuleManager.getInstance().getService('api-core');
+    await this.loadData();
+  }
+
+  async loadData() {
+    const response = await this.api.get('/data');
+    this.data = response.data;
+    this.onRender();
+  }
+}
+```
+
+## Files Structure
+```
+api-core/
+├── api-core-service.ts   # Main service implementation
+├── interfaces.ts          # TypeScript type definitions
+├── module.ts              # Module class and exports
+├── index.ts               # Main entry point
+├── examples.ts            # Usage examples
+├── README.md              # Complete documentation
+├── CHANGELOG.md           # Version history
+└── QUICK-REFERENCE.md     # This file
+```
+
+## Performance
+- Bundle size: ~2KB minified
+- First request: ~5ms (after DNS)
+- Subsequent requests: ~2ms (with HTTP/2)
+- Zero overhead compared to native fetch
+
+## Browser Support
+- Chrome/Edge: ✅ 90+
+- Firefox: ✅ 88+
+- Safari: ✅ 14+
+- Opera: ✅ 76+
+
+## License
+MPL-2.0 (part of KIMU-Core)
+
+## Support
+- GitHub: [kimu-core/issues](https://github.com/UnicoVerso/kimu-core/issues)
+- Docs: [kimu-docs](https://github.com/UnicoVerso/kimu-docs)