@afoures/http-client 0.0.0 → 0.1.0

package/docs/http-client.md

@@ -0,0 +1,147 @@
+# HTTP Client
+
+The `http_client` function creates a typed API client from a map of endpoints.
+
+## Basic Usage
+
+```typescript
+import { Endpoint, http_client } from '@afoures/http-client'
+import { z } from 'zod'
+
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: {
+    users: new Endpoint({
+      method: 'GET',
+      pathname: '/users',
+      data: { schema: z.array(z.object({ id: z.string() })) },
+    }),
+  },
+})
+
+const result = await api.users({})
+```
+
+## Organizing Endpoints
+
+Nest endpoints in objects for logical grouping:
+
+```typescript
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: {
+    users: {
+      list: new Endpoint({ method: 'GET', pathname: '/users' }),
+      get: new Endpoint({ method: 'GET', pathname: '/users/(:id)' }),
+      create: new Endpoint({ method: 'POST', pathname: '/users' }),
+      update: new Endpoint({ method: 'PUT', pathname: '/users/(:id)' }),
+      delete: new Endpoint({ method: 'DELETE', pathname: '/users/(:id)' }),
+    },
+    posts: {
+      list: new Endpoint({ method: 'GET', pathname: '/posts' }),
+      get: new Endpoint({ method: 'GET', pathname: '/posts/(:id)' }),
+      comments: {
+        list: new Endpoint({ method: 'GET', pathname: '/posts/(:postId)/comments' }),
+        create: new Endpoint({ method: 'POST', pathname: '/posts/(:postId)/comments' }),
+      },
+    },
+  },
+})
+
+// Fully typed paths
+await api.users.list({})
+await api.users.get({ params: { id: '123' } })
+await api.posts.comments.create({ params: { postId: '1' }, body: { text: 'Nice!' } })
+```
+
+## Shared Options
+
+Provide sync or async default options for all requests:
+
+```typescript
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: { /* ... */ },
+  options: async () => {
+    const token = await getAuthToken()
+    return {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    }
+  },
+})
+```
+
+Options are merged in this order (later overrides earlier):
+1. `options()` from `http_client`
+2. Endpoint default options
+3. Per-request options
+
+## Custom Fetch
+
+Provide a custom fetch function for proxying, logging, or modifying requests:
+
+```typescript
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: { /* ... */ },
+  fetch: async (request) => {
+    console.log('Request:', request.url)
+    const response = await fetch(request)
+    console.log('Response:', response.status)
+    return response
+  },
+})
+```
+
+For testing, use tools like [MSW](https://mswjs.io/) instead of custom fetch.
+
+## Per-Request Options
+
+All `RequestInit` options plus custom options can be passed per-request:
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  headers: { 'X-Custom': 'value' },
+  signal: abortController.signal,
+  timeout: 5000,
+  retry: { attempts: 3, delay: 1000 },
+})
+```
+
+## Headers with Reducers
+
+Headers can be functions that receive the current value:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  headers: {
+    'X-Request-ID': (current) => current ?? crypto.randomUUID(),
+  },
+})
+```
+
+## Response Handling
+
+All endpoint functions return a union type:
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+// Can be an error
+if (result instanceof Error) {
+  // TimeoutError, NetworkError, SerializationError, etc.
+  return
+}
+
+// Or a response
+if (result.ok) {
+  console.log(result.data)
+} else {
+  console.log(result.error)
+}
+```

package/docs/response-parsing.md

@@ -0,0 +1,243 @@
+# Response Parsing
+
+Endpoints parse HTTP responses into typed results based on status code.
+
+## Response Types
+
+### Successful Response (20x)
+
+```typescript
+type SuccessfulResponse<Data> = {
+  ok: true
+  status: 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
+  data: Data
+  headers: Headers
+  raw_response: Response
+}
+```
+
+### Redirect (30x)
+
+```typescript
+type RedirectMessage = {
+  ok: false
+  status: 300 | 301 | 302 | 303 | 304 | 307 | 308
+  redirect_to: string | null
+  headers: Headers
+  raw_response: Response
+}
+```
+
+### Client Error (40x)
+
+```typescript
+type ClientErrorResponse<Error> = {
+  ok: false
+  status: 400 | 401 | 402 | 403 | 404 | /* ... */
+  error: Error
+  headers: Headers
+  raw_response: Response
+}
+```
+
+### Server Error (50x)
+
+```typescript
+type ServerErrorResponse<Error> = {
+  ok: false
+  status: 500 | 501 | 502 | 503 | 504 | /* ... */
+  error: Error
+  headers: Headers
+  raw_response: Response
+}
+```
+
+## Data Parser
+
+Define a `data` parser for successful responses:
+
+### JSON (Default)
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  data: {
+    schema: z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  },
+})
+
+const result = await endpoint.parse_response(response)
+if (result.ok) {
+  console.log(result.data) // { id: string, name: string }
+}
+```
+
+### Text
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/health',
+  data: {
+    schema: z.string(),
+    deserialization: 'text',
+  },
+})
+```
+
+### Custom Deserialization
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/data',
+  data: {
+    schema: z.object({ value: z.number() }),
+    deserialization: async (body) => {
+      const text = await new Response(body).text()
+      return JSON.parse(text)
+    },
+  },
+})
+```
+
+### 204 No Content
+
+For endpoints that return no content:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'DELETE',
+  pathname: '/users/(:id)',
+})
+
+const result = await endpoint.parse_response(response)
+// result.ok === true, result.status === 204, result.data === null
+```
+
+## Error Parser
+
+Define an `error` parser for error responses:
+
+### JSON
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/users',
+  body: { schema: z.object({ name: z.string() }) },
+  error: {
+    schema: z.object({
+      message: z.string(),
+      code: z.string(),
+    }),
+    deserialization: 'json',
+  },
+})
+
+const result = await endpoint.parse_response(response)
+if (!result.ok && result.status === 400) {
+  console.log(result.error.message)
+  console.log(result.error.code)
+}
+```
+
+### Text
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  error: {
+    schema: z.string(),
+    deserialization: 'text',
+  },
+})
+
+const result = await endpoint.parse_response(response)
+if (!result.ok && result.status === 404) {
+  console.log(result.error) // "Not Found"
+}
+```
+
+### Default (No Schema)
+
+Without an error parser, errors default to text:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+})
+
+const result = await endpoint.parse_response(response)
+if (!result.ok) {
+  console.log(typeof result.error) // "string"
+}
+```
+
+## Schema Transforms
+
+Schemas can transform response data:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  data: {
+    schema: z.object({
+      name: z.string().transform(s => s.toUpperCase()),
+      createdAt: z.string().transform(s => new Date(s)),
+    }),
+  },
+})
+
+const result = await endpoint.parse_response(response)
+if (result.ok) {
+  console.log(result.data.name)      // uppercase string
+  console.log(result.data.createdAt) // Date object
+}
+```
+
+## Deserialization Errors
+
+If response parsing fails validation, a `DeserializationError` is returned:
+
+```typescript
+const result = await endpoint.parse_response(response)
+
+if (result instanceof DeserializationError) {
+  console.log(result.message) // "Response deserialization failed"
+  console.log(result.cause)    // Schema validation issues
+}
+```
+
+## Handling All Cases
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (result instanceof Error) {
+  // UnexpectedError, NetworkError, TimeoutError, etc.
+  console.log(result.message)
+  return
+}
+
+if (result.ok) {
+  // 20x success
+  console.log(result.data)
+} else if (result.status >= 300 && result.status < 400) {
+  // Redirect
+  console.log(result.redirect_to)
+} else if (result.status >= 400 && result.status < 500) {
+  // Client error
+  console.log(result.error)
+} else {
+  // Server error
+  console.log(result.error)
+}
+```

