alien-middleware/router

Functions

routes

Create a router that can be used as middleware in a chain.

export function routes<T extends AnyMiddlewareChain = EmptyMiddlewareChain>(middlewares?: T): Router<T>;

^{🔍 routes on GitHub}

Types

AnyMiddleware

Any request middleware function or middleware chain.

export type AnyMiddleware = Middleware | AnyMiddlewareChain;

^{🔍 AnyMiddleware on GitHub}

AnyMiddleware

Any request middleware function or middleware chain.

export type AnyMiddleware = Middleware | AnyMiddlewareChain;

^{🔍 AnyMiddleware on GitHub}

AnyMiddlewareChain

A value with middleware-chain type metadata.

export type AnyMiddlewareChain<T extends AnyMiddlewareTypes = AnyMiddlewareTypes> = {
    $MiddlewareChain: T;
};

^{🔍 AnyMiddlewareChain on GitHub}

AnyMiddlewareChain

A value with middleware-chain type metadata.

export type AnyMiddlewareChain<T extends AnyMiddlewareTypes = AnyMiddlewareTypes> = {
    $MiddlewareChain: T;
};

^{🔍 AnyMiddlewareChain on GitHub}

AnyMiddlewareTypes

Type metadata for any middleware chain.

type AnyMiddlewareTypes = {
    initial: {
        env: any;
        properties: any;
    };
    current: {
        env: any;
        properties: any;
    };
    runtime: any;
};

^{🔍 AnyMiddlewareTypes on GitHub}

AnyMiddlewareTypes

Type metadata for any middleware chain.

type AnyMiddlewareTypes = {
    initial: {
        env: any;
        properties: any;
    };
    current: {
        env: any;
        properties: any;
    };
    runtime: any;
};

^{🔍 AnyMiddlewareTypes on GitHub}

ApplyFirstMiddleware

Convert a Middleware type into a MiddlewareTypes type.

type ApplyFirstMiddleware<T extends AnyMiddleware> = T extends AnyMiddlewareChain<infer TInternal> ? TInternal : ApplyMiddleware<EmptyMiddlewareChain<MiddlewareRuntime<T>>, T>;

^{🔍 ApplyFirstMiddleware on GitHub}

ApplyFirstMiddleware

Convert a Middleware type into a MiddlewareTypes type.

type ApplyFirstMiddleware<T extends AnyMiddleware> = T extends AnyMiddlewareChain<infer TInternal> ? TInternal : ApplyMiddleware<EmptyMiddlewareChain<MiddlewareRuntime<T>>, T>;

^{🔍 ApplyFirstMiddleware on GitHub}

ApplyMiddleware

This applies a middleware to a chain. If the type TSecond is itself a chain, it's treated as a nested chain, which won't leak its plugins into the parent chain.

The TFirst type is allowed to be never, which results in the middleware's output types being used as the request handler's input types.

export type ApplyMiddleware<TFirst extends AnyMiddlewareChain, TSecond extends AnyMiddleware> = ApplyMiddlewareOutputs<TFirst, TSecond> extends infer TCurrent extends MiddlewareTypes['current'] & {
    runtime: unknown;
} ? {
    initial: CastNever<Inputs<TFirst>, MiddlewareInputs<TSecond>>;
    current: Pick<TCurrent, 'env' | 'properties'>;
    runtime: TCurrent['runtime'];
} : never;

^{🔍 ApplyMiddleware on GitHub}

ApplyMiddleware

This applies a middleware to a chain. If the type TSecond is itself a chain, it's treated as a nested chain, which won't leak its plugins into the parent chain.

The TFirst type is allowed to be never, which results in the middleware's output types being used as the request handler's input types.

export type ApplyMiddleware<TFirst extends AnyMiddlewareChain, TSecond extends AnyMiddleware> = ApplyMiddlewareOutputs<TFirst, TSecond> extends infer TCurrent extends MiddlewareTypes['current'] & {
    runtime: unknown;
} ? {
    initial: CastNever<Inputs<TFirst>, MiddlewareInputs<TSecond>>;
    current: Pick<TCurrent, 'env' | 'properties'>;
    runtime: TCurrent['runtime'];
} : never;

^{🔍 ApplyMiddleware on GitHub}

ApplyMiddlewareOutputs

Outputs produced after appending one middleware or chain to another.

