@dcc-bs/communication.bs.js 0.0.4 → 0.1.0

package/README.md

@@ -2,28 +2,38 @@
 
 A TypeScript library for type-safe API communication with built-in error handling, schema validation, and Vue composables. Designed for modern web applications that require robust HTTP request handling with automatic response parsing and validation.
 
-This library expects the API to follow a consistent error response format to leverage its full capabilities. The error responses should include fields such as `errorId`, `statusCode`, and an optional `debugMessage` to ensure seamless integration with the library's error handling mechanisms.
+This library expects the API to follow a consistent error response format to leverage its full capabilities. The error responses should include fields such as `errorId`, `status`, and an optional `debugMessage` to ensure seamless integration with the library's error handling mechanisms.
 ```json
 { 
     "errorId": "string",          // Unique identifier for the error type
-    "statusCode": 400,            // HTTP status code associated with the error
+    "status": 400,                // HTTP status code associated with the error
     "debugMessage": "string"      // Optional detailed debug message for developers
 }
 ```
 
-![GitHub License](https://img.shields.io/github/license/DCC-BS/communication.bs.js) [![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev) ![NPM Version](https://img.shields.io/npm/v/%40dcc-bs%2Fcommunication.bs.js)
+![GitHub License](https://img.shields.io/github/license/DCC-BS/communication.bs.js)
+[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)
+[![NPM Version](https://img.shields.io/npm/v/%40dcc-bs%2Fcommunication.bs.js)](https://www.npmjs.com/package/@dcc-bs/communication.bs.js)
 
 
 ## Features
 
-- **Type-Safe API Requests**: Full TypeScript support with type inference
+- **Type-Safe API Requests**: Full TypeScript support with type inference and overloaded function signatures
+- **Factory Pattern**: Create multiple API clients with different configurations
 - **Schema Validation**: Built-in Zod schema validation for API responses
+- **Advanced Configuration**: Flexible fetcher builder with extensive configuration options
 - **Error Handling**: Standardized API error responses with custom error types
-- **Streaming Support**: Handle streaming API responses with ease
+- **Streaming Support**: Handle streaming API responses with ease including async iteration
 - **Vue Composables**: Ready-to-use Vue 3 composables for reactive API calls
 - **Multiple Response Types**: Support for JSON, text, and streaming responses
+- **Request Hooks**: Intercept requests with beforeRequest, afterResponse, and onError hooks
+- **Automatic Retries**: Configurable retry logic with exponential backoff
+- **Request Deduplication**: Prevent duplicate simultaneous requests automatically
+- **Timeout Management**: Set request timeouts with automatic abort
+- **Authentication**: Built-in support for Bearer tokens and Basic authentication
 - **Abort Support**: Request cancellation with AbortController integration
 - **FormData Support**: Automatic handling of multipart/form-data requests
+- **Debug Mode**: Optional request/response logging for development
 
 ## Technology Stack
 
@@ -49,6 +59,48 @@ npm install @dcc-bs/communication.bs.js
 pnpm add @dcc-bs/communication.bs.js
 ```
 
+## Quick Start
+
+### Simple Usage (Recommended for most cases)
+
+The library provides ready-to-use functions for immediate use:
+
+```typescript
+import { apiFetch, isApiError } from '@dcc-bs/communication.bs.js';
+
+// Simple API call
+const response = await apiFetch<{ message: string }>('/api/hello');
+
+if (isApiError(response)) {
+  console.error('Error:', response.errorId);
+} else {
+  console.log(response.message); // Fully typed!
+}
+```
+
+### Advanced Usage with Factory Pattern
+
+For advanced configuration, create custom API clients:
+
+```typescript
+import { createApiClient, createFetcherBuilder } from '@dcc-bs/communication.bs.js';
+
+// Create a custom fetcher with configuration
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .addHeader('X-API-Key', 'your-api-key')
+  .setRequestTimeout(5000)
+  .setRetries(3)
+  .enableDebug()
+  .build();
+
+// Create an API client with the custom fetcher
+const apiClient = createApiClient(fetcher);
+
+// Use the client
+const user = await apiClient.apiFetch('/users/1');
+```
+
 ## Usage
 
 ### Basic API Fetch
@@ -173,6 +225,222 @@ await for(const text of textResults) {
 }
 ```
 
+## Advanced Configuration
+
+The `createFetcherBuilder()` function provides a fluent API for configuring custom HTTP clients with advanced features.
+
+### Base URL and Headers
+
+```typescript
+import { createFetcherBuilder, createApiClient } from '@dcc-bs/communication.bs.js';
+
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com/v1')
+  .addHeader('X-API-Key', 'your-api-key')
+  .addHeader('X-Custom-Header', 'value')
+  .build();
+
+const client = createApiClient(fetcher);
+
+// Now all requests use the base URL and headers
+const user = await client.apiFetch('/users/1'); // GET https://api.example.com/v1/users/1
+```
+
+### Authentication
+
+```typescript
+// Bearer Token Authentication
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .setAuth({
+    type: 'bearer',
+    token: 'your-jwt-token'
+  })
+  .build();
+
+// Basic Authentication
+const fetcher = createFetcherBuilder()
+  .setAuth({
+    type: 'basic',
+    username: 'user',
+    password: 'pass'
+  })
+  .build();
+```
+
+### Retries and Timeouts
+
+```typescript
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .setRequestTimeout(5000) // 5 second timeout
+  .setRetries(
+    3, // Max 3 retries
+    1000, // Initial delay in ms
+    [500, 502, 503, 504], // Retry on these status codes
+  )
+  .build();
+```
+
+### Request/Response Hooks
+
+```typescript
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .setBeforeRequest((url, options) => {
+      console.log(`Sending request to: ${url}`);
+  })
+  .setAfterResponse((response) => {
+    // Process response after receiving
+    console.log(`Received response with status: ${response.status}`);
+    return response;
+  })
+  .setOnError((error) => {
+    console.error('Request failed:', error);
+  })
+  .build();
+```
+
+### Query Parameters and CORS
+
+```typescript
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .setQueryParams({ version: '1.0', format: 'json' })
+  .setCredentials('include') // 'omit' | 'same-origin' | 'include'
+  .setMode('cors') // 'cors' | 'no-cors' | 'same-origin'
+  .setCache('no-cache') // any valid RequestCache value
+  .build();
+```
+
+### Request Deduplication
+
+Prevent duplicate simultaneous requests to the same endpoint:
+
+```typescript
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .enableDeduplication()
+  .build();
+
+const client = createApiClient(fetcher);
+
+// These three simultaneous requests will only trigger one actual HTTP request
+const [user1, user2, user3] = await Promise.all([
+  client.apiFetch('/users/1'),
+  client.apiFetch('/users/1'),
+  client.apiFetch('/users/1')
+]);
+```
+
+### Debug Mode
+
+Enable detailed logging for development:
+
+```typescript
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com')
+  .enableDebug() // Logs all requests and responses
+  .build();
+```
+
+### Complete Example
+
+```typescript
+import { createFetcherBuilder, createApiClient } from '@dcc-bs/communication.bs.js';
+
+const fetcher = createFetcherBuilder()
+  .setBaseURL('https://api.example.com/v1')
+  .setAuth({ type: 'bearer', token: process.env.API_TOKEN })
+  .addHeader('X-App-Version', '1.0.0')
+  .setRequestTimeout(10000)
+  .setRetries({ maxRetries: 3, retryDelay: 1000 })
+  .setBeforeRequest((url, options) => {
+    console.log(`→ ${options.method || 'GET'} ${url}`);
+    return { url, options };
+  })
+  .setAfterResponse((response) => {
+    console.log(`← ${response.status} ${response.url}`);
+    return response;
+  })
+  .enableDeduplication()
+  .enableDebug()
+  .build();
+
+const apiClient = createApiClient(fetcher);
+
+export { apiClient };
+```
+
+## Framework Integration
+
+### Nuxt 3 Plugin
+
+Create a Nuxt plugin to provide the API client throughout your application:
+
+**`plugins/api.ts`**:
+```typescript
+import { createFetcherBuilder, createApiClient } from '@dcc-bs/communication.bs.js';
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig();
+  
+  // Create a configured fetcher
+  const fetcher = createFetcherBuilder()
+    .setBaseURL(config.public.apiBaseUrl)
+    .setAuth({
+      type: 'bearer',
+      token: config.public.apiToken
+    })
+    .setRequestTimeout(10000)
+    .setRetries(2, 1000)
+    .enableDebug(!!import.meta.dev)
+    .build();
+
+  // Create the API client
+  const apiClient = createApiClient(fetcher);
+
+  // Provide the client to the app
+  return {
+    provide: {
+      api: apiClient
+    }
+  };
+});
+```
+
+**Composable to access the API client**:
+```ts
+// composables/useApi.ts
+export function useApi() {
+    const { $api } = useNuxtApp();
+    return $api;
+}
+```
+
+**Usage in pages/components**:
+```vue
+<script setup lang="ts">
+import { z } from 'zod';
+
+const { apiFetch } = useApi();
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email()
+});
+
+// Use the provided API client
+const response = await apiFetch('/users/1', {
+  schema: UserSchema
+});
+
+if (!isApiError(response)) {
+  console.log(response.name); // Fully typed!
+}
+</script>
+```
 ## Development
 
 ### Setup
@@ -214,19 +482,32 @@ bun run check
 
 ```
 src/
-├── apiFetch.ts              # Core API fetch functions
+├── apiFetch.ts              # Default API fetch function exports
+├── apiFetchFactory.ts       # API client factory
+├── apiFetchUtils.ts         # Utility functions (isApiError, error extraction)
+├── fetcherFactory.ts        # Fetcher builder with advanced configuration
 ├── index.ts                 # Main entry point
 ├── composables/             # Vue composables
 │   ├── apiFetch.composable.ts
 │   └── useApiFetchWithSchema.ts
-└── models/                  # TypeScript models
-    ├── api_error.ts
-    ├── api_error_response.ts
-    └── api_fetch_options.ts
+├── types/                   # TypeScript type definitions
+│   ├── api_client.ts        # ApiClient, ApiFetchFunction, ApiResponse types
+│   ├── api_error.ts         # ApiError class
+│   ├── api_error_response.ts
+│   ├── api_fetch_options.ts # Request options interfaces
+│   ├── auth.ts              # Authentication configuration types
+│   ├── fetcher.ts           # Fetcher function type
+│   ├── fetcher_builder_options.ts
+│   └── hooks.ts             # Hook function types
+└── utils/                   # Utility modules
 tests/                       # Test files
 ├── apiFetch.test.ts
+├── apiFetchFactory.test.ts
 ├── apiFetchTextMany.test.ts
+├── apiFetchUtils.test.ts
 ├── apiStreamFetch.test.ts
+├── fetcherFactory.test.ts
+├── integration.test.ts
 └── isApiError.test.ts
 ```
 
@@ -237,12 +518,32 @@ The library provides standardized error handling with predefined error types:
 - `unexpected_error`: Unexpected API response format
 - `fetch_failed`: Network or fetch operation failure
 - `request_aborted`: Request was cancelled via AbortController
+- `schema_validation_failed`: Response data doesn't match the provided Zod schema
 
 All errors follow the `ApiError` structure with:
 - `errorId`: Unique error identifier
-- `statusCode`: HTTP status code
+- `status`: HTTP status code
 - `debugMessage`: Optional debug information
 
+### Type Guard
+
+Use the `isApiError()` function to check if a response is an error:
+
+```typescript
+import { apiFetch, isApiError } from '@dcc-bs/communication.bs.js';
+
+const response = await apiFetch('/api/data');
+
+if (isApiError(response)) {
+  // response is ApiError
+  console.error(`Error ${response.errorId}: ${response.debugMessage}`);
+  console.error(`Status: ${response.status}`);
+} else {
+  // response is your data type
+  console.log(response);
+}
+```
+
 ## License
 
 [MIT](LICENSE) © Data Competence Center Basel-Stadt