Requests, headers, and bodies
FetchRequest is a FetchRequestInit plus required url: string. FetchRequestInit<BODY> extends native RequestInit, replacing headers with RequestHeaders and body with RequestBodyType; it adds timeout, urlParams, and abortController. Native credentials, cache, mode, redirect, integrity, and other supported Fetch options pass through.
For ordinary calls, pass a request object to the client method; call mergeRequest directly only when composing two configurations yourself. Use urlParams.path for template values and urlParams.query for the query string. body selects payload content, while resultExtractor belongs in the separate third method argument, not inside the request.
Request fields
| Field/type | Contract |
|---|---|
RequestHeaders / RequestHeadersCapable | Plain string-keyed record of string | undefined; not a native Headers instance. |
RequestBodyType | BodyInit | Record<string, any> | string | null; a missing body remains missing. |
BaseURLCapable | Required baseURL: string; UrlParamsCapable supplies optional urlParams. |
HttpMethod | String enum GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE; platform restrictions still apply. |
CONTENT_TYPE_HEADER | 'Content-Type'; ContentTypeValues.APPLICATION_JSON is 'application/json', TEXT_EVENT_STREAM is 'text/event-stream'. |
Merge rules
mergeRequest(first, second): FetchRequestInit merges path and query records one level deep, and merges headers case-insensitively. The second request wins. For method, body, timeout, signal, and abortController, a nullish second value falls back to the first; body: null therefore does not clear an existing body in this helper. Other native fields follow object spread semantics. Empty-input shortcuts may return an original object when there are no headers; this is not a deep clone.
mergeRequestOptions(first?, second?) chooses the second non-nullish resultExtractor and attributes, then the first; its extractor fallback is Exchange. Attributes are replaced as a whole, not merged. mergeRecords(first?, second?) does a shallow second-wins merge and can return an existing record when only one exists. mergeRecordToMap(record?, map?) writes a record or map into the supplied map (or a new map) and returns that same map.
Header helpers
| Function | Result and mutation |
|---|---|
getHeader(headers, name) | Last case-insensitive matching value, or undefined; no mutation. |
deleteHeader(headers, name) | Removes all case variants; returns void. |
setHeader(headers, name, value) | Removes all variants, then sets the supplied spelling; undefined means delete. |
mergeHeaders(...records) | New record, later values win; later undefined removes an inherited header. |
Body conversion
RequestBodyInterceptor runs before normal order-zero request interceptors. Strings and nullish bodies pass through. Blob, File, FormData, and URLSearchParams pass through after removing all Content-Type spellings so Fetch chooses the type/boundary. ArrayBuffer, typed-array/DataView views, and ReadableStream pass through without header adjustment. Other objects (including arrays) use JSON.stringify; JSON Content-Type is added only if absent. An explicit non-JSON Content-Type does not prevent JSON serialization. Circular data or BigInt may fail serialization and enter the error pipeline.
Streaming upload support and additional runtime-specific request fields remain the caller's responsibility. See pipeline ordering before inserting a body transformer.
Complete example
import { Fetcher, mergeRequest, getHeader } from '@ahoo-wang/fetcher';
const client = new Fetcher({ baseURL: 'https://api.example.com' });
const request = mergeRequest(
{ headers: { Authorization: 'Bearer demo' }, timeout: 3000 },
{ headers: { authorization: undefined }, timeout: 0, body: { name: 'Ada' } },
);
const exchange = client.resolveExchange({
...request,
url: '/users',
method: 'POST',
});
console.assert(
getHeader(exchange.request.headers, 'authorization') === undefined,
);
console.assert(exchange.request.timeout === 0);Public symbols and source
| Symbol | Implementation |
|---|---|
BaseURLCapable | fetchRequest.ts:23 |
HttpMethod | fetchRequest.ts:37 |
UrlParamsCapable | fetchRequest.ts:48 |
CONTENT_TYPE_HEADER | fetchRequest.ts:55 |
ContentTypeValues | fetchRequest.ts:57 |
RequestHeaders | fetchRequest.ts:68 |
RequestHeadersCapable | fetchRequest.ts:81 |
RequestBodyType | fetchRequest.ts:88 |
FetchRequestInit | fetchRequest.ts:112 |
FetchRequest | fetchRequest.ts:176 |
mergeRequest | mergeRequest.ts:65 |
mergeRequestOptions | mergeRequest.ts:118 |
getHeader | requestHeaders.ts:17 |
deleteHeader | requestHeaders.ts:29 |
setHeader | requestHeaders.ts:39 |
mergeHeaders | requestHeaders.ts:56 |
mergeRecords | utils.ts:42 |
mergeRecordToMap | utils.ts:71 |