type ApplyMiddlewareOutputs<TFirst extends AnyMiddlewareChain, TSecond extends AnyMiddleware> = TSecond extends AnyMiddlewareChain ? {
    env: Merge<Env<TFirst>, Env<TSecond>>;
    properties: Merge<Properties<TFirst>, Properties<TSecond>>;
    runtime: Runtime<TSecond>;
} : TSecond extends (...args: any[]) => Awaitable<infer TResult> ? ApplyMiddlewareResult<TFirst, Exclude<TResult, Response>> : Current<TFirst> & {
    runtime: Runtime<TFirst>;
};

^{🔍 ApplyMiddlewareOutputs on GitHub}

ApplyMiddlewareOutputs

Outputs produced after appending one middleware or chain to another.

type ApplyMiddlewareOutputs<TFirst extends AnyMiddlewareChain, TSecond extends AnyMiddleware> = TSecond extends AnyMiddlewareChain ? {
    env: Merge<Env<TFirst>, Env<TSecond>>;
    properties: Merge<Properties<TFirst>, Properties<TSecond>>;
    runtime: Runtime<TSecond>;
} : TSecond extends (...args: any[]) => Awaitable<infer TResult> ? ApplyMiddlewareResult<TFirst, Exclude<TResult, Response>> : Current<TFirst> & {
    runtime: Runtime<TFirst>;
};

^{🔍 ApplyMiddlewareOutputs on GitHub}

ApplyMiddlewareResult

Merge a request plugin into a middleware chain.

type ApplyMiddlewareResult<TParent extends AnyMiddlewareChain, TResult> = Eval<{
    env: Merge<Env<TParent>, TResult extends {
        env: infer TEnv extends object | undefined;
    } ? TEnv : undefined>;
    properties: Merge<Properties<TParent>, TResult extends RequestPlugin ? Omit<TResult, keyof ReservedProperties> : undefined>;
    runtime: [TResult] extends [never] ? Runtime<TParent> : TResult extends {
        runtime: infer TRuntime;
    } ? TRuntime : Runtime<TParent>;
}>;

^{🔍 ApplyMiddlewareResult on GitHub}

ApplyMiddlewareResult

Merge a request plugin into a middleware chain.

type ApplyMiddlewareResult<TParent extends AnyMiddlewareChain, TResult> = Eval<{
    env: Merge<Env<TParent>, TResult extends {
        env: infer TEnv extends object | undefined;
    } ? TEnv : undefined>;
    properties: Merge<Properties<TParent>, TResult extends RequestPlugin ? Omit<TResult, keyof ReservedProperties> : undefined>;
    runtime: [TResult] extends [never] ? Runtime<TParent> : TResult extends {
        runtime: infer TRuntime;
    } ? TRuntime : Runtime<TParent>;
}>;

^{🔍 ApplyMiddlewareResult on GitHub}

ApplyMiddlewares

Flatten a list of middlewares into a MiddlewareTypes type.

export type ApplyMiddlewares<T extends AnyMiddleware[]> = T extends [
    ...infer TRest extends AnyMiddleware[],
    infer TLast extends AnyMiddleware
] ? ApplyMiddleware<MiddlewareChain<ApplyMiddlewares<TRest>>, TLast> : ApplyFirstMiddleware<T[0]>;

^{🔍 ApplyMiddlewares on GitHub}

ApplyMiddlewares

Flatten a list of middlewares into a MiddlewareTypes type.

export type ApplyMiddlewares<T extends AnyMiddleware[]> = T extends [
    ...infer TRest extends AnyMiddleware[],
    infer TLast extends AnyMiddleware
] ? ApplyMiddleware<MiddlewareChain<ApplyMiddlewares<TRest>>, TLast> : ApplyFirstMiddleware<T[0]>;

^{🔍 ApplyMiddlewares on GitHub}

Awaitable

A value that may be returned synchronously or through a promise.

type Awaitable<T> = T | Promise<T>;

^{🔍 Awaitable on GitHub}

Awaitable

A value that may be returned synchronously or through a promise.

type Awaitable<T> = T | Promise<T>;

^{🔍 Awaitable on GitHub}

CastNever

Replace never with a fallback type.

type CastNever<T, U> = [T] extends [never] ? U : T;

^{🔍 CastNever on GitHub}

CastNever

Replace never with a fallback type.

type CastNever<T, U> = [T] extends [never] ? U : T;

^{🔍 CastNever on GitHub}

Current

Outputs provided by the end of a middleware chain.

type Current<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['current'];

^{🔍 Current on GitHub}

Current

Outputs provided by the end of a middleware chain.

type Current<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['current'];

^{🔍 Current on GitHub}

