Documentation menu
API referenceMarkdown ↗

maligator:http

On this page
API reference0.1.0-alpha.35

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.

typescript
export const serve: (options: ServeOptions) => Server;

Types: ServeOptions, Server

typescript
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.

typescript
export const serveAsset: (asset: Assets.EmbeddedFile | Assets.EmbeddedDirectory, options?: ServeAssetOptions) => Handler;

Types: Handler, ServeAssetOptions, EmbeddedFile, EmbeddedDirectory

typescript
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.

typescript
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.

typescript
export const fetch: typeof globalThis.fetch;
typescript
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.

typescript
type Handler = (request: Request) => Response | PromiseLike<Response>;

ErrorHandler

Turns a handler failure into a response.

typescript
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
typescript
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.

typescript
fetch: Handler;

Types: Handler

ServeOptions.error

Answers instead when fetch throws or rejects. Defaults to logging the error and a plain 500 response.

typescript
error?: ErrorHandler;

Types: ErrorHandler

ServeOptions.hostname

Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener.

typescript
hostname?: string;

ServeOptions.port

TCP port, 0 through 65535. Defaults to 0, which lets the OS choose.

typescript
port?: number;

ServeOptions.signal

Closes the server when aborted.

typescript
signal?: AbortSignal;

ServeOptions.headersTimeout

Header deadline in milliseconds; 0 selects the default of 60000.

typescript
headersTimeout?: number;

ServeOptions.requestTimeout

Request deadline in milliseconds; 0 selects the default of 300000.

typescript
requestTimeout?: number;

ServeOptions.keepAliveTimeout

Idle keep-alive deadline in milliseconds; 0 selects the default of 5000.

typescript
keepAliveTimeout?: number;

ServeOptions.maxConnections

Concurrent connection limit; 0 selects the default of 1024.

typescript
maxConnections?: number;

Server

A listening server. await using closes it at the end of a scope.

Full TypeScript declaration
typescript
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.

typescript
readonly port: number;

Server.hostname

typescript
readonly hostname: string;

Server.url

A URL that reaches the server from this machine.

typescript
readonly url: string;

Server.close

Stops accepting and fulfills once in-flight requests finished. Repeated calls share one promise.

typescript
close(): Promise<void>;

Server.[Symbol.asyncDispose]

typescript
[Symbol.asyncDispose](): Promise<void>;

ServeAssetOptions

How request paths map onto the asset. A path ending in / serves its index.html.

Full TypeScript declaration
typescript
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.

typescript
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.

typescript
fallback?: string;

ServeAssetOptions.immutable

Patterns of member paths with content-hashed names, served as cacheable forever.

typescript
immutable?: ReadonlyArray<string>;
Maligator 0.1.0-alpha.35 · Experimental · Source 7a9e60fb1f28
Edit this page · Compatibility

Search guides and API reference.

Browse the API · Troubleshooting