@taserjs/router 0.0.0

package/dist/esm/types/index.d.ts

@@ -0,0 +1,305 @@
+import { Awaitable, TaserCookieJar, TaserHeaders } from '@taserjs/router-core';
+import { ReplyResult } from '@taserjs/router-utils';
+import { RouterRegister } from '../register.js';
+import { MergeMiddlewareField, MergeMiddlewareInputField, MergePart, RequestShape, RuntimeContextFields, Simplify } from './type-utils.js';
+import { ReturnsMap, ValidHandlerReply } from './returns.js';
+import { Schema } from './schema.js';
+import { AppContext, HandlerContext, HandlerUnit, Method, MiddlewareDefinition, MiddlewareReturnFromParts, MiddlewareUnit, NativeContext, ValidatorParts } from './units.js';
+export type { Awaitable } from '@taserjs/router-core';
+export type { SchemaRequestShape, InferInput, InferOutput, Schema, StandardSchemaV1, } from './schema.js';
+export type { RouterRegister } from '../register.js';
+export type { MergeMiddlewareField, MergeMiddlewareInputField, MergePart, RequestShape, Simplify, UnwrapPart, } from './type-utils.js';
+export type { EmptyReturns, EnforceHandlerReply, HandlerReply, HasReturns, MergeReturns, ReplyResultFor, ReturnsMap, StatusCode, ValidHandlerReply, } from './returns.js';
+export type { AppContext, HandlerContext, HandlerUnit, HttpMethod, InlineMiddlewareOptions, Method, MiddlewareDefinition, MiddlewareNext, MiddlewareReturnFromParts, MiddlewareUnit, NativeContext, StandaloneMiddlewareContext, ValidatorParts, } from './units.js';
+export type RoutePath = RouterRegister extends {
+    RoutePath: infer P;
+} ? P : never;
+export type LayoutId = RouterRegister extends {
+    LayoutId: infer L;
+} ? L : never;
+export type LayoutTree = RouterRegister extends {
+    LayoutTree: infer T;
+} ? T : Record<never, never>;
+export type RouteByPathMethod = RouterRegister extends {
+    RouteByPathMethod: infer R;
+} ? R : Record<never, never>;
+type ParseParam<Segment extends string> = Segment extends '*' ? {
+    _splat: string;
+} : Segment extends `:${infer Name extends string}` ? Name extends '' ? {} : {
+    [K in Name]: string;
+} : {};
+type ParseParamsFromSegments<S extends string> = S extends `${infer Segment}/${infer Rest}` ? ParseParam<Segment> & ParseParamsFromSegments<Rest> : ParseParam<S>;
+export type PathParams<Path extends string> = Path extends `/${infer Rest}` ? ParseParamsFromSegments<Rest> : {};
+type LayoutParent<Layout extends LayoutId> = LayoutTree[Layout] extends {
+    parent: infer Parent extends LayoutId | null;
+} ? Parent : null;
+type ResolveLayoutMiddlewares<Layout extends LayoutId | null> = Layout extends null ? readonly [] : Layout extends LayoutId ? readonly [
+    ...ResolveLayoutMiddlewares<LayoutParent<Layout>>,
+    ...LayoutTree[Layout]['middlewares']
+] : readonly [];
+/** Fold layout middleware Acc from a route's layoutChain (shallow → deep). */
+type ResolveLayoutChainMiddlewares<Chain extends readonly LayoutId[]> = Chain extends readonly [infer Head extends LayoutId, ...infer Rest] ? readonly [
+    ...LayoutTree[Head]['middlewares'],
+    ...ResolveLayoutChainMiddlewares<Rest extends readonly LayoutId[] ? Rest : readonly []>
+] : readonly [];
+type RouteEntry<Path extends RoutePath, TMethod extends Method> = RouteByPathMethod[Path] extends {
+    [K in TMethod]: infer Entry;
+} ? Entry : never;
+type RouteParent<Path extends RoutePath, TMethod extends Method> = RouteEntry<Path, TMethod> extends {
+    parent: infer Parent extends LayoutId | null;
+} ? Parent : null;
+type RouteLayoutChain<Path extends RoutePath, TMethod extends Method> = RouteEntry<Path, TMethod> extends {
+    layoutChain: infer Chain extends readonly LayoutId[];
+} ? Chain : RouteParent<Path, TMethod> extends LayoutId ? readonly [RouteParent<Path, TMethod>] : readonly [];
+type RouteResolvedField<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Field extends 'query' | 'params' | 'body' | 'state' | 'ctx'> = MergeMiddlewareField<ResolveLayoutChainMiddlewares<RouteLayoutChain<Path, TMethod>>, Field> & MergeMiddlewareField<Acc, Field>;
+type MiddlewareCtxField<Layout extends LayoutId, Field extends 'query' | 'params' | 'body' | 'state' | 'ctx'> = MergeMiddlewareField<ResolveLayoutMiddlewares<LayoutParent<Layout>>, Field>;
+type RouteChainField<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Field extends 'query' | 'params' | 'body' | 'state' | 'ctx'> = RouteResolvedField<Path, TMethod, Acc, Field>;
+type UnitRuntimeContext = RuntimeContextFields<NativeContext>;
+export type RouteChainContext<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], TQuery, TParams, TBody, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & RouteChainField<Path, TMethod, Acc, 'ctx'> & {
+    query: Simplify<MergePart<TQuery, RouteChainField<Path, TMethod, Acc, 'query'>>>;
+    params: Simplify<PathParams<Path> & MergePart<TParams, RouteChainField<Path, TMethod, Acc, 'params'>>>;
+    body: Simplify<MergePart<TBody, RouteChainField<Path, TMethod, Acc, 'body'>>>;
+    state: Simplify<RouteChainField<Path, TMethod, Acc, 'state'>>;
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+export type RouteHandleContext<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends {
+    query?: unknown;
+    params?: unknown;
+    body?: unknown;
+}, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & RouteResolvedField<Path, TMethod, Acc, 'ctx'> & {
+    path: Path;
+    method: TMethod;
+    query: Simplify<MergePart<Validators extends {
+        query?: infer Q;
+    } ? Q : unknown, RouteResolvedField<Path, TMethod, Acc, 'query'>>>;
+    params: Simplify<PathParams<Path> & MergePart<Validators extends {
+        params?: infer P;
+    } ? P : unknown, RouteResolvedField<Path, TMethod, Acc, 'params'>>>;
+    body: Simplify<MergePart<Validators extends {
+        body?: infer B;
+    } ? B : unknown, RouteResolvedField<Path, TMethod, Acc, 'body'>>>;
+    state: Simplify<RouteResolvedField<Path, TMethod, Acc, 'state'>>;
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+export type RouteHandleContextWithoutBody<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends {
+    query?: unknown;
+    params?: unknown;
+}, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & RouteResolvedField<Path, TMethod, Acc, 'ctx'> & {
+    path: Path;
+    method: TMethod;
+    query: Simplify<MergePart<Validators extends {
+        query?: infer Q;
+    } ? Q : unknown, RouteResolvedField<Path, TMethod, Acc, 'query'>>>;
+    params: Simplify<PathParams<Path> & MergePart<Validators extends {
+        params?: infer P;
+    } ? P : unknown, RouteResolvedField<Path, TMethod, Acc, 'params'>>>;
+    body: never;
+    state: Simplify<RouteResolvedField<Path, TMethod, Acc, 'state'>>;
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+type RouteResolvedInputField<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Field extends 'query' | 'params' | 'body'> = MergeMiddlewareInputField<ResolveLayoutChainMiddlewares<RouteLayoutChain<Path, TMethod>>, Field> & MergeMiddlewareInputField<Acc, Field>;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsEmptyObject<T> = [keyof T] extends [never] ? true : false;
+type InputFacet<T, K extends string> = IsNever<T> extends true ? {} : IsEmptyObject<T> extends true ? {} : {
+    [Key in K]: T;
+};
+type RouteQueryInput<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts> = Simplify<MergePart<RequestShape<Validators extends {
+    queryIn?: infer QI;
+} ? QI : unknown, Validators extends {
+    query?: infer Q;
+} ? Q : unknown>, RouteResolvedInputField<Path, TMethod, Acc, 'query'>>>;
+type RouteParamsInput<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts> = Simplify<PathParams<Path> & MergePart<RequestShape<Validators extends {
+    paramsIn?: infer PI;
+} ? PI : unknown, Validators extends {
+    params?: infer P;
+} ? P : unknown>, RouteResolvedInputField<Path, TMethod, Acc, 'params'>>>;
+type RouteBodyInput<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts> = Simplify<MergePart<RequestShape<Validators extends {
+    bodyIn?: infer BI;
+} ? BI : unknown, Validators extends {
+    body?: infer B;
+} ? B : unknown>, RouteResolvedInputField<Path, TMethod, Acc, 'body'>>>;
+export type RouteHandleInputWithoutBody<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts = {}> = Simplify<InputFacet<RouteQueryInput<Path, TMethod, Acc, Validators>, 'query'> & InputFacet<RouteParamsInput<Path, TMethod, Acc, Validators>, 'params'>>;
+export type RouteHandleInput<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts = {}> = Simplify<RouteHandleInputWithoutBody<Path, TMethod, Acc, Validators> & InputFacet<RouteBodyInput<Path, TMethod, Acc, Validators>, 'body'>>;
+export type InferRouteInput<Path extends RoutePath, TMethod extends Method> = RouteEntry<Path, TMethod> extends {
+    route: infer Route;
+} ? Route extends {
+    $Infer: {
+        Input: infer I;
+    };
+} ? I : never : never;
+type MiddlewareChainField<Layout extends LayoutId, Acc extends readonly unknown[], Field extends 'query' | 'params' | 'body' | 'state' | 'ctx'> = MiddlewareCtxField<Layout, Field> & MergeMiddlewareField<Acc, Field>;
+export type MiddlewareChainContext<Layout extends LayoutId, Acc extends readonly unknown[], TQuery, TParams, TBody, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & MiddlewareChainField<Layout, Acc, 'ctx'> & {
+    query: Simplify<MergePart<TQuery, MiddlewareChainField<Layout, Acc, 'query'>>>;
+    params: Simplify<MergePart<TParams, MiddlewareChainField<Layout, Acc, 'params'>>>;
+    body: Simplify<MergePart<TBody, MiddlewareChainField<Layout, Acc, 'body'>>>;
+    state: Simplify<MiddlewareChainField<Layout, Acc, 'state'>>;
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+type StatefulUseOptions<Ctx, TState, TQuery, TParams, TBody, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown> = {
+    state: Schema<TState>;
+    query?: Schema<TQuery, TQueryIn>;
+    params?: Schema<TParams, TParamsIn>;
+    body?: Schema<TBody, TBodyIn>;
+    returns?: TReturns;
+    handler: (ctx: Ctx, next: (args: {
+        state: TState;
+    }) => Promise<ReplyResult>) => Awaitable<ReplyResult | Response | unknown>;
+};
+type CtxUseOptions<Ctx, TCtx, TQuery, TParams, TBody, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown> = {
+    ctx: Schema<TCtx>;
+    query?: Schema<TQuery, TQueryIn>;
+    params?: Schema<TParams, TParamsIn>;
+    body?: Schema<TBody, TBodyIn>;
+    returns?: TReturns;
+    handler: (ctx: Ctx, next: (args: {
+        ctx: TCtx;
+    }) => Promise<ReplyResult>) => Awaitable<ReplyResult | Response | unknown>;
+};
+type StateAndCtxUseOptions<Ctx, TState, TCtx, TQuery, TParams, TBody, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown> = {
+    state: Schema<TState>;
+    ctx: Schema<TCtx>;
+    query?: Schema<TQuery, TQueryIn>;
+    params?: Schema<TParams, TParamsIn>;
+    body?: Schema<TBody, TBodyIn>;
+    returns?: TReturns;
+    handler: (ctx: Ctx, next: (args: {
+        state: TState;
+        ctx: TCtx;
+    }) => Promise<ReplyResult>) => Awaitable<ReplyResult | Response | unknown>;
+};
+type StatelessUseOptions<Ctx, TQuery, TParams, TBody, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown> = {
+    query?: Schema<TQuery, TQueryIn>;
+    params?: Schema<TParams, TParamsIn>;
+    body?: Schema<TBody, TBodyIn>;
+    returns?: TReturns;
+    handler: (ctx: Ctx, next: () => Promise<ReplyResult>) => Awaitable<ReplyResult | Response | unknown>;
+};
+export type MiddlewareBuilder<Layout extends LayoutId, Acc extends readonly unknown[] = readonly [], TAppContext extends Record<string, unknown> = AppContext> = Acc & {
+    readonly layout: Layout;
+    readonly middlewares: readonly MiddlewareDefinition[];
+    readonly $Infer: {
+        Context: MiddlewareChainContext<Layout, Acc, unknown, unknown, unknown, TAppContext>;
+    };
+    use<TAcc, TReturns extends ReturnsMap = {}>(unit: MiddlewareUnit<TAcc, TReturns>): MiddlewareBuilder<Layout, readonly [...Acc, TAcc], TAppContext>;
+    use<TState, TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StateAndCtxUseOptions<MiddlewareChainContext<Layout, Acc, TQuery, TParams, TBody, TAppContext>, TState, TCtx, TQuery, TParams, TBody, TReturns, TQueryIn, TParamsIn, TBodyIn>): MiddlewareBuilder<Layout, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], TAppContext>;
+    use<TState, TQuery = unknown, TParams = unknown, TBody = unknown, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatefulUseOptions<MiddlewareChainContext<Layout, Acc, TQuery, TParams, TBody, TAppContext>, TState, TQuery, TParams, TBody, TReturns, TQueryIn, TParamsIn, TBodyIn>): MiddlewareBuilder<Layout, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], TAppContext>;
+    use<TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: CtxUseOptions<MiddlewareChainContext<Layout, Acc, TQuery, TParams, TBody, TAppContext>, TCtx, TQuery, TParams, TBody, TReturns, TQueryIn, TParamsIn, TBodyIn>): MiddlewareBuilder<Layout, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], TAppContext>;
+    use<TQuery = unknown, TParams = unknown, TBody = unknown, TReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatelessUseOptions<MiddlewareChainContext<Layout, Acc, TQuery, TParams, TBody, TAppContext>, TQuery, TParams, TBody, TReturns, TQueryIn, TParamsIn, TBodyIn>): MiddlewareBuilder<Layout, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], TAppContext>;
+};
+export type RouteExport<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], TReturns extends ReturnsMap = {}, TOutput = Response> = Acc & {
+    readonly path: Path;
+    readonly method: TMethod | 'ANY' | 'ALL';
+    readonly methods?: readonly Method[];
+    readonly middlewares: readonly MiddlewareDefinition[];
+    readonly handlerMiddlewares: readonly MiddlewareDefinition[];
+    readonly returns?: TReturns;
+    handler: (ctx: unknown) => Awaitable<Response>;
+    readonly $Infer: {
+        Context: TMethod extends 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' ? RouteHandleContextWithoutBody<Path, TMethod, Acc, {}> : RouteHandleContext<Path, TMethod, Acc, {}>;
+        /** Concrete handler reply (`ReplyOf` union) for client inference. */
+        Output: TOutput;
+    };
+    query?: Schema<unknown>;
+    params?: Schema<unknown>;
+    body?: Schema<unknown>;
+    handlerQuery?: Schema<unknown>;
+    handlerParams?: Schema<unknown>;
+    handlerBody?: Schema<unknown>;
+};
+type RouteHandleResult<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[], Validators extends ValidatorParts, TReturns extends ReturnsMap = {}, TOutput = Response, TAppContext extends Record<string, unknown> = AppContext> = Omit<RouteExport<Path, TMethod, Acc, TReturns, TOutput>, '$Infer'> & {
+    readonly $Infer: {
+        Context: TMethod extends 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' ? RouteHandleContextWithoutBody<Path, TMethod, Acc, Validators, TAppContext> : RouteHandleContext<Path, TMethod, Acc, Validators, TAppContext>;
+        Input: TMethod extends 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' ? RouteHandleInputWithoutBody<Path, TMethod, Acc, Validators> : RouteHandleInput<Path, TMethod, Acc, Validators>;
+        Output: TOutput;
+    };
+};
+export type RouteBuilder<Path extends RoutePath, TMethod extends Method, Acc extends readonly unknown[] = readonly [], Validators extends ValidatorParts = {}, TReturns extends ReturnsMap = {}, TAppContext extends Record<string, unknown> = AppContext> = {
+    readonly path: Path;
+    readonly method: TMethod;
+    readonly $Infer: {
+        Context: TMethod extends 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' ? RouteHandleContextWithoutBody<Path, TMethod, Acc, Validators, TAppContext> : RouteHandleContext<Path, TMethod, Acc, Validators, TAppContext>;
+    };
+    returns<const M extends ReturnsMap>(map: M): RouteBuilder<Path, TMethod, Acc, Validators, Omit<TReturns, keyof M> & M, TAppContext>;
+    use<TAcc, UReturns extends ReturnsMap = {}>(unit: MiddlewareUnit<TAcc, UReturns>): RouteBuilder<Path, TMethod, readonly [...Acc, TAcc], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TState, TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StateAndCtxUseOptions<RouteChainContext<Path, TMethod, Acc, TQuery, TParams, TBody, TAppContext>, TState, TCtx, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): RouteBuilder<Path, TMethod, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TState, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatefulUseOptions<RouteChainContext<Path, TMethod, Acc, TQuery, TParams, TBody, TAppContext>, TState, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): RouteBuilder<Path, TMethod, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: CtxUseOptions<RouteChainContext<Path, TMethod, Acc, TQuery, TParams, TBody, TAppContext>, TCtx, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): RouteBuilder<Path, TMethod, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatelessUseOptions<RouteChainContext<Path, TMethod, Acc, TQuery, TParams, TBody, TAppContext>, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): RouteBuilder<Path, TMethod, readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    handler<R extends Response = Response>(fn: (ctx: TMethod extends 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' ? RouteHandleContextWithoutBody<Path, TMethod, Acc, Validators, TAppContext> : RouteHandleContext<Path, TMethod, Acc, Validators, TAppContext>) => Awaitable<R>, ..._assert: [R] extends [ValidHandlerReply<R, TReturns>] ? [] : [
+        {
+            expected: ValidHandlerReply<R, TReturns>;
+            actual: R;
+        }
+    ]): RouteHandleResult<Path, TMethod, Acc, Validators, TReturns, R, TAppContext>;
+    handler<HandlerAcc extends readonly unknown[] = readonly [], HandlerValidators extends ValidatorParts = ValidatorParts, HReturns extends ReturnsMap = {}, HOutput = Response>(unit: HandlerUnit<HandlerAcc, HandlerValidators, HReturns, HOutput>): RouteHandleResult<Path, TMethod, readonly [...Acc, ...HandlerAcc], Validators, Omit<TReturns, keyof HReturns> & HReturns, HOutput, TAppContext>;
+};
+export type HandlerBuilder<Acc extends readonly unknown[] = readonly [], Validators extends ValidatorParts = {}, TReturns extends ReturnsMap = {}, TAppContext extends Record<string, unknown> = AppContext> = {
+    returns<const M extends ReturnsMap>(map: M): HandlerBuilder<Acc, Validators, Omit<TReturns, keyof M> & M, TAppContext>;
+    use<TAcc, UReturns extends ReturnsMap = {}>(unit: MiddlewareUnit<TAcc, UReturns>): HandlerBuilder<readonly [...Acc, TAcc], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TState, TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StateAndCtxUseOptions<HandlerContext<Acc, {
+        query: TQuery;
+        params: TParams;
+        body: TBody;
+    }, TAppContext>, TState, TCtx, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): HandlerBuilder<readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TState, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatefulUseOptions<HandlerContext<Acc, {
+        query: TQuery;
+        params: TParams;
+        body: TBody;
+    }, TAppContext>, TState, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): HandlerBuilder<readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TCtx, TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: CtxUseOptions<HandlerContext<Acc, {
+        query: TQuery;
+        params: TParams;
+        body: TBody;
+    }, TAppContext>, TCtx, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): HandlerBuilder<readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, TCtx, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    use<TQuery = unknown, TParams = unknown, TBody = unknown, UReturns extends ReturnsMap = {}, TQueryIn = unknown, TParamsIn = unknown, TBodyIn = unknown>(options: StatelessUseOptions<HandlerContext<Acc, {
+        query: TQuery;
+        params: TParams;
+        body: TBody;
+    }, TAppContext>, TQuery, TParams, TBody, UReturns, TQueryIn, TParamsIn, TBodyIn>): HandlerBuilder<readonly [
+        ...Acc,
+        MiddlewareReturnFromParts<TQuery, TParams, TBody, {}, unknown, TQueryIn, TParamsIn, TBodyIn>
+    ], Validators, Omit<TReturns, keyof UReturns> & UReturns, TAppContext>;
+    handler<R extends Response = Response>(fn: (ctx: HandlerContext<Acc, Validators, TAppContext>) => Awaitable<R>, ..._assert: [R] extends [ValidHandlerReply<R, TReturns>] ? [] : [
+        {
+            expected: ValidHandlerReply<R, TReturns>;
+            actual: R;
+        }
+    ]): HandlerUnit<Acc, Validators, TReturns, R>;
+};