EmptyMiddlewareChain

Empty chain type used when starting from no middleware.

export type EmptyMiddlewareChain<TRuntime = unknown> = MiddlewareChain<{
    initial: {
        env: {};
        properties: {};
    };
    current: {
        env: {};
        properties: {};
    };
    runtime: TRuntime;
}>;

^{🔍 EmptyMiddlewareChain on GitHub}

EmptyMiddlewareChain

Empty chain type used when starting from no middleware.

export type EmptyMiddlewareChain<TRuntime = unknown> = MiddlewareChain<{
    initial: {
        env: {};
        properties: {};
    };
    current: {
        env: {};
        properties: {};
    };
    runtime: TRuntime;
}>;

^{🔍 EmptyMiddlewareChain on GitHub}

Env

Environment variables provided by the end of a middleware chain.

type Env<T extends AnyMiddlewareChain> = Current<T>['env'];

^{🔍 Env on GitHub}

Env

Environment variables provided by the end of a middleware chain.

type Env<T extends AnyMiddlewareChain> = Current<T>['env'];

^{🔍 Env on GitHub}

EnvAccessor

The context.env method used to access environment variables.

export type EnvAccessor<TEnv extends object> = {
    <K extends keyof TEnv>(key: Extract<K, string>): TEnv[K];
    (key: never): string | undefined;
};

^{🔍 EnvAccessor on GitHub}

EnvAccessor

The context.env method used to access environment variables.

export type EnvAccessor<TEnv extends object> = {
    <K extends keyof TEnv>(key: Extract<K, string>): TEnv[K];
    (key: never): string | undefined;
};

^{🔍 EnvAccessor on GitHub}

Eval

Expand an object or intersection type into a readable property map.

type Eval<T> = {} & {
    [K in keyof T]: T[K] extends infer U ? U : never;
};

^{🔍 Eval on GitHub}

Eval

Expand an object or intersection type into a readable property map.

type Eval<T> = {} & {
    [K in keyof T]: T[K] extends infer U ? U : never;
};

^{🔍 Eval on GitHub}

ExtractMiddleware

Extract a Middleware type from a MiddlewareChain type.

export type ExtractMiddleware<T extends AnyMiddleware> = [T] extends [never] ? Middleware<{}, {}, any> : T extends AnyMiddlewareChain ? Middleware<Env<T>, Properties<T>, Runtime<T>> : T extends Middleware ? Extract<T, Middleware> : never;

^{🔍 ExtractMiddleware on GitHub}

ExtractMiddleware

Extract a Middleware type from a MiddlewareChain type.

export type ExtractMiddleware<T extends AnyMiddleware> = [T] extends [never] ? Middleware<{}, {}, any> : T extends AnyMiddlewareChain ? Middleware<Env<T>, Properties<T>, Runtime<T>> : T extends Middleware ? Extract<T, Middleware> : never;

^{🔍 ExtractMiddleware on GitHub}

InputEnv

Environment variables required by the start of a middleware chain.

type InputEnv<T extends AnyMiddlewareChain> = Inputs<T>['env'];

^{🔍 InputEnv on GitHub}

InputEnv

Environment variables required by the start of a middleware chain.

type InputEnv<T extends AnyMiddlewareChain> = Inputs<T>['env'];

^{🔍 InputEnv on GitHub}

InputProperties

Context properties required by the start of a middleware chain.

type InputProperties<T extends AnyMiddlewareChain> = Inputs<T>['properties'];

^{🔍 InputProperties on GitHub}

InputProperties

Context properties required by the start of a middleware chain.

type InputProperties<T extends AnyMiddlewareChain> = Inputs<T>['properties'];

^{🔍 InputProperties on GitHub}

Inputs

Inputs required by the start of a middleware chain.

type Inputs<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['initial'];

^{🔍 Inputs on GitHub}

Inputs

Inputs required by the start of a middleware chain.

type Inputs<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['initial'];

^{🔍 Inputs on GitHub}

IsolatedContext

Context visible inside a chain wrapped with MiddlewareChain.isolate().

type IsolatedContext<T extends AnyMiddlewareChain> = RequestContext<InputEnv<T>, InputProperties<T>, Runtime<T>>;

^{🔍 IsolatedContext on GitHub}

IsolatedContext

Context visible inside a chain wrapped with MiddlewareChain.isolate().

type IsolatedContext<T extends AnyMiddlewareChain> = RequestContext<InputEnv<T>, InputProperties<T>, Runtime<T>>;

