maligator:http
On this page
Serve HTTP with Fetch API handlers and embedded assets. A server whose whole handler serves an asset answers without running JavaScript per request.
Import from maligator:http. This API is experimental. Load declarations as described in Use TypeScript.
Each fetch handler receives a buffered Request. Request bodies are limited to 16 MiB, and handlers return a Response whose body the server writes whole. See Serve HTTP for walkthroughs of handlers, assets and frontends.
serve
Listen and answer each request with fetch. Invalid options and bind failures throw.
export const serve: (options: ServeOptions) => Server;Types: ServeOptions, Server
import { serve } from "maligator:http";
const server = serve({
hostname: "127.0.0.1",
port: 3000,
fetch: () => new Response("hello"),
});
console.log(server.url);serveAsset
A handler that serves an embedded file or directory with its media type, ETag, cache headers, conditional and range requests, and precompressed copies in production builds. While a declaration's watcher runs, the handler forwards to the watcher's URL instead.
export const serveAsset: (asset: Assets.EmbeddedFile | Assets.EmbeddedDirectory, options?: ServeAssetOptions) => Handler;Types: Handler, ServeAssetOptions, EmbeddedFile, EmbeddedDirectory
import { embedDirectory } from "maligator:assets";
import { serve, serveAsset } from "maligator:http";
const files = serveAsset(embedDirectory("./public"), { fallback: "index.html" });
serve({ port: 3000, fetch: files });proxy
A handler that forwards each request to the same path below target and returns the answer.
export const proxy: (target: string) => Handler;Types: Handler
fetch
The Fetch API's fetch, the same function as the global one. Importing it links the HTTP client without installing the global.
export const fetch: typeof globalThis.fetch;import { fetch } from "maligator:http";
const response = await fetch("https://example.com/");
console.log(response.status);Handler
Answers a buffered request. A thrown error or rejection reaches the server's error handler.
type Handler = (request: Request) => Response | PromiseLike<Response>;ErrorHandler
Turns a handler failure into a response.
type ErrorHandler = (error: unknown, request: Request) => Response | PromiseLike<Response>;ServeOptions
Where to listen and how to answer. Limits are integers from 0 through 2147483647.
Full TypeScript declaration
type ServeOptions = {
/** Answers each request. */
fetch: Handler;
/** Answers instead when `fetch` throws or rejects. Defaults to logging the error and a plain 500 response. */
error?: ErrorHandler;
/** Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener. */
hostname?: string;
/** TCP port, 0 through 65535. Defaults to 0, which lets the OS choose. */
port?: number;
/** Closes the server when aborted. */
signal?: AbortSignal;
/** Header deadline in milliseconds; 0 selects the default of 60000. */
headersTimeout?: number;
/** Request deadline in milliseconds; 0 selects the default of 300000. */
requestTimeout?: number;
/** Idle keep-alive deadline in milliseconds; 0 selects the default of 5000. */
keepAliveTimeout?: number;
/** Concurrent connection limit; 0 selects the default of 1024. */
maxConnections?: number;
};Types: Handler, ErrorHandler
ServeOptions.fetch
Answers each request.
fetch: Handler;Types: Handler
ServeOptions.error
Answers instead when fetch throws or rejects. Defaults to logging the error and a plain 500 response.
error?: ErrorHandler;Types: ErrorHandler
ServeOptions.hostname
Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener.
hostname?: string;ServeOptions.port
TCP port, 0 through 65535. Defaults to 0, which lets the OS choose.
port?: number;ServeOptions.signal
Closes the server when aborted.
signal?: AbortSignal;ServeOptions.headersTimeout
Header deadline in milliseconds; 0 selects the default of 60000.
headersTimeout?: number;ServeOptions.requestTimeout
Request deadline in milliseconds; 0 selects the default of 300000.
requestTimeout?: number;ServeOptions.keepAliveTimeout
Idle keep-alive deadline in milliseconds; 0 selects the default of 5000.
keepAliveTimeout?: number;ServeOptions.maxConnections
Concurrent connection limit; 0 selects the default of 1024.
maxConnections?: number;Server
A listening server. await using closes it at the end of a scope.
Full TypeScript declaration
interface Server {
/** The bound port, including one the OS chose. */
readonly port: number;
readonly hostname: string;
/** A URL that reaches the server from this machine. */
readonly url: string;
/** Stops accepting and fulfills once in-flight requests finished. Repeated calls share one promise. */
close(): Promise<void>;
[Symbol.asyncDispose](): Promise<void>;
}Server.port
The bound port, including one the OS chose.
readonly port: number;Server.hostname
readonly hostname: string;Server.url
A URL that reaches the server from this machine.
readonly url: string;Server.close
Stops accepting and fulfills once in-flight requests finished. Repeated calls share one promise.
close(): Promise<void>;Server.[Symbol.asyncDispose]
[Symbol.asyncDispose](): Promise<void>;ServeAssetOptions
How request paths map onto the asset. A path ending in / serves its index.html.
Full TypeScript declaration
type ServeAssetOptions = {
/** The URL path the directory is served below, such as `/static`. Defaults to the root. */
prefix?: string;
/** The member served for paths below the prefix that name no file, such as `index.html` for a client-side router. */
fallback?: string;
/** Patterns of member paths with content-hashed names, served as cacheable forever. */
immutable?: ReadonlyArray<string>;
};ServeAssetOptions.prefix
The URL path the directory is served below, such as /static. Defaults to the root.
prefix?: string;ServeAssetOptions.fallback
The member served for paths below the prefix that name no file, such as index.html for a client-side router.
fallback?: string;ServeAssetOptions.immutable
Patterns of member paths with content-hashed names, served as cacheable forever.
immutable?: ReadonlyArray<string>;