chubbyts-http-types

Description

TypeScript types for HTTP messages, handlers and middlewares, inspired by PSR-7, PSR-15 and PSR-17.

A contract only: types (plus pipe), no implementation. Frameworks, routers and middlewares depend on it and stay interchangeable, any implementation of the factories and helpers creates and changes the messages. A body is an AsyncIterable<Uint8Array>, so Node.js streams and web ReadableStreams need no conversion.

A, I and O extend and default to Attributes (Record<string, unknown>).

Requirements

• node: 22

Installation

Through NPM as @chubbyts/chubbyts-http-types.

npm i @chubbyts/chubbyts-http-types@^4.2.2

Usage

Messages

import { Readable } from 'node:stream';
import type { ServerRequest } from '@chubbyts/chubbyts-http-types/message';

// GET https://user:password@localhost:10443/api?key1=value1&key2[]=value2&key3[key31]=value3#fragment
const request: ServerRequest = {
  method: 'GET',
  uri: {
    scheme: 'https',
    userInfo: 'user:password',
    host: 'localhost',
    port: 10443,
    path: '/api',
    query: 'key1=value1&key2[]=value2&key3[key31]=value3',
    fragment: 'fragment',
  },
  protocolVersion: '1.1',
  headers: { accept: ['application/json'] },
  body: Readable.from([]),
  signal: new AbortController().signal,
  attributes: {},
};

• method: the known methods get autocompleted, any extension method (PROPFIND) is allowed.
• uri.port: undefined without an explicit port. uri.query: raw and percent-encoded, without ?.
• headers: lowercase names, each with a list of values.
• body: read once by iterating it (e.g. text(body) from node:stream/consumers), the chunks are bytes, never objects.
• signal: aborted when the request is no longer needed (e.g. the client disconnected). The server bridge owns it, handlers pass it on, e.g. fetch(url, { signal: request.signal }).
• attributes: values derived from the request (route parameters, the user), see Typed attributes.

A Request is the same without attributes, a Response has status, reasonPhrase, protocolVersion, headers and body.

Factories

Created messages have the protocol version 1.1, no headers and an empty body. Each request gets a signal of its own (a shared one would pile up the listeners), a given Uri is used as is, a server request starts without attributes. The reason phrase falls back to STATUS_CODES (an empty string if unknown).

Helpers

The helpers read and change messages and uris, split like the PSR-7 interfaces. Every implementation has to follow these rules, so middlewares work with whichever gets injected:

• header names are case-insensitive and stored lowercase, a name has to be a token (RFC 9110 5.1), a value must not contain CR, LF or NUL, otherwise the with* helpers throw
• the with* helpers return a new message or uri, the given one stays unchanged
• a query gets parsed with nested (key[sub]=value, key[]=value) and repeated keys into objects and arrays, + and percent-encodings decoded, __proto__ never changes the prototype, the limits (depth, array size, parameters) are up to the implementation
• query params get serialized with indexed keys (key[sub]=value, key[0]=value), percent-encoded (RFC 3986, space as %20), empty arrays and objects dropped, so parsing them returns them again
• the port of a uri is undefined if it is the standard one of its scheme (80 for http, 443 for https)

MessageHelpers (PSR-7 MessageInterface):

RequestHelpers (PSR-7 RequestInterface), including the MessageHelpers:

ServerRequestHelpers (PSR-7 ServerRequestInterface), including the RequestHelpers:

(*) With a name only known at runtime (string), any attribute could get replaced, so their types widen to include the type of the value.

ResponseHelpers (PSR-7 ResponseInterface), including the MessageHelpers:

UriHelpers (PSR-7 UriInterface):

The cookie helpers follow RFC 6265 (PSR-7 has no cookie support):

• a name has to be a token, a value consists of cookie-octets, optionally within double quotes, and gets neither encoded nor decoded
• path and domain must not contain ; or control characters, an invalid maxAge or expires throws
• sameSite: 'None' and partitioned require secure, a __Secure- prefix requires secure, a __Host- prefix secure, the path / and no domain
• attributes get serialized in the order Path, Domain, Max-Age, Expires, Secure, HttpOnly, SameSite, Partitioned
• withoutCookie sets an empty value, Max-Age=0 and an Expires within 1970, path and domain have to match the ones the cookie got set with