^{🔍 IsolatedContext on GitHub}

IsOptional

Detect whether a key is optional on an object type.

type IsOptional<T, K> = K extends keyof T ? T[K] extends Required<T>[K] ? false : true : true;

^{🔍 IsOptional on GitHub}

IsOptional

Detect whether a key is optional on an object type.

type IsOptional<T, K> = K extends keyof T ? T[K] extends Required<T>[K] ? false : true : true;

^{🔍 IsOptional on GitHub}

Keys

Collect keys from each object in a union.

type Keys<T> = T extends any ? keyof T : never;

^{🔍 Keys on GitHub}

Keys

Collect keys from each object in a union.

type Keys<T> = T extends any ? keyof T : never;

^{🔍 Keys on GitHub}

Merge

Merge a union of object types (possibly undefined) into a single object type.

FIXME: Optional properties resolve as foo: Foo | undefined instead of foo?: Foo.

type Merge<TSource extends object, TOverrides extends object | undefined> = Eval<Omit<CastNever<TSource, {}>, Keys<TOverrides>> & {
    [K in Keys<TOverrides>]: TOverrides extends any ? MergeProperty<CastNever<TSource, {}>, TOverrides, K> : never;
}>;

^{🔍 Merge on GitHub}

Merge

Merge a union of object types (possibly undefined) into a single object type.

FIXME: Optional properties resolve as foo: Foo | undefined instead of foo?: Foo.

type Merge<TSource extends object, TOverrides extends object | undefined> = Eval<Omit<CastNever<TSource, {}>, Keys<TOverrides>> & {
    [K in Keys<TOverrides>]: TOverrides extends any ? MergeProperty<CastNever<TSource, {}>, TOverrides, K> : never;
}>;

^{🔍 Merge on GitHub}

MergeProperty

Resolve one property after applying an override object to a source object.

type MergeProperty<TSource, TOverrides, K> = (K extends keyof TOverrides ? PossiblyUndefined<TOverrides, K> extends true ? TOverrides[K] : Exclude<TOverrides[K], undefined> : never) | (IsOptional<TOverrides, K> extends true ? K extends keyof TSource ? TSource[K] : undefined : never) extends infer TProperty ? TProperty : never;

^{🔍 MergeProperty on GitHub}

MergeProperty

Resolve one property after applying an override object to a source object.

type MergeProperty<TSource, TOverrides, K> = (K extends keyof TOverrides ? PossiblyUndefined<TOverrides, K> extends true ? TOverrides[K] : Exclude<TOverrides[K], undefined> : never) | (IsOptional<TOverrides, K> extends true ? K extends keyof TSource ? TSource[K] : undefined : never) extends infer TProperty ? TProperty : never;

^{🔍 MergeProperty on GitHub}

Middleware

Middleware that can end the request or extend the downstream context.

export type Middleware<TEnv extends object = any, TProperties extends object = {}, TRuntime = any> = {
    (context: RequestContext<TEnv, TProperties, TRuntime>): Awaitable<Response | RequestPlugin | void>;
    $Middleware?: MiddlewareTypes & {
        initial: {
            env: TEnv;
            properties: TProperties;
        };
    };
};

Remarks

Return a Response to stop request-phase processing, return a RequestPlugin to add context data for later middleware, or return nothing to continue unchanged. Use context.onResponse or a plugin onResponse property to observe or replace the final response.

Properties

• $Middleware This property won't exist at runtime. It contains type information for inference purposes.

^{🔍 Middleware on GitHub}

Middleware

Middleware that can end the request or extend the downstream context.

export type Middleware<TEnv extends object = any, TProperties extends object = {}, TRuntime = any> = {
    (context: RequestContext<TEnv, TProperties, TRuntime>): Awaitable<Response | RequestPlugin | void>;
    $Middleware?: MiddlewareTypes & {
        initial: {
            env: TEnv;
            properties: TProperties;
        };
    };
};

Remarks

Return a Response to stop request-phase processing, return a RequestPlugin to add context data for later middleware, or return nothing to continue unchanged. Use context.onResponse or a plugin onResponse property to observe or replace the final response.

Properties

• $Middleware This property won't exist at runtime. It contains type information for inference purposes.

^{🔍 Middleware on GitHub}

MiddlewareContext

Extract a RequestContext type from a MiddlewareChain type.

When type T is never, a default context is returned.

