@standard-server/fetch

@standard-server/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 | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | @standard-server/core | The shared contract: types, body parsing rules, validators, and SSE helpers | | @standard-server/fetch | Fetch API adapter for browsers, workers, and other Fetch-based runtimes | | @standard-server/node | Node.js HTTP and HTTP/2 adapter | | @standard-server/fastify | Fastify adapter built on the Node.js adapter | | @standard-server/aws-lambda | AWS Lambda adapter with response streaming | | @standard-server/peer | Message-based adapter for WebSocket, MessagePort, and custom transports | | @standard-server/shared | 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 @standard-server/core.

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.

import type { StandardLazyRequest, StandardResponse } from '@standard-server/core'
import { toFetchResponse, toStandardLazyRequest } from '@standard-server/fetch'

async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
  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<Response> {
  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.

import { toFetchBody, toFetchHeaders, toStandardLazyResponse } from '@standard-server/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 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, then inference from the content headers. See 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.

Sponsors

Like what we build over at middleapi? You can help keep it going through GitHub Sponsors or Open Collective. Every bit helps! 🚀

Special Sponsors

Organization Sponsors

Sponsors

Backers

With thanks to 36 past sponsors who helped get us here.

License

Distributed under the MIT License. See LICENCE for more information.