package/dist/esm/types/returns.d.ts

@@ -0,0 +1,37 @@
+import { ReplyOf } from '@taserjs/router-utils';
+import { Simplify } from './type-utils.js';
+import { Schema, InferOutput } from './schema.js';
+/**
+ * Known HTTP status codes. `number & {}` allows custom codes while keeping
+ * literal autocomplete / inference for well-known values.
+ */
+export type StatusCode = 100 | 101 | 102 | 103 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | (number & {});
+/** Status-code → Standard Schema map for route/middleware/handler outputs. */
+export type ReturnsMap = {
+    readonly [K in StatusCode]?: Schema<unknown>;
+};
+/** Later map wins on overlapping status keys. */
+export type MergeReturns<A extends ReturnsMap, B extends ReturnsMap> = Omit<A, keyof B> & B;
+/** Typed reply union for statuses declared in a returns map. */
+export type ReplyResultFor<M extends ReturnsMap> = {
+    [S in keyof M]-?: S extends StatusCode ? M[S] extends Schema<unknown> ? ReplyOf<S, Simplify<InferOutput<M[S]>>> : never : never;
+}[keyof M];
+export type EmptyReturns = {};
+/** True when no status schemas have been declared yet. */
+export type HasReturns<M extends ReturnsMap> = [keyof M] extends [never] ? false : true;
+/**
+ * Validate a concrete reply `R` against returns map `M`.
+ * Declared statuses must match schema output; undeclared statuses stay open
+ * (same rule as runtime `validateReply`).
+ */
+export type ValidHandlerReply<R, M extends ReturnsMap> = R extends ReplyOf<infer S, infer B> ? S extends keyof M ? M[S] extends Schema<unknown> ? B extends Simplify<InferOutput<M[S]>> ? R : never : R : R : R extends Response ? R : never;
+/**
+ * Narrow a handler return so declared statuses are schema-checked without
+ * breaking multi-status unions (avoids circular `R extends …<R>` constraints).
+ */
+export type EnforceHandlerReply<R, M extends ReturnsMap> = [R] extends [ValidHandlerReply<R, M>] ? R : ValidHandlerReply<R, M>;
+/**
+ * Expected `.handler` return type for a returns map.
+ * Prefer constraining handler generics with {@link EnforceHandlerReply}.
+ */
+export type HandlerReply<M extends ReturnsMap> = HasReturns<M> extends true ? ReplyResultFor<M> | Response : Response;