export type MiddlewareContext<T extends AnyMiddlewareChain | AnyMiddleware[]> = [
    T
] extends [never] ? RequestContext<{}, never, unknown> : T extends AnyMiddlewareChain ? RequestContext<Env<T>, Properties<T>, Runtime<T>> : T extends AnyMiddleware[] ? MiddlewareContext<MiddlewareChain<ApplyMiddlewares<T>>> : never;

^{🔍 MiddlewareContext on GitHub}

MiddlewareContext

Extract a RequestContext type from a MiddlewareChain type.

When type T is never, a default context is returned.

export type MiddlewareContext<T extends AnyMiddlewareChain | AnyMiddleware[]> = [
    T
] extends [never] ? RequestContext<{}, never, unknown> : T extends AnyMiddlewareChain ? RequestContext<Env<T>, Properties<T>, Runtime<T>> : T extends AnyMiddleware[] ? MiddlewareContext<MiddlewareChain<ApplyMiddlewares<T>>> : never;

^{🔍 MiddlewareContext on GitHub}

MiddlewareInputs

Inputs required by a middleware or chain.

type MiddlewareInputs<T extends AnyMiddleware> = T extends AnyMiddlewareChain ? Inputs<T> : T extends Middleware<infer TEnv, infer TProperties> ? {
    env: TEnv;
    properties: TProperties;
} : never;

^{🔍 MiddlewareInputs on GitHub}

MiddlewareInputs

Inputs required by a middleware or chain.

type MiddlewareInputs<T extends AnyMiddleware> = T extends AnyMiddlewareChain ? Inputs<T> : T extends Middleware<infer TEnv, infer TProperties> ? {
    env: TEnv;
    properties: TProperties;
} : never;

^{🔍 MiddlewareInputs on GitHub}

MiddlewareRuntime

Runtime type associated with a middleware or chain.

type MiddlewareRuntime<T extends AnyMiddleware> = T extends AnyMiddlewareChain ? Runtime<T> : T extends Middleware<any, any, infer TRuntime> ? TRuntime : never;

^{🔍 MiddlewareRuntime on GitHub}

MiddlewareRuntime

Runtime type associated with a middleware or chain.

type MiddlewareRuntime<T extends AnyMiddleware> = T extends AnyMiddlewareChain ? Runtime<T> : T extends Middleware<any, any, infer TRuntime> ? TRuntime : never;

^{🔍 MiddlewareRuntime on GitHub}

MiddlewareTypes

Type metadata carried by middleware chains and handlers.

export type MiddlewareTypes<TEnv extends object = object, TProperties extends object = object, TRuntime = unknown> = {
    initial: {
        env: TEnv;
        properties: TProperties;
    };
    current: {
        env: TEnv;
        properties: TProperties;
    };
    runtime: TRuntime;
};

Properties

• initial Values expected by the start of the chain.

• current Values provided by the end of the chain.

• runtime Values from the host runtime.

^{🔍 MiddlewareTypes on GitHub}

MiddlewareTypes

Type metadata carried by middleware chains and handlers.

export type MiddlewareTypes<TEnv extends object = object, TProperties extends object = object, TRuntime = unknown> = {
    initial: {
        env: TEnv;
        properties: TProperties;
    };
    current: {
        env: TEnv;
        properties: TProperties;
    };
    runtime: TRuntime;
};

Properties

• initial Values expected by the start of the chain.

• current Values provided by the end of the chain.

• runtime Values from the host runtime.

^{🔍 MiddlewareTypes on GitHub}

OneOrMany

A single value or a readonly list of values.

type OneOrMany<T> = T | readonly T[];

^{🔍 OneOrMany on GitHub}

PossiblyUndefined

Detect whether a property type accepts undefined.

type PossiblyUndefined<T, K extends keyof T> = undefined extends Required<T>[K] ? true : false;

^{🔍 PossiblyUndefined on GitHub}

PossiblyUndefined

Detect whether a property type accepts undefined.

type PossiblyUndefined<T, K extends keyof T> = undefined extends Required<T>[K] ? true : false;

^{🔍 PossiblyUndefined on GitHub}

Properties

Context properties provided by the end of a middleware chain.

type Properties<T extends AnyMiddlewareChain> = Current<T>['properties'];

^{🔍 Properties on GitHub}

Properties

Context properties provided by the end of a middleware chain.

type Properties<T extends AnyMiddlewareChain> = Current<T>['properties'];

^{🔍 Properties on GitHub}

RequestContext

An extensible Web request context object.

NOTE: When using this type on the right side of an extends clause, you should prefer RequestContext<any> over RequestContext (no type parameters), as the default type is stricter.

