@sigiljs/sigil/dist/route/route.d.ts

TypeScript-first Node.js HTTP framework offering schema-driven routing, modifier-based middleware, plugin extensibility, and flexible response templating

import { ObjectSchema } from '@sigiljs/seal';
import { InferSchema } from '@sigiljs/seal/types';
import { ModifierConstructor } from './modifier';
import { DebugOptions } from '../sigil/types';
import { Internal } from '../types';
import { default as RouteRequests } from './route-requests';
type Constructor = (readonly ModifierConstructor<any, any>[]) | undefined;
/**
 * Configuration options for the Route.
 *
 * @template Modifier a tuple of modifier constructors to apply.
 */
export interface RouteOptions<Modifier extends Constructor> {
    /** Array of modifier constructors to apply to this route. */
    modifiers?: Modifier;
    /** Tags to associate with this route (for documentation). */
    tags?: string[];
    /** Custom logger instance. */
    logger?: Internal.AbstractLogger;
    /** Debugging options for validation and logging. */
    debug?: Partial<DebugOptions>;
}
type MetaDescriptor<Schema extends Record<any, any>> = Partial<Internal.Route.RouteDescriptor<InferSchema<ObjectSchema<Schema>>>>;
/**
 * Main router class for registering HTTP routes and metadata.
 * Extends RouteRequests to offer schema-based validation and
 * automatic type derivation for request handlers.
 *
 * @template Modifiers tuple of modifier constructors applied to this route.
 * @template BodySchema shape of the request body schema, if applied.
 * @template HeadersSchema shape of the request headers schema, if applied.
 * @template QuerySchema shape of the request query schema, if applied.
 */
export default class Route<Modifiers extends readonly ModifierConstructor<any, any>[] | undefined = undefined, BodySchema extends Record<string, any> | undefined = undefined, HeadersSchema extends Record<string, string | undefined> = Record<string, string | undefined>, QuerySchema extends Record<string, string | undefined> = Record<string, string | undefined>> extends RouteRequests<Modifiers, BodySchema, HeadersSchema, QuerySchema> {
    /**
     * Creates a new Route instance with optional configuration.
     * Instantiates the underlying Pathfinder router and applies modifiers.
     *
     * @param options configuration options for the router.
     */
    constructor(options?: RouteOptions<Modifiers>);
    /**
     * Registers a validation schema for the request body of the next handler.
     * After calling this, GET routes will be disabled until a new router clone is created.
     *
     * @param schema object schema defining the expected request body.
     * @param meta optional metadata (e.g., name, description) for documentation.
     * @returns temporary cloned router with the body schema applied (without `get` method if appropriate).
     */
    body<Schema extends Internal.Route.RequestSchemaDescriptor["body"]>(schema: Schema | [Schema, MetaDescriptor<Schema> | undefined], meta?: MetaDescriptor<Schema>): Omit<Route<Modifiers, InferSchema<ObjectSchema<Schema>>, HeadersSchema, QuerySchema>, "get">;
    /**
     * Registers a validation schema for the request headers of the next handler.
     *
     * @param schema object schema defining the expected headers.
     * @returns temporary cloned router with the headers schema applied.
     */
    headers<Schema extends Internal.Route.RequestSchemaDescriptor["headers"]>(schema: Schema | [Schema, MetaDescriptor<Schema> | undefined]): (BodySchema extends Record<any, any> ? Omit<Route<Modifiers, BodySchema, { [K in keyof Schema]: InferSchema<Schema[K]>; }, QuerySchema>, "get"> : Route<Modifiers, BodySchema, { [K in keyof Schema]: InferSchema<Schema[K]>; }, QuerySchema>);
    /**
     * Registers a validation schema for the query parameters of the next handler.
     *
     * @param schema object schema defining the expected query parameters.
     * @returns temporary cloned router with the query schema applied.
     */
    query<Schema extends Internal.Route.RequestSchemaDescriptor["query"]>(schema: Schema | [Schema, MetaDescriptor<Schema> | undefined]): (BodySchema extends Record<any, any> ? Omit<Route<Modifiers, BodySchema, HeadersSchema, { [K in keyof Schema]: InferSchema<Schema[K]>; }>, "get"> : Route<Modifiers, BodySchema, HeadersSchema, { [K in keyof Schema]: InferSchema<Schema[K]>; }>);
    /**
     * Registers a validation schema for the path parameters of the next handler.
     *
     * @param schema object schema defining the expected path parameters.
     * @returns temporary cloned router with the params schema applied.
     */
    params<Schema extends Internal.Route.RequestSchemaDescriptor["params"]>(schema: Schema | [Schema, MetaDescriptor<Schema> | undefined]): this;
    /**
     * Internal method that clones the current router instance and applies a new schema.
     * Used to isolate schema settings per handler registration.
     *
     * @param key schema type key ("body", "headers", "query", or "params").
     * @param schema validation schema object.
     * @param meta optional metadata to attach to the schema.
     * @returns cloned Route instance with the updated schema.
     * @private
     */
    private $cloneWithSchema;
    /**
     * Internal helper to attach metadata (name, description, example, etc.)
     * to a given schema.
     *
     * @param schema ObjectSchema to which metadata will be applied.
     * @param meta partial metadata properties to assign.
     * @returns schema instance with metadata applied.
     * @private
     */
    private $applyMetadata;
}
export {};