package/dist/esm/types/schema.d.ts

@@ -0,0 +1,14 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { RequestShape } from './type-utils.js';
+export type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * A Standard Schema validator.
+ * `TOutput` is the validated/output type; `TInput` is the pre-parse input (request shape).
+ */
+export type Schema<TOutput = unknown, TInput = unknown> = StandardSchemaV1<TInput, TOutput>;
+/** Infers the output type from a Standard Schema. */
+export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
+/** Infers the input type from a Standard Schema. */
+export type InferInput<S> = S extends StandardSchemaV1<infer I, unknown> ? I : never;
+/** Pre-parse request shape from a Standard Schema. */
+export type SchemaRequestShape<S> = S extends StandardSchemaV1<infer I, infer O> ? RequestShape<I, O> : S;

package/dist/esm/types/type-utils.d.ts

@@ -0,0 +1,52 @@
+export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+export type HttpMethod = Method;
+export type MiddlewareFieldName = 'query' | 'params' | 'body' | 'state' | 'ctx';
+export type MiddlewareInputFieldName = 'query' | 'params' | 'body';
+export type UnwrapPart<T> = unknown extends T ? {} : T;
+export type MergePart<T, Base> = unknown extends T ? Base : Base & T;
+/** Collapse intersections so `Omit`/`keyof` treat the result as one object type. */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Request prop: when schema input is `unknown` (e.g. zod coerce),
+ * fall back to the validated output type.
+ */
+type RequestPropType<TIn, TOut> = [unknown] extends [Exclude<TIn, undefined>] ? TOut : TIn;
+/**
+ * Pre-parse request shape. Prefer input types (defaults → optional),
+ * but replace `unknown` input props with output types.
+ */
+export type RequestShape<TIn, TOut> = unknown extends TIn ? UnwrapPart<TOut> : Simplify<{
+    [K in keyof TIn]: K extends keyof TOut ? RequestPropType<TIn[K], TOut[K]> : TIn[K];
+}>;
+export type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer Value) => void ? Value : never;
+export type MiddlewareField<Middleware, Field extends MiddlewareFieldName> = Field extends 'query' ? Middleware extends {
+    query: infer Query;
+} ? Query : {} : Field extends 'params' ? Middleware extends {
+    params: infer Params;
+} ? Params : {} : Field extends 'body' ? Middleware extends {
+    body: infer Body;
+} ? Body : {} : Field extends 'state' ? Middleware extends {
+    state: infer State;
+} ? State : {} : Field extends 'ctx' ? Middleware extends {
+    ctx: infer Ctx;
+} ? Ctx : {} : {};
+export type MiddlewareInputField<Middleware, Field extends MiddlewareInputFieldName> = Middleware extends {
+    input: {
+        [K in Field]: infer V;
+    };
+} ? V : {};
+export type MergeMiddlewareField<Middlewares extends readonly unknown[], Field extends MiddlewareFieldName> = [Middlewares] extends [readonly []] ? {} : UnionToIntersection<MiddlewareField<Middlewares[number], Field>>;
+export type MergeMiddlewareInputField<Middlewares extends readonly unknown[], Field extends MiddlewareInputFieldName> = [Middlewares] extends [readonly []] ? {} : UnionToIntersection<MiddlewareInputField<Middlewares[number], Field>>;
+export type RuntimeContextFields<TNative = unknown> = {
+    request: Request;
+    method: Method;
+    url: URL;
+    headers: import('@taserjs/router-core').TaserHeaders;
+    cookies: import('@taserjs/router-core').TaserCookieJar;
+    reply: typeof import('@taserjs/router-utils').reply;
+    var: Record<string, unknown>;
+    native?: TNative;
+};
+export {};