package/docs/retry-policy.md

@@ -0,0 +1,197 @@
+# Retry Policy
+
+Configure automatic retries for failed requests.
+
+## Configuration
+
+```typescript
+type RetryPolicy = {
+  attempts?: number | ((ctx: { request: Request }) => number | Promise<number>)
+  delay?: number | ((ctx: { request: Request; response?: Response; error?: Error; attempt: number }) => number | Promise<number>)
+  when?: (ctx: { request: Request; response?: Response; error?: Error }) => boolean | Promise<boolean>
+}
+```
+
+## Basic Usage
+
+### Fixed Attempts and Delay
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  retry: {
+    attempts: 3,
+    delay: 1000, // 1 second
+  },
+})
+```
+
+### Conditional Retry
+
+By default, retries on non-OK responses. Customize with `when`:
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  retry: {
+    attempts: 3,
+    delay: 1000,
+    when: ({ response, error }) => {
+      // Retry on server errors or network failures
+      if (error) return true
+      if (response && response.status >= 500) return true
+      return false
+    },
+  },
+})
+```
+
+### Retry on Specific Status
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  retry: {
+    attempts: 5,
+    delay: 2000,
+    when: ({ response }) => {
+      if (!response) return false
+      return response.status === 503 // Service Unavailable
+    },
+  },
+})
+```
+
+## Exponential Backoff
+
+Use a delay function for exponential backoff:
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  retry: {
+    attempts: 5,
+    delay: ({ attempt }) => Math.min(1000 * Math.pow(2, attempt), 30000),
+    when: ({ error }) => !!error,
+  },
+})
+```
+
+## Retry on All GET Requests
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  retry: {
+    attempts: 3,
+    delay: 1000,
+    when: ({ request }) => request.method === 'GET',
+  },
+})
+```
+
+## Dynamic Attempts
+
+Determine max attempts dynamically:
+
+```typescript
+const result = await api.users.get({
+  params: { id: '123' },
+  retry: {
+    attempts: ({ request }) => {
+      // Check custom header or metadata
+      const priority = request.headers.get('X-Priority')
+      return priority === 'high' ? 5 : 2
+    },
+    delay: 1000,
+  },
+})
+```
+
+## Context Information
+
+The `when` and `delay` functions receive context about the request:
+
+```typescript
+retry: {
+  when: ({ request, response, error }) => {
+    // request: The Request object
+    // response: The Response if received, undefined if network error
+    // error: NetworkError, TimeoutError, etc. if occurred
+    return true
+  },
+  delay: ({ request, response, error, attempt }) => {
+    // attempt: Current attempt number (1-indexed)
+    return attempt * 1000
+  },
+}
+```
+
+## Default Behavior
+
+Without a `when` condition, retries on non-OK responses:
+
+```typescript
+retry: {
+  attempts: 3,
+  delay: 0,
+  // when: defaults to ({ response }) => response?.ok === false
+}
+```
+
+## Endpoint-Level Retry
+
+Set default retry on the endpoint:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  retry: {
+    attempts: 3,
+    delay: 1000,
+  },
+})
+```
+
+Per-request retry overrides endpoint defaults.
+
+## AbortSignal with Retry
+
+Retries respect `AbortSignal`:
+
+```typescript
+const controller = new AbortController()
+
+const result = await api.users.get({
+  params: { id: '123' },
+  signal: controller.signal,
+  retry: { attempts: 10, delay: 1000 },
+})
+
+// Call controller.abort() to cancel retries
+```
+
+## Example: Resilient API Client
+
+```typescript
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: {
+    users: new Endpoint({
+      method: 'GET',
+      pathname: '/users',
+      retry: {
+        attempts: 3,
+        delay: ({ attempt }) => Math.min(100 * Math.pow(2, attempt), 5000),
+        when: ({ response, error }) => {
+          if (error) return true
+          if (!response) return false
+          return response.status >= 500 || response.status === 429
+        },
+      },
+    }),
+  },
+})
+```