# @mongez/http

> Robust native-fetch HTTP client for TypeScript. Returns `{data, error}` discriminated unions. Per-request `.cancel()`. Typed errors. Caching, retry, interceptors. `Resource` class for RESTful CRUD. SSR-safe by default, with `fetchInit` for Next.js `next: { revalidate, tags }`.

## Install

```
npm i @mongez/http
```

## Quick start

```ts
import { Http, setCurrentHttp, Resource } from '@mongez/http';

const http = new Http({
  baseURL: 'https://api.example.com',
  auth: () => `Bearer ${getToken()}`,
});
setCurrentHttp(http);

// Direct calls
const { data, error } = await http.get<User[]>('/users');
if (error) { /* handle */ }

// Resource pattern
class UsersResource extends Resource { route = '/users'; }
const usersResource = new UsersResource();
const { data: users } = await usersResource.list({ page: 1 });
```

## Key types

- `HttpResult<T>` — `{ data: T; error: null } | { data: null; error: HttpError }`
- `CancellablePromise<T>` — `Promise<T> & { cancel(reason?): void; signal: AbortSignal }`
- `CancellableAsyncIterable<T>` — returned by `stream()`; has `.cancel()` and `.error`
- `HttpError` — status, body, isAborted, isTimeout, isNetwork, isNotFound, isValidationError, …
- `HttpConfig` — baseURL, auth, timeout, headers, cache, retry, putToPost, publishKey, serializer, fetchCache, fetchInit, dedupe, dedupeKey
- `RequestOptions` — params, headers, signal, cache, cacheKey, dedupe, dedupeKey, retry, throw, timeout, data, responseType, fetchCache, fetchInit, onDownloadProgress
- `StreamRequestOptions` — method, data, format (sse/ndjson), parseLine, reconnect, reconnectDelay
- `CacheDriver` — get / set / remove / clear interface
- `ResourceService` — list / get / create / update / patch / delete / bulkDelete / publish

## Skills

- [`skills/overview/SKILL.md`](skills/overview/SKILL.md) — Bootstrap, exports table, package setup
  - *Auto-trigger:* Load when installing or configuring `@mongez/http` globally with `setCurrentHttp`/`getCurrentHttp`, or when **replacing axios/fetch** in a @mongez/warlock app.
- [`skills/http-client/SKILL.md`](skills/http-client/SKILL.md) — Http class, request methods, response typing (generics), HttpConfig, RequestOptions, cancellation, React patterns
  - *Auto-trigger:* Load when making HTTP/API requests, **replacing axios/fetch**, calling `http.get/post/put/patch/delete/all/race`, `new Http(...)`, **typing a response** (`http.get<User>()` — default is `unknown`), or configuring auth, timeout, putToPost, serializer, fetchCache, dedupeKey.
- [`skills/error-handling/SKILL.md`](skills/error-handling/SKILL.md) — HttpError, HttpResult, status predicates, validation errors
  - *Auto-trigger:* Load when handling `HttpError`, checking `isNotFound`/`isUnauthorized`/`isValidationError`, or narrowing `HttpResult<T>`.
- [`skills/streaming/SKILL.md`](skills/streaming/SKILL.md) — stream(), responseType "stream", onDownloadProgress, SSE/NDJSON
  - *Auto-trigger:* Load when using `http.stream()`, `responseType: "stream"`, SSE, NDJSON, or download progress bars.
- [`skills/interceptors/SKILL.md`](skills/interceptors/SKILL.md) — before/after interceptors, events, retry config, 401 redirect
  - *Auto-trigger:* Load when adding `before()`/`after()`, listening to lifecycle events, or configuring `HttpRetryConfig`.
- [`skills/caching/SKILL.md`](skills/caching/SKILL.md) — CacheDriver, HttpCacheConfig, invalidate
  - *Auto-trigger:* Load when caching GET responses with a `CacheDriver`, setting `cacheKey`, or calling `invalidate`/`invalidateAll`.
- [`skills/resource/SKILL.md`](skills/resource/SKILL.md) — Resource class, CRUD, publish, action, pagination subclass
  - *Auto-trigger:* Load when writing `class XResource extends Resource`, using CRUD methods, or building paginated/nested resources.
- [`skills/server-side/SKILL.md`](skills/server-side/SKILL.md) — SSR/Next.js safety: dedupe + cache defaults off the browser, identity-aware keys, `fetchInit`, `revalidateTag`, `setCurrentHttp` caveat
  - *Auto-trigger:* Load when using the package on a **server** — Next.js App Router / server components / SSR, Node services, workers, multi-tenant processes — or when setting `dedupe`/`dedupeKey`/`fetchInit`, forwarding `next: { revalidate, tags }`, or wiring `revalidateTag`.
- [`skills/recipes/SKILL.md`](skills/recipes/SKILL.md) — cross-feature compositions: token refresh via `replay()`, retry with jitter, cancel-on-unmount, uploads, typed CRUD, dedupe, Next.js tags
  - *Auto-trigger:* Load when composing several features together — auth refresh on 401, React cancel-on-unmount, multipart upload with abort, or Next.js cache tagging.
- [`skills/changelog/SKILL.md`](skills/changelog/SKILL.md) — dated release history, newest first
  - *Auto-trigger:* Load when asked what changed in a version, when a feature landed, or before bumping/releasing the package.

## Files

- `src/Http.ts` — main class
- `src/HttpError.ts` — error class
- `src/Resource.ts` — RESTful resource helper
- `src/cancellable.ts` — CancellablePromise / CancellableAsyncIterable factory
- `src/current-http.ts` — setCurrentHttp / getCurrentHttp
- `src/Http.types.ts` — all type definitions
- `src/utils/params.ts` — buildQueryString, appendParams
- `src/utils/body.ts` — prepareBody, parseBody