package/dist/esm/types/units.d.ts

@@ -0,0 +1,98 @@
+import { Awaitable, TaserCookieJar, TaserHeaders } from '@taserjs/router-core';
+import { ReplyResult } from '@taserjs/router-utils';
+import { RouterRegister } from '../register.js';
+import { MergeMiddlewareField, MergePart, RequestShape, RuntimeContextFields, Simplify, UnwrapPart } from './type-utils.js';
+import { ReturnsMap } from './returns.js';
+import { Schema } from './schema.js';
+export type { HttpMethod, Method } from './type-utils.js';
+export type { EmptyReturns, MergeReturns, ReturnsMap, HandlerReply, HasReturns, StatusCode, ValidHandlerReply, EnforceHandlerReply } from './returns.js';
+/** Default empty app context for standalone units without a bound router instance. */
+export type AppContext = Record<never, never>;
+export type NativeContext = RouterRegister extends {
+    NativeContext: infer N;
+} ? N : unknown;
+export type ValidatorParts = {
+    query?: unknown;
+    params?: unknown;
+    body?: unknown;
+    queryIn?: unknown;
+    paramsIn?: unknown;
+    bodyIn?: unknown;
+};
+export type MiddlewareNext = {
+    (args?: {
+        state?: unknown;
+        ctx?: unknown;
+    }): Promise<ReplyResult>;
+};
+export type MiddlewareDefinition = {
+    state?: unknown;
+    ctx?: unknown;
+    query?: unknown;
+    params?: unknown;
+    body?: unknown;
+    returns?: ReturnsMap;
+    handler: (ctx: unknown, next: MiddlewareNext) => Awaitable<ReplyResult | Response | unknown>;
+};
+export type MiddlewareReturnFromParts<TQuery, TParams, TBody, TState, TCtx = unknown, TQueryIn = TQuery, TParamsIn = TParams, TBodyIn = TBody> = {
+    query: Simplify<UnwrapPart<TQuery>>;
+    params: Simplify<UnwrapPart<TParams>>;
+    body: Simplify<UnwrapPart<TBody>>;
+    state: Simplify<UnwrapPart<TState>>;
+    ctx: Simplify<UnwrapPart<TCtx>>;
+    /** Pre-parse shapes merged into route `$Infer.Input`. */
+    input: {
+        query: RequestShape<TQueryIn, TQuery>;
+        params: RequestShape<TParamsIn, TParams>;
+        body: RequestShape<TBodyIn, TBody>;
+    };
+};
+type UnitRuntimeContext = RuntimeContextFields<NativeContext>;
+export type StandaloneMiddlewareContext<TQuery = unknown, TParams = unknown, TBody = unknown, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & {
+    query: Simplify<UnwrapPart<TQuery>>;
+    params: Simplify<UnwrapPart<TParams>>;
+    body: Simplify<UnwrapPart<TBody>>;
+    state: {};
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+export type HandlerContext<Acc extends readonly unknown[], Validators extends ValidatorParts, TAppContext extends Record<string, unknown> = AppContext> = Simplify<TAppContext & UnitRuntimeContext & MergeMiddlewareField<Acc, 'ctx'> & {
+    query: Simplify<MergePart<Validators extends {
+        query?: infer Q;
+    } ? Q : unknown, MergeMiddlewareField<Acc, 'query'>>>;
+    params: Simplify<MergePart<Validators extends {
+        params?: infer P;
+    } ? P : unknown, MergeMiddlewareField<Acc, 'params'>>>;
+    body: Simplify<MergePart<Validators extends {
+        body?: infer B;
+    } ? B : unknown, MergeMiddlewareField<Acc, 'body'>>>;
+    state: Simplify<MergeMiddlewareField<Acc, 'state'>>;
+    headers: TaserHeaders;
+    cookies: TaserCookieJar;
+}>;
+export type MiddlewareUnit<TAcc = unknown, TReturns extends ReturnsMap = {}> = MiddlewareDefinition & {
+    readonly __middlewareAcc: TAcc;
+    readonly __returns?: TReturns;
+};
+export type HandlerUnit<_Acc extends readonly unknown[], _Validators extends ValidatorParts, TReturns extends ReturnsMap = {}, TOutput = Response> = {
+    readonly __returns?: TReturns;
+    readonly $Infer: {
+        Output: TOutput;
+    };
+    middlewares: readonly MiddlewareDefinition[];
+    handler: (ctx: unknown) => Awaitable<ReplyResult | Response>;
+    returns?: ReturnsMap;
+    query?: Schema<unknown>;
+    params?: Schema<unknown>;
+    body?: Schema<unknown>;
+};
+export type InlineMiddlewareOptions = {
+    state?: Schema<unknown>;
+    ctx?: Schema<unknown>;
+    query?: Schema<unknown>;
+    params?: Schema<unknown>;
+    body?: Schema<unknown>;
+    returns?: ReturnsMap;
+    handler: (ctx: unknown, next: MiddlewareNext) => Awaitable<unknown>;
+};
+export declare function isHandlerUnit(value: unknown): value is HandlerUnit<readonly unknown[], ValidatorParts>;

package/dist/esm/types/units.js

@@ -0,0 +1,8 @@
+//#region src/types/units.ts
+function isHandlerUnit(value) {
+	return typeof value === "object" && value !== null && "handler" in value && "middlewares" in value && Array.isArray(value.middlewares);
+}
+//#endregion
+export { isHandlerUnit };
+
+//# sourceMappingURL=units.js.map

package/dist/esm/types/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","names":[],"sources":["../../../src/types/units.ts"],"sourcesContent":["import type { Awaitable, TaserCookieJar, TaserHeaders } from '@taserjs/router-core'\nimport type { ReplyResult } from '@taserjs/router-utils'\n\nimport type { RouterRegister } from '../register.js'\nimport type {\n  MergeMiddlewareField,\n  MergePart,\n  RequestShape,\n  RuntimeContextFields,\n  Simplify,\n  UnwrapPart,\n} from './type-utils.js'\nimport type { ReturnsMap } from './returns.js'\nimport type { Schema } from './schema.js'\n\nexport type { HttpMethod, Method } from './type-utils.js'\nexport type { EmptyReturns, MergeReturns, ReturnsMap, HandlerReply, HasReturns, StatusCode, ValidHandlerReply, EnforceHandlerReply } from './returns.js'\n\n/** Default empty app context for standalone units without a bound router instance. */\nexport type AppContext = Record<never, never>\n\nexport type NativeContext = RouterRegister extends { NativeContext: infer N } ? N : unknown\n\nexport type ValidatorParts = {\n  query?: unknown\n  params?: unknown\n  body?: unknown\n  queryIn?: unknown\n  paramsIn?: unknown\n  bodyIn?: unknown\n}\n\nexport type MiddlewareNext = {\n  (args?: { state?: unknown, ctx?: unknown }): Promise<ReplyResult>\n}\n\nexport type MiddlewareDefinition = {\n  state?: unknown\n  ctx?: unknown\n  query?: unknown\n  params?: unknown\n  body?: unknown\n  returns?: ReturnsMap\n  handler: (\n    ctx: unknown,\n    next: MiddlewareNext,\n  ) => Awaitable<ReplyResult | Response | unknown>\n}\n\nexport type MiddlewareReturnFromParts<\n  TQuery,\n  TParams,\n  TBody,\n  TState,\n  TCtx = unknown,\n  TQueryIn = TQuery,\n  TParamsIn = TParams,\n  TBodyIn = TBody,\n> = {\n  query: Simplify<UnwrapPart<TQuery>>\n  params: Simplify<UnwrapPart<TParams>>\n  body: Simplify<UnwrapPart<TBody>>\n  state: Simplify<UnwrapPart<TState>>\n  ctx: Simplify<UnwrapPart<TCtx>>\n  /** Pre-parse shapes merged into route `$Infer.Input`. */\n  input: {\n    query: RequestShape<TQueryIn, TQuery>\n    params: RequestShape<TParamsIn, TParams>\n    body: RequestShape<TBodyIn, TBody>\n  }\n}\n\ntype UnitRuntimeContext = RuntimeContextFields<NativeContext>\n\nexport type StandaloneMiddlewareContext<\n  TQuery = unknown,\n  TParams = unknown,\n  TBody = unknown,\n  TAppContext extends Record<string, unknown> = AppContext,\n> = Simplify<\n  TAppContext & UnitRuntimeContext & {\n    query: Simplify<UnwrapPart<TQuery>>\n    params: Simplify<UnwrapPart<TParams>>\n    body: Simplify<UnwrapPart<TBody>>\n    state: {}\n    headers: TaserHeaders\n    cookies: TaserCookieJar\n  }\n>\n\nexport type HandlerContext<\n  Acc extends readonly unknown[],\n  Validators extends ValidatorParts,\n  TAppContext extends Record<string, unknown> = AppContext,\n> = Simplify<\n  TAppContext\n  & UnitRuntimeContext\n  & MergeMiddlewareField<Acc, 'ctx'>\n  & {\n    query: Simplify<MergePart<\n      Validators extends { query?: infer Q } ? Q : unknown,\n      MergeMiddlewareField<Acc, 'query'>\n    >>\n    params: Simplify<MergePart<\n      Validators extends { params?: infer P } ? P : unknown,\n      MergeMiddlewareField<Acc, 'params'>\n    >>\n    body: Simplify<MergePart<\n      Validators extends { body?: infer B } ? B : unknown,\n      MergeMiddlewareField<Acc, 'body'>\n    >>\n    state: Simplify<MergeMiddlewareField<Acc, 'state'>>\n    headers: TaserHeaders\n    cookies: TaserCookieJar\n  }\n>\n\nexport type MiddlewareUnit<\n  TAcc = unknown,\n  TReturns extends ReturnsMap = {},\n> = MiddlewareDefinition & {\n  readonly __middlewareAcc: TAcc\n  readonly __returns?: TReturns\n}\n\nexport type HandlerUnit<\n  _Acc extends readonly unknown[],\n  _Validators extends ValidatorParts,\n  TReturns extends ReturnsMap = {},\n  TOutput = Response,\n> = {\n  readonly __returns?: TReturns\n  readonly $Infer: {\n    Output: TOutput\n  }\n  middlewares: readonly MiddlewareDefinition[]\n  handler: (ctx: unknown) => Awaitable<ReplyResult | Response>\n  returns?: ReturnsMap\n  query?: Schema<unknown>\n  params?: Schema<unknown>\n  body?: Schema<unknown>\n}\n\nexport type InlineMiddlewareOptions = {\n  state?: Schema<unknown>\n  ctx?: Schema<unknown>\n  query?: Schema<unknown>\n  params?: Schema<unknown>\n  body?: Schema<unknown>\n  returns?: ReturnsMap\n  handler: (\n    ctx: unknown,\n    next: MiddlewareNext,\n  ) => Awaitable<unknown>\n}\n\nexport function isHandlerUnit(\n  value: unknown,\n): value is HandlerUnit<readonly unknown[], ValidatorParts> {\n  return (\n    typeof value === 'object'\n    && value !== null\n    && 'handler' in value\n    && 'middlewares' in value\n    && Array.isArray((value as HandlerUnit<readonly unknown[], ValidatorParts>).middlewares)\n  )\n}\n"],"mappings":";AA4JA,SAAgB,cACd,OAC0D;CAC1D,OACE,OAAO,UAAU,YACd,UAAU,QACV,aAAa,SACb,iBAAiB,SACjB,MAAM,QAAS,MAA0D,WAAW;AAE3F"}