export type RequestContext<TEnv extends object = any, TProperties extends object = {}, TRuntime = any> = WebRequestContext<TRuntime, TEnv> & CastNever<TProperties, unknown>;

^{🔍 RequestContext on GitHub}

RequestContext

An extensible Web request context object.

NOTE: When using this type on the right side of an extends clause, you should prefer RequestContext<any> over RequestContext (no type parameters), as the default type is stricter.

export type RequestContext<TEnv extends object = any, TProperties extends object = {}, TRuntime = any> = WebRequestContext<TRuntime, TEnv> & CastNever<TProperties, unknown>;

^{🔍 RequestContext on GitHub}

RequestHandler

Callable middleware chain that always resolves to a Response.

export interface RequestHandler<T extends MiddlewareTypes = any> extends MiddlewareChain<T> {
    (context: RequestContext<any, any, T['runtime']>): Awaitable<Response>;
}

^{🔍 RequestHandler on GitHub}

RequestHandler

Callable middleware chain that always resolves to a Response.

export interface RequestHandler<T extends MiddlewareTypes = any> extends MiddlewareChain<T> {
    (context: RequestContext<any, any, T['runtime']>): Awaitable<Response>;
}

^{🔍 RequestHandler on GitHub}

RequestHost

Host-provided request metadata and lifecycle hooks.

export interface RequestHost<TRuntime = unknown> {
    env?(variable: string): unknown;
    ip?: string;
    runtime?: TRuntime;
    waitUntil?(promise: Promise<unknown>): void;
}

Properties

• env Read an environment variable supplied by the host.

• ip Client IP address supplied by the host, when available.

• runtime Runtime-specific host metadata, such as srvx runtime details.

• waitUntil Schedule work that should continue after a response is produced.

^{🔍 RequestHost on GitHub}

RequestHost

Host-provided request metadata and lifecycle hooks.

export interface RequestHost<TRuntime = unknown> {
    env?(variable: string): unknown;
    ip?: string;
    runtime?: TRuntime;
    waitUntil?(promise: Promise<unknown>): void;
}

Properties

• env Read an environment variable supplied by the host.

• ip Client IP address supplied by the host, when available.

• runtime Runtime-specific host metadata, such as srvx runtime details.

• waitUntil Schedule work that should continue after a response is produced.

^{🔍 RequestHost on GitHub}

RequestMiddleware

A middleware function that runs before a response is finalized.

export type RequestMiddleware<T extends AnyMiddlewareChain = MiddlewareChain> = (context: RequestContext<InputEnv<T>, InputProperties<T>, Runtime<T>>) => Awaitable<Response | RequestPlugin | void>;

^{🔍 RequestMiddleware on GitHub}

RequestMiddleware

A middleware function that runs before a response is finalized.

export type RequestMiddleware<T extends AnyMiddlewareChain = MiddlewareChain> = (context: RequestContext<InputEnv<T>, InputProperties<T>, Runtime<T>>) => Awaitable<Response | RequestPlugin | void>;

^{🔍 RequestMiddleware on GitHub}

RequestPlugin

The object returned by a request middleware and merged into the active request context for downstream middleware.

May contain special properties:

• env: Add type-safe environment variables.
• runtime: Narrow context.host.runtime at the type level.
• onResponse: Register a response callback.

export type RequestPlugin = Record<string, unknown> & ReservedProperties;

Remarks

Plain properties are defined on the request context. If a later plugin uses the same property name, the later descriptor replaces the earlier one.

^{🔍 RequestPlugin on GitHub}

RequestPlugin

The object returned by a request middleware and merged into the active request context for downstream middleware.

May contain special properties:

• env: Add type-safe environment variables.
• runtime: Narrow context.host.runtime at the type level.
• onResponse: Register a response callback.

export type RequestPlugin = Record<string, unknown> & ReservedProperties;

Remarks

Plain properties are defined on the request context. If a later plugin uses the same property name, the later descriptor replaces the earlier one.

^{🔍 RequestPlugin on GitHub}

ReservedProperties

Special request plugin keys consumed by the middleware runner.

type ReservedProperties = {
    env?: object;
    runtime?: object;
    onResponse?: ResponseCallback;
};

Properties

• env Add type-safe environment variables. These are accessed with the env() method on the request context.

• runtime Narrow context.host.runtime for downstream middleware.

• onResponse Intercept the response before it's sent to the client.

^{🔍 ReservedProperties on GitHub}

