1000fetches 0.2.0 → 0.2.2

package/docs/API.md

@@ -0,0 +1,754 @@
+# 1000fetches API Documentation
+
+## Table of Contents
+
+- [HttpClient](#httpclient)
+- [Configuration Options](#configuration-options)
+- [HTTP Methods](#http-methods)
+- [Response Methods](#response-methods)
+- [Schema Validation](#schema-validation)
+- [Error Handling](#error-handling)
+- [Middleware](#middleware)
+- [Retry Logic](#retry-logic)
+- [Type Safety](#type-safety)
+
+## HttpClient
+
+The main HTTP client that provides a fluent API for making HTTP requests with optional schema validation.
+
+### Constructor
+
+```typescript
+createHttpClient(config?: HttpClientConfig)
+```
+
+**Parameters:**
+
+- `config` (optional): Configuration options for the HTTP client
+
+**Example:**
+
+```typescript
+import { createHttpClient } from '1000fetches'
+
+const client = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  timeout: 5_000,
+  headers: {
+    Authorization: 'Bearer your-token',
+  },
+})
+
+// Or use the shortcut instance
+import http from '1000fetches/http'
+```
+
+`1000fetches/http` intentionally exposes only a default export. Use the root `1000fetches` entrypoint for `createHttpClient`, error classes, and public types.
+
+## Configuration Options
+
+### HttpClientConfig
+
+```typescript
+interface HttpClientConfig {
+  baseUrl?: string
+  timeout?: number
+  headers?: HttpHeaders
+  retry?: RetryOptions | boolean
+  schemaValidator?: SchemaValidator
+  fetch?: CustomFetch
+  serializeBody?: SerializeBody
+  serializeParams?: SerializeParams
+  onRequestMiddleware?: <TBody = unknown>(
+    context: RequestContext<TBody>
+  ) => RequestContext<TBody> | Promise<RequestContext<TBody>>
+  onResponseMiddleware?: (
+    response: ResponseType<unknown>
+  ) => ResponseType<unknown> | Promise<ResponseType<unknown>>
+}
+```
+
+**Properties:**
+
+- **`baseUrl`** (optional): Base URL for all requests. Must be an absolute URL or a root-relative path starting with `/`. Native Node.js `fetch` still requires absolute URLs unless you provide a custom `fetch` implementation.
+- **`timeout`** (optional): Request timeout in milliseconds (default: 30_000)
+- **`headers`** (optional): Default headers to include with every request
+- **`retry`** (optional): Opt-in retry configuration for failed requests. Use `true` for the default retry policy, `false` to disable retry, or a `RetryOptions` object for custom retry behavior.
+- **`schemaValidator`** (optional): Custom schema validator
+- **`fetch`** (optional): Custom fetch implementation
+- **`serializeBody`** (optional): Custom body serializer
+- **`serializeParams`** (optional): Custom params serializer
+- **`onRequestMiddleware`** (optional): Request middleware for modifying requests
+- **`onResponseMiddleware`** (optional): Response middleware for modifying responses
+
+### RetryOptions
+
+```typescript
+interface RetryOptions {
+  maxRetries?: number
+  retryDelay?: number
+  backoffFactor?: number
+  retryStatusCodes?: number[]
+  retryNetworkErrors?: boolean
+  maxRetryDelay?: number
+  retryMethods?: readonly HttpMethod[]
+  retryUnsafeMethods?: boolean
+  jitter?:
+    | 'none'
+    | 'full'
+    | 'equal'
+    | ((delay: number, retryCount: number) => number)
+  respectRetryAfter?: boolean
+  onRetry?: (event: RetryEvent) => void | Promise<void>
+  shouldRetry?: (
+    error: Error,
+    retryCount: number,
+    context: RetryContext
+  ) => boolean | Promise<boolean>
+}
+```
+
+Retries are disabled by default. Set client `retry`, request `retry: true`, or per-request retry settings to enable them. The built-in policy retries idempotent methods by default and skips one-shot stream bodies.
+
+**Properties:**
+
+- **`maxRetries`**: Maximum number of retry attempts when retries are enabled (default: 3)
+- **`retryDelay`**: Initial delay between retries in milliseconds when retries are enabled (default: 300)
+- **`backoffFactor`**: Exponential backoff multiplier (default: 2)
+- **`retryStatusCodes`**: HTTP status codes that trigger retries when retries are enabled (default: [408, 429, 500, 502, 503, 504])
+- **`retryNetworkErrors`**: Whether to retry on network errors when retries are enabled (default: true)
+- **`maxRetryDelay`**: Maximum delay between retries when retries are enabled (default: 30_000)
+- **`retryMethods`**: Methods eligible for built-in retries (default: GET, HEAD, OPTIONS, PUT, DELETE)
+- **`retryUnsafeMethods`**: Allow built-in retries for methods outside `retryMethods` (default: false)
+- **`jitter`**: Optional jitter strategy for exponential backoff delays (default: 'none')
+- **`respectRetryAfter`**: Honor `Retry-After` headers on HTTP errors (default: true)
+- **`onRetry`**: Hook called before waiting for the next attempt
+- **`shouldRetry`**: Custom function to determine if a request should be retried
+
+## HTTP Methods
+
+All HTTP methods return a response object that allows you to optionally attach schema validation.
+
+### GET Request
+
+```typescript
+client.get<Path, TParams>(url: Path, options?: EnforcedPathParamsOptions<never, TParams, Path>): SchemaableResponse<unknown>
+```
+
+**Example:**
+
+```typescript
+// Basic GET request - returns unknown data
+const users = await client.get('/users')
+// users.data 👉 unknown
+
+// GET with path parameters
+const user = await client.get('/users/:id', {
+  pathParams: { id: '123' },
+})
+
+// GET with query parameters
+const filteredUsers = await client.get('/users', {
+  params: {
+    page: 1,
+    limit: 10,
+    status: 'active',
+  },
+})
+
+// GET with schema validation
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string(),
+})
+
+const validatedUser = await client.get('/users/1').schema(userSchema)
+// validatedUser.data 👉 { id: number, name: string, email: string }
+```
+
+### POST Request
+
+```typescript
+client.post<Path, TBody, TParams>(url: Path, body?: TBody, options?: EnforcedPathParamsOptions<TBody, TParams, Path>): SchemaableResponse<unknown>
+```
+
+**Example:**
+
+```typescript
+// Basic POST request - returns unknown data
+const newUser = await client.post('/users', {
+  name: 'John Doe',
+  email: 'john@example.com',
+})
+
+// POST with schema
+const createUserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+})
+
+const responseSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string(),
+  createdAt: z.string(),
+})
+
+const validatedUser = await client
+  .post('/users', userData)
+  .schema(responseSchema)
+// validatedUser.data 👉 { id: number, name: string, email: string, createdAt: string }
+```
+
+### PUT Request
+
+```typescript
+client.put<Path, TBody, TParams>(url: Path, body?: TBody, options?: EnforcedPathParamsOptions<TBody, TParams, Path>): SchemaableResponse<unknown>
+```
+
+### PATCH Request
+
+```typescript
+client.patch<Path, TBody, TParams>(url: Path, body?: TBody, options?: EnforcedPathParamsOptions<TBody, TParams, Path>): SchemaableResponse<unknown>
+```
+
+### DELETE Request
+
+```typescript
+client.delete<Path, TParams>(url: Path, options?: EnforcedPathParamsOptions<never, TParams, Path>): SchemaableResponse<unknown>
+```
+
+### Generic Request
+
+```typescript
+client.request<Path, TBody, TParams>(url: Path, options?: HttpRequestOptions<TBody, TParams>): SchemaableResponse<unknown>
+```
+
+**Example:**
+
+```typescript
+// HEAD request
+const headResponse = await client.request('/users/1', { method: 'HEAD' })
+
+// OPTIONS request
+const optionsResponse = await client.request('/users', { method: 'OPTIONS' })
+```
+
+## Response Methods
+
+All HTTP methods return a `SchemaableResponse<unknown>` that provides extraction helpers:
+
+### SchemaableResponse Interface
+
+```typescript
+interface SchemaableResponse<T> extends Promise<ResponseType<T>> {
+  schema<S extends Schema>(schema: S): ExtractableResponse<InferSchemaOutput<S>>
+  data(): Promise<T>
+  void(): Promise<void>
+}
+```
+
+### Methods
+
+#### `.schema(schema)`
+
+Validates the response data against a schema and returns a typed response.
+
+```typescript
+const response = await client.get('/users/1').schema(userSchema)
+// awaited response 👉 ResponseType<User>
+// response.data 👉 User
+```
+
+#### `.data()`
+
+Extracts the data from the response without schema validation.
+
+```typescript
+const data = await client.get('/users/1').data()
+// data 👉 unknown
+```
+
+#### `.void()`
+
+Runs the request and resolves without returning response data. Errors and schema validation still run.
+
+```typescript
+await client.delete('/users/1').void()
+```
+
+### Design Philosophy
+
+1. **Fetch unknown data once** - All requests return `unknown` data by default
+2. **Schema changes type** - If `.schema()` is called, it validates and types the data
+3. **No schema = unknown data** - If no schema is provided, data remains `unknown`
+4. **Single HTTP request** - Schema validation happens client-side, no duplicate requests
+
+## Error Handling
+
+### Error Types
+
+The library provides structured error types for different failure scenarios:
+
+#### HttpError
+
+Thrown when an HTTP request fails with a non-2xx status code.
+
+```typescript
+class HttpError extends Error {
+  readonly status: number
+  readonly statusText: string
+  readonly data: unknown
+  readonly response: Response
+  readonly url: string
+  readonly method: string
+}
+```
+
+#### NetworkError
+
+Thrown when a network-level error occurs.
+
+```typescript
+class NetworkError extends Error {
+  readonly cause?: Error
+}
+```
+
+#### TimeoutError
+
+Thrown when a request exceeds the timeout limit.
+
+```typescript
+class TimeoutError extends Error {
+  readonly cause?: Error
+}
+```
+
+#### SchemaValidationError
+
+Thrown when response data fails schema validation.
+
+```typescript
+class SchemaValidationError extends Error {
+  readonly schema: unknown
+  readonly data: unknown
+  readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>
+  readonly cause?: Error
+}
+```
+
+#### MiddlewareError
+
+Thrown when middleware fails.
+
+```typescript
+class MiddlewareError extends Error {
+  readonly type: 'request' | 'response'
+  readonly url?: string
+  readonly method?: string
+  readonly cause?: Error
+}
+```
+
+#### PathParameterError
+
+Thrown when required path parameters are missing.
+
+```typescript
+class PathParameterError extends Error {
+  readonly url: string
+  readonly requiredParams: string[]
+  readonly providedParams: string[]
+  readonly cause?: Error
+}
+```
+
+#### SerializationError
+
+Thrown when request serialization or successful-response parsing fails.
+
+```typescript
+class SerializationError extends Error {
+  readonly cause?: Error
+}
+```
+
+#### InvalidSchemaError
+
+Thrown when `.schema()` receives a value that does not implement Standard Schema v1.
+
+```typescript
+class InvalidSchemaError extends Error {
+  readonly schema: unknown
+  readonly cause?: Error
+}
+```
+
+#### InvalidBaseUrlError
+
+Thrown when `baseUrl` is not an absolute URL or root-relative path.
+
+```typescript
+class InvalidBaseUrlError extends Error {
+  readonly baseUrl: string
+  readonly cause?: Error
+}
+```
+
+#### AsyncSchemaValidationError
+
+Exported for custom schema integrations that need a structured async-schema validation error.
+
+```typescript
+class AsyncSchemaValidationError extends Error {
+  readonly schema: unknown
+  readonly cause?: Error
+}
+```
+
+### Error Handling Examples
+
+```typescript
+import {
+  HttpError,
+  NetworkError,
+  TimeoutError,
+  SchemaValidationError,
+} from '1000fetches'
+
+try {
+  await client.get('/users/1')
+} catch (error) {
+  if (error instanceof HttpError) {
+    console.log(`HTTP Error: ${error.status} ${error.statusText}`)
+    console.log(`Request: ${error.method} ${error.url}`)
+    console.log('Response data:', error.data)
+  } else if (error instanceof NetworkError) {
+    console.log('Network error occurred')
+  } else if (error instanceof TimeoutError) {
+    console.log('Request timed out')
+  } else if (error instanceof SchemaValidationError) {
+    console.log('Response data validation failed')
+  }
+}
+```
+
+## Middleware
+
+Middleware allows you to modify requests before they are sent and responses before they are returned.
+
+### Request Middleware
+
+```typescript
+const client = createHttpClient({
+  onRequestMiddleware: async (context: RequestContext) => {
+    // Modify the request context
+    context.headers.set('X-Custom-Header', 'value')
+    return context
+  },
+})
+```
+
+### Response Middleware
+
+Response middleware receives the parsed response before HTTP status handling. The returned `ResponseType` is authoritative: if middleware changes `status`, that changed status controls whether the request resolves or throws `HttpError`, and it also affects retry decisions.
+
+Use this deliberately for explicit recovery or status normalization. For example, a middleware can turn a `404` response into a successful `null` result:
+
+```typescript
+const client = createHttpClient({
+  onResponseMiddleware: async response => {
+    if (response.status === 404) {
+      return {
+        ...response,
+        status: 200,
+        statusText: 'Recovered Not Found',
+        data: null,
+      }
+    }
+
+    return response
+  },
+})
+
+const user = await client.get('/users/missing').data()
+// user 👉 null
+```
+
+If middleware only needs to normalize error payloads, preserve `status` so the client still throws for real non-2xx responses:
+
+```typescript
+const client = createHttpClient({
+  onResponseMiddleware: async (response: ResponseType<unknown>) => {
+    const data =
+      response.data && typeof response.data === 'object'
+        ? response.data
+        : { value: response.data }
+
+    return {
+      ...response,
+      data: {
+        ...data,
+        processed: true,
+      },
+    }
+  },
+})
+```
+
+### Middleware Examples
+
+```typescript
+// Authentication middleware
+const client = createHttpClient({
+  onRequestMiddleware: async context => {
+    const token = await getAuthToken()
+    context.headers.set('Authorization', `Bearer ${token}`)
+    return context
+  },
+})
+
+// Logging middleware
+const client = createHttpClient({
+  onRequestMiddleware: async context => {
+    console.log(`Making request: ${context.method} ${context.url}`)
+    return context
+  },
+  onResponseMiddleware: async response => {
+    console.log(`Response received: ${response.status} ${response.statusText}`)
+    return response
+  },
+})
+
+// Error handling middleware
+const client = createHttpClient({
+  onResponseMiddleware: async response => {
+    if (response.status === 401) {
+      // Handle unauthorized
+      await refreshToken()
+    }
+    return response
+  },
+})
+```
+
+## Schema Validation
+
+The library supports schema validation using popular validation libraries through the Standard Schema interface. Schema validation is applied using the `.schema()` method.
+
+### Supported Libraries
+
+- **Zod**
+- **Valibot**
+- **ArkType**
+- **Custom validators**
+
+### Usage Examples
+
+```typescript
+import { z } from 'zod'
+
+// Define schemas
+const userSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string(),
+  age: z.number().optional(),
+})
+
+const createUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string(),
+})
+
+// Response validation
+const user = await client.get('/users/1').schema(userSchema)
+// user.data 👉 { id: number, name: string, email: string, age?: number }
+
+// POST with response validation
+const newUser = await client.post('/users', userData).schema(userSchema)
+```
+
+### Custom Schema Validator
+
+```typescript
+import { createHttpClient } from '1000fetches'
+import type { SchemaValidator } from '1000fetches'
+
+const customValidator: SchemaValidator = {
+  async validate<T>(schema, data): Promise<T> {
+    const result = await schema['~standard'].validate(data)
+
+    if (result.issues) {
+      throw new Error(JSON.stringify(result.issues))
+    }
+
+    return result.value
+  },
+}
+
+const client = createHttpClient({
+  schemaValidator: customValidator,
+})
+```
+
+## Retry Logic
+
+The library includes built-in retry defaults with exponential backoff for handling transient failures when retries are enabled.
+
+### Retry Defaults When Enabled
+
+```typescript
+const defaultRetryOptions = {
+  maxRetries: 3,
+  retryDelay: 300,
+  backoffFactor: 2,
+  retryStatusCodes: [408, 429, 500, 502, 503, 504],
+  retryNetworkErrors: true,
+  maxRetryDelay: 30_000,
+  retryMethods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'],
+  retryUnsafeMethods: false,
+  jitter: 'none',
+  respectRetryAfter: true,
+}
+```
+
+### Custom Retry Configuration
+
+```typescript
+import { NetworkError, createHttpClient } from '1000fetches'
+
+const client = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  retry: {
+    maxRetries: 5,
+    retryDelay: 1_000,
+    backoffFactor: 1.5,
+    retryStatusCodes: [500, 502, 503, 504],
+    jitter: 'full',
+    onRetry: event => {
+      console.log(event.method, event.url, event.nextAttempt)
+    },
+    shouldRetry: (error, retryCount, context) => {
+      // Custom retry logic
+      return (
+        retryCount < 3 &&
+        context.bodyReplayable &&
+        error instanceof NetworkError
+      )
+    },
+  },
+})
+```
+
+### Per-Request Retry Configuration
+
+```typescript
+// Disable retries for this request
+await client.get('/users', { retry: false })
+
+// Custom retry for this request
+await client.get('/users', {
+  retry: {
+    maxRetries: 1,
+    retryDelay: 500,
+  },
+})
+```
+
+## Type Safety
+
+The library provides comprehensive TypeScript support with automatic type inference through response methods.
+
+### Response Method Types
+
+```typescript
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+// Without schema - data is unknown
+const response = await client.get('/users/1')
+// response.data 👉 unknown
+
+// With schema - data is typed
+const user = await client.get('/users/1').schema(userSchema)
+// user.data 👉 User
+
+// Array responses
+const users = await client.get('/users').schema(z.array(userSchema))
+// users.data 👉 User[]
+```
+
+### Path Parameter Validation
+
+```typescript
+// Compile-time path parameter validation
+await client.get('/users/:id', {
+  pathParams: { id: '123' }, // ✓ Valid
+})
+
+await client.get('/users/:id', {
+  pathParams: { userId: '123' }, // ✗ TypeScript error: 'id' is required
+})
+```
+
+Optional path params are supported only for trailing final segments like `/users/:id?`.
+Shapes like `/users/:id?/cards/:cardId` are rejected at compile time and runtime.
+
+### Request Options Type
+
+```typescript
+interface HttpRequestOptions<
+  TBody = unknown,
+  TParams extends RequestParamsType = RequestParamsType,
+> {
+  method?: HttpMethod
+  headers?: HttpHeaders
+  params?: TParams
+  pathParams?: Record<string, string | number | undefined>
+  body?: TBody
+  timeout?: number
+  signal?: AbortSignal
+  credentials?: RequestCredentials
+  cache?: RequestCache
+  mode?: RequestMode
+  redirect?: RequestRedirect
+  fetchOptions?: FetchOptions
+  onUploadStreaming?: (event: UploadStreamingEvent) => void
+  onDownloadStreaming?: (event: DownloadStreamingEvent) => void
+  responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData'
+  retry?: RetryOptions | boolean
+}
+```
+
+### Response Types
+
+```typescript
+interface ResponseType<T = unknown> {
+  data: T
+  status: number
+  statusText: string
+  headers: Record<string, string>
+  method: string
+  url: string
+  raw: Response
+}
+
+interface SchemaableResponse<T> extends Promise<ResponseType<T>> {
+  schema<S extends Schema>(schema: S): ExtractableResponse<InferSchemaOutput<S>>
+  data(): Promise<T>
+  void(): Promise<void>
+}
+
+interface ExtractableResponse<T> extends Promise<ResponseType<T>> {
+  data(): Promise<T>
+  void(): Promise<void>
+}
+```