@mpen/routekit 0.1.0 → 0.1.2

package/src/router/types.ts

@@ -1,657 +0,0 @@
-import type { HttpMethod } from '@mpen/http'
-import type { Logger } from '@mpen/logger'
-import type { Router } from './router'
-import type { RouterBodyInit } from './fetch-types'
-import type { DeclaredMiddleware } from './middleware/define'
-import type { RequestBodyParser, RoutekitRequest } from './request'
-import type {
-    ResponseBodySerializer,
-    RoutekitBody,
-    RoutekitResponse,
-    RoutekitYield,
-} from './response'
-
-export type NonEmptyArray<T> = [T, ...T[]]
-export type OneOrMany<T> = T | NonEmptyArray<T>
-export type MaybePromise<T> = T | Promise<T>
-export type RoutePath = string | URLPattern
-
-/**
- * JSON Schema value used for runtime request and response metadata.
- */
-export type JsonSchema = boolean | Record<string, unknown>
-
-/**
- * JSON Schema object used for path and query parameter declarations.
- */
-export type JsonObjectSchema = Record<string, unknown>
-
-/**
- * Schema metadata used to describe route request inputs and response bodies.
- *
- * @example
- * ```ts
- * const schema: RouteSchema = {
- *   request: {
- *     query: {
- *       type: 'object',
- *       properties: {
- *         page: {type: 'integer'},
- *       },
- *     },
- *     path: {
- *       type: 'object',
- *       properties: {
- *         id: {type: 'string'},
- *       },
- *       required: ['id'],
- *     },
- *     body: {
- *       type: 'object',
- *       properties: {
- *         name: {type: 'string'},
- *       },
- *       required: ['name'],
- *     },
- *   },
- *   response: {
- *     body: {
- *       200: {
- *         type: 'object',
- *         properties: {
- *           ok: {type: 'boolean'},
- *         },
- *         required: ['ok'],
- *       },
- *     },
- *   },
- * }
- * ```
- */
-export interface RouteSchema {
-    request?: {
-        query?: JsonObjectSchema
-        path?: JsonObjectSchema
-        body?: JsonSchema
-    }
-    response?: {
-        body?: Partial<Record<number | 'default', JsonSchema>>
-    }
-}
-
-/**
- * Custom request matcher used when a route needs logic beyond pathname, method, or `accept`.
- *
- * @example
- * ```ts
- * const match: RouteMatch = request => request.headers.get('x-internal') === 'true'
- * ```
- *
- * @param request - Incoming request to test.
- * @returns `true` when the route should handle the request.
- */
-export type RouteMatch = (request: RoutekitRequest) => boolean
-
-/**
- * Route metadata used by tooling like OpenAPI generation.
- */
-export interface RouteMeta {
-    /**
-     * OpenAPI operation metadata for this route.
-     */
-    openapi?: Record<string, unknown>
-    [key: string]: unknown
-}
-
-type AddedContextOf<Middleware> =
-    Exclude<Middleware, null | undefined | false> extends DeclaredMiddleware<infer AddedCtx, any>
-        ? AddedCtx
-        : Exclude<Middleware, null | undefined | false> extends ContextMiddleware<
-                infer AddedCtx,
-                any
-            >
-          ? AddedCtx
-          : Exclude<Middleware, null | undefined | false> extends RequestMiddleware<
-                  infer AddedCtx,
-                  any
-              >
-            ? AddedCtx
-            : {}
-
-type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (
-    value: infer Intersection,
-) => void
-    ? Intersection
-    : never
-
-type AddedContextFromList<List extends readonly unknown[]> = List extends readonly [
-    infer First,
-    ...infer Rest,
-]
-    ? AddedContextOf<First> & AddedContextFromList<Rest>
-    : number extends List['length']
-      ? UnionToIntersection<AddedContextOf<List[number]>>
-      : {}
-
-type ContextOf<Middleware> =
-    Exclude<Middleware, null | undefined | false> extends DeclaredMiddleware<any, infer Ctx>
-        ? Ctx
-        : Exclude<Middleware, null | undefined | false> extends ContextMiddleware<any, infer Ctx>
-          ? Ctx
-          : Exclude<Middleware, null | undefined | false> extends RequestMiddleware<any, infer Ctx>
-            ? Ctx
-            : object
-
-type ContextFromList<List extends readonly unknown[]> = List extends readonly [
-    infer First,
-    ...infer Rest,
-]
-    ? ContextOf<First> & ContextFromList<Rest>
-    : number extends List['length']
-      ? UnionToIntersection<ContextOf<List[number]>>
-      : object
-
-/**
- * Context added by a middleware value or middleware list.
- *
- * @example
- * ```ts
- * type AuthContext = AddedContextFromMiddlewareInput<typeof requireAuth>
- * ```
- *
- * @typeParam Middleware - Middleware value or list whose added context should be inferred.
- */
-export type AddedContextFromMiddlewareInput<Middleware> = Middleware extends readonly unknown[]
-    ? AddedContextFromList<Middleware>
-    : AddedContextOf<Middleware>
-
-/**
- * Base context expected by a middleware value or middleware list.
- *
- * @example
- * ```ts
- * type ServicesContext = ContextFromMiddlewareInput<typeof requireAuth>
- * ```
- *
- * @typeParam Middleware - Middleware value or list whose base context should be inferred.
- */
-export type ContextFromMiddlewareInput<Middleware> = Middleware extends readonly unknown[]
-    ? ContextFromList<Middleware>
-    : ContextOf<Middleware>
-
-/**
- * Declarative route definition that the router can normalize and register.
- *
- * @example
- * ```ts
- * const route: Route = {
- *   name: 'user.detail',
- *   method: HttpMethod.GET,
- *   path: '/users/:id',
- *   handler: async ({request}) => new Response(await request.body.text()),
- * }
- * ```
- */
-export interface Route<
-    Ctx extends object = AnyContext,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
-    HandlerCtx extends object = Ctx & AddedContextFromMiddlewareInput<RouteMiddleware>,
-> {
-    name?: OneOrMany<string>
-    /**
-     * Path pattern matched by the default route matcher.
-     */
-    path: RoutePath
-    handler: Handler<any, HandlerCtx>
-    method?: OneOrMany<HttpMethod>
-    /**
-     * Middleware applied only to this route after router and mount middleware.
-     *
-     * @example
-     * ```ts
-     * const route: Route = {
-     *   path: '/me',
-     *   middleware: auth(),
-     *   handler: ({userId}) => new Response(userId),
-     * }
-     * ```
-     */
-    middleware?: RouteMiddleware
-    /**
-     * Optional custom matcher. When omitted, the router matches using `path`, `method`, and `accept`.
-     */
-    match?: RouteMatch
-    /**
-     * Arbitrary metadata attached to the route.
-     *
-     * @example
-     * ```ts
-     * const route: Route = {
-     *   path: '/pets',
-     *   method: HttpMethod.GET,
-     *   meta: {
-     *     openapi: {
-     *       description: 'Returns all pets from the system that the user has access to',
-     *       responses: {
-     *         200: {description: 'A list of pets'},
-     *       },
-     *     },
-     *   },
-     *   handler: () => new Response('ok'),
-     * }
-     * ```
-     */
-    meta?: RouteMeta
-    /**
-     * Expected media type(s) for the incoming request body. When provided, the router compares each
-     * entry against the incoming `Content-Type` header.
-     *
-     * @example
-     * ```ts
-     * const route: Route = {
-     *   path: '/upload',
-     *   method: HttpMethod.POST,
-     *   accept: ['multipart/form-data', {type: 'application/json'}],
-     *   handler: async () => new Response('ok'),
-     * }
-     * ```
-     */
-    accept?: OneOrMany<string | MediaType>
-    /**
-     * Runtime request and response schemas used by tooling such as OpenAPI generation and API client codegen.
-     */
-    schema?: RouteSchema
-}
-
-/**
- * Route definition fields accepted by method-specific router helpers.
- *
- * @example
- * ```ts
- * const options: RouteOptions = {
- *   name: 'user.detail',
- *   handler: async ({request}) => new Response(request.url),
- * }
- * router.get('/users/:id', options)
- * ```
- */
-export type RouteOptions<
-    Ctx extends object = AnyContext,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
-    HandlerCtx extends object = Ctx & AddedContextFromMiddlewareInput<RouteMiddleware>,
-> = Omit<Route<Ctx, RouteMiddleware, HandlerCtx>, 'method' | 'path'>
-
-/**
- * Normalized route metadata used internally by the router.
- *
- * @example
- * ```ts
- * const route: NormalizedRoute = {
- *   name: ['user', 'detail'],
- *   method: HttpMethod.GET,
- *   path: new URLPattern({pathname: '/users/:id'}),
- *   handler: async ({request}) => new Response(await request.body.text()),
- * }
- * ```
- */
-export interface NormalizedRoute<Ctx extends object = AnyContext> {
-    name: string[]
-    path: URLPattern
-    handler: Handler<any, Ctx>
-    method?: HttpMethod | HttpMethod[]
-    accept?: MediaType[]
-    match?: RouteMatch
-    meta?: RouteMeta
-    schema?: RouteSchema
-}
-
-/**
- * Parameterized HTTP `Content-Type` media type.
- *
- * @example
- * ```ts
- * const contentType: ContentType = {type: 'application/json', charset: 'utf-8'}
- * ```
- */
-export type ContentType = {
-    type: string
-    charset?: string
-    boundary?: string
-    parameters?: Record<string, string>
-}
-
-/**
- * Backwards-compatible alias for a concrete media type.
- *
- * @example
- * ```ts
- * const media: MediaType = {type: 'application/json'}
- * ```
- */
-export type MediaType = ContentType
-
-/**
- * Media range parsed from an HTTP `Accept` header.
- *
- * @example
- * ```ts
- * const accept: AcceptMediaRange = {type: 'application/json', q: 1}
- * ```
- */
-export type AcceptMediaRange = ContentType & {
-    q: number
-}
-
-/**
- * Generic context dictionary used when no custom context type is provided.
- *
- * @example
- * ```ts
- * const ctx: AnyContext = {featureFlag: true}
- * ```
- */
-export type AnyContext = Record<string, any>
-
-/**
- * Extension hook that intentionally configures a router instance.
- *
- * @example
- * ```ts
- * const extension: RouterExtension = router => {
- *   router.onNotFound(() => new Response('missing', {status: 404}))
- * }
- *
- * new Router().install(extension)
- * ```
- *
- * @typeParam Ctx - Context carried by the router being configured.
- */
-export type RouterExtension<Ctx extends object = AnyContext> = (router: Router<Ctx>) => void
-
-/**
- * Request context made available to middleware.
- * Extended data can be attached by middleware via the generic parameter.
- *
- * @example
- * ```ts
- * const middleware: ContextMiddleware<{userId: string}> = ctx => {
- *   ctx.userId = 'user-123'
- * }
- * ```
- */
-export type RequestContext<Ctx extends object = AnyContext> = {
-    /**
-     * Routekit request wrapper for the current request.
-     */
-    request: RoutekitRequest
-    /**
-     * Contextual logger selected for the current request.
-     */
-    logger: Logger
-} & Ctx
-
-/**
- * Context object provided to route handlers.
- * Includes request metadata as well as any context extensions added by middleware.
- *
- * @example
- * ```ts
- * const handler: HandlerContext = {
- *   request,
- *   url: new URL('https://example.com/users/123'),
- *   path: {id: '123'},
- * }
- * ```
- */
-export type HandlerContext<Ctx extends object = AnyContext> = RequestContext<Ctx> & {
-    /**
-     * Parsed request URL for convenience.
-     */
-    url: URL
-    /**
-     * Route path parameters extracted from the matched URL pattern.
-     */
-    path: unknown
-}
-
-/**
- * Values yielded by generator-style handlers.
- *
- * @example
- * ```ts
- * async function* handler() {
- *   yield head(HttpStatus.OK, {'cache-control': 'no-store'})
- *   return {ok: true}
- * }
- * ```
- */
-export type HandlerYield = RoutekitYield
-
-/**
- * Native body value that can be passed to the Fetch [`Response`]{@link Response} constructor.
- *
- * @example
- * ```ts
- * const body: HandlerBody = 'ok'
- * ```
- */
-export type HandlerBody = RouterBodyInit | null | undefined
-
-/**
- * Final value a handler or generator may return.
- */
-export type HandlerFinalResult<TOkRes = unknown> =
-    | Response
-    | RoutekitResponse<TOkRes>
-    | RoutekitBody<TOkRes>
-    | TOkRes
-    | HandlerBody
-
-/**
- * Allowed handler return values.
- *
- * @example
- * ```ts
- * const handler: Handler = async ({request}) => new Response(await request.body.text())
- * ```
- */
-export type HandlerResult<TOkRes = unknown> =
-    | HandlerFinalResult<TOkRes>
-    | Promise<HandlerFinalResult<TOkRes> | AsyncGenerator<HandlerYield, HandlerFinalResult<TOkRes>>>
-    | AsyncGenerator<HandlerYield, HandlerFinalResult<TOkRes>>
-
-/**
- * Route handler signature that preserves generic type parameters for API generation.
- *
- * @example
- * ```ts
- * const handler: Handler = ({path}) => {
- *   return JSON.stringify(path)
- * }
- * ```
- *
- * The handler is invoked with `this` bound to the active [`Router`]{@link Router}.
- *
- * @param ctx - Handler context containing the incoming [`RoutekitRequest`]{@link RoutekitRequest}, parsed [`URL`]{@link URL}, path parameters, and middleware extensions.
- * @returns A response, a serializable value handled by middleware, or a streaming generator that yields response metadata.
- */
-export type Handler<TOkRes = unknown, Ctx extends object = AnyContext> = (
-    this: Router<any>,
-    ctx: HandlerContext<Ctx>,
-) => HandlerResult<TOkRes>
-
-/**
- * Middleware that extends request context and then continues routing.
- *
- * @example
- * ```ts
- * const addRequestId = (): ContextMiddleware<{requestId: number}> => ctx => {
- *   ctx.requestId = 123
- * }
- * ```
- *
- * @param ctx - Request context for the current request, including any added fields.
- * @returns Nothing, or a promise resolved after context initialization.
- */
-export type ContextMiddleware<
-    AddedCtx extends object = AnyContext,
-    Ctx extends object = AnyContext,
-> = (ctx: RequestContext<Ctx & AddedCtx>) => void | Promise<void>
-
-/**
- * Middleware that surrounds final response production for every incoming request.
- *
- * @example
- * ```ts
- * const timing: RequestMiddleware = async (ctx, next) => {
- *   const started = performance.now()
- *   const response = await next()
- *   ctx.logger.info('completed', {duration: performance.now() - started})
- *   return response
- * }
- * ```
- *
- * @param ctx - Request context shared with downstream middleware and handlers.
- * @param next - Continue processing and obtain the final response.
- * @returns The final response, optionally decorated by the middleware.
- * @typeParam AddedCtx - Context fields made available to downstream processing.
- * @typeParam Ctx - Context required before this middleware executes.
- */
-export type RequestMiddleware<AddedCtx extends object = {}, Ctx extends object = AnyContext> = (
-    ctx: HandlerContext<Ctx & AddedCtx>,
-    next: () => Promise<Response>,
-) => Response | Promise<Response>
-
-/**
- * Middleware entry accepted inside typed middleware lists.
- *
- * @example
- * ```ts
- * const middleware = [auth(), false] satisfies MiddlewareEntry[]
- * ```
- *
- * @typeParam Ctx - Base context available before this middleware runs.
- */
-export type MiddlewareEntry<Ctx extends object = AnyContext> =
-    | ContextMiddleware<any, Ctx>
-    | DeclaredMiddleware<any, Ctx>
-    | null
-    | undefined
-    | false
-
-/**
- * Middleware that performs context-only request initialization.
- *
- * @example
- * ```ts
- * const middleware: Middleware = ctx => {
- *   ctx.request.headers.get('accept')
- * }
- * ```
- *
- * @param ctx - Request context for the current request.
- * @returns Nothing, or a promise resolved after context initialization.
- */
-export type Middleware<Ctx extends object = AnyContext> = ContextMiddleware<{}, Ctx>
-
-/**
- * Middleware list container for registering multiple middleware entries.
- *
- * @example
- * ```ts
- * const middleware: MiddlewareList = [auth(), logging()]
- * ```
- *
- * @param list - Collection of middleware entries, optionally including falsy values.
- * @returns A list of middleware compatible with `Router.use`.
- */
-export type MiddlewareList<Ctx extends object = AnyContext> = ReadonlyArray<MiddlewareEntry<Ctx>>
-
-/**
- * Middleware value accepted by router middleware registration APIs.
- *
- * @example
- * ```ts
- * const input: MiddlewareInput = [auth(), logging()]
- * ```
- *
- * @typeParam Ctx - Base context available before this middleware runs.
- */
-export type MiddlewareInput<Ctx extends object = AnyContext> =
-    | OneOrMany<MiddlewareEntry<Ctx>>
-    | MiddlewareList<Ctx>
-    | null
-    | undefined
-    | false
-
-/**
- * Request-boundary middleware entry accepted by [`Router.useRequest`]{@link Router#useRequest}.
- *
- * @typeParam Ctx - Base context available before this middleware runs.
- */
-export type RequestMiddlewareEntry<Ctx extends object = AnyContext> =
-    | RequestMiddleware<any, Ctx>
-    | null
-    | undefined
-    | false
-
-/**
- * Request-boundary middleware input accepted by [`Router.useRequest`]{@link Router#useRequest}.
- *
- * @typeParam Ctx - Base context available before this middleware runs.
- */
-export type RequestMiddlewareInput<Ctx extends object = AnyContext> =
-    | OneOrMany<RequestMiddlewareEntry<Ctx>>
-    | ReadonlyArray<RequestMiddlewareEntry<Ctx>>
-    | null
-    | undefined
-    | false
-
-/**
- * Request body parser value accepted by router request body parser APIs.
- *
- * @example
- * ```ts
- * const input: RequestBodyParserInput = [jsonRequestBodyParser()]
- * ```
- */
-export type RequestBodyParserInput =
-    | RequestBodyParser
-    | ReadonlyArray<RequestBodyParser | null | undefined | false>
-    | null
-    | undefined
-    | false
-
-/**
- * Response body serializer value accepted by router response body serializer APIs.
- *
- * @example
- * ```ts
- * const input: ResponseBodySerializerInput = [jsonResponseBodySerializer()]
- * ```
- */
-export type ResponseBodySerializerInput =
-    | ResponseBodySerializer
-    | ReadonlyArray<ResponseBodySerializer | null | undefined | false>
-    | null
-    | undefined
-    | false
-
-/**
- * Options for mounting a router or configuring a scoped inline router.
- *
- * @example
- * ```ts
- * const options: RouterMountOptions = {prefix: '/admin', middleware: auth()}
- * ```
- */
-export interface RouterMountOptions<Ctx extends object = AnyContext> {
-    /**
-     * Optional pathname prefix for the mounted routes.
-     */
-    prefix?: string
-    /**
-     * Middleware applied to the mounted router scope.
-     */
-    middleware?: MiddlewareInput<Ctx>
-}