1000fetches 0.2.0 → 0.2.2

package/docs/MIGRATION.md

@@ -0,0 +1,719 @@
+# Migration Guide
+
+This guide helps you migrate from other HTTP clients to 1000fetches.
+
+## Table of Contents
+
+- [From Axios](#from-axios)
+- [From Fetch API](#from-fetch-api)
+- [From Node-Fetch](#from-node-fetch)
+- [From Ky](#from-ky)
+- [From Got](#from-got)
+- [Common Migration Patterns](#common-migration-patterns)
+
+## From Axios
+
+### Basic Setup
+
+**Axios:**
+
+```typescript
+import axios from 'axios'
+
+const api = axios.create({
+  baseURL: 'https://api.example.com',
+  timeout: 10_000,
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+```
+
+**1000fetches:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  timeout: 10_000,
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+```
+
+### HTTP Methods
+
+**Axios:**
+
+```typescript
+// GET request
+const usersResponse = await api.get('/users')
+const users = usersResponse.data
+
+// POST request
+const createdUserResponse = await api.post('/users', {
+  name: 'John',
+  email: 'john@example.com',
+})
+
+// With query parameters
+const filteredUsersResponse = await api.get('/users', {
+  params: { page: 1, limit: 10 },
+})
+```
+
+**1000fetches:**
+
+```typescript
+const usersResponse = await api.get('/users')
+const users = usersResponse.data
+
+const createdUserResponse = await api.post('/users', {
+  name: 'John',
+  email: 'john@example.com',
+})
+
+const filteredUsersResponse = await api.get('/users', {
+  params: { page: 1, limit: 10 },
+})
+```
+
+### Middleware
+
+**Axios:**
+
+```typescript
+api.interceptors.request.use(
+  config => {
+    config.headers.Authorization = `Bearer ${getToken()}`
+    return config
+  },
+  error => Promise.reject(error)
+)
+
+api.interceptors.response.use(
+  response => response,
+  error => {
+    if (error.response?.status === 401) {
+      // Handle unauthorized
+    }
+    return Promise.reject(error)
+  }
+)
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  onRequestMiddleware: async context => {
+    context.headers.set('Authorization', `Bearer ${getToken()}`)
+    return context
+  },
+  onResponseMiddleware: async response => {
+    if (response.status === 401) {
+      // Handle unauthorized
+    }
+    return response
+  },
+})
+```
+
+### Error Handling
+
+**Axios:**
+
+```typescript
+try {
+  const response = await api.get('/users/1')
+} catch (error) {
+  if (axios.isAxiosError(error)) {
+    if (error.response) {
+      console.log(error.response.status)
+      console.log(error.response.data)
+    } else if (error.request) {
+      console.log('Network error')
+    }
+  }
+}
+```
+
+**1000fetches:**
+
+```typescript
+import { HttpError, NetworkError } from '1000fetches'
+
+try {
+  const response = await api.get('/users/1')
+} catch (error) {
+  if (error instanceof HttpError) {
+    console.log(error.status)
+    console.log(error.data)
+    console.log(`Request: ${error.method} ${error.url}`)
+  } else if (error instanceof NetworkError) {
+    console.log('Network error')
+  }
+}
+```
+
+### Request Cancellation
+
+**Axios:**
+
+```typescript
+const source = axios.CancelToken.source()
+
+const response = await api.get('/users', {
+  cancelToken: source.token,
+})
+
+source.cancel('Request canceled')
+```
+
+**1000fetches:**
+
+```typescript
+const controller = new AbortController()
+
+const response = await api.get('/users', {
+  signal: controller.signal,
+})
+
+controller.abort()
+```
+
+### Retry Logic
+
+**Axios (with axios-retry):**
+
+```typescript
+import axiosRetry from 'axios-retry'
+
+axiosRetry(api, {
+  retries: 3,
+  retryDelay: axiosRetry.exponentialDelay,
+  retryCondition: axiosRetry.isNetworkOrIdempotentRequestError,
+})
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  retry: {
+    maxRetries: 3,
+    retryDelay: 300,
+    backoffFactor: 2,
+    retryStatusCodes: [408, 429, 500, 502, 503, 504],
+    retryNetworkErrors: true,
+  },
+})
+```
+
+## From Fetch API
+
+### Basic Usage
+
+**Fetch:**
+
+```typescript
+const response = await fetch('https://api.example.com/users', {
+  method: 'GET',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer token',
+  },
+})
+
+if (!response.ok) {
+  throw new Error(`HTTP error! status: ${response.status}`)
+}
+
+const users = await response.json()
+```
+
+**1000fetches:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+
+const response = await api.get('/users')
+const users = response.data
+```
+
+### POST Requests
+
+**Fetch:**
+
+```typescript
+const response = await fetch('https://api.example.com/users', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    name: 'John',
+    email: 'john@example.com',
+  }),
+})
+
+const user = await response.json()
+```
+
+**1000fetches:**
+
+```typescript
+const response = await api.post('/users', {
+  name: 'John',
+  email: 'john@example.com',
+})
+const user = response.data
+```
+
+### Error Handling
+
+**Fetch:**
+
+```typescript
+try {
+  const response = await fetch('/api/users/1')
+
+  if (!response.ok) {
+    const errorData = await response.json()
+    throw new Error(`${response.status}: ${errorData.message}`)
+  }
+
+  const user = await response.json()
+} catch (error) {
+  if (error instanceof TypeError) {
+    console.log('Network error')
+  } else {
+    console.log(error.message)
+  }
+}
+```
+
+**1000fetches:**
+
+```typescript
+import { HttpError, NetworkError } from '1000fetches'
+
+try {
+  const response = await api.get('/users/1')
+  const user = response.data
+} catch (error) {
+  if (error instanceof HttpError) {
+    console.log(`${error.status}: ${error.message}`)
+  } else if (error instanceof NetworkError) {
+    console.log('Network error')
+  }
+}
+```
+
+## From Node-Fetch
+
+### Basic Migration
+
+**Node-Fetch:**
+
+```typescript
+import fetch from 'node-fetch'
+
+const response = await fetch('https://api.example.com/users', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ name: 'John' }),
+})
+
+const data = await response.json()
+```
+
+**1000fetches:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+})
+
+const response = await api.post('/users', { name: 'John' })
+const data = response.data
+```
+
+### Timeout Handling
+
+**Node-Fetch:**
+
+```typescript
+import fetch from 'node-fetch'
+import AbortController from 'abort-controller'
+
+const controller = new AbortController()
+const timeout = setTimeout(() => controller.abort(), 5_000)
+
+try {
+  const response = await fetch(url, {
+    signal: controller.signal,
+  })
+} finally {
+  clearTimeout(timeout)
+}
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  timeout: 5_000,
+})
+
+const response = await api.get('/users')
+```
+
+## From Ky
+
+### Basic Setup
+
+**Ky:**
+
+```typescript
+import ky from 'ky'
+
+const api = ky.create({
+  prefixUrl: 'https://api.example.com',
+  timeout: 10_000,
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+```
+
+**1000fetches:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  timeout: 10_000,
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+```
+
+### Hooks (Middleware)
+
+**Ky:**
+
+```typescript
+const api = ky.create({
+  hooks: {
+    beforeRequest: [
+      request => {
+        request.headers.set('Authorization', `Bearer ${getToken()}`)
+      },
+    ],
+    afterResponse: [
+      (request, options, response) => {
+        if (response.status === 401) {
+          // Handle unauthorized
+        }
+      },
+    ],
+  },
+})
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  onRequestMiddleware: async context => {
+    context.headers.set('Authorization', `Bearer ${getToken()}`)
+    return context
+  },
+  onResponseMiddleware: async response => {
+    if (response.status === 401) {
+      // Handle unauthorized
+    }
+    return response
+  },
+})
+```
+
+### Retry Logic
+
+**Ky:**
+
+```typescript
+const api = ky.create({
+  retry: {
+    limit: 3,
+    methods: ['get'],
+    statusCodes: [408, 413, 429, 500, 502, 503, 504],
+  },
+})
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  retry: {
+    maxRetries: 3,
+    retryStatusCodes: [408, 413, 429, 500, 502, 503, 504],
+  },
+})
+```
+
+## From Got
+
+### Basic Usage
+
+**Got:**
+
+```typescript
+import got from 'got'
+
+const api = got.extend({
+  prefixUrl: 'https://api.example.com',
+  timeout: { request: 10_000 },
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+
+const users = await api.get('users').json()
+```
+
+**1000fetches:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  timeout: 10_000,
+  headers: {
+    Authorization: 'Bearer token',
+  },
+})
+
+const response = await api.get('/users')
+const users = response.data
+```
+
+### Hooks
+
+**Got:**
+
+```typescript
+const api = got.extend({
+  hooks: {
+    beforeRequest: [
+      options => {
+        options.headers.authorization = `Bearer ${getToken()}`
+      },
+    ],
+    afterResponse: [
+      response => {
+        if (response.statusCode === 401) {
+          // Handle unauthorized
+        }
+        return response
+      },
+    ],
+  },
+})
+```
+
+**1000fetches:**
+
+```typescript
+const api = createHttpClient({
+  onRequestMiddleware: async context => {
+    context.headers.set('Authorization', `Bearer ${getToken()}`)
+    return context
+  },
+  onResponseMiddleware: async response => {
+    if (response.status === 401) {
+      // Handle unauthorized
+    }
+    return response
+  },
+})
+```
+
+## Common Migration Patterns
+
+### Authentication
+
+**Before (various libraries):**
+
+```typescript
+// Axios
+api.defaults.headers.common['Authorization'] = `Bearer ${token}`
+
+// Fetch
+headers: { 'Authorization': `Bearer ${token}` }
+
+// Got
+headers: { 'authorization': `Bearer ${token}` }
+```
+
+**After (1000fetches):**
+
+```typescript
+const api = createHttpClient({
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+})
+
+// Or with middleware for dynamic tokens
+const apiWithDynamicAuth = createHttpClient({
+  onRequestMiddleware: async context => {
+    context.headers.set('Authorization', `Bearer ${await getToken()}`)
+    return context
+  },
+})
+```
+
+### Response Transformation
+
+**Before:**
+
+```typescript
+// Axios
+api.interceptors.response.use(response => {
+  return response.data.result
+})
+
+// Manual with fetch
+const response = await fetch('/api/users')
+const data = await response.json()
+return data.result
+```
+
+**After:**
+
+```typescript
+const api = createHttpClient({
+  onResponseMiddleware: async response => {
+    const data = response.data
+
+    return {
+      ...response,
+      data:
+        data && typeof data === 'object' && 'result' in data
+          ? data.result
+          : data,
+    }
+  },
+})
+```
+
+Response middleware is authoritative, like a full response interceptor. If it changes `status`, that changed status controls whether 1000fetches resolves or throws `HttpError`. Preserve `status` when you only want to transform response data.
+
+### Error Standardization
+
+**Before:**
+
+```typescript
+// Different error handling for each library
+try {
+  // ... request
+} catch (error) {
+  if (axios.isAxiosError(error)) {
+    // Axios specific
+  } else if (error instanceof TypeError) {
+    // Fetch network error
+  } else if (error instanceof got.HTTPError) {
+    // Got specific
+  }
+}
+```
+
+**After:**
+
+```typescript
+import { HttpError, NetworkError, TimeoutError } from '1000fetches'
+
+try {
+  // ... request
+} catch (error) {
+  if (error instanceof HttpError) {
+    // HTTP error with status, data, url, method
+  } else if (error instanceof NetworkError) {
+    // Network error
+  } else if (error instanceof TimeoutError) {
+    // Timeout error
+  }
+}
+```
+
+### Type Safety
+
+**Before:**
+
+```typescript
+// Manual typing
+interface User {
+  id: number
+  name: string
+}
+
+const response = await api.get<User>('/users/1')
+const user: User = response.data
+```
+
+**After:**
+
+```typescript
+import { z } from 'zod'
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+})
+
+const response = await api.get('/users/1').schema(UserSchema)
+// response.data is automatically typed and validated
+```
+
+## Migration Checklist
+
+- [ ] **Replace HTTP client import** with 1000fetches
+- [ ] **Update client configuration** (baseUrl, timeout, headers)
+- [ ] **Migrate interceptors** to request/response middleware
+- [ ] **Update error handling** to use structured error types
+- [ ] **Add schema validation** for better type safety
+- [ ] **Configure retry logic** if needed
+- [ ] **Update request cancellation** to use AbortController
+- [ ] **Test all API calls** to ensure compatibility
+- [ ] **Update TypeScript types** if using custom interfaces
+- [ ] **Review and update tests** to work with new client
+
+## Benefits After Migration
+
+✅ **Better Type Safety**: Automatic type inference and runtime validation
+✅ **Structured Errors**: Clear error types with context information
+✅ **Built-in Retry Logic**: No need for additional retry libraries
+✅ **Schema Validation**: Runtime validation with popular validation libraries
+✅ **Modern API**: Promise-based with async/await support
+✅ **Better Developer Experience**: Enhanced error messages with request context
+✅ **Consistent Interface**: Same API across different environments