Polka Typescript definitions

index.d.ts

/**
 * Potential candidate for @types/polka.
 */

// Type definitions for polka 1.0.0
// Project: https://github.com/lukeed/polka
// Definitions by: Freek Zijlmans <https://github.com/frzi>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 3.0

/// <reference types="node" />
/// <reference types="trouter" />

import { IncomingMessage, ServerResponse } from 'http';
import { Server } from 'net'
import Trouter from 'trouter';

declare function polka(options?: polka.Options): polka.Polka;

declare namespace polka {
	type NextHandler = (err?: Error | string) => void;
	type RequestHandler = (req: IncomingMessage, res: ServerResponse, next?: NextHandler) => void;
	type Middleware = Polka | RequestHandler;

	type ErrorHandler = (err: Error | string, req: IncomingMessage, res: ServerResponse, next: NextHandler) => void;

	interface Options {
		onError?: ErrorHandler;
		onNoMatch?: RequestHandler;
		server?: typeof Server;
	}

	interface URLDescription {
		_raw: string;
		href: string;
		path: string;
		pathname: string;
		query: string | null;
		search: string | null;
	}

	interface Polka extends Trouter<RequestHandler> {
		readonly server: typeof Server;
		readonly wares: RequestHandler[];
		
		readonly onError: ErrorHandler;
		readonly onNoMatch: RequestHandler;

		attach: (req: IncomingMessage, res: ServerResponse) => void;
		parse: (req: IncomingMessage) => URLDescription | void;

		use(...handlers: Middleware[]): this;
		use(pattern: string, ...handlers: Middleware[]): this;

		readonly handler: RequestHandler

		listen: Server['listen'];
	}
}

export = polka;

Overlooked some things~

1. A true next handler receives a string or Error. You have this correctly defined in your RequestHandler type, but for clarity, it should be extracted as its own NextHandler type.

   // new NextHandler
   type NextHandler = (err?: Error | string) => void;
   
   // updated RequestHandler – "next" is always optional
   type RequestHandler = (req: IncomingMessage, res: ServerResponse, next?: NextHandler) => void;

2. That means the existing NextHandler should be renamed, probably to PolkaOrHandler? And it should only be for use() methods.

3. Polka itself only accepts a RequestHandler (the new one, from #1)

   export class Polka extends Trouter<RequestHandler> {
     // ...
   }

4. In the new Polka, the 3rd argument is no longer info. Instead, it's now also an optional next? arg:

   handler(req: IncomingMessage, res: ServerResponse, next?: NextHandler) => void;

   Is there any way to say handler = RequestHandler? Because the signature is the same

5. The onNoMatch handler is just a regular RequestHandler (the new one)

---

import { IncomingMessage, ServerResponse, Server } from 'http';
import Trouter from 'trouter';

declare function polka(options?: polka.Options): polka.Polka;

declare namespace polka {
	type NextHandler = (err?: Error | string) => void;
	type RequestHandler = (req: IncomingMessage, res: ServerResponse, next?: NextHandler) => void;

	type UseHandler = RequestHandler | Polka;
	type ErrorHandler = (err: Error | string, req: IncomingMessage, res: ServerResponse, next?: NextHandler) => void;

	interface Options {
		onError?: ErrorHandler;
		onNoMatch?: RequestHandler;
		server?: typeof Server;
	}

	interface URLDescription {
		path: string;
		pathname: string;
		query: string | null;
		search: string | null;
		href: string;
		_raw: string;
	}

	export class Polka extends Trouter<RequestHandler> {
		readonly server: typeof Server;
		readonly wares: RequestHandler[];
		
		readonly onError: ErrorHandler;
		readonly onNoMatch: RequestHandler;

		parse: (req: IncomingMessage) => URLDescription | void;

		use(...handlers: UseHandler[]): this;
		use(pattern: string, ...handlers: UseHandler[]): this;

		attach: (req: IncomingMessage, res: ServerResponse) => void;
		handler(req: IncomingMessage, res: ServerResponse, next?: NextHandler): void;

		listen(port: number, callback?: (err?: Error) => void): this;
		listen(port: number, hostname: string, callback?: (err?: Error) => void): this;
	}
}

export = polka

Hey hey 👋

Checking in to let you know that wares has been removed