ReservedProperties

Special request plugin keys consumed by the middleware runner.

type ReservedProperties = {
    env?: object;
    runtime?: object;
    onResponse?: ResponseCallback;
};

Properties

• env Add type-safe environment variables. These are accessed with the env() method on the request context.

• runtime Narrow context.host.runtime for downstream middleware.

• onResponse Intercept the response before it's sent to the client.

^{🔍 ReservedProperties on GitHub}

ResponseCallback

Callback that observes or replaces the generated response.

export type ResponseCallback = (response: Response) => Awaitable<Response | void>;

^{🔍 ResponseCallback on GitHub}

ResponseCallback

Callback that observes or replaces the generated response.

export type ResponseCallback = (response: Response) => Awaitable<Response | void>;

^{🔍 ResponseCallback on GitHub}

RouteContext

Request context passed to a route handler.

export type RouteContext<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<MiddlewareChain<ApplyMiddleware<MiddlewareChain<T['$Router']>, () => {
    params: TPathParams;
    method: TMethod;
}>>>;

^{🔍 RouteContext on GitHub}

RouteContext

Request context passed to a route handler.

export type RouteContext<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<MiddlewareChain<ApplyMiddleware<MiddlewareChain<T['$Router']>, () => {
    params: TPathParams;
    method: TMethod;
}>>>;

^{🔍 RouteContext on GitHub}

RouteHandler

Function invoked when a router path and method match.

export type RouteHandler<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = (context: RouteContext<T, TPathParams, TMethod>) => Awaitable<Response | void>;

^{🔍 RouteHandler on GitHub}

RouteHandler

Function invoked when a router path and method match.

export type RouteHandler<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = (context: RouteContext<T, TPathParams, TMethod>) => Awaitable<Response | void>;

^{🔍 RouteHandler on GitHub}

RouteMethod

HTTP method values accepted by the router.

type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});

^{🔍 RouteMethod on GitHub}

RouteMethod

HTTP method values accepted by the router.

type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});

^{🔍 RouteMethod on GitHub}

Router

Callable router with path and method registration helpers.

export interface Router<T extends AnyMiddlewareChain = any> extends RouterTypes<T> {
    /** Run the router against a request context. */
    (context: RequestContext<any, any, Runtime<T>>): Awaitable<void | Response>;
    use<TPath extends string>(path: TPath, handler: RouteHandler<this, InferParams<TPath>>): Router;
    use<TPath extends string, TMethod extends RouteMethod = RouteMethod>(method: OneOrMany<TMethod> | '*', path: TPath, handler: RouteHandler<this, InferParams<TPath>, TMethod>): Router;
}

Properties

• use Register a handler for any method matching the path pattern.

• use Register a handler for one or more methods matching the path pattern.

^{🔍 Router on GitHub}

RouterContext

Extract the request context type accepted by a router.

export type RouterContext<TRouter extends Router> = TRouter extends Router<infer T> ? MiddlewareContext<T> : never;

^{🔍 RouterContext on GitHub}

Runtime

Host runtime data carried through a middleware chain.

type Runtime<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['runtime'];

^{🔍 Runtime on GitHub}

Runtime

Host runtime data carried through a middleware chain.

type Runtime<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['runtime'];

^{🔍 Runtime on GitHub}

WebRequestContext

Base Web request context shared by all middleware.

export interface WebRequestContext<TRuntime, TEnv extends object> {
    request: Request;
    host: RequestHost<TRuntime>;
    env: EnvAccessor<TEnv>;
    passThrough(): never;
    waitUntil(promise: Promise<unknown>): void;
    url: URL;
    setHeader(name: string, value: string): void;
    onResponse(callback: ResponseCallback): void;
}

Properties

• request The Web request currently being handled.

• host Host metadata and lifecycle hooks for the current request.

• env Type-safe access to environment values.

• passThrough Skip the remaining middleware in the current chain.

• waitUntil Schedule work through host.waitUntil when the host supports it.

• url The request.url string parsed into a URL object. Parsing is performed on-demand and the result is cached.

• setHeader Set a response header from a request middleware.

  Response middlewares should use response.headers.set() instead.

• onResponse Add a callback to be called when a response is generated.

^{🔍 WebRequestContext on GitHub}

WebRequestContext

Base Web request context shared by all middleware.

export interface WebRequestContext<TRuntime, TEnv extends object> {
    request: Request;
    host: RequestHost<TRuntime>;
    env: EnvAccessor<TEnv>;
    passThrough(): never;
    waitUntil(promise: Promise<unknown>): void;
    url: URL;
    setHeader(name: string, value: string): void;
    onResponse(callback: ResponseCallback): void;
}

