@vfarcic/dot-ai/dist/interfaces/rest-route-registry.d.ts

AI-powered development productivity platform that enhances software development workflows through intelligent automation and AI-driven assistance

/**
 * REST API Route Registry
 *
 * Central registry for all REST API routes with their metadata and schemas.
 * Provides single source of truth for routing, OpenAPI generation, and fixture validation.
 *
 * PRD #354: REST API Route Registry with Auto-Generated OpenAPI and Test Fixtures
 */
import { z } from 'zod';
import { Logger } from '../core/error-handling';
/**
 * HTTP methods supported by the REST API
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
/**
 * Route handler function type
 */
export type RouteHandler<TParams, TQuery, TBody, TResponse> = (context: {
    params: TParams;
    query: TQuery;
    body: TBody;
    requestId: string;
}) => Promise<TResponse>;
/**
 * Route definition with full metadata for routing, documentation, and validation
 */
export interface RouteDefinition<TParams = unknown, TQuery = unknown, TBody = unknown, TResponse = unknown> {
    /** Route path with optional parameters (e.g., "/api/v1/visualize/:sessionId") */
    path: string;
    /** HTTP method */
    method: HttpMethod;
    /** Human-readable description for OpenAPI documentation */
    description: string;
    /** OpenAPI tags for grouping endpoints */
    tags: string[];
    /** Zod schema for path parameters */
    params?: z.ZodSchema<TParams>;
    /** Zod schema for query string parameters */
    query?: z.ZodSchema<TQuery>;
    /** Zod schema for request body */
    body?: z.ZodSchema<TBody>;
    /** Zod schema for successful response */
    response: z.ZodSchema<TResponse>;
    /** Zod schemas for error responses by HTTP status code */
    errorResponses?: Record<number, z.ZodSchema<unknown>>;
    /** Route handler function (optional - can be set during migration) */
    handler?: RouteHandler<TParams, TQuery, TBody, TResponse>;
}
/**
 * Result of matching a request path against registered routes
 */
export interface RouteMatch {
    /** The matched route definition */
    route: RouteDefinition<unknown, unknown, unknown, unknown>;
    /** Extracted path parameters */
    params: Record<string, string>;
}
/**
 * Registry for managing REST API routes
 *
 * Provides:
 * - Route registration with Zod schemas
 * - Path matching with parameter extraction
 * - Route discovery for OpenAPI generation
 * - Schema access for fixture validation
 */
export declare class RestRouteRegistry {
    private routes;
    private logger;
    constructor(logger: Logger);
    /**
     * Generate a unique key for a route based on method and path pattern
     */
    private getRouteKey;
    /**
     * Compile a path pattern into a regex for matching
     *
     * Converts path parameters like :sessionId into capture groups
     * Example: "/api/v1/visualize/:sessionId" -> /^\/api\/v1\/visualize\/([^/]+)$/
     */
    private compilePath;
    /**
     * Register a route in the registry
     *
     * @param route - Route definition with path, method, schemas, and metadata
     * @throws Error if route with same method and path is already registered
     */
    register<TParams, TQuery, TBody, TResponse>(route: RouteDefinition<TParams, TQuery, TBody, TResponse>): void;
    /**
     * Find a matching route for the given method and path
     *
     * Checks routes in order:
     * 1. Exact matches (no parameters)
     * 2. Parameterized routes (extracts parameter values)
     *
     * @param method - HTTP method
     * @param path - Request path to match
     * @returns RouteMatch with route and extracted params, or null if no match
     */
    findRoute(method: string, path: string): RouteMatch | null;
    /**
     * Find allowed methods for a path (ignoring method)
     *
     * Used to return METHOD_NOT_ALLOWED with proper Allow header
     * when a path matches but method doesn't.
     *
     * @param path - Request path to match
     * @returns Array of allowed methods, or empty array if path doesn't match any route
     */
    findAllowedMethods(path: string): HttpMethod[];
    /**
     * Get all registered route definitions
     *
     * Used by OpenAPI generator to document all endpoints
     */
    getAllRoutes(): RouteDefinition<unknown, unknown, unknown, unknown>[];
    /**
     * Get the response schema for a specific route
     *
     * Used by fixture validator to validate fixture data
     *
     * @param method - HTTP method
     * @param pathPattern - Route path pattern (e.g., "/api/v1/visualize/:sessionId")
     * @returns Zod schema for the response, or null if route not found
     */
    getResponseSchema(method: string, pathPattern: string): z.ZodSchema<unknown> | null;
    /**
     * Get the error response schema for a specific route and status code
     *
     * @param method - HTTP method
     * @param pathPattern - Route path pattern
     * @param statusCode - HTTP status code
     * @returns Zod schema for the error response, or null if not defined
     */
    getErrorResponseSchema(method: string, pathPattern: string, statusCode: number): z.ZodSchema<unknown> | null;
    /**
     * Check if a route is registered
     */
    hasRoute(method: string, pathPattern: string): boolean;
    /**
     * Get the number of registered routes
     */
    getRouteCount(): number;
    /**
     * Get all unique tags from registered routes
     */
    getTags(): string[];
    /**
     * Get routes filtered by tag
     */
    getRoutesByTag(tag: string): RouteDefinition<unknown, unknown, unknown, unknown>[];
    /**
     * Clear all registered routes
     */
    clear(): void;
    /**
     * Get registry statistics
     */
    getStats(): {
        totalRoutes: number;
        tags: string[];
        routesByMethod: Record<HttpMethod, number>;
    };
}
//# sourceMappingURL=rest-route-registry.d.ts.map