create-request 1.6.0 → 2.0.0-next.0

package/CHANGELOG.md

@@ -1 +1,59 @@
 # Changelog
+
+## 2.0.0 — unreleased
+
+A ground-up rewrite with the same fluent API, a fifth fewer bytes on the wire, a 70 % smaller package and none of the known bugs. See [MIGRATION.md](MIGRATION.md) for the v1 → v2 map.
+
+### Breaking
+
+- **Node.js 22+** is required. The package ships `dist/index.js` (ESM), `dist/index.cjs` (CommonJS) and bundled declaration files; the `production` export condition and the `dist/library/*` files are gone.
+- **No global configuration.** `create.config` and the `Config` singleton are removed; defaults live on immutable api instances (`createApi()` / `create.api()`), which now have every request method except body and signal ones, derived from the request type.
+- **String literals instead of enums.** The `.withCache.NO_CACHE()`-style getters and the runtime enums (`CacheMode`, `CredentialsPolicy`, `RequestMode`, `RedirectMode`, `ReferrerPolicy`, `RequestPriority`, `SameSitePolicy`, `HttpMethod`) are removed; the setters take the DOM string unions.
+- **CSRF is explicit.** Nothing is sent automatically: `withCsrf()` enables the XSRF-cookie → header copy (same-origin only), `withCsrf({ token })` sends a token you hold; `withoutCsrfProtection()`, `withAntiCsrfHeaders()` and `X-Requested-With` by default are gone.
+- **One request class.** `GetRequest`, `PostRequest`, … are now type aliases of `HttpRequest<M, T>`; construct requests with the factories.
+- `getJson<T>()` returns `Promise<T>` (an empty body still yields `null` at runtime); `getData`'s selector receives `T`, not `T | null`.
+- `RequestError` takes an options object (`{ code, url, method, … }`), `error.getJson()` becomes `error.data`, and the static factories are removed. Messages are readable (`HTTP 404 Not Found`, `Request timed out after 5000ms`, …) and every rejection carries a `code`.
+- Retries only retry retriable failures (network errors, timeouts, 408/425/429/500/502/503/504), with exponential backoff by default and `Retry-After` support; validation errors are not retried by default, aborts and stream bodies never; error interceptors run once, after the last attempt.
+- `withQueryParams` replaces a key that is already present instead of appending; `null` removes it.
+- Interceptors run in registration order (api-level first); a request interceptor may return nothing; `config.headers` is a lower-case-keyed copy; short-circuit responses go through the status check.
+- `withCookie` / `withCookies` take string values sent verbatim; `CookieOptions` and `CookieUtils` are gone.
+- `error.response`'s body is consumed when `error.body` is captured; `body` is capped at 1 MB (a larger declared `Content-Length` leaves the body unread, a longer chunked or compressed body is cut off and `body` is `undefined`).
+
+### Added
+
+- `withSignal(signal)` (combinable), `getResult()` (`{ data, error }`), `getFormData()`, `clone()`, `create.delete()` / `api.delete()`, `withCsrf(options)`, `isRequestError()`.
+- Standard Schema validation: `getJson(schema)`, `getData(schema, selector?)`, `getResult(schema)` with zod, valibot, arktype and any other implementation — typed from the schema, failures have `code: "VALIDATION"` and `error.issues`.
+- Response types at the request: `api.get<User>("/me").getJson()`.
+- `RetryConfig.statuses`, `methods`, `maxDelay`, `shouldRetry`, `onRetry`; the `delay` callback receives `{ attempt, error }`, `onRetry` receives `{ attempt, error, delay }`.
+- Query values accept numbers, booleans, `Date`s, arrays and `URLSearchParams`; header values accept numbers and `null` (unset).
+- `DELETE` requests can carry a body; `ReadableStream` bodies are sent with `duplex: "half"`.
+- `withRedirect("manual")` and `withMode("no-cors")` resolve with the redirect / opaque response.
+- `withTimeout()` covers the whole exchange (response and body read); `0` / `Infinity` remove a timeout; a signal from `AbortSignal.timeout()` is reported as `"TIMEOUT"`.
+- Response and error interceptors receive the `HttpRequest` as a second argument, so a failed request can be replayed with `request.clone()`.
+- `withQueryParams`, `withHeaders`, `withCookies` and `withGraphQL` variables accept interface-typed objects.
+- A `FormData` body drops any `Content-Type` (fetch sets the multipart boundary); an already-aborted signal fails the request before interceptors run; api defaults are validated when set; `Retry-After` accepts decimals.
+
+### Fixed
+
+- Reading a body in two formats (`getText()` then `getJson()`, …) no longer throws "Body used".
+- Aborts with a custom reason are classified as aborted; network errors carry the underlying cause's message (or code) in their own message and keep `cause`; timeouts are detected from the signal, not from message text.
+- Query strings are inserted before a `#fragment`; `./users` joins onto a base URL cleanly.
+- Case-insensitive header merging; basic auth handles UTF-8 credentials.
+- Library options (`timeout`, `retries`, …) no longer leak into `fetch`'s `RequestInit`.
+- The timeout starts after request interceptors ran.
+- An interceptor's header mutations no longer persist on the request across executions.
+- A `URIError` from a malformed cookie can no longer escape `getResponse()`.
+- `import { RequestError } from "create-request"` tree-shakes to ≈ 0.2 KB.
+
+### Security
+
+- CSRF/XSRF tokens are attached only to same-origin requests, judged on the final URL after interceptors and before any redirect, unless `crossOrigin: true` is passed (v1 leaked them to every host, cf. axios CVE-2023-45857). Outside a browser every URL counts as same-origin; `fetch` forwards custom headers across redirects, so pair `withCsrf()` with `withRedirect("error")` on endpoints that may redirect elsewhere.
+- Error bodies are capped at 1 MB however they are encoded (a compressed or chunked 5xx can no longer inflate into memory), header values `fetch` would reject fail before the request is sent instead of being retried, and header/cookie objects are read by own keys only.
+
+### Internal
+
+- Build with `tsdown`; ESLint (typescript-eslint strict), Prettier, lint-staged and commitlint; CI on Node 22/24 with lint, type-check, type tests (including every README code block), 100% test coverage, package linting (`attw`, `publint`) and a `size-limit` gate; npm publishing with provenance.
+
+## 1.6.1 and earlier
+
+See the [GitHub releases](https://github.com/DanielAmenou/create-request/releases).

package/MIGRATION.md

@@ -0,0 +1,158 @@
+# Migrating from v1 to v2
+
+v2 is a redesign of the internals with a smaller, more correct and fully typed surface. The
+fluent style and most method names are unchanged, so for most code bases the migration is
+mechanical: replace the enum getters with string literals, move global configuration to an api
+instance, and drop a few options that never did anything.
+
+Node.js 22+ is required. The published files are `dist/index.js` (ESM),
+`dist/index.cjs` (CommonJS) and their declaration files; deep imports of `dist/library/*` no
+longer exist.
+
+## Checklist
+
+1. Replace `.withX.VALUE()` getters and enum arguments with string literals.
+2. Replace `create.config.*` with an api instance you export from one module.
+3. Replace `withoutCsrfProtection()` / `withAntiCsrfHeaders()` / automatic XSRF handling with
+   `withCsrf()` where you need it.
+4. Rename `error.getJson()` to `error.data`, and check `error.code` instead of message prefixes.
+5. Remove `| null` handling around `getJson()` unless the endpoint really answers `204`.
+6. Review retries: they now retry only retriable failures, with backoff, and honour `Retry-After`.
+7. Check `withQueryParams` calls that relied on repeated keys — pass an array instead.
+8. Cookie values are sent verbatim; `CookieOptions` objects are gone.
+
+## Method by method
+
+| v1                                                                                                                                                               | v2                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.withCache.NO_CACHE()`, `.withCredentials.INCLUDE()`, `.withMode.CORS()`, `.withRedirect.FOLLOW()`, `.withReferrerPolicy.NO_REFERRER()`, `.withPriority.HIGH()` | `.withCache("no-cache")`, `.withCredentials("include")`, `.withMode("cors")`, `.withRedirect("follow")`, `.withReferrerPolicy("no-referrer")`, `.withPriority("high")` — the DOM string unions, autocompleted |
+| `withCache(CacheMode.NO_CACHE)` and the other enum arguments                                                                                                     | the string literal                                                                                                                                                                                            |
+| `import { CacheMode, CredentialsPolicy, RequestMode, RedirectMode, ReferrerPolicy, RequestPriority, SameSitePolicy, HttpMethod }`                                | removed — use string literals; the `Method` type replaces `HttpMethod`                                                                                                                                        |
+| `withKeepAlive(true)`                                                                                                                                            | `withKeepAlive()` (`true` is the default; `withKeepAlive(false)` still works)                                                                                                                                 |
+| `withTimeout(ms)` (headers only; `0` threw)                                                                                                                      | covers the whole exchange including the body read; `0` / `Infinity` remove the timeout                                                                                                                        |
+| `withResponseInterceptor(response => …)`, `withErrorInterceptor(error => …)`                                                                                     | unchanged, and both also receive the `HttpRequest` as a second argument (`(error, request) => request.clone()…`)                                                                                              |
+| `withQueryParams({ page: 2 })` called twice with the same key → `page=1&page=2`                                                                                  | the last call wins (`page=2`); pass an array for repeated keys                                                                                                                                                |
+| `withQueryParam("ids", ["1", "2"])` (strings only)                                                                                                               | numbers, booleans, `Date`s and arrays are accepted too (`withQueryParams` also takes a `URLSearchParams`); `null` removes a key                                                                               |
+| `withHeaders({ a: undefined })` (type error, ignored at runtime)                                                                                                 | allowed: `null` / `undefined` remove the header (useful to drop an api default)                                                                                                                               |
+| `withCookie("t", { value: "x", secure: true })`, `CookieOptions`, `SameSitePolicy`                                                                               | `withCookie("t", "x")` — values are sent verbatim, options were never sent anyway                                                                                                                             |
+| `withAbortController(controller)`                                                                                                                                | unchanged; `withSignal(signal)` added (call several times to combine signals)                                                                                                                                 |
+| `withoutCsrfProtection()`                                                                                                                                        | removed — nothing is automatic any more                                                                                                                                                                       |
+| `withAntiCsrfHeaders()`                                                                                                                                          | `withHeader("X-Requested-With", "XMLHttpRequest")` if a framework still checks it                                                                                                                             |
+| `withCsrfToken(token, header?)`                                                                                                                                  | unchanged                                                                                                                                                                                                     |
+| `withBody(...)` on `DeleteRequest`                                                                                                                               | now allowed (`DELETE` may carry a body); still a compile error on `GET`, `HEAD`, `OPTIONS`                                                                                                                    |
+| `withGraphQL(query, variables, { throwOnError })`                                                                                                                | unchanged; GraphQL errors now have `code: "GRAPHQL"`                                                                                                                                                          |
+| `withRetries({ attempts, delay })`                                                                                                                               | unchanged shape, plus `statuses`, `methods`, `maxDelay`, `shouldRetry`, `onRetry`                                                                                                                             |
+| `onRetry(({ attempt, error }) => …)`                                                                                                                             | unchanged; the callback also receives `delay`                                                                                                                                                                 |
+| `getJson<T>(): Promise<T \| null>`                                                                                                                               | `getJson<T>(): Promise<T>` — write `getJson<T \| null>()` where an empty body is possible                                                                                                                     |
+| `getData<T, R>(d => d!.x)`                                                                                                                                       | `getData<T, R>(d => d.x)` — or `api.get<T>(url).getData(d => d.x)`; the selector receives `T`, not `T \| null`                                                                                                |
+| `getResponse()` throwing on every non-2xx                                                                                                                        | unchanged; `getResult()` added as the path that resolves with the error; `redirect: "manual"` 3xx and opaque responses no longer throw                                                                        |
+| `getBlob()` after `getText()` → "Body used"                                                                                                                      | works: every reader shares one buffer                                                                                                                                                                         |
+| —                                                                                                                                                                | added: `getFormData()`, `getResult()`, `clone()`, `withSignal()`, `withCsrf()`, `create.delete()`, `getJson(schema)`, `isRequestError()`                                                                      |
+
+## Global configuration → api instances
+
+```typescript
+// v1
+create.config.addRequestInterceptor(addTraceId);
+create.config.setCsrfToken(token);
+create.config.setEnableAntiCsrf(false);
+const users = await create.get("https://api.example.com/users").getJson();
+
+// v2 — src/lib/api.ts
+export const api = createApi().withBaseURL("https://api.example.com").withRequestInterceptor(addTraceId).withCsrf({ token }); // or withCsrf() for the XSRF-TOKEN cookie, or nothing at all
+const users = await api.get("/users").getJson();
+```
+
+| v1 `create.config.*`                                                            | v2                                                                                       |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `addRequestInterceptor`, `addResponseInterceptor`, `addErrorInterceptor`        | `api.withRequestInterceptor(fn)`, … — interceptors are part of the instance              |
+| `removeRequestInterceptor(id)`, `clearInterceptors()`                           | create another instance without them (`const anonymous = createApi().withBaseURL(base)`) |
+| `setCsrfToken(token)`, `setCsrfHeaderName(name)`                                | `api.withCsrf({ token, header })`                                                        |
+| `setXsrfCookieName(name)`, `setXsrfHeaderName(name)`, `setEnableAutoXsrf(bool)` | `api.withCsrf({ cookie, header })` — off unless you call it                              |
+| `setEnableAntiCsrf(bool)`                                                       | `api.withHeader("X-Requested-With", "XMLHttpRequest")` — off unless you add it           |
+| `reset()`                                                                       | not needed: there is no global state to reset between tests                              |
+
+There is no ambient configuration in v2 on purpose: state that leaked across tests, tenants and
+SSR requests was the source of several v1 bugs. Code you do not control that calls `create.get`
+directly is unaffected by your api instance — hand it the instance instead.
+
+## Errors
+
+```typescript
+// v1
+if (error instanceof RequestError) {
+  if (error.isTimeout) retryLater();
+  else if (error.message.startsWith("HTTP")) console.log(error.status, error.getJson());
+}
+
+// v2
+if (isRequestError(error)) {
+  switch (error.code) {
+    case "TIMEOUT":
+      retryLater();
+      break;
+    case "HTTP":
+      console.log(error.status, error.data);
+      break;
+  }
+}
+```
+
+| v1                                                                                                | v2                                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `error.getJson()`                                                                                 | `error.data` (a typed getter; never throws)                                                                                                                                                      |
+| `error.isTimeout`, `error.isAborted`                                                              | unchanged (getters over `code`)                                                                                                                                                                  |
+| message prefixes `"HTTP 404"`, `"Timeout:5000"`, `"Net:…"`, `"ReqI: …"`                           | `error.code` plus readable messages (`HTTP 404 Not Found`, `Request timed out after 5000ms`, `Network error: fetch failed (getaddrinfo ENOTFOUND api.example)`, `Request interceptor failed: …`) |
+| `new RequestError(message, url, method, options)`                                                 | `new RequestError(message, { code, url, method, ...options })`                                                                                                                                   |
+| `RequestError.timeout()`, `.fromResponse()`, `.networkError()`, `.abortError()`, `.captureBody()` | removed (they were implementation details)                                                                                                                                                       |
+| `error.name === "AbortError"` (never true in v1 either)                                           | `error.code === "ABORTED"`                                                                                                                                                                       |
+| a `URIError` or `TypeError` escaping `getResponse()`                                              | cannot happen: every rejection is a `RequestError` (even a broken `withFetch` stub, a throwing schema or a hostile GraphQL body is wrapped)                                                      |
+
+## Interceptors
+
+- Request interceptors may return nothing: in-place changes to `config` are kept. In v1 that
+  crashed the request.
+- `config.headers` is a copy with lower-case keys; mutating it no longer changes the request
+  object. `config.body` is already serialised (a string for JSON bodies).
+- Api-level interceptors run before request-level ones, all in registration order (v1 ran global
+  response/error interceptors in reverse).
+- Error interceptors run once per request, after retries (v1 ran them on every attempt).
+- A `Response` returned by a request interceptor goes through the status check and the response
+  interceptors like a fetched response (`withTimeout()` does not apply to it — nothing was fetched).
+
+## Retries
+
+- Only network errors, timeouts and 408/425/429/500/502/503/504 are retried by default. v1
+  retried everything, including 404s, invalid URLs and aborted requests.
+- The default delay is exponential backoff with jitter (v1: none). `Retry-After` is honoured
+  unless you set `delay`; one longer than `maxDelay` (30 s) cancels the retry.
+- Requests with a `ReadableStream` body are never retried.
+
+## Types
+
+| v1                                                                                                       | v2                                                                                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BaseRequest`, `BodyRequest` (classes)                                                                   | `HttpRequest<M, T>` class; `BaseRequest<T>` / `BodyRequest<T>` kept as type aliases                                                                                                                         |
+| `GetRequest`, `PostRequest`, … (classes)                                                                 | type aliases of `HttpRequest<"GET", T>`, `HttpRequest<"POST", T>`, …; `new GetRequest(url)` → `createGet(url)`                                                                                              |
+| `ApiBuilder` (hand-written)                                                                              | `ApiBuilder`, derived from `HttpRequest`                                                                                                                                                                    |
+| `RequestOptions`, `RetryCallback`, `RetryDelayFunction`, `CookieOptions`, `CookiesRecord` (with options) | removed / `RetryConfig["onRetry"]`, `RetryConfig["delay"]`, `CookiesRecord` is `Record<string, string>`                                                                                                     |
+| `RequestConfig.method: string`                                                                           | `Method`                                                                                                                                                                                                    |
+| `withQueryParams(record)`, `withHeaders(record)` requiring an index signature                            | interface-typed objects are accepted                                                                                                                                                                        |
+| `FetchFunction = (input: string \| URL \| Request, init?) => …`                                          | `(url: string, init: RequestInit) => Promise<Response>` — every v1 implementation still fits                                                                                                                |
+| `CookieUtils`                                                                                            | removed (internal)                                                                                                                                                                                          |
+| —                                                                                                        | added: `Method`, `BodyMethod`, `RequestErrorCode`, `RetryContext`, `QueryValue`, `QueryParams`, `HeadersRecord`, `CsrfOptions`, `CookiesRecord`, `RequestResult`, `RequestErrorOptions`, `StandardSchemaV1` |
+
+## Behaviour changes you might notice
+
+- Header names are stored lower-case; `withHeader("Content-Type", …)` and
+  `withHeader("content-type", …)` are the same header.
+- Query strings are inserted before a `#fragment`.
+- `./users` joins onto a base URL cleanly (`https://e.com/users`).
+- Basic auth encodes UTF-8 credentials correctly.
+- `withTimeout` starts counting after request interceptors ran, and applies per attempt.
+- `withMode("no-cors")` and `withRedirect("manual")` resolve instead of throwing.
+- `error.body` is capped at 1 MB: a response declaring more is left unread on `error.response`, a longer
+  chunked or compressed one is cut off (`body` is `undefined`).
+- `error.response`'s body has been read when `error.body` is set; use `error.body` / `error.data`.
+- A `FormData` body removes any `Content-Type` header (including an api-level default).
+- A request whose signal is already aborted fails before interceptors run and before `fetch` is called.