stacks-http

# Stacks HTTP ## Key Paths - Core package: `storage/framework/core/http/src/` - Composables (useFetch/createFetch): `storage/framework/core/composables/src/useFetch.ts`, `storage/framework/core/composables/src/createFetch.ts` - Buddy CLI command: `storage/framework/core/buddy/src/commands/http.ts` - httx dependency (installed): `node_modules/@stacksjs/httx/` - Package: `@stacksjs/http` (status codes), `@stacksjs/httx` (HTTP client), `@stacksjs/composables` (useFetch/createFetch) ## Source Files ``` http/src/ └── index.ts # Response enum — all HTTP status codes (100-511) composables/src/ ├── useFetch.ts # Chainable reactive fetch composable (builder pattern) └── createFetch.ts # Factory for pre-configured useFetch with baseUrl buddy/src/commands/ └── http.ts # `buddy http [domain]` CLI command using HttxClient ``` ## Response Enum — HTTP Status Codes (index.ts) The `@stacksjs/http` package exports a single `Response` enum with all standard HTTP status codes: ```typescript import { Response } from '@stacksjs/http' Response.HTTP_OK // 200 Response.HTTP_CREATED // 201 Response.HTTP_NO_CONTENT // 204 Response.HTTP_MOVED_PERMANENTLY // 301 Response.HTTP_NOT_MODIFIED // 304 Response.HTTP_BAD_REQUEST // 400 Response.HTTP_UNAUTHORIZED // 401 Response.HTTP_FORBIDDEN // 403 Response.HTTP_NOT_FOUND // 404 Response.HTTP_UNPROCESSABLE_ENTITY // 422 Response.HTTP_TOO_MANY_REQUESTS // 429 Response.HTTP_INTERNAL_SERVER_ERROR // 500 Response.HTTP_SERVICE_UNAVAILABLE // 503 ``` ### Full Status Code Categories - **1xx Informational**: `HTTP_CONTINUE` (100), `HTTP_SWITCHING_PROTOCOLS` (101) - **2xx Success**: `HTTP_OK` (200), `HTTP_CREATED` (201), `HTTP_ACCEPTED` (202), `HTTP_NON_AUTHORITATIVE_INFORMATION` (203), `HTTP_NO_CONTENT` (204), `HTTP_RESET_CONTENT` (205), `HTTP_PARTIAL_CONTENT` (206) - **3xx Redirection**: `HTTP_MULTIPLE_CHOICES` (300), `HTTP_MOVED_PERMANENTLY` (301), `HTTP_FOUND` (302), `HTTP_SEE_OTHER` (303), `HTTP_NOT_MODIFIED` (304), `HTTP_USE_PROXY` (305), `HTTP_UNUSED` (306), `HTTP_TEMPORARY_REDIRECT` (307), `HTTP_PERMANENT_REDIRECT` (308) - **4xx Client Error**: `HTTP_BAD_REQUEST` (400) through `HTTP_UNAVAILABLE_FOR_LEGAL_REASONS` (451) — includes `HTTP_I_AM_A_TEAPOT` (418) - **5xx Server Error**: `HTTP_INTERNAL_SERVER_ERROR` (500) through `HTTP_NETWORK_AUTHENTICATION_REQUIRED` (511) ## HttxClient — Outbound HTTP Client (@stacksjs/httx) The `@stacksjs/httx` package provides the `HttxClient` class for making outbound HTTP requests. It wraps Bun's `fetch()` with retry logic, timeouts, timing data, and Result-based error handling via `ts-error-handling`. ```typescript import { HttxClient } from '@stacksjs/httx' const client = new HttxClient(config?: Partial<HttxConfig>) const result = await client.request<T>(url: string, options: RequestOptions): Promise<Result<HttxResponse<T>, Error>> ``` ### HttxConfig ```typescript interface HttxConfig { verbose?: boolean | string[] // Enable debug logging (or filter by category) defaultHeaders?: Record<string, string> baseUrl?: string // Prepended to all request URLs timeout?: number // Request timeout in ms retry?: RetryOptions // Default retry configuration } ``` ### RequestOptions ```typescript interface RequestOptions { method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' query?: Record<string, string> // URL query parameters form?: boolean // Send body as form-encoded multipart?: boolean // Send body as multipart/form-data json?: boolean // Send body as JSON unix?: string // Unix socket path proxy?: string // Proxy URL downloadProgress?: (progress: number) => void retry?: RetryOptions // Per-request retry override stream?: boolean // Stream response acceptHeader?: string // Override Accept header verbose?: boolean timeout?: number body?: BodyInit | Record<string, string> headers?: HeadersInit } ``` ### RetryOptions ```typescript interface RetryOptions { retries?: number // Max retry attempts retryDelay?: number // Base delay between retries (ms) retryOn?: number[] // HTTP status codes that trigger retry shouldRetry?: (error: Error, attempt: number) => boolean // Custom retry predicate } ``` ### HttxResponse ```typescript interface HttxResponse<T = unknown> { status: number statusText: string headers: Headers data: T timings: { start: number end: number duration: number // Total request duration in ms } } ``` ### Result Pattern (from ts-error-handling) `client.request()` returns a `Result<HttxResponse<T>, Error>`. Use `.match()` to handle success/failure: ```typescript const result = await client.request('https://api.example.com/users', { method: 'GET', }) result.match({ ok: (response) => { console.log(response.status) // 200 console.log(response.timings.duration) // e.g. 142 (ms) console.log(response.data) // parsed response body }, err: (error) => { console.error(error.message) }, }) ``` Or use `result.isOk` / `result.value` / `result.error` directly. ### Error Classes ```typescript class HttxError extends Error { readonly context?: Record<string, unknown> } class HttxRequestError extends HttxError { readonly method: string readonly url: string readonly statusCode?: number } class HttxTimeoutError extends HttxError { readonly method: string readonly url: string readonly timeout: number } class HttxNetworkError extends HttxError { readonly method: string readonly url: string readonly originalError?: Error } class HttxResponseError extends HttxRequestError { readonly statusText: string readonly responseBody?: unknown } ``` ### Utility Exports ```typescript import { debugLog, sleep } from '@stacksjs/httx' debugLog(category: string, message: string | (() => string), verbose?: boolean | string[]): void sleep(ms: number): Promise<void> ``` ### Config Exports ```typescript import { config, defaultConfig, getConfig } from '@stacksjs/httx' const config: HttxConfig // Synchronous access with default fallback const defaultConfig: HttxConfig // Default configuration object function getConfig(): Promise<HttxConfig> // Async config loader ``` ## useFetch — Reactive Fetch Composable (@stacksjs/composables) A chainable, reactive fetch composable using the builder pattern. Uses native `fetch()` under the hood (not HttxClient). Returns reactive `Ref` values from `@stacksjs/stx`. ```typescript import { useFetch } from '@stacksjs/composables' // Builder pattern: method -> format -> result const { data, error, isFetching } = await useFetch('/api/posts').get().json() ``` ### FetchBuilder Interface ```typescript interface FetchBuilder { get: () => FetchBuilder post: (body?: string) => FetchBuilder patch: (body?: string) => FetchBuilder put: (body?: string) => FetchBuilder delete: () => FetchBuilder json: () => UseFetchResult } ``` ### UseFetchResult Interface ```typescript interface UseFetchResult { data: Ref<any> // Reactive ref — populated with parsed JSON on success error: Ref<any> // Reactive ref — populated with error JSON or Error object isFetching: Ref<boolean> // Starts as true, becomes false when request completes then: (resolve: (value: { data: Ref<any>, error: Ref<any> }) => void) => Promise<void> } ``` ### Usage Examples ```typescript import { useFetch } from '@stacksjs/composables' // GET request const { data, error } = await useFetch('/api/users').get().json() // POST with JSON body const { data, error } = await useFetch('/api/users') .post(JSON.stringify({ name: 'Alice', email: 'alice@example.com' })) .json() // PATCH with body const { data, error } = await useFetch('/api/users/1') .patch(JSON.stringify({ name: 'Updated' })) .json() // DELETE const { data, error } = await useFetch('/api/users/1').delete().json() // Synchronous access (reactive — updates when request completes) const result = useFetch('/api/items').get().json() result.isFetching.value // true (synchronously, before microtask resolves) // ... later ... result.data.value // parsed JSON response result.isFetching.value // false ``` ### How json() Works Internally 1. Builds a `RequestInit` with the configured method and `Accept: application/json` header 2. For POST/PATCH/PUT with a body, also sets `Content-Type: application/json` 3. Calls native `fetch(url, init)` 4. On success (`response.ok`), parses JSON into `data.value` 5. On HTTP error, parses JSON into `error.value` 6. On network error, sets `error.value` to the caught Error 7. Always sets `isFetching.value = false` in `finally` ## createFetch — Pre-configured Fetch Factory (@stacksjs/composables) Creates a reusable `useFetch` instance with a pre-configured base URL. ```typescript import { createFetch } from '@stacksjs/composables' interface CreateFetchOptions { baseUrl?: string // Base URL prepended to all requests options?: RequestInit // Default options (currently unused in implementation) } const useApi = createFetch({ baseUrl: 'https://api.example.com' }) // URL becomes: https://api.example.com/users const { data, error } = await useApi('/users').get().json() ``` ### URL Resolution `createFetch` joins the base URL and path by stripping trailing/leading slashes: - `baseUrl: 'https://api.example.com/'` + `'/users'` → `'https://api.example.com/users'` - `baseUrl: 'https://api.example.com'` + `'users'` → `'https://api.example.com/users'` ## CLI Command — buddy http ```bash buddy http [domain] # Send a GET request (defaults to config.app.url) buddy http example.com # GET https://example.com buddy http -v example.com # Verbose output ``` The CLI command uses `HttxClient` from `@stacksjs/httx`: - Prepends `https://` if the URL does not start with `http` - Logs status code, status text, and duration - Prints response body (string or pretty-printed JSON) ## Gotchas - **`@stacksjs/http` is status codes only** — it exports a single `Response` enum with HTTP status code constants. It does NOT contain an HTTP client, request helpers, or fetch utilities - **The actual HTTP client is `@stacksjs/httx`** — a separate package (not part of `@stacksjs/http`). It is used by `buddy http` and available for general use - **`useFetch` uses native `fetch()`, not HttxClient** — despite `@stacksjs/httx` being available, the `useFetch` composable calls the global `fetch()` directly - **`useFetch` only supports `.json()` format** — there is no `.text()`, `.blob()`, or `.arrayBuffer()` method. The only terminal method is `.json()` - **Method chaining overrides previous method** — calling `.post('body').get()` will send a GET request (last method wins, body is cleared for GET/DELETE) - **`createFetch` ignores the `options` parameter** — the `CreateFetchOptions.options` field is declared in the interface but not used in the implementation - **`useFetch` body is only sent for POST/PATCH/PUT** — GET and DELETE requests strip the body even if one was set - **The `Response` enum name conflicts with the global `Response`** — importing `Response` from `@stacksjs/http` shadows the native Fetch API `Response` type. Use a named import alias if both are needed: `import { Response as HttpStatus } from '@stacksjs/http'` - **HttxClient uses Result pattern** — `request()` returns `Result<HttxResponse, Error>` from `ts-error-handling`, not a plain Promise. Use `.match()`, `.isOk`, or `.value`/`.error` to unwrap - **`useFetch` returns reactive Refs** — `data`, `error`, and `isFetching` are `Ref<T>` from `@stacksjs/stx`. Access values via `.value` property - **No request interceptors or middleware** — neither `useFetch` nor `HttxClient` support request/response interceptors - **For API route handling, use `@stacksjs/router`** — `@stacksjs/http` and `@stacksjs/httx` are for outbound requests only, not for defining API endpoints