Properties

• request The Web request currently being handled.

• host Host metadata and lifecycle hooks for the current request.

• env Type-safe access to environment values.

• passThrough Skip the remaining middleware in the current chain.

• waitUntil Schedule work through host.waitUntil when the host supports it.

• url The request.url string parsed into a URL object. Parsing is performed on-demand and the result is cached.

• setHeader Set a response header from a request middleware.

  Response middlewares should use response.headers.set() instead.

• onResponse Add a callback to be called when a response is generated.

^{🔍 WebRequestContext on GitHub}

import { InferParams } from 'pathic';

Classes

MiddlewareChain

Immutable list of request middleware with type metadata for inference.

export class MiddlewareChain<T extends MiddlewareTypes = any> {
    /** This property won't exist at runtime. It contains type information for inference purposes. */
    $MiddlewareChain: T;
    /** The number of parameters when called as a function. */
    readonly length: 1;
    protected [kRequestChain]: RequestMiddleware[];
    /** Number of request middleware functions in this chain. */
    get middlewareCount(): number;
    /**
     * Add a request middleware to the end of the chain.
     *
     * If a middleware chain is given, its middlewares will be executed after any
     * existing middlewares in this chain.
     *
     * @returns a new `MiddlewareChain` instance
     */
    use<const TMiddleware extends ExtractMiddleware<this>>(middleware: TMiddleware | null): RequestHandler<ApplyMiddleware<this, TMiddleware>>;
    /**
     * Create a middleware function that encapsulates this middleware chain, so
     * any modifications it makes to the request context are not leaked.
     */
    isolate(): (ctx: IsolatedContext<this>) => Awaitable<Response | void>;
    /**
     * @internal You should not need to call this method, unless you want a
     * `RequestHandler` type from an empty middleware chain. If your middleware
     * chain is **not** empty, you won't need this.
     */
    toHandler<T2 extends MiddlewareTypes = T>(): RequestHandler<T2>;
}

^{🔍 MiddlewareChain on GitHub}

MiddlewareChain

Immutable list of request middleware with type metadata for inference.

export class MiddlewareChain<T extends MiddlewareTypes = any> {
    /** This property won't exist at runtime. It contains type information for inference purposes. */
    $MiddlewareChain: T;
    /** The number of parameters when called as a function. */
    readonly length: 1;
    protected [kRequestChain]: RequestMiddleware[];
    /** Number of request middleware functions in this chain. */
    get middlewareCount(): number;
    /**
     * Add a request middleware to the end of the chain.
     *
     * If a middleware chain is given, its middlewares will be executed after any
     * existing middlewares in this chain.
     *
     * @returns a new `MiddlewareChain` instance
     */
    use<const TMiddleware extends ExtractMiddleware<this>>(middleware: TMiddleware | null): RequestHandler<ApplyMiddleware<this, TMiddleware>>;
    /**
     * Create a middleware function that encapsulates this middleware chain, so
     * any modifications it makes to the request context are not leaked.
     */
    isolate(): (ctx: IsolatedContext<this>) => Awaitable<Response | void>;
    /**
     * @internal You should not need to call this method, unless you want a
     * `RequestHandler` type from an empty middleware chain. If your middleware
     * chain is **not** empty, you won't need this.
     */
    toHandler<T2 extends MiddlewareTypes = T>(): RequestHandler<T2>;
}

^{🔍 MiddlewareChain on GitHub}

RouterTypes

Type metadata carried by router functions.

class RouterTypes<T extends AnyMiddlewareChain = any> extends Function {
    /** This property won't exist at runtime. It contains type information for inference purposes. */
    $Router: T['$MiddlewareChain'];
}

^{🔍 RouterTypes on GitHub}

RouterTypes

Type metadata carried by router functions.

class RouterTypes<T extends AnyMiddlewareChain = any> extends Function {
    /** This property won't exist at runtime. It contains type information for inference purposes. */
    $Router: T['$MiddlewareChain'];
}

^{🔍 RouterTypes on GitHub}

Constants

kRequestChain

Symbol key for a chain's internal request middleware list.

const kRequestChain: unique symbol;

^{🔍 kRequestChain on GitHub}

kRequestChain

Symbol key for a chain's internal request middleware list.

const kRequestChain: unique symbol;

^{🔍 kRequestChain on GitHub}