TypeScript

TypeScript API - itty-router

AutoRouterOptions

Options for AutoRouter

type AutoRouterOptions<
  RequestType,
  Args extends any[],
> = {
  missing?: RequestHandler<RequestType, Args>
  format?: ResponseHandler
} & RouterOptions<RequestType, Args>

RequestHandler, ResponseHandler, RouterOptions

AutoRouterType

Type definition for AutoRouter.

type AutoRouterType<
  RequestType = IRequest,
  Args extends any[] = any[],
  ResponseType = any
> = {
  missing?: RequestHandler<RequestType, Args>
  format?: ResponseHandler
} & RouterType<RequestType, Args, ResponseType>

RequestHandler, ResponseHandler, RouterType

ErrorHandler

An advanced error handler, used as the catch stage in AutoRouter and Router. Unlike a normal error handler attached to the .catch(err) block of a Promise chain, this one has access to the original Error as well as the Request (and other args) passed to the .fetch() of the router. This allows for controlled logging of thrown errors.

type ErrorHandler<
  ErrorType extends Error = StatusError,
  RequestType = IRequest, Args extends any[] = any[]
> = (error: ErrorType, request: RequestType, ...args: Args) => any

StatusError, IRequest

GenericTraps internal

Utility type to allow for unspecified attributes on any object. Used in IRequest.

type GenericTraps = Record<string, any>

HasContent

Utility type for extending Request types when expecting POST/PATCH/etc. content after using withContent.

type HasContent<ContentType> = {
  content: ContentType
} & IRequestStrict

IRequestStrict

IRequest

IRequest is the default request type in itty, and is the union of IRequestStrict and GenericTraps. As a result, typical requests have access to both native Request attributes, as well as anything else you may store there.

type IRequest = IRequestStrict & GenericTraps

IRequestStrict

IRequestStrict

IRequestStrict strictly extends Request with the known attributes that itty embeds, such as route, params, and query. Use this instead of IRequest for stricter typings in your API.

type IRequestStrict = {
  route: string
  params: {
    [key: string]: string
  }
  query: {
    [key: string]: string | string[] | undefined
  }
  proxy?: any
} & Request

IttyRouterOptions

Options for IttyRouter. The generic traps are used to allow any instantiated router to accept unknown properties (which will remain on the route itself). With this, you can the router itself, while adding expected properites from your runtime (e.g. { port: 3000 } and such).

type IttyRouterOptions = {
  base?: string
  routes?: RouteEntry[]
} & GenericTraps

RouteEntry, GenericTraps

IttyRouterType internal

Hopefully you'll never need to use this.

type IttyRouterType<
  RequestType = IRequest,
  Args extends any[] = any[],
  ResponseType = any,
> = {
  __proto__: IttyRouterType<RequestType, Args, ResponseType>
  routes: RouteEntry[]
  fetch: <A extends any[] = Args>(request: RequestLike, ...extra: A) => Promise<ResponseType>
  all: Route<RequestType, Args>
  delete: Route<RequestType, Args>
  get: Route<RequestType, Args>
  head: Route<RequestType, Args>
  options: Route<RequestType, Args>
  patch: Route<RequestType, Args>
  post: Route<RequestType, Args>
  put: Route<RequestType, Args>
} & CustomRoutes<Route<RequestType, Args>> & GenericTraps

IRequest, RequestLike, Route, CustomRoutes, GenericTraps

RequestHandler

A generic request handler, as used in route definitions, middleware, and the before stage of AutoRouter and Router.

type RequestHandler<
  RequestType = IRequest,
  Args extends Array<any> = any[]
> = (request: RequestType, ...args: Args) => any

IRequest

RequestLike internal

The bare minimum object type for use in the router's .fetch() method.

type RequestLike = {
  method: string
  url: string
} & GenericTraps

GenericTraps

ResponseFormatter internal

Used to format content into a valid Response object within createResponse().

type ResponseFormatter =
  (body?: any, options?: ResponseInit) => Response

ResponseHandler

This is for downstream handlers in the finally stage of AutoRouter and Router. Each ResponseHandler has access to a response, a request, and any additional arguments provided to the router's .fetch() method.

type ResponseHandler<
  ResponseType = Response, 
  RequestType = IRequest, 
  Args extends any[] = any[]
> = (
  response: ResponseType & any, 
  request: RequestType & any, 
  ...args: Args
) => any

IRequest

Route internal

This allows you to overwrite request/args using generics at the route-level. Bonus points if you can follow this.

type Route<
  R = IRequest,
  A extends Array<any> = any[],
> = <
  RequestType = R,
  Args extends Array<any> = A,
>(
  path: string,
  ...handlers: RequestHandler<RequestType, Args>[]
) => IttyRouterType<R, A>

RouteEntry advanced

If you plan to manually modify the .routes collection on a router manually, this is the format you'll need for each entry.

type RouteEntry<RequestType = IRequest, Args extends any[] = any[]> = [
  httpMethod: string,
  match: RegExp,
  handlers: RequestHandler<RequestType, Args>[],
  path?: string,
]

RequestHandler, IRequest

RouterOptions

Options for Router. This adds a before, catch, and finally stage to IttyRouterOptions.

type RouterOptions<
  RequestType = IRequest,
  Args extends any[] = [],
> = {
  before?: RequestHandler<RequestType, Args>[]
  catch?: ErrorHandler<StatusError, RequestType, Args>
  finally?: ResponseHandler<any, RequestType, Args>[]
} & IttyRouterOptions

RequestHandler, ErrorHandler, ResponseHandler, IttyRouterOptions, StatusError

RouterType

Type for Router. This adds a before, catch, and finally stage to IttyRouterType.

type RouterType<
  RequestType = IRequest,
  Args extends any[] = any[],
  ResponseType = any
> = {
  before?: RequestHandler<RequestType, Args>[]
  catch?: ErrorHandler<StatusError, RequestType, Args>
  finally?: ResponseHandler<any, RequestType, Args>[]
} & IttyRouterType<RequestType, Args, ResponseType>

RequestHandler, ErrorHandler, ResponseHandler, IttyRouterType, StatusError

StatusError

Type for StatusError

type StatusError = {
  status: number
  [key: string]: any
} & Error