@small-web/kitten/polka/index.d.ts

Type-safe global Kitten namespace.

import type { IncomingMessage, ServerResponse } from 'http';
import type { ListenOptions, Server } from 'net';

// Parsed URL

declare interface ParsedURL {
	pathname: string;
	search: string;
	query: Record<string, string | string[]> | void;
	raw: string;
}

declare function parse(req: IncomingMessage): ParsedURL;


// Trouter 

// Thank you: @fwilkerson, @stahlstift
// ---

/** @type {import('http').METHODS} */
type Methods = 'ACL' | 'BIND' | 'CHECKOUT' | 'CONNECT' | 'COPY' | 'DELETE' | 'GET' | 'HEAD' | 'LINK' | 'LOCK' |'M-SEARCH' | 'MERGE' | 'MKACTIVITY' |'MKCALENDAR' | 'MKCOL' | 'MOVE' |'NOTIFY' | 'OPTIONS' | 'PATCH' | 'POST' | 'PRI' | 'PROPFIND' |  'PROPPATCH' |  'PURGE' | 'PUT' | 'REBIND' | 'REPORT' | 'SEARCH' | 'SOURCE' | 'SUBSCRIBE' | 'TRACE' | 'UNBIND' | 'UNLINK' | 'UNLOCK' | 'UNSUBSCRIBE';

type Pattern = RegExp | string;

declare class Trouter<T = Function> {
	find(method: Methods, url: string): {
		params: Record<string, string>;
		handlers: T[];
	};
	add(method: Methods, pattern: Pattern, ...handlers: T[]): this;
	use(pattern: Pattern, ...handlers: T[]): this;
	all(pattern: Pattern, ...handlers: T[]): this;
	get(pattern: Pattern, ...handlers: T[]): this;
	head(pattern: Pattern, ...handlers: T[]): this;
	patch(pattern: Pattern, ...handlers: T[]): this;
	options(pattern: Pattern, ...handlers: T[]): this;
	connect(pattern: Pattern, ...handlers: T[]): this;
	delete(pattern: Pattern, ...handlers: T[]): this;
	trace(pattern: Pattern, ...handlers: T[]): this;
	post(pattern: Pattern, ...handlers: T[]): this;
	put(pattern: Pattern, ...handlers: T[]): this;
}

// Polka

type Promisable<T> = Promise<T> | T;
type ListenCallback = () => Promisable<void>;

declare namespace polka {
	export interface IError extends Error {
		code?: number;
		status?: number;
		details?: any;
	}

	export type NextHandler = (err?: string | IError) => Promisable<void>;
	export type ErrorHandler<T extends Request = Request> = (err: string | IError, req: T, res: Response, next: NextHandler) => Promisable<void>;
	export type Middleware<T extends IncomingMessage = Request> = (req: T & Request, res: Response, next: NextHandler) => Promisable<void>;

	export interface IOptions<T extends Request = Request> {
		server?: Server;
		onNoMatch?: Middleware<T>;
		onError?: ErrorHandler<T>;
	}

	export type Response = ServerResponse;

	export interface Request extends IncomingMessage {
		url: string;
		method: string;
		originalUrl: string;
		params: Record<string, string>;
		path: string;
		search: string;
		query: Record<string,string>;
		body?: any;
		_decoded?: true;
		_parsedUrl: ParsedURL;
	}

	export interface Polka<T extends Request = Request> extends Trouter<Middleware<T>> {
		readonly server: Server;
		readonly wares: Middleware<T>[];

		readonly onError: ErrorHandler<T>;
		readonly onNoMatch: Middleware<T>;

		readonly handler: Middleware<T>;
		parse: (req: IncomingMessage) => ParsedURL;

		use(pattern: RegExp|string, ...handlers: (Polka<T> | Middleware<T>)[]): this;
		use(...handlers: (Polka<T> | Middleware<T>)[]): this;

		listen(port?: number, hostname?: string, backlog?: number, callback?: ListenCallback): this;
		listen(port?: number, hostname?: string, callback?: ListenCallback): this;
		listen(port?: number, backlog?: number, callback?: ListenCallback): this;
		listen(port?: number, callback?: ListenCallback): this;
		listen(path: string, backlog?: number, callback?: ListenCallback): this;
		listen(path: string, callback?: ListenCallback): this;
		listen(options: ListenOptions, callback?: ListenCallback): this;
		listen(handle: any, backlog?: number, callback?: ListenCallback): this;
		listen(handle: any, callback?: ListenCallback): this;
	}
}

declare function polka<T extends polka.Request = polka.Request>(
	options?: polka.IOptions<T>
): polka.Polka<T>;

export = polka;