Runtime globals

On this page

The lowercase mal namespace exposes captured assets. The uppercase Mal namespace exposes the Web host extension. Their declarations are always available after loading the package types; the build configuration controls runtime availability.

mal

Requires surface.maligator (enabled by default). Configure named assets before calling mal.assets.materialize. Unknown names, invalid options, and filesystem failures throw synchronously. Completed snapshots are reused by content identity; the returned path is absolute. See Embed files for a complete file/directory example.

Mal

Requires surface.webPlatform (disabled by default). Mal.serve starts an HTTP listener and returns its bound port. The API is experimental: the handle has no public shutdown method, and invalid handlers or bind failures are not yet consistently reported as exceptions. Use valid options and verify startup before accepting traffic.

Run this as src/index.ts with surface.webPlatform: true; curl http://127.0.0.1:3000/ returns hello. See Serve HTTP for the config and Node alternative.

http.ts

import { ready } from "maligator:application";

const server = Mal.serve({
	hostname: "127.0.0.1",
	port: 3000,
	fetch(request) {
		if (new URL(request.url).pathname === "/") {
			return new Response("hello", { headers: { "content-type": "text/plain" } });
		}
		return new Response("Not found", { status: 404 });
	},
});
console.log(`Listening on http://127.0.0.1:${server.port}`);
ready();

MaligatorMaterializeOptions

Full TypeScript declaration

typescript

export interface MaligatorMaterializeOptions {
	/** Parent directory for the content-addressed materialization. Defaults to the OS temporary directory. */
	baseDirectory?: string;
}

MaligatorMaterializeOptions.baseDirectory

Parent directory for the content-addressed materialization. Defaults to the OS temporary directory.

typescript

baseDirectory?: string;

MaligatorAssets

Full TypeScript declaration

typescript

export interface MaligatorAssets {
	/**
	 * Atomically write a named snapshot and return its absolute file/directory path.
	 * Completed materializations are reused by content identity. Unknown names,
	 * invalid options, and filesystem failures throw synchronously.
	 * @see https://maligator.ddv.tools/api/runtime#mal.assets.materialize
	 */
	materialize(name: string, options?: MaligatorMaterializeOptions): string;
}

Types: MaligatorMaterializeOptions

mal.assets.materialize

Atomically write a named snapshot and return its absolute file/directory path. Completed materializations are reused by content identity. Unknown names, invalid options, and filesystem failures throw synchronously.

typescript

materialize(name: string, options?: MaligatorMaterializeOptions): string;

Types: MaligatorMaterializeOptions

MaligatorRuntime

Full TypeScript declaration

typescript

export interface MaligatorRuntime {
	readonly assets: MaligatorAssets;
}

Types: MaligatorAssets

MaligatorRuntime.assets

typescript

readonly assets: MaligatorAssets;

Types: MaligatorAssets

MaligatorServeOptions

Full TypeScript declaration

typescript

export interface MaligatorServeOptions {
	/** 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 asks the OS to choose a port. */
	port?: number;
	/** Handle a request with a Response or an awaited response. */
	fetch(request: Request): Response | PromiseLike<Response>;
	/** Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 60000 */
	headersTimeout?: number;
	/** Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 300000 */
	requestTimeout?: number;
	/** Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 5000 */
	keepAliveTimeout?: number;
	/** Concurrent connection limit; 0 also selects the default. Integer 0..2147483647.
	 * @default 1024 */
	maxConnections?: number;
}

MaligatorServeOptions.hostname

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

typescript

hostname?: string;

MaligatorServeOptions.port

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

typescript

port?: number;

MaligatorServeOptions.fetch

Handle a request with a Response or an awaited response.

typescript

fetch(request: Request): Response | PromiseLike<Response>;

MaligatorServeOptions.headersTimeout

Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647. Default: 60000.

typescript

headersTimeout?: number;

MaligatorServeOptions.requestTimeout

Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647. Default: 300000.

typescript

requestTimeout?: number;

MaligatorServeOptions.keepAliveTimeout

Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647. Default: 5000.

typescript

keepAliveTimeout?: number;

MaligatorServeOptions.maxConnections

Concurrent connection limit; 0 also selects the default. Integer 0..2147483647. Default: 1024.

typescript

maxConnections?: number;

MaligatorServer

Full TypeScript declaration

typescript

export interface MaligatorServer {
	/** Actual bound port, including an OS-selected port when the requested port was 0. */
	readonly port: number;
}

MaligatorServer.port

Actual bound port, including an OS-selected port when the requested port was 0.

typescript

readonly port: number;

MaligatorWebRuntime

Full TypeScript declaration

typescript

export interface MaligatorWebRuntime {
	/**
	 * Start an HTTP listener. Requires surface.webPlatform. The current handle exposes
	 * its bound port; it has no public stop method. Invalid timeout/connection limits throw.
	 * @see https://maligator.ddv.tools/api/runtime#Mal.serve
	 */
	serve(options: MaligatorServeOptions): MaligatorServer;
}

Types: MaligatorServeOptions, MaligatorServer

Mal.serve

Start an HTTP listener. Requires surface.webPlatform. The current handle exposes its bound port; it has no public stop method. Invalid timeout/connection limits throw.

typescript

serve(options: MaligatorServeOptions): MaligatorServer;

Types: MaligatorServeOptions, MaligatorServer