# @standardserver/fetch
`@standardserver/fetch` adapts the Fetch API to the transport-agnostic request and response model defined by Standard Server.
Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you write handlers and clients against the same request, response, body, and streaming primitives whether the underlying transport is Fetch, Node.js HTTP, or a peer-style message channel.
Standard Server ships as a small ecosystem of packages:
| Package | Description |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`@standardserver/core`](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md) | The shared contract: types, body parsing rules, validators, and SSE helpers |
| [`@standardserver/fetch`](https://github.com/middleapi/standardserver/blob/main/packages/fetch/README.md) | Fetch API adapter for browsers, workers, and other Fetch-based runtimes |
| [`@standardserver/node`](https://github.com/middleapi/standardserver/blob/main/packages/node/README.md) | Node.js HTTP and HTTP/2 adapter |
| [`@standardserver/fastify`](https://github.com/middleapi/standardserver/blob/main/packages/fastify/README.md) | Fastify adapter built on the Node.js adapter |
| [`@standardserver/aws-lambda`](https://github.com/middleapi/standardserver/blob/main/packages/aws-lambda/README.md) | AWS Lambda adapter with response streaming |
| [`@standardserver/peer`](https://github.com/middleapi/standardserver/blob/main/packages/peer/README.md) | Message-based adapter for WebSocket, MessagePort, and custom transports |
| [`@standardserver/shared`](https://github.com/middleapi/standardserver/blob/main/packages/shared/README.md) | Internal utilities shared across the ecosystem |
This package is the Fetch API adapter for that model. It converts between native `Request`, `Response`, `Headers`, and stream values and the corresponding Standard Server shapes from [`@standardserver/core`](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md).
## Package overview
The package exposes three groups of helpers:
| Group | Exports | Purpose |
| ----------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Request and response | `toStandardLazyRequest()`, `toStandardLazyResponse()`, `toFetchResponse()` | Convert between Fetch API objects and Standard Server |
| Body and stream helpers | `toStandardBody()`, `toFetchBody()`, `toAsyncIteratorObject()`, `toEventStream()` | Parse and serialize body values, including SSE |
| Header and URL helpers | `toStandardHeaders()`, `toFetchHeaders()`, `toStandardUrl()` | Normalize Fetch headers and URLs for Standard Server |
Use these helpers when you want Standard Server handlers to run in Fetch-based runtimes such as browsers, Cloudflare Workers, Bun, Deno, service workers, or server frameworks that expose the standard Fetch API.
## Server-side request handling
Use `toStandardLazyRequest()` to convert an incoming Fetch `Request` into a `StandardLazyRequest`, then `toFetchResponse()` to turn the resulting `StandardResponse` back into a Fetch `Response`.
```ts
import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
import { toFetchResponse, toStandardLazyRequest } from '@standardserver/fetch'
async function handle(request: StandardLazyRequest): Promise {
const body = await request.resolveBody()
return {
status: 200,
headers: { 'content-type': 'application/json' },
body: {
ok: true,
method: request.method,
url: request.url,
received: body,
},
}
}
export async function fetchHandler(request: Request): Promise {
const standardRequest = toStandardLazyRequest(request)
const standardResponse = await handle(standardRequest)
return toFetchResponse(standardResponse, {/** options */})
}
```
## Client-side response handling
Use `toFetchBody()` and `toFetchHeaders()` to serialize an outgoing request, and `toStandardLazyResponse()` when you receive a Fetch `Response` but want to work with the Standard Server response contract.
```ts
import { toFetchBody, toFetchHeaders, toStandardLazyResponse } from '@standardserver/fetch'
const standardRequest = {
method: 'POST',
url: '/echo',
headers: { 'content-type': 'application/json' },
body: { message: 'hello' },
}
const [body, headers] = toFetchBody(standardRequest.body, standardRequest.headers, {/** options */})
const response = await fetch(standardRequest.url, {
method: standardRequest.method,
headers: toFetchHeaders(headers),
body,
})
const standardResponse = toStandardLazyResponse(response)
const payload = await standardResponse.resolveBody()
```
`toFetchBody()` also prepares the content headers for the body it serializes β for example, a `Blob` or `File` body gains `standard-server: file`, `content-length`, and a generated `content-disposition`, so the receiver reconstructs the same body type. See [the `standard-server` header](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md#the-standard-server-header) in the core README for why.
> [!TIP]
> When sending requests or responses, you can pass additional options such as event-stream keep-alive.
## Resolving Body
`resolveBody(hint?)` follows the shared Standard Server resolution rules: an explicit `hint` wins, then the [`standard-server` header](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md#the-standard-server-header), then inference from the content headers. See [how body parsing works](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md#how-body-parsing-works) in the core README for the full algorithm.
> [!TIP]
> For efficient communication, set the `standard-server` header to explicitly hint the body type, especially for file or binary streaming. For example, if you upload a file with a common `content-type` such as `application/json` but omit the `standard-server` header, the server may interpret it as JSON and parse it unexpectedly.
## Learn more
For the project overview and the shared contract this adapter implements, see the [core documentation](https://github.com/middleapi/standardserver/blob/main/packages/core/README.md).
## Sponsors
Like what we build over at [middleapi](https://github.com/middleapi)? You can help keep it going here: [GitHub Sponsors](https://github.com/sponsors/dinwwwh). Every bit helps! π
### π Platinum Sponsor
### π₯ Silver Sponsor
### Generous Sponsors
### Sponsors
### Backers
With thanks to 37 past sponsors who helped get us here.
## License
Distributed under the MIT License. See [LICENCE](https://github.com/middleapi/standardserver/blob/main/LICENCE) for more information.