Handler

A handler turns a server request into a response, its dependencies get injected:

import type { Handler } from '@chubbyts/chubbyts-http-types/handler';
import type { BodyFactory, ResponseFactory } from '@chubbyts/chubbyts-http-types/message-factory';
import type { ResponseHelpers } from '@chubbyts/chubbyts-http-types/message-helper';

export const createPingHandler = (
  responseFactory: ResponseFactory,
  bodyFactory: BodyFactory,
  responseHelpers: ResponseHelpers,
): Handler => {
  return async () => {
    const response = responseHelpers.withBody(
      responseFactory(200),
      bodyFactory(JSON.stringify({ datetime: new Date().toISOString() })),
    );

    return responseHelpers.withHeader(response, 'content-type', 'application/json');
  };
};

Middleware

A middleware changes the request before and the response after the next handler, or responds on its own:

import type { Attributes } from '@chubbyts/chubbyts-http-types/message';
import type { ResponseHelpers, ServerRequestHelpers } from '@chubbyts/chubbyts-http-types/message-helper';
import type { Middleware } from '@chubbyts/chubbyts-http-types/middleware';

export const createRequestIdMiddleware = (
  serverRequestHelpers: ServerRequestHelpers,
  responseHelpers: ResponseHelpers,
): Middleware<Attributes, { requestId: string }> => {
  return async (request, handler) => {
    const requestId = crypto.randomUUID();

    const response = await handler(serverRequestHelpers.withAttribute(request, 'requestId', requestId));

    return responseHelpers.withHeader(response, 'x-request-id', requestId);
  };
};

Pipe

pipe composes middlewares into one, the first being the outermost:

import type { Handler } from '@chubbyts/chubbyts-http-types/handler';
import type { Middleware } from '@chubbyts/chubbyts-http-types/middleware';
import { pipe } from '@chubbyts/chubbyts-http-types/pipe';

declare const handler: Handler;
declare const middlewares: Array<Middleware>;

const middleware: Middleware = pipe(middlewares);

export const app: Handler = (request) => middleware(request, handler);

Typed attributes

A handler or middleware relying on attributes set earlier (by a router or an authentication) declares them, one that adds attributes declares the ones it receives and the ones it passes on as Middleware<I, O>:

import type { Handler } from '@chubbyts/chubbyts-http-types/handler';
import type { ResponseFactory } from '@chubbyts/chubbyts-http-types/message-factory';
import type { ResponseHelpers, ServerRequestHelpers } from '@chubbyts/chubbyts-http-types/message-helper';
import type { Middleware } from '@chubbyts/chubbyts-http-types/middleware';

type RequestIdAttributes = { requestId: string };
type UserAttributes = RequestIdAttributes & { userId: string };

export const createAuthenticationMiddleware = (
  serverRequestHelpers: ServerRequestHelpers,
  resolveUserId: (authorization: string) => Promise<string>,
): Middleware<RequestIdAttributes, UserAttributes> => {
  return async (request, handler) => {
    const userId = await resolveUserId(serverRequestHelpers.getHeaderLine(request, 'authorization'));

    return handler(serverRequestHelpers.withAttribute(request, 'userId', userId));
  };
};

export const createUserHandler =
  (responseFactory: ResponseFactory, responseHelpers: ResponseHelpers): Handler<UserAttributes> =>
  async (request) =>
    responseHelpers.withHeader(responseFactory(204), 'x-user-id', request.attributes.userId);

pipe only composes middlewares sharing the same attributes (Middleware<A>). With m1: Middleware<RequestIdAttributes, UserAttributes> and m2: Middleware<UserAttributes, PingAttributes>, pipe([m1, m2]) compiles to a Middleware<UserAttributes>: it requires the userId upfront and hides the ping. Chain such middlewares by hand:

const app: Handler<RequestIdAttributes> = (request) => m1(request, (userRequest) => m2(userRequest, handler));

Upgrade from 3.x

Copyright

2026 Dominik Zogg