nural 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,458 @@
+import { z } from 'zod';
+export { z } from 'zod';
+import { Request, Response } from 'express';
+import { FastifyRequest, FastifyReply } from 'fastify';
+export { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+
+/**
+ * Middleware Types and Helpers
+ */
+/**
+ * Middleware handler function type
+ * Returns data to be merged into route context
+ */
+type MiddlewareHandler<Req = unknown, Res = unknown> = (req: Req, res: Res) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * Define a type-safe middleware
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = defineMiddleware(async (req: Request) => {
+ *   const token = req.headers.authorization;
+ *   if (!token) throw new Error('Unauthorized');
+ *   return { user: { id: '123', role: 'admin' } };
+ * });
+ * ```
+ */
+declare function defineMiddleware<T extends Record<string, unknown> | void, Req = unknown, Res = unknown>(fn: (req: Req, res: Res) => Promise<T> | T): (req: Req, res: Res) => Promise<T> | T;
+
+/**
+ * HTTP Types
+ * Centralized HTTP-related type definitions
+ */
+/**
+ * Supported HTTP methods
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+/**
+ * Common HTTP status codes
+ */
+type HttpStatusCode = 200 | 201 | 204 | 400 | 401 | 403 | 404 | 500;
+
+/**
+ * Route Types
+ * Type definitions for route configuration and handlers
+ */
+
+/**
+ * Generic Zod type - either a Zod schema or undefined
+ */
+type ZodAny = z.ZodTypeAny | undefined;
+/**
+ * Inference helper: extracts type from Zod schema, returns unknown if undefined
+ */
+type InferZ<T extends ZodAny> = T extends z.ZodTypeAny ? z.infer<T> : unknown;
+/**
+ * Extract the return type of a single middleware
+ */
+type MiddlewareReturn<M> = M extends MiddlewareHandler<any, any> ? Awaited<ReturnType<M>> : {};
+/**
+ * Convert an array of middlewares into an intersection type
+ * @example [{user: string}] & [{role: string}] -> {user: string, role: string}
+ */
+type MergeMiddlewareTypes<M extends MiddlewareHandler<any, any>[] | undefined> = M extends Array<any> ? MiddlewareReturn<M[number]> extends infer R ? R extends void ? {} : R : {} : {};
+/**
+ * Context passed to route handlers
+ */
+type RouteContext<P extends ZodAny, Q extends ZodAny, B extends ZodAny, M extends MiddlewareHandler<any, any>[] | undefined> = {
+    /** Validated path parameters */
+    params: InferZ<P>;
+    /** Validated query parameters */
+    query: InferZ<Q>;
+    /** Validated request body */
+    body: InferZ<B>;
+    /** Raw request object (Express or Fastify) */
+    req: Request | FastifyRequest;
+    /** Raw response object (Express or Fastify) */
+    res: Response | FastifyReply;
+} & MergeMiddlewareTypes<M>;
+/**
+ * Route handler function type
+ */
+type RouteHandler<P extends ZodAny, Q extends ZodAny, B extends ZodAny, R extends ZodAny, M extends MiddlewareHandler<any, any>[] | undefined> = (ctx: RouteContext<P, Q, B, M>) => Promise<InferZ<R> | void> | InferZ<R> | void;
+/**
+ * Route configuration object
+ */
+interface RouteConfig<P extends ZodAny = undefined, Q extends ZodAny = undefined, B extends ZodAny = undefined, R extends ZodAny = undefined, M extends MiddlewareHandler<any, any>[] | undefined = undefined> {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route path (supports :param syntax) */
+    path: string;
+    /** Short summary for documentation */
+    summary?: string;
+    /** Detailed description for documentation */
+    description?: string;
+    /** Tags for grouping in documentation */
+    tags?: string[];
+    /** Middleware to run before handler */
+    middleware?: M;
+    /** Request validation schemas */
+    request?: {
+        /** Path parameters schema */
+        params?: P;
+        /** Query parameters schema */
+        query?: Q;
+        /** Request body schema */
+        body?: B;
+    };
+    /** Response schemas by status code */
+    responses?: Record<number, z.ZodTypeAny>;
+    /** Route handler function */
+    handler: RouteHandler<P, Q, B, R, M>;
+}
+/**
+ * Catch-all type for arrays of routes
+ */
+type AnyRouteConfig = RouteConfig<any, any, any, any, any>;
+
+/**
+ * Error Types and Handler
+ * Types for global error handling
+ */
+
+/**
+ * Error context passed to error handlers
+ */
+interface ErrorContext {
+    /** The error that occurred */
+    error: Error;
+    /** HTTP request (Express or Fastify) */
+    request: Request | FastifyRequest;
+    /** HTTP response (Express or Fastify) */
+    response: Response | FastifyReply;
+    /** Route path that errored */
+    path?: string;
+    /** HTTP method */
+    method?: string;
+}
+/**
+ * Error response returned by error handlers
+ */
+interface ErrorResponse {
+    /** HTTP status code */
+    status: number;
+    /** Response body */
+    body: Record<string, unknown>;
+    /** Optional headers to set */
+    headers?: Record<string, string>;
+}
+/**
+ * Global error handler function type
+ */
+type ErrorHandler = (ctx: ErrorContext) => ErrorResponse | Promise<ErrorResponse>;
+/**
+ * Error handler configuration
+ */
+interface ErrorHandlerConfig {
+    /** Custom error handler function */
+    handler?: ErrorHandler;
+    /** Include stack trace in development */
+    includeStack?: boolean;
+    /** Log errors to console */
+    logErrors?: boolean;
+    /** Custom error logger */
+    logger?: (error: Error, ctx: ErrorContext) => void;
+}
+
+/**
+ * Middleware Configuration Types
+ * Types for CORS and Helmet middleware configuration
+ */
+/**
+ * CORS configuration options
+ */
+interface CorsConfig {
+    /**
+     * Allowed origins
+     * - `true` or `'*'` allows all origins
+     * - String for single origin
+     * - Array for multiple origins
+     * - Function for dynamic origin check
+     */
+    origin?: boolean | string | string[] | ((origin: string) => boolean);
+    /** Allowed HTTP methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Headers exposed to client */
+    exposedHeaders?: string[];
+    /** Allow credentials (cookies, authorization headers) */
+    credentials?: boolean;
+    /** Preflight cache max age in seconds */
+    maxAge?: number;
+    /** Pass preflight response to next handler */
+    preflightContinue?: boolean;
+    /** Success status code for OPTIONS requests */
+    optionsSuccessStatus?: number;
+}
+/**
+ * Helmet configuration options
+ */
+interface HelmetConfig {
+    /** Content-Security-Policy header */
+    contentSecurityPolicy?: boolean | {
+        directives?: Record<string, string[]>;
+    };
+    /** Cross-Origin-Embedder-Policy header */
+    crossOriginEmbedderPolicy?: boolean;
+    /** Cross-Origin-Opener-Policy header */
+    crossOriginOpenerPolicy?: boolean | {
+        policy?: string;
+    };
+    /** Cross-Origin-Resource-Policy header */
+    crossOriginResourcePolicy?: boolean | {
+        policy?: string;
+    };
+    /** X-DNS-Prefetch-Control header */
+    dnsPrefetchControl?: boolean | {
+        allow?: boolean;
+    };
+    /** X-Frame-Options header */
+    frameguard?: boolean | {
+        action?: "deny" | "sameorigin";
+    };
+    /** Strict-Transport-Security header */
+    hsts?: boolean | {
+        maxAge?: number;
+        includeSubDomains?: boolean;
+        preload?: boolean;
+    };
+    /** X-Content-Type-Options header */
+    noSniff?: boolean;
+    /** X-Permitted-Cross-Domain-Policies header */
+    permittedCrossDomainPolicies?: boolean | {
+        policy?: string;
+    };
+    /** Referrer-Policy header */
+    referrerPolicy?: boolean | {
+        policy?: string | string[];
+    };
+    /** X-XSS-Protection header (legacy) */
+    xssFilter?: boolean;
+}
+
+/**
+ * Configuration Types
+ * Types for Nural framework configuration
+ */
+/**
+ * Documentation configuration options
+ */
+interface DocsConfig {
+    /** Enable documentation endpoint */
+    enabled?: boolean;
+    /** API title shown in docs */
+    title?: string;
+    /** API version */
+    version?: string;
+    /** API description */
+    description?: string;
+    /** Documentation UI path (default: /docs) */
+    path?: string;
+    /** Documentation UI type */
+    ui?: "scalar" | "swagger";
+}
+/**
+ * Main Nural framework configuration
+ */
+interface NuralConfig {
+    /** Server framework to use */
+    framework?: "express" | "fastify";
+    /** Documentation settings (true for defaults, false to disable, or DocsConfig) */
+    docs?: boolean | DocsConfig;
+    /** CORS settings (true for defaults, false to disable, or CorsConfig) */
+    cors?: boolean | CorsConfig;
+    /** Helmet security headers (true for defaults, false to disable, or HelmetConfig) */
+    helmet?: boolean | HelmetConfig;
+    /** Logger configuration */
+    logger?: {
+        enabled?: boolean;
+        showUserAgent?: boolean;
+        showTime?: boolean;
+    };
+    /** Global error handler (true for defaults, function, or config) */
+    errorHandler?: boolean | ErrorHandler | ErrorHandlerConfig;
+}
+
+/**
+ * Zero-Dependency Logger
+ * Lightweight, colorful, and powerful logging system
+ */
+interface LoggerConfig {
+    /** Enable/disable logging */
+    enabled?: boolean;
+    /** Minimum log level */
+    minLevel?: "log" | "error" | "warn" | "debug";
+    /** Show timestamp */
+    timestamp?: boolean;
+}
+/**
+ * Logger class for specialized context logging
+ */
+declare class Logger {
+    private context;
+    private config;
+    constructor(context?: string, config?: LoggerConfig);
+    private getTimestamp;
+    private print;
+    log(message: string): void;
+    error(message: string, trace?: string): void;
+    warn(message: string): void;
+    debug(message: string): void;
+}
+
+/**
+ * Nural Framework
+ * Main application class that orchestrates adapters and documentation
+ */
+
+/**
+ * Nural - The intelligent, schema-first REST framework
+ *
+ * @example
+ * ```typescript
+ * const app = new Nural({
+ *   framework: 'express',
+ *   docs: true,
+ *   cors: true,
+ *   helmet: true,
+ *   errorHandler: true,
+ * });
+ * app.register([userRoute, healthRoute]);
+ * app.start(3000);
+ * ```
+ */
+declare class Nural {
+    private adapter;
+    private docsGenerator;
+    private docsConfig;
+    private corsConfig;
+    private helmetConfig;
+    private errorHandlerConfig;
+    private isExpress;
+    logger: Logger;
+    constructor(config?: NuralConfig);
+    /**
+     * Apply CORS and Helmet middleware based on config
+     */
+    private applyBuiltInMiddleware;
+    /**
+     * Register routes with the application
+     */
+    register(routes: AnyRouteConfig[]): void;
+    /**
+     * Start the server
+     */
+    start(port: number): void;
+    /**
+     * Setup documentation routes
+     */
+    private setupDocs;
+}
+
+/**
+ * Route Helper
+ */
+
+/**
+ * Create a type-safe route configuration
+ *
+ * @example
+ * ```typescript
+ * const userRoute = createRoute({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ *   summary: 'Get User by ID',
+ *   request: { params: z.object({ id: z.string() }) },
+ *   responses: { 200: z.object({ id: z.string(), name: z.string() }) },
+ *   handler: async ({ params }) => {
+ *     return { id: params.id, name: 'Chetan' };
+ *   }
+ * });
+ * ```
+ */
+declare function createRoute<P extends ZodAny = undefined, Q extends ZodAny = undefined, B extends ZodAny = undefined, R extends ZodAny = undefined, M extends MiddlewareHandler<any, any>[] | undefined = undefined>(config: RouteConfig<P, Q, B, R, M>): RouteConfig<P, Q, B, R, M>;
+
+/**
+ * Unified Exception System
+ * NestJS-style HTTP exceptions for standardized error handling
+ */
+interface HttpErrorResponse {
+    statusCode: number;
+    message: string;
+    error?: string;
+    timestamp?: string;
+    path?: string;
+    details?: unknown;
+}
+/**
+ * Base HTTP Exception Class
+ */
+declare class HttpException extends Error {
+    readonly statusCode: number;
+    readonly error: string;
+    readonly details?: unknown;
+    constructor(response: string | Record<string, any>, statusCode: number, details?: unknown);
+    getResponse(): HttpErrorResponse;
+    private getStatusName;
+}
+declare class BadRequestException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class UnauthorizedException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ForbiddenException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class NotFoundException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ConflictException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class GoneException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class PayloadTooLargeException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class UnsupportedMediaTypeException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class UnprocessableEntityException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class InternalServerErrorException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class NotImplementedException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class BadGatewayException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ServiceUnavailableException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class GatewayTimeoutException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Custom Exception for specific use cases
+ */
+declare class CustomException extends HttpException {
+    constructor(message: string, statusCode: number, details?: unknown);
+}
+
+export { type AnyRouteConfig, BadGatewayException, BadRequestException, ConflictException, type CorsConfig, CustomException, type DocsConfig, type ErrorContext, type ErrorHandler, type ErrorHandlerConfig, ForbiddenException, GatewayTimeoutException, GoneException, type HelmetConfig, type HttpErrorResponse, HttpException, type HttpMethod, type HttpStatusCode, InternalServerErrorException, Logger, type LoggerConfig, NotFoundException, NotImplementedException, Nural, type NuralConfig, PayloadTooLargeException, type RouteConfig, type RouteContext, type RouteHandler, ServiceUnavailableException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, createRoute, defineMiddleware };