`@standardserver/core` is the shared contract package for **Standard Server** — a unified interface for client-server communication across HTTP and message-based transports. It lets you keep handler and client code transport-agnostic by working with the same request, response, body, and streaming abstractions whether the 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 foundation of that model. It defines the request and response types every adapter converts to and from, the body parsing rules they all share, runtime validators, header and URL utilities, and event stream (SSE) helpers.
## Request and response types
The package exposes four transport-agnostic shapes:
| Export | Description |
| ---------------------- | --------------------------------------------------------------- |
| `StandardRequest` | Eager request object with a parsed `body` |
| `StandardLazyRequest` | Request object with `resolveBody(hint?)` for lazy body parsing |
| `StandardResponse` | Eager response object with a parsed `body` |
| `StandardLazyResponse` | Response object with `resolveBody(hint?)` for lazy body parsing |
Supporting primitives:
| Export | Description |
| ------------------ | ------------------------------------------------------------- |
| `StandardMethod` | Common HTTP verbs plus any custom string value |
| `StandardUrl` | A request URL that must start with `/` and exclude the origin |
| `StandardHeaders` | `Record` |
| `StandardBodyHint` | Parsing hint for lazy body resolution |
| `StandardBody` | Shared body union used by requests and responses |
By convention, adapters normalize headers to lowercase keys. `signal` is part of `StandardRequest` only and is used to propagate request cancellation.
```ts
import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
export 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,
},
}
}
```
## Body types
`StandardBodyHint` and `StandardBody` describe the shared body contract used across adapters:
| Hint | `StandardBody` value | Typical content type | Notes |
| ------------------- | ------------------------------ | ----------------------------------- | ----------------------------------------------------- |
| `json` | `unknown` | `application/json` | Primitives, objects, and arrays |
| `form-data` | `FormData` | `multipart/form-data` | Multipart form submissions |
| `url-search-params` | `URLSearchParams` | `application/x-www-form-urlencoded` | URL-encoded forms |
| `event-stream` | `AsyncIteratorObject` | `text/event-stream` | Server-Sent Events (SSE) |
| `octet-stream` | `ReadableStream` | any | Binary streaming |
| `file` | `File` | any | Fixed-size binary payloads for both `File` and `Blob` |
| `none` | `undefined` | | Empty body |
### JSON body
Standard Server treats primitive values, objects, and arrays as JSON.
```ts
import type { StandardRequest } from '@standardserver/core'
const request: StandardRequest = {
method: 'POST',
url: '/submit',
headers: {},
body: { name: 'John Doe', email: 'john.doe@example.com' },
}
```
### FormData and URLSearchParams body
Standard Server treats [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) as form submissions.
```ts
import type { StandardRequest } from '@standardserver/core'
const requestWithURLSearchParams: StandardRequest = {
method: 'POST',
url: '/submit',
headers: {},
body: new URLSearchParams({ name: 'John Doe', email: 'john.doe@example.com' }),
}
const formData = new FormData()
formData.append('name', 'John Doe')
formData.append('file', new Blob(['Hello, World!'], { type: 'text/plain' }), 'hello.txt')
const requestWithFormData: StandardRequest = {
method: 'POST',
url: '/submit',
headers: {},
body: formData,
}
```
> [!TIP]
> HTML forms submit data as `application/x-www-form-urlencoded` or `multipart/form-data`, so these body types are especially helpful there.
### File and Blob body
Standard Server treats [File](https://developer.mozilla.org/en-US/docs/Web/API/File) and [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) as fixed-size binary payloads.
> [!NOTE]
> Since `File` extends `Blob`, `resolveBody` always returns a `File` when representing either `File` or `Blob` bodies.
```ts
import type { StandardResponse } from '@standardserver/core'
const response: StandardResponse = {
status: 200,
headers: {
'content-disposition': [], // <- remove auto-set header
},
body: new File(['Hello, World!'], 'hello.txt', { type: 'text/plain' }),
}
```
When sending a file or blob body, adapters automatically set the `content-length`, `content-type`, `content-disposition`, and `standard-server` headers based on the provided body. You can override any of them by explicitly providing a header value, or remove one entirely by assigning an empty array.
### Event-stream body
Standard Server uses [AsyncIteratorObject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator) to represent an event stream body, and you can use `withEventMeta()` to attach additional [SSE event metadata](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format) to each emitted event.
```ts
import type { StandardResponse } from '@standardserver/core'
import { ErrorEvent, withEventMeta } from '@standardserver/core'
const response: StandardResponse = {
status: 200,
headers: {},
async* body() {
yield withEventMeta(
{ message: 'Hello, World!' },
{ id: '1', retry: 3000, comments: ['hidden'] },
)
throw new ErrorEvent({ message: 'Something went wrong' })
return { message: 'This is the end of the stream' }
},
}
```
Events are interpreted as follows: `yield` emits a `message`, `throw` emits an `error`, and `return` emits a `close` event. Note that `close` does not cause [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) to close the connection because it is not part of the SSE specification. However, when using Standard Server for client-side streaming, `close` is treated as the end of the stream, so the connection is closed and no reconnection is attempted.
For explicit SSE encoding, decoding, and metadata handling, see the [Event-Stream Helpers](#event-stream-helpers) below.
### Octet-stream body
Standard Server uses [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) to represent a binary streaming body.
```ts
import type { StandardResponse } from '@standardserver/core'
const response: StandardResponse = {
status: 200,
headers: {
'content-type': 'application/octet-stream',
},
body: new ReadableStream({
start(controller) {
const encoder = new TextEncoder()
controller.enqueue(encoder.encode('Hello, World!'))
controller.close()
},
}),
}
```
When sending a binary streaming body, adapters automatically set the `content-type` and `standard-server` headers. You can override `content-type` by providing an explicit header value, or remove it entirely by assigning an empty array.
## How body parsing works
> [!NOTE]
> This section applies to the HTTP adapters (Fetch, Node.js, Fastify, AWS Lambda). It does not apply to the [peer adapter](https://github.com/middleapi/standardserver/blob/main/packages/peer/README.md#body-resolution), which identifies body types through its own message protocol — a different but fairly similar mechanism.
`resolveBody(hint?)` on `StandardLazyRequest` and `StandardLazyResponse` resolves the body lazily — the underlying stream is only consumed once you call it. The `StandardBodyHint` that decides how the raw body is parsed comes from three places: an explicit `hint` argument, the `standard-server` header, or inference from the content headers.
### The `standard-server` header
A `StandardBody` is richer than what HTTP content headers can describe. `content-type` tells the receiver the _media type_ of the bytes, but not which `StandardBody` representation the sender intended:
- A file upload can legitimately carry `content-type: application/json`. Without more information, the receiver would parse it into a JSON value when the sender meant a `File` to be stored as-is.
- A fixed-size binary payload (`file`) and a binary stream (`octet-stream`) can share any content type. Telling them apart otherwise depends on `content-length`, which proxies may rewrite and some runtimes drop when the payload is empty.
The `standard-server` header closes this gap. It carries the sender's `StandardBodyHint` verbatim — `json`, `form-data`, `url-search-params`, `event-stream`, `octet-stream`, `file`, or `none` — so the receiver reconstructs exactly the body representation the sender had.
Adapters set the header automatically for the ambiguous body types: a `Blob` or `File` body is sent with `standard-server: file`, and a `ReadableStream` body with `standard-server: octet-stream`, alongside the usual content headers. A header you set yourself always wins, and assigning an empty array removes it entirely. For the other body types, the content headers are enough, so adapters clear it.
The header is optional: when it is absent or invalid, the receiver falls back to content-header inference, so plain HTTP clients work as-is. Just set the header yourself whenever the content type alone could be misread:
```ts
const response = await fetch('/upload', {
method: 'POST',
headers: {
'content-type': 'application/json',
'standard-server': 'file', // <- keep the payload a File on the server
},
body: new Blob(['{"message": "Hello, world!"}'], { type: 'application/json' }),
})
```
### Resolution order
The hint is chosen in this order:
1. **Explicit `hint` argument.** If you pass a hint to `resolveBody(hint)`, it always wins.
2. **The `standard-server` header.** If present and holding a valid hint value, it is used verbatim. Unknown values are ignored.
3. **Content-header inference:**
1. No `content-type`, and `content-length` absent or `0` → `none`.
2. A common `content-type` → `application/json` parses as `json`, `multipart/form-data` as `form-data`, `application/x-www-form-urlencoded` as `url-search-params`, and `text/event-stream` as `event-stream`. Media type casing and parameters such as `; charset=utf-8` are ignored.
3. A `content-disposition` carrying a filename, or any `content-length` → `file`.
4. Anything else → `octet-stream`.
This resolution is implemented once in this package as `resolveStandardBodyHint(headers)` and shared by every HTTP adapter, so the same body parses the same way regardless of which HTTP transport carried it:
```ts
import { resolveStandardBodyHint } from '@standardserver/core'
resolveStandardBodyHint({ 'content-type': 'application/json' })
// 'json'
resolveStandardBodyHint({
'content-type': 'application/json',
'standard-server': 'file',
})
// 'file'
resolveStandardBodyHint({})
// 'none'
```
Use it when building a custom adapter, or when you need to know how a body will parse without consuming it.
## Utilities
The package also exports a small set of helpers for common header and URL operations.
### Content-Disposition helpers
Use `generateContentDisposition()` to produce a safe `Content-Disposition` value and `getFilenameFromContentDisposition()` to read a filename back from an existing header.
```ts
import {
generateContentDisposition,
getFilenameFromContentDisposition,
} from '@standardserver/core'
const disposition = generateContentDisposition('report "Q2".csv')
// inline; filename="report \"Q2\".csv"; filename*=utf-8''report%20%22Q2%22.csv
const filename = getFilenameFromContentDisposition(disposition)
// 'report "Q2".csv'
```
`generateContentDisposition()` preserves an ASCII-safe `filename="..."` value and also emits `filename*=` for UTF-8 aware clients.
### Header helpers
`mergeStandardHeaders()` combines two `StandardHeaders` objects while preserving duplicate values, and `flattenStandardHeader()` turns a single header value into a plain string when needed.
```ts
import {
flattenStandardHeader,
mergeStandardHeaders,
} from '@standardserver/core'
const headers = mergeStandardHeaders(
{ 'accept': 'application/json', 'set-cookie': ['a=1'] },
{ 'set-cookie': 'b=2', 'vary': 'accept', 'warning': undefined },
)
// {
// accept: 'application/json',
// 'set-cookie': ['a=1', 'b=2'],
// vary: 'accept',
// }
const cookieHeader = flattenStandardHeader(headers['set-cookie'])
// 'a=1, b=2'
```
### URL parsing
`parseStandardUrl()` splits a `StandardUrl` into `[pathname, search, hash]` without requiring a full origin.
```ts
import { parseStandardUrl } from '@standardserver/core'
const [pathname, search, hash] = parseStandardUrl('/users/123?tab=settings#profile')
// pathname => '/users/123'
// search => '?tab=settings'
// hash => '#profile'
```
## Validators
Runtime type guards are useful when requests or responses cross process, transport, or message boundaries.
| Export | Checks |
| ---------------------- | ------------------------------------------------------ |
| `isStandardMethod()` | Any string value |
| `isStandardUrl()` | A string starting with `/` |
| `isStandardHeaders()` | Object values are `string`, `string[]`, or `undefined` |
| `isStandardRequest()` | |
| `isStandardResponse()` | |
```ts
import { isStandardRequest } from '@standardserver/core'
export function expectStandardRequest(input: unknown) {
if (!isStandardRequest(input)) {
throw new TypeError('Expected a StandardRequest-compatible value')
}
return input
}
```
## Event-Stream Helpers
Use Event-Stream Helpers when you need explicit SSE encoding, decoding, or metadata handling.
### Message types and codecs
The event-stream helpers include:
- `EventMeta` for `id`, `retry`, and `comments`
- `EventStreamMessage` for complete SSE messages
- `encodeEventStreamMessage()` and `decodeEventStreamMessage()` for single-message codec operations
- `EventStreamDecoder` and `EventStreamDecoderStream` for chunked stream decoding
```ts
import {
decodeEventStreamMessage,
encodeEventStreamMessage,
} from '@standardserver/core'
const encoded = encodeEventStreamMessage({
comments: ['bootstrap'],
event: 'message',
id: '42',
retry: 3000,
data: 'hello\nworld',
})
const decoded = decodeEventStreamMessage(encoded)
// {
// comments: ['bootstrap'],
// event: 'message',
// id: '42',
// retry: 3000,
// data: 'hello\nworld',
// }
```
For streaming decode, pipe text chunks through `EventStreamDecoderStream`:
```ts
import { EventStreamDecoderStream } from '@standardserver/core'
const messages = response.body!
.pipeThrough(new TextDecoderStream())
.pipeThrough(new EventStreamDecoderStream())
```
### Iterator metadata helpers
`StandardBody` uses async iterators for event-stream bodies. To attach SSE metadata to a yielded value without changing its visible shape, use `withEventMeta()`.
```ts
import type { StandardResponse } from '@standardserver/core'
import { getEventMeta, unwrapEvent, withEventMeta } from '@standardserver/core'
const event = withEventMeta(
{ message: 'hello' },
{ id: '1', retry: 3000, comments: ['bootstrap'] },
)
const [data, meta] = unwrapEvent(event)
// data => { message: 'hello' }
// meta => { id: '1', retry: 3000, comments: ['bootstrap'] }
const extractedMeta = getEventMeta(event)
// { id: '1', retry: 3000, comments: ['bootstrap'] }
const response: StandardResponse = {
status: 200,
headers: {},
async* body() {
yield event
},
}
```
> [!WARNING]
> Metadata is validated before it is attached: `id`, `event`, and comments must not contain line breaks, and `retry` must be a non-negative integer.
### Errors and low-level assertions
The package also exports:
- `EventStreamEncoderError` for invalid outbound SSE messages
- `EventStreamDecoderError` for incomplete or invalid inbound stream decoding
- `ErrorEvent` for wrapping structured event-stream error payloads in an `Error`
- `assertEventStreamMessageId()`, `assertEventStreamMessageName()`, `assertEventStreamMessageRetry()`, and `assertEventStreamMessageComment()` for low-level validation when building custom SSE tooling
```ts
import { ErrorEvent } from '@standardserver/core'
const error = new ErrorEvent(
{ code: 'E_STREAM', detail: 'Connection lost' },
{ message: 'stream error' },
)
error.message
// 'stream error'
error.data
// { code: 'E_STREAM', detail: 'Connection lost' }
```
## Learn more
For transport-specific quick-starts and options, see the adapter documentation: [Fetch](https://github.com/middleapi/standardserver/blob/main/packages/fetch/README.md) · [Node.js](https://github.com/middleapi/standardserver/blob/main/packages/node/README.md) · [Fastify](https://github.com/middleapi/standardserver/blob/main/packages/fastify/README.md) · [AWS Lambda](https://github.com/middleapi/standardserver/blob/main/packages/aws-lambda/README.md) · [Peer](https://github.com/middleapi/standardserver/blob/main/packages/peer/README.md)
## Sponsors
Like what we build over at [middleapi](https://github.com/middleapi)? You can help keep it going through [GitHub Sponsors](https://github.com/sponsors/dinwwwh) or [Open Collective](https://opencollective.com/middleapi). Every bit helps! 🚀
With thanks to [36 past sponsors](https://htmlpreview.github.io/?https://github.com/middleapi/static/blob/main/sponsors.svg) who helped get us here.
## License
Distributed under the MIT License. See [LICENCE](https://github.com/middleapi/standardserver/blob/main/LICENCE) for more information.
---
_Source: https://npm.io/package/@standardserver/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
ScreenshotOne.com
Yuzu
MisskeyHQ
