nural 0.3.7 → 0.3.10

package/dist/index.d.cts

@@ -1,130 +1,12 @@
+import * as node_http from 'node:http';
+import * as fastify from 'fastify';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { Server } from 'http';
+import { Request, Response } from 'express';
 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>;
-    /**
-     * OpenAPI Security Requirements
-     * @example [{ bearerAuth: [] }]
-     */
-    security?: Array<Record<string, string[]>>;
-    /**
-     * OpenAPI Operation overrides
-     * Allows full customization of the operation (e.g., custom headers, externalDocs)
-     */
-    openapi?: Record<string, any>;
-    /** 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
@@ -427,6 +309,127 @@ interface NuralConfig {
     errorHandler?: boolean | ErrorHandler | ErrorHandlerConfig;
 }
 
+/**
+ * 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>;
+    /**
+     * OpenAPI Security Requirements
+     * @example [{ bearerAuth: [] }]
+     */
+    security?: Array<Record<string, string[]>>;
+    /**
+     * OpenAPI Operation overrides
+     * Allows full customization of the operation (e.g., custom headers, externalDocs)
+     */
+    openapi?: Record<string, any>;
+    /** 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>;
+
 /**
  * Zero-Dependency Logger
  * Lightweight, colorful, and powerful logging system
@@ -454,11 +457,6 @@ declare class Logger {
     debug(message: string): void;
 }
 
-/**
- * Nural Framework
- * Main application class that orchestrates adapters and documentation
- */
-
 /**
  * Nural - The intelligent, schema-first REST framework
  *
@@ -485,6 +483,7 @@ declare class Nural {
     private isExpress;
     logger: Logger;
     constructor(config?: NuralConfig);
+    get server(): fastify.RawServerDefault | Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>;
     /**
      * Apply CORS and Helmet middleware based on config
      */
@@ -496,7 +495,7 @@ declare class Nural {
     /**
      * Start the server
      */
-    start(port: number): void;
+    start(port: number): Server;
     /**
      * Setup documentation routes
      */

package/dist/index.d.ts

@@ -1,130 +1,12 @@
+import * as node_http from 'node:http';
+import * as fastify from 'fastify';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { Server } from 'http';
+import { Request, Response } from 'express';
 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>;
-    /**
-     * OpenAPI Security Requirements
-     * @example [{ bearerAuth: [] }]
-     */
-    security?: Array<Record<string, string[]>>;
-    /**
-     * OpenAPI Operation overrides
-     * Allows full customization of the operation (e.g., custom headers, externalDocs)
-     */
-    openapi?: Record<string, any>;
-    /** 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
@@ -427,6 +309,127 @@ interface NuralConfig {
     errorHandler?: boolean | ErrorHandler | ErrorHandlerConfig;
 }
 
+/**
+ * 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>;
+    /**
+     * OpenAPI Security Requirements
+     * @example [{ bearerAuth: [] }]
+     */
+    security?: Array<Record<string, string[]>>;
+    /**
+     * OpenAPI Operation overrides
+     * Allows full customization of the operation (e.g., custom headers, externalDocs)
+     */
+    openapi?: Record<string, any>;
+    /** 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>;
+
 /**
  * Zero-Dependency Logger
  * Lightweight, colorful, and powerful logging system
@@ -454,11 +457,6 @@ declare class Logger {
     debug(message: string): void;
 }
 
-/**
- * Nural Framework
- * Main application class that orchestrates adapters and documentation
- */
-
 /**
  * Nural - The intelligent, schema-first REST framework
  *
@@ -485,6 +483,7 @@ declare class Nural {
     private isExpress;
     logger: Logger;
     constructor(config?: NuralConfig);
+    get server(): fastify.RawServerDefault | Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>;
     /**
      * Apply CORS and Helmet middleware based on config
      */
@@ -496,7 +495,7 @@ declare class Nural {
     /**
      * Start the server
      */
-    start(port: number): void;
+    start(port: number): Server;
     /**
      * Setup documentation routes
      */