yinzerflow 0.2.10 → 0.3.0

package/index.d.ts

@@ -7,11 +7,158 @@ export type DeepPartial<T> = {
 	[P in keyof T]?: T[P] extends object ? T[P] extends Array<infer U> ? Array<U> // Keep arrays as-is, don't make array items partial
 	 : DeepPartial<T[P]> : T[P];
 };
+/**
+ * Generic types for handler callbacks that define the structure of request data
+ *
+ * This interface allows you to customize the types of body, response, query,
+ * params, and state data that your handlers can work with. Extend this interface
+ * to create type-safe contexts for your specific use cases.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default types
+ * const handler: HandlerCallback = async (ctx) => {
+ *   // ctx.request.body is unknown
+ *   // ctx.state is Record<string, unknown>
+ *   return { message: 'Hello' };
+ * };
+ *
+ * // Custom types for specific endpoints
+ * interface UserCreateContext extends InternalHandlerCallbackGenerics {
+ *   body: { name: string; email: string; age: number };
+ *   response: { id: string; name: string; email: string };
+ *   state: { requestId: string; userAgent: string };
+ * }
+ *
+ * const createUser: HandlerCallback<UserCreateContext> = async (ctx) => {
+ *   // Fully typed!
+ *   const { name, email, age } = ctx.request.body; // Type: { name: string; email: string; age: number }
+ *   const { requestId, userAgent } = ctx.state;    // Type: { requestId: string; userAgent: string }
+ *
+ *   const user = await createUserInDatabase({ name, email, age });
+ *
+ *   return { id: user.id, name: user.name, email: user.email }; // Must match response type
+ * };
+ * ```
+ */
 export interface InternalHandlerCallbackGenerics {
+	/**
+	 * The expected type of the request body
+	 *
+	 * Defaults to `unknown` for safety. Override with your specific body schema
+	 * to get full type safety and IntelliSense.
+	 *
+	 * @example
+	 * ```typescript
+	 * interface LoginContext extends InternalHandlerCallbackGenerics {
+	 *   body: { username: string; password: string };
+	 * }
+	 *
+	 * const login: HandlerCallback<LoginContext> = async (ctx) => {
+	 *   const { username, password } = ctx.request.body; // Fully typed!
+	 *   // ... authentication logic
+	 * };
+	 * ```
+	 */
 	body?: unknown;
+	/**
+	 * The expected type of the response data
+	 *
+	 * Defaults to `unknown`. Override to ensure your handler returns the correct
+	 * data structure and get compile-time validation.
+	 *
+	 * @example
+	 * ```typescript
+	 * interface UserListContext extends InternalHandlerCallbackGenerics {
+	 *   response: { users: Array<{ id: string; name: string }>; total: number };
+	 * }
+	 *
+	 * const listUsers: HandlerCallback<UserListContext> = async (ctx) => {
+	 *   const users = await getUsersFromDatabase();
+	 *
+	 *   // TypeScript will ensure this matches the response type
+	 *   return {
+	 *     users: users.map(u => ({ id: u.id, name: u.name })),
+	 *     total: users.length
+	 *   };
+	 * };
+	 * ```
+	 */
 	response?: unknown;
+	/**
+	 * The expected type of query parameters
+	 *
+	 * Defaults to `Record<string, string>`. Override for more specific query
+	 * parameter validation and typing.
+	 *
+	 * @example
+	 * ```typescript
+	 * interface SearchContext extends InternalHandlerCallbackGenerics {
+	 *   query: { q: string; limit?: string; page?: string };
+	 * }
+	 *
+	 * const search: HandlerCallback<SearchContext> = async (ctx) => {
+	 *   const { q, limit = '10', page = '1' } = ctx.request.query;
+	 *   const limitNum = parseInt(limit);
+	 *   const pageNum = parseInt(page);
+	 *
+	 *   // ... search logic
+	 * };
+	 * ```
+	 */
 	query?: Record<string, string>;
+	/**
+	 * The expected type of route parameters
+	 *
+	 * Defaults to `Record<string, string>`. Override for more specific route
+	 * parameter validation and typing.
+	 *
+	 * @example
+	 * ```typescript
+	 * interface UserDetailContext extends InternalHandlerCallbackGenerics {
+	 *   params: { id: string; tab?: string };
+	 * }
+	 *
+	 * const getUser: HandlerCallback<UserDetailContext> = async (ctx) => {
+	 *   const { id, tab = 'profile' } = ctx.request.params;
+	 *
+	 *   // ... user retrieval logic
+	 * };
+	 * ```
+	 */
 	params?: Record<string, string>;
+	/**
+	 * User-defined state data that persists throughout the request lifecycle
+	 *
+	 * This allows you to store custom data like:
+	 * - Authenticated user information
+	 * - Request-scoped variables
+	 * - Middleware data
+	 * - Custom context information
+	 *
+	 * @example
+	 * ```typescript
+	 * interface AuthContext extends InternalHandlerCallbackGenerics {
+	 *   state: {
+	 *     user: User;
+	 *     permissions: string[];
+	 *     requestId: string;
+	 *   };
+	 * }
+	 *
+	 * const handler: HandlerCallback<AuthContext> = async (ctx) => {
+	 *   // Fully typed state access
+	 *   const { user, permissions, requestId } = ctx.state;
+	 *
+	 *   if (permissions.includes('admin')) {
+	 *     return { message: 'Admin access granted', user };
+	 *   }
+	 *
+	 *   return { error: 'Insufficient permissions' };
+	 * };
+	 * ```
+	 */
+	state?: Record<string, unknown>;
 }
 declare const httpStatusCode: {
 	readonly ok: 200;
@@ -126,38 +273,861 @@ declare const httpHeaders: {
 	readonly clearSiteData: "Clear-Site-Data";
 	readonly noVarySearch: "No-Vary-Search";
 };
+/**
+ * HTTP status code constants for response status.
+ *
+ * Standard HTTP status codes used in responses to indicate
+ * the result of processing a request.
+ *
+ * ## Status Code Categories
+ *
+ * - **2xx Success**: Request was successful
+ * - **3xx Redirection**: Further action needed
+ * - **4xx Client Error**: Request was invalid
+ * - **5xx Server Error**: Server failed to process request
+ *
+ * @example
+ * ```typescript
+ * // Setting response status codes
+ * ctx.response.setStatusCode(InternalHttpStatusCode.ok);           // 200
+ * ctx.response.setStatusCode(InternalHttpStatusCode.created);      // 201
+ * ctx.response.setStatusCode(InternalHttpStatusCode.noContent);    // 204
+ *
+ * // Error handling
+ * try {
+ *   const result = await processRequest(ctx.request);
+ *   ctx.response.setStatusCode(InternalHttpStatusCode.ok);
+ *   return result;
+ * } catch (error) {
+ *   if (error.name === 'ValidationError') {
+ *     ctx.response.setStatusCode(InternalHttpStatusCode.badRequest);        // 400
+ *     return { error: 'Validation failed' };
+ *   }
+ *
+ *   if (error.name === 'UnauthorizedError') {
+ *     ctx.response.setStatusCode(InternalHttpStatusCode.unauthorized);      // 401
+ *     return { error: 'Unauthorized' };
+ *   }
+ *
+ *   ctx.response.setStatusCode(InternalHttpStatusCode.internalServerError); // 500
+ *   return { error: 'Internal server error' };
+ * }
+ *
+ * // Status code validation
+ * const isValidStatusCode = (code: number): boolean => {
+ *   return Object.values(InternalHttpStatusCode).includes(code as any);
+ * };
+ * ```
+ *
+ * @see {@link InternalHttpStatus} for corresponding status text
+ * @see {@link httpStatusCode} for the underlying constant values
+ */
 export type InternalHttpStatusCode = CreateEnum<typeof httpStatusCode>;
+/**
+ * HTTP method constants for request methods.
+ *
+ * Standard HTTP methods used in requests to specify the desired
+ * action to be performed on the identified resource.
+ *
+ * ## HTTP Methods
+ *
+ * - **GET**: Retrieve a resource
+ * - **POST**: Create a new resource
+ * - **PUT**: Replace an entire resource
+ * - **PATCH**: Partially modify a resource
+ * - **DELETE**: Remove a resource
+ * - **HEAD**: Get resource metadata only
+ * - **OPTIONS**: Get available methods
+ *
+ * @example
+ * ```typescript
+ * // Method-based routing
+ * const handleRequest = async (ctx: Context) => {
+ *   switch (ctx.request.method) {
+ *     case InternalHttpMethod.get:
+ *       return await getResource(ctx.request.params.id);
+ *
+ *     case InternalHttpMethod.post:
+ *       return await createResource(ctx.request.body);
+ *
+ *     case InternalHttpMethod.put:
+ *       return await updateResource(ctx.request.params.id, ctx.request.body);
+ *
+ *     case InternalHttpMethod.patch:
+ *       return await patchResource(ctx.request.params.id, ctx.request.body);
+ *
+ *     case InternalHttpMethod.delete:
+ *       return await deleteResource(ctx.request.params.id);
+ *
+ *     case InternalHttpMethod.options:
+ *       return { methods: ['GET', 'POST', 'PUT', 'DELETE'] };
+ *
+ *     default:
+ *       throw new Error(`Method ${ctx.request.method} not supported`);
+ *   }
+ * };
+ *
+ * // Method validation
+ * const isReadMethod = (method: string): boolean => {
+ *   return method === InternalHttpMethod.get || method === InternalHttpMethod.head;
+ * };
+ *
+ * const isWriteMethod = (method: string): boolean => {
+ *   return [InternalHttpMethod.post, InternalHttpMethod.put,
+ *           InternalHttpMethod.patch, InternalHttpMethod.delete].includes(method as any);
+ * };
+ * ```
+ *
+ * @see {@link httpMethod} for the underlying constant values
+ */
 export type InternalHttpMethod = CreateEnum<typeof httpMethod>;
+/**
+ * HTTP header constants for request and response headers.
+ *
+ * Comprehensive collection of HTTP header names organized by category,
+ * including standard headers, security headers, and custom headers.
+ *
+ * ## Header Categories
+ *
+ * - **Authentication**: Authorization, WWW-Authenticate
+ * - **Caching**: Cache-Control, ETag, Expires
+ * - **Content**: Content-Type, Content-Length, Content-Encoding
+ * - **CORS**: Access-Control-Allow-*, Access-Control-Request-*
+ * - **Security**: Content-Security-Policy, X-Frame-Options
+ * - **Custom**: X-Powered-By, X-Request-ID
+ *
+ * @example
+ * ```typescript
+ * // Setting security headers
+ * ctx.response.addHeaders({
+ *   [InternalHttpHeaders.contentSecurityPolicy]: "default-src 'self'",
+ *   [InternalHttpHeaders.xFrameOptions]: 'DENY',
+ *   [InternalHttpHeaders.xContentTypeOptions]: 'nosniff',
+ *   [InternalHttpHeaders.strictTransportSecurity]: 'max-age=31536000'
+ * });
+ *
+ * // CORS headers
+ * ctx.response.addHeaders({
+ *   [InternalHttpHeaders.accessControlAllowOrigin]: '*',
+ *   [InternalHttpHeaders.accessControlAllowMethods]: 'GET, POST, PUT, DELETE',
+ *   [InternalHttpHeaders.accessControlAllowHeaders]: 'Content-Type, Authorization'
+ * });
+ *
+ * // Custom headers
+ * ctx.response.addHeaders({
+ *   [InternalHttpHeaders.xRequestId]: generateRequestId(),
+ *   [InternalHttpHeaders.xProcessingTime]: `${processingTime}ms`
+ * });
+ *
+ * // Header validation
+ * const isSecurityHeader = (headerName: string): boolean => {
+ *   const securityHeaders = [
+ *     InternalHttpHeaders.contentSecurityPolicy,
+ *     InternalHttpHeaders.xFrameOptions,
+ *     InternalHttpHeaders.xContentTypeOptions,
+ *     InternalHttpHeaders.strictTransportSecurity
+ *   ];
+ *   return securityHeaders.includes(headerName as any);
+ * };
+ *
+ * // Request header processing
+ * const processRequestHeaders = (headers: Record<string, string>) => {
+ *   const authToken = headers[InternalHttpHeaders.authorization];
+ *   const contentType = headers[InternalHttpHeaders.contentType];
+ *   const userAgent = headers[InternalHttpHeaders.userAgent];
+ *
+ *   // Process headers...
+ *   return { authToken, contentType, userAgent };
+ * };
+ * ```
+ *
+ * @see {@link httpHeaders} for the underlying constant values
+ * @see {@link Request} for accessing headers in requests
+ * @see {@link Response} for setting headers in responses
+ */
 export type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
 interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
+	/**
+	 * The HTTP protocol version (e.g., "HTTP/1.1").
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   if (ctx.request.protocol === 'HTTP/2.0') {
+	 *     // Use HTTP/2 specific features
+	 *     ctx.response.addHeaders({ 'X-HTTP-Version': '2.0' });
+	 *   }
+	 *
+	 *   return { protocol: ctx.request.protocol };
+	 * };
+	 * ```
+	 */
 	protocol: string;
+	/**
+	 * The HTTP method of the request (GET, POST, PUT, DELETE, etc.).
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { method } = ctx.request;
+	 *
+	 *   switch (method) {
+	 *     case 'GET':
+	 *       return { action: 'retrieve', data: await getData() };
+	 *     case 'POST':
+	 *       return { action: 'create', data: await createData(ctx.request.body) };
+	 *     case 'PUT':
+	 *       return { action: 'update', data: await updateData(ctx.request.body) };
+	 *     case 'DELETE':
+	 *       return { action: 'delete', data: await deleteData(ctx.request.params.id) };
+	 *     default:
+	 *       throw new Error(`Unsupported method: ${method}`);
+	 *   }
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHttpMethod} for all available HTTP methods
+	 */
 	method: InternalHttpMethod;
+	/**
+	 * The request path/URL without query parameters.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { path } = ctx.request;
+	 *
+	 *   // Log the requested path
+	 *   console.log(`Request to: ${path}`);
+	 *
+	 *   // Route-specific logic based on path
+	 *   if (path.startsWith('/api/v1/')) {
+	 *     ctx.state.apiVersion = 'v1';
+	 *   } else if (path.startsWith('/api/v2/')) {
+	 *     ctx.state.apiVersion = 'v2';
+	 *   }
+	 *
+	 *   return { requestedPath: path, apiVersion: ctx.state.apiVersion };
+	 * };
+	 * ```
+	 */
 	path: string;
+	/**
+	 * HTTP headers sent with the request.
+	 *
+	 * Headers are case-insensitive and commonly include authorization,
+	 * content-type, user-agent, and custom headers.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { headers } = ctx.request;
+	 *
+	 *   // Authentication
+	 *   const authToken = headers.authorization;
+	 *   if (!authToken) {
+	 *     throw new Error('Authorization header required');
+	 *   }
+	 *
+	 *   // Content type validation
+	 *   const contentType = headers['content-type'];
+	 *   if (contentType !== 'application/json') {
+	 *     throw new Error('Content-Type must be application/json');
+	 *   }
+	 *
+	 *   // Custom headers
+	 *   const requestId = headers['x-request-id'];
+	 *   const userId = headers['x-user-id'];
+	 *
+	 *   return {
+	 *     hasAuth: !!authToken,
+	 *     contentType,
+	 *     requestId,
+	 *     userId
+	 *   };
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHttpHeaders} for all available header names
+	 */
 	headers: Partial<Record<InternalHttpHeaders, string>>;
+	/**
+	 * The parsed request body, typed according to the generic parameter.
+	 *
+	 * The body is automatically parsed based on Content-Type header.
+	 * For JSON requests, this will be the parsed JavaScript object.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Basic body access
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { body } = ctx.request;
+	 *
+	 *   // body is typed as 'unknown' by default
+	 *   if (typeof body === 'object' && body !== null) {
+	 *     const userData = body as { name: string; email: string };
+	 *     return { received: userData };
+	 *   }
+	 *
+	 *   return { error: 'Invalid body format' };
+	 * };
+	 *
+	 * // Typed body with generics
+	 * interface CreateUserRequest extends InternalHandlerCallbackGenerics {
+	 *   body: { name: string; email: string; age: number };
+	 * }
+	 *
+	 * const createUser: HandlerCallback<CreateUserRequest> = async (ctx) => {
+	 *   const { name, email, age } = ctx.request.body; // Fully typed!
+	 *
+	 *   // Validate age
+	 *   if (age < 18) {
+	 *     throw new Error('User must be 18 or older');
+	 *   }
+	 *
+	 *   const user = await createUserInDatabase({ name, email, age });
+	 *   return { success: true, user };
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHandlerCallbackGenerics} for custom body typing
+	 */
 	body: T["body"];
+	/**
+	 * Query parameters from the URL, typed according to the generic parameter.
+	 *
+	 * Query parameters are the key-value pairs after the ? in the URL.
+	 * They're automatically parsed and made available here.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Basic query parameter access
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { query } = ctx.request;
+	 *
+	 *   // query is typed as 'unknown' by default
+	 *   if (typeof query === 'object' && query !== null) {
+	 *     const { page, limit, search } = query as { page?: string; limit?: string; search?: string };
+	 *
+	 *     const pageNum = parseInt(page || '1');
+	 *     const limitNum = parseInt(limit || '10');
+	 *
+	 *     return { pagination: { page: pageNum, limit: limitNum }, search };
+	 *   }
+	 *
+	 *   return { pagination: { page: 1, limit: 10 } };
+	 * };
+	 *
+	 * // Typed query parameters with generics
+	 * interface UserListRequest extends InternalHandlerCallbackGenerics {
+	 *   query: { page: string; limit: string; search?: string; sort?: string };
+	 * }
+	 *
+	 * const listUsers: HandlerCallback<UserListRequest> = async (ctx) => {
+	 *   const { page, limit, search, sort } = ctx.request.query; // Fully typed!
+	 *
+	 *   const pageNum = parseInt(page);
+	 *   const limitNum = parseInt(limit);
+	 *
+	 *   const users = await getUsersFromDatabase({
+	 *     page: pageNum,
+	 *     limit: limitNum,
+	 *     search: search || '',
+	 *     sort: sort || 'name'
+	 *   });
+	 *
+	 *   return { users, pagination: { page: pageNum, limit: limitNum } };
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHandlerCallbackGenerics} for custom query typing
+	 */
 	query: T["query"];
+	/**
+	 * Route parameters extracted from the URL path, typed according to the generic parameter.
+	 *
+	 * Route parameters are the dynamic parts of the URL path (e.g., /users/:id).
+	 * They're automatically extracted and made available here.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Basic route parameter access
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { params } = ctx.request;
+	 *
+	 *   // params is typed as 'unknown' by default
+	 *   if (typeof params === 'object' && params !== null) {
+	 *     const { id, category } = params as { id?: string; category?: string };
+	 *
+	 *     if (!id) {
+	 *       throw new Error('User ID is required');
+	 *     }
+	 *
+	 *     return { userId: id, category: category || 'default' };
+	 *   }
+	 *
+	 *   return { error: 'No parameters found' };
+	 * };
+	 *
+	 * // Typed route parameters with generics
+	 * interface UserDetailRequest extends InternalHandlerCallbackGenerics {
+	 *   params: { id: string; tab?: string };
+	 * }
+	 *
+	 * const getUser: HandlerCallback<UserDetailRequest> = async (ctx) => {
+	 *   const { id, tab } = ctx.request.params; // Fully typed!
+	 *
+	 *   const user = await getUserById(id);
+	 *   if (!user) {
+	 *     throw new Error('User not found');
+	 *   }
+	 *
+	 *   // Return different data based on tab parameter
+	 *   switch (tab) {
+	 *     case 'profile':
+	 *       return { user: { id: user.id, name: user.name, email: user.email } };
+	 *     case 'settings':
+	 *       return { user: { id: user.id, preferences: user.preferences } };
+	 *     default:
+	 *       return { user };
+	 *   }
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHandlerCallbackGenerics} for custom params typing
+	 */
 	params: T["params"];
-	ipAddress: string; // The ip address of the client (Configure proxy hops if behind a proxy, load balancer, etc.)
-	rawBody: Buffer | string; // The raw body of the request. Useful for parsing the body manually.
+	/**
+	 * The IP address of the client making the request.
+	 *
+	 * **Important**: If you're behind a proxy, load balancer, or reverse proxy,
+	 * you may need to configure it to forward the real client IP address.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { ipAddress } = ctx.request;
+	 *
+	 *   // Log client IP for security and analytics
+	 *   console.log(`Request from IP: ${ipAddress}`);
+	 *
+	 *   // Rate limiting by IP
+	 *   const requestCount = await getRequestCount(ipAddress);
+	 *   if (requestCount > 100) {
+	 *     throw new Error('Rate limit exceeded');
+	 *   }
+	 *
+	 *   // Geolocation (if needed)
+	 *   const country = await getCountryFromIP(ipAddress);
+	 *   ctx.state.clientCountry = country;
+	 *
+	 *   return {
+	 *     message: 'Request processed',
+	 *     clientIP: ipAddress,
+	 *     country
+	 *   };
+	 * };
+	 * ```
+	 */
+	ipAddress: string;
+	/**
+	 * The raw, unparsed request body as a Buffer or string.
+	 *
+	 * This is useful when you need to parse the body manually or when
+	 * the automatic parsing doesn't meet your needs.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { rawBody, headers } = ctx.request;
+	 *
+	 *   // Manual parsing for specific content types
+	 *   const contentType = headers['content-type'];
+	 *
+	 *   if (contentType === 'application/xml') {
+	 *     // Parse XML manually
+	 *     const xmlString = rawBody.toString('utf8');
+	 *     const xmlDoc = await parseXML(xmlString);
+	 *     return { parsed: xmlDoc };
+	 *   }
+	 *
+	 *   if (contentType === 'multipart/form-data') {
+	 *     // Handle file uploads manually
+	 *     const formData = await parseMultipartFormData(rawBody);
+	 *     return { files: formData.files, fields: formData.fields };
+	 *   }
+	 *
+	 *   // For other types, use the parsed body
+	 *   return { body: ctx.request.body, rawBodyLength: rawBody.length };
+	 * };
+	 * ```
+	 */
+	rawBody: Buffer | string;
 }
 interface Response$1 {
+	/**
+	 * Sets the HTTP status code for the response.
+	 *
+	 * Common status codes:
+	 * - **2xx Success**: 200 (OK), 201 (Created), 204 (No Content)
+	 * - **3xx Redirection**: 301 (Moved), 302 (Found), 304 (Not Modified)
+	 * - **4xx Client Error**: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found)
+	 * - **5xx Server Error**: 500 (Internal Server Error), 502 (Bad Gateway)
+	 *
+	 * @param statusCode - The HTTP status code to set
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { response, request } = ctx;
+	 *
+	 *   try {
+	 *     if (request.method === 'POST') {
+	 *       // Resource created successfully
+	 *       response.setStatusCode(201);
+	 *       return { message: 'Resource created' };
+	 *     }
+	 *
+	 *     if (request.method === 'DELETE') {
+	 *       // Resource deleted successfully
+	 *       response.setStatusCode(204);
+	 *       return; // No content for DELETE
+	 *     }
+	 *
+	 *     // Default success response
+	 *     response.setStatusCode(200);
+	 *     return { message: 'Operation successful' };
+	 *
+	 *   } catch (error) {
+	 *     if (error.name === 'ValidationError') {
+	 *       response.setStatusCode(400);
+	 *       return { error: 'Validation failed', details: error.message };
+	 *     }
+	 *
+	 *     if (error.name === 'UnauthorizedError') {
+	 *       response.setStatusCode(401);
+	 *       return { error: 'Unauthorized' };
+	 *     }
+	 *
+	 *     // Default error response
+	 *     response.setStatusCode(500);
+	 *     return { error: 'Internal server error' };
+	 *   }
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHttpStatusCode} for all available status codes
+	 */
 	setStatusCode: (statusCode: InternalHttpStatusCode) => void;
+	/**
+	 * Adds or updates HTTP response headers.
+	 *
+	 * Headers are key-value pairs that provide metadata about the response.
+	 * Common headers include Content-Type, Cache-Control, and custom headers.
+	 *
+	 * @param headers - Object containing header names and values
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { response, request } = ctx;
+	 *
+	 *   // Set basic response headers
+	 *   response.addHeaders({
+	 *     'Content-Type': 'application/json',
+	 *     'Cache-Control': 'max-age=3600, public'
+	 *   });
+	 *
+	 *   // Add security headers
+	 *   response.addHeaders({
+	 *     'X-Content-Type-Options': 'nosniff',
+	 *     'X-Frame-Options': 'DENY',
+	 *     'X-XSS-Protection': '1; mode=block',
+	 *     'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
+	 *   });
+	 *
+	 *   // Add custom headers
+	 *   response.addHeaders({
+	 *     'X-API-Version': 'v1.0.0',
+	 *     'X-Request-ID': generateRequestId(),
+	 *     'X-Processing-Time': `${Date.now() - ctx.state.startTime}ms`
+	 *   });
+	 *
+	 *   // CORS headers for cross-origin requests
+	 *   response.addHeaders({
+	 *     'Access-Control-Allow-Origin': '*',
+	 *     'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+	 *     'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+	 *   });
+	 *
+	 *   return { message: 'Headers set successfully' };
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHttpHeaders} for all available header names
+	 */
 	addHeaders: (headers: Partial<Record<InternalHttpHeaders, string>>) => void;
+	/**
+	 * Removes specific HTTP response headers by name.
+	 *
+	 * This is useful when you want to remove headers that might have been
+	 * set by default or by previous middleware.
+	 *
+	 * @param headerNames - Array of header names to remove
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { response } = ctx;
+	 *
+	 *   // Remove default headers that might interfere
+	 *   response.removeHeaders([
+	 *     'X-Powered-By',
+	 *     'Server',
+	 *     'Date'
+	 *   ]);
+	 *
+	 *   // Add custom headers
+	 *   response.addHeaders({
+	 *     'X-Custom-Header': 'Custom Value',
+	 *     'Cache-Control': 'no-cache, no-store, must-revalidate'
+	 *   });
+	 *
+	 *   return { message: 'Custom response configured' };
+	 * };
+	 *
+	 * // Conditional header removal
+	 * const conditionalHandler: HandlerCallback = async (ctx) => {
+	 *   const { response, request } = ctx;
+	 *
+	 *   // Remove cache headers for sensitive operations
+	 *   if (request.method === 'POST' || request.method === 'PUT') {
+	 *     response.removeHeaders(['Cache-Control', 'ETag', 'Last-Modified']);
+	 *
+	 *     // Add no-cache headers
+	 *     response.addHeaders({
+	 *       'Cache-Control': 'no-cache, no-store, must-revalidate',
+	 *       'Pragma': 'no-cache',
+	 *       'Expires': '0'
+	 *     });
+	 *   }
+	 *
+	 *   return { message: 'Response configured based on method' };
+	 * };
+	 * ```
+	 *
+	 * @see {@link InternalHttpHeaders} for all available header names
+	 */
 	removeHeaders: (headerNames: Array<InternalHttpHeaders>) => void;
 }
+/**
+ * Request context that provides access to request, response, and user-defined state
+ *
+ * The context is the central object passed to all route handlers and middleware.
+ * It contains the request and response objects, plus any custom state data
+ * defined by the user through generics.
+ *
+ * @template T - Extends InternalHandlerCallbackGenerics to provide custom typing
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default context
+ * const handler: HandlerCallback = async (ctx) => {
+ *   // Access request data
+ *   const userId = ctx.request.params.id;
+ *   const userData = ctx.request.body;
+ *
+ *   // Store custom data in state
+ *   ctx.state.user = { id: userId, name: 'John' };
+ *   ctx.state.requestId = generateRequestId();
+ *
+ *   // Control response
+ *   ctx.response.setStatusCode(200);
+ *   ctx.response.addHeaders({ 'X-User-ID': userId });
+ *
+ *   // Return response body
+ *   return { success: true, user: ctx.state.user };
+ * };
+ *
+ * // Advanced usage with custom state typing
+ * interface AuthContext extends InternalHandlerCallbackGenerics {
+ *   state: {
+ *     user: User;
+ *     permissions: string[];
+ *     session: Session;
+ *   };
+ * }
+ *
+ * const authHandler: HandlerCallback<AuthContext> = async (ctx) => {
+ *   // Fully type-safe access to state
+ *   const { user, permissions, session } = ctx.state;
+ *
+ *   // No type assertions needed!
+ *   if (permissions.includes('admin')) {
+ *     ctx.response.setStatusCode(200);
+ *     return { message: 'Admin access granted', user };
+ *   }
+ *
+ *   ctx.response.setStatusCode(403);
+ *   return { error: 'Insufficient permissions' };
+ * };
+ * ```
+ */
 export interface Context<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
+	/**
+	 * The incoming request object containing all request data and metadata
+	 *
+	 * Provides access to headers, body, query parameters, route parameters, and metadata.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const userId = ctx.request.params.id;
+	 *   const userData = ctx.request.body;
+	 *   const authToken = ctx.request.headers.authorization;
+	 *   const clientIp = ctx.request.ipAddress;
+	 *
+	 *   return { userId, userData, hasAuth: !!authToken };
+	 * };
+	 * ```
+	 *
+	 * @see {@link Request} for complete request interface documentation
+	 */
 	request: Request$1<T>;
+	/**
+	 * The outgoing response object for controlling HTTP response behavior
+	 *
+	 * Provides methods to set status codes, add headers, and control response formatting.
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler: HandlerCallback = async (ctx) => {
+	 *   const { request, response } = ctx;
+	 *
+	 *   response.setStatusCode(201);
+	 *   response.addHeaders({
+	 *     'Location': `/api/users/${request.params.id}`,
+	 *     'X-User-ID': request.params.id
+	 *   });
+	 *
+	 *   return { message: 'User created successfully' };
+	 * };
+	 * ```
+	 *
+	 * @see {@link Response} for complete response interface documentation
+	 */
 	response: Response$1;
+	/**
+	 * User-defined state data that persists throughout the request lifecycle
+	 *
+	 * State is request-scoped data that can be accessed by route handlers and middleware.
+	 * Each request gets its own isolated state object that's automatically cleaned up.
+	 *
+	 * ## State Lifecycle
+	 *
+	 * 1. **Request Start**: State object is created as empty object
+	 * 2. **Global Hooks**: `beforeAll` hooks can populate state
+	 * 3. **Route Hooks**: `beforeHooks` can access and modify state
+	 * 4. **Route Handler**: Your handler can access and modify state
+	 * 5. **Route Hooks**: `afterHooks` can access state and modify response
+	 * 6. **Global Hooks**: `afterAll` hooks can access state and modify response
+	 * 7. **Request End**: State is automatically garbage collected
+	 *
+	 * @example
+	 * ```typescript
+	 * // Store data in state
+	 * ctx.state.user = { id: 1, name: 'John' };
+	 * ctx.state.requestId = generateRequestId();
+	 *
+	 * // Access the data
+	 * const user = ctx.state.user;
+	 * const requestId = ctx.state.requestId;
+	 * ```
+	 */
+	state: T["state"] extends Record<string, unknown> ? T["state"] : Record<string, unknown>;
 }
 /**
- * Represents a route handler function that returns a response body
+ * Represents a route handler function that processes requests and returns responses.
+ *
+ * This type defines the signature for all route handlers, middleware, and hooks
+ * in YinzerFlow. The function receives a context object and can optionally
+ * receive an error parameter for error handlers.
+ *
+ * ## Handler Types
+ *
+ * - **Route Handlers**: Process requests and return response data
+ * - **Middleware**: Modify context or perform side effects
+ * - **Hooks**: beforeHooks, afterHooks, beforeAll, afterAll
+ * - **Error Handlers**: Handle errors with error parameter
+ *
+ * ## Return Values
+ *
+ * Handlers can return:
+ * - **Response Data**: Objects, strings, numbers, etc. (automatically JSON serialized)
+ * - **Promise**: Async operations that resolve to response data
+ * - **Void**: No response body (useful for middleware)
+ * - **Error**: Thrown errors are caught by error handlers
+ *
+ * @template T - Extends InternalHandlerCallbackGenerics for custom typing
+ * @param ctx - The request context containing request, response, and state objects
+ * @param error - Optional error object (only provided to error handlers)
+ * @returns Response data, promise, or void
+ *
+ * @example
+ * ```typescript
+ * // Basic route handler
+ * const userHandler: HandlerCallback = async (ctx) => {
+ *   const userId = ctx.request.params.id;
+ *   const user = await getUserById(userId);
+ *
+ *   return { user, timestamp: new Date().toISOString() };
+ * };
+ *
+ * // Typed route handler with custom state
+ * interface UserContext extends InternalHandlerCallbackGenerics {
+ *   body: { name: string; email: string };
+ *   response: { id: string; name: string; email: string };
+ *   state: { user: User; permissions: string[] };
+ * }
  *
- * This type defines the signature for route handlers that process requests
- * and return a response. The function can return either a promise that resolves
- * to a response body or a response body directly.
+ * const createUser: HandlerCallback<UserContext> = async (ctx) => {
+ *   const { name, email } = ctx.request.body; // Fully typed!
+ *   const { user, permissions } = ctx.state;  // Fully typed!
  *
- * @param ctx - The request context containing request and response objects
- * @returns A response body or a promise that resolves to a response body
+ *   if (!permissions.includes('create')) {
+ *     throw new Error('Insufficient permissions');
+ *   }
+ *
+ *   const newUser = await createUserInDatabase({ name, email });
+ *
+ *   return { id: newUser.id, name: newUser.name, email: newUser.email };
+ * };
+ *
+ * // Middleware that doesn't return data
+ * const authMiddleware: HandlerCallback = async (ctx) => {
+ *   const token = ctx.request.headers.authorization;
+ *   const user = await validateToken(token);
+ *
+ *   ctx.state.user = user;
+ *   ctx.state.isAuthenticated = true;
+ *
+ *   // No return value needed for middleware
+ * };
+ *
+ * // Error handler
+ * const errorHandler: HandlerCallback = async (ctx, error) => {
+ *   console.error('Error occurred:', error);
+ *
+ *   ctx.response.setStatusCode(500);
+ *   return {
+ *     error: 'Internal server error',
+ *     message: process.env.NODE_ENV === 'production' ? 'Something went wrong' : error.message
+ *   };
+ * };
+ * ```
+ *
+ * @see {@link Context} for context interface details
+ * @see {@link InternalHandlerCallbackGenerics} for custom typing options
  */
 export type HandlerCallback<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> = (ctx: Context<T>, error?: unknown) => Promise<T["response"] | void> | T["response"] | void;
 export type InternalGlobalHookOptions = {
@@ -181,39 +1151,406 @@ export interface InternalHookRegistryImpl {
 	_addOnError: (handler: HandlerCallback) => void;
 	_addOnNotFound: (handler: HandlerCallback) => void;
 }
+/**
+ * Internal route registry implementation for managing route storage and lookup.
+ *
+ * This interface provides the core functionality for registering routes and
+ * finding them efficiently at runtime. It maintains separate collections for
+ * exact routes and parameterized routes for optimal performance.
+ *
+ * ## Route Types
+ *
+ * - **Exact Routes**: Direct string matches (e.g., "/api/users")
+ * - **Parameterized Routes**: Dynamic routes with parameters (e.g., "/users/:id")
+ *
+ * ## Performance Characteristics
+ *
+ * - **Exact Routes**: O(1) lookup time using Map
+ * - **Parameterized Routes**: O(n) lookup time with pre-compiled regex patterns
+ *
+ * @example
+ * ```typescript
+ * // This interface is used internally by YinzerFlow
+ * // Users typically don't interact with it directly
+ *
+ * // However, if you're extending the framework:
+ * class CustomRouteRegistry implements InternalRouteRegistryImpl {
+ *   readonly _exactRoutes = new Map();
+ *   readonly _parameterizedRoutes = new Map();
+ *
+ *   _register(route: InternalRouteRegistry) {
+ *     // Custom registration logic
+ *   }
+ *
+ *   _findRoute(method: InternalHttpMethod, path: string) {
+ *     // Custom route finding logic
+ *     return undefined;
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link InternalRouteRegistry} for individual route structure
+ * @see {@link InternalPreCompiledRoute} for parameterized route details
+ * @see {@link InternalHttpMethod} for available HTTP methods
+ */
 export interface InternalRouteRegistryImpl {
+	/**
+	 * Map of exact route matches organized by HTTP method and path.
+	 *
+	 * Provides O(1) lookup for routes that have no dynamic parameters.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Structure: Map<Method, Map<Path, Route>>
+	 * _exactRoutes = new Map([
+	 *   ['GET', new Map([
+	 *     ['/api/users', userListRoute],
+	 *     ['/api/posts', postListRoute]
+	 *   ])],
+	 *   ['POST', new Map([
+	 *     ['/api/users', createUserRoute]
+	 *   ])]
+	 * ]);
+	 * ```
+	 */
 	readonly _exactRoutes: Map<InternalHttpMethod, Map<string, InternalRouteRegistry>>;
+	/**
+	 * Array of parameterized routes with pre-compiled regex patterns.
+	 *
+	 * These routes contain dynamic parameters and require regex matching
+	 * at runtime. They're pre-compiled for performance.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Structure: Array of pre-compiled routes
+	 * _parameterizedRoutes = [
+	 *   {
+	 *     pattern: /^\/users\/([^\/]+)$/,
+	 *     paramNames: ['id'],
+	 *     path: '/users/:id',
+	 *     method: 'GET'
+	 *   }
+	 * ];
+	 * ```
+	 */
 	readonly _parameterizedRoutes: Map<InternalHttpMethod, Array<InternalPreCompiledRoute>>;
+	/**
+	 * Registers a new route in the appropriate collection.
+	 *
+	 * Routes are automatically categorized as exact or parameterized
+	 * based on whether they contain dynamic parameters.
+	 *
+	 * @param route - The route to register
+	 *
+	 * @example
+	 * ```typescript
+	 * _register({
+	 *   path: '/api/users/:id',
+	 *   method: 'GET',
+	 *   handler: getUserHandler,
+	 *   options: { beforeHooks: [authMiddleware] },
+	 *   params: {}
+	 * });
+	 * ```
+	 */
 	_register: (route: InternalRouteRegistry) => void;
+	/**
+	 * Finds a matching route for the given HTTP method and path.
+	 *
+	 * Searches exact routes first (O(1)), then parameterized routes (O(n))
+	 * until a match is found.
+	 *
+	 * @param method - The HTTP method to search for
+	 * @param path - The request path to match
+	 * @returns The matching route or undefined if no match found
+	 *
+	 * @example
+	 * ```typescript
+	 * const route = _findRoute('GET', '/api/users/123');
+	 * if (route) {
+	 *   // Extract parameters from path
+	 *   const params = extractParams(route, '/api/users/123');
+	 *   // Execute route handler
+	 *   await route.handler(context);
+	 * }
+	 * ```
+	 */
 	_findRoute: (method: InternalHttpMethod, path: string) => InternalRouteRegistry | undefined;
 }
+/**
+ * Configuration options for route registration.
+ *
+ * Defines hooks that will be executed before and after the route handler.
+ * Both hooks are optional and can be used independently.
+ *
+ * @example
+ * ```typescript
+ * // Route with authentication middleware
+ * const authRoute: InternalRouteRegistryOptions = {
+ *   beforeHooks: [
+ *     async (ctx) => {
+ *       const token = ctx.request.headers.authorization;
+ *       if (!token) throw new Error('Unauthorized');
+ *       ctx.state.user = await validateToken(token);
+ *     }
+ *   ]
+ * };
+ *
+ * // Route with response logging
+ * const loggingRoute: InternalRouteRegistryOptions = {
+ *   afterHooks: [
+ *     async (ctx, result) => {
+ *       console.log(`Response: ${JSON.stringify(result)}`);
+ *     }
+ *   ]
+ * };
+ *
+ * // Route with both hooks
+ * const fullRoute: InternalRouteRegistryOptions = {
+ *   beforeHooks: [authMiddleware],
+ *   afterHooks: [loggingMiddleware, metricsMiddleware]
+ * };
+ * ```
+ *
+ * @see {@link HandlerCallback} for hook function signature
+ */
 export interface InternalRouteRegistryOptions {
-	beforeHooks: Array<HandlerCallback>;
-	afterHooks: Array<HandlerCallback>;
+	/**
+	 * Hooks to execute before the route handler.
+	 *
+	 * These hooks run in order and can modify the context or throw errors.
+	 * If any hook throws an error, the route handler is not executed.
+	 *
+	 * @example
+	 * ```typescript
+	 * beforeHooks: [
+	 *   async (ctx) => {
+	 *     // Authentication
+	 *     ctx.state.user = await authenticate(ctx.request.headers.authorization);
+	 *   },
+	 *   async (ctx) => {
+	 *     // Rate limiting
+	 *     await checkRateLimit(ctx.request.ipAddress);
+	 *   },
+	 *   async (ctx) => {
+	 *     // Request validation
+	 *     validateRequest(ctx.request.body);
+	 *   }
+	 * ]
+	 * ```
+	 */
+	beforeHooks?: Array<HandlerCallback>;
+	/**
+	 * Hooks to execute after the route handler.
+	 *
+	 * These hooks run in reverse order and can modify the response or context.
+	 * They always execute, even if the route handler throws an error.
+	 *
+	 * @example
+	 * ```typescript
+	 * afterHooks: [
+	 *   async (ctx, result) => {
+	 *     // Response logging
+	 *     console.log(`Response: ${JSON.stringify(result)}`);
+	 *   },
+	 *   async (ctx) => {
+	 *     // Add response headers
+	 *     ctx.response.addHeaders({
+	 *       'X-Processing-Time': `${Date.now() - ctx.state.startTime}ms`
+	 *     });
+	 *   }
+	 * ]
+	 * ```
+	 */
+	afterHooks?: Array<HandlerCallback>;
 }
+/**
+ * Individual route registration with all necessary metadata.
+ *
+ * Each route contains the path, method, handler, and configuration options.
+ * Routes can be either exact matches or parameterized with dynamic segments.
+ *
+ * @example
+ * ```typescript
+ * const userRoute: InternalRouteRegistry = {
+ *   path: '/api/users/:id',
+ *   method: 'GET',
+ *   handler: async (ctx) => {
+ *     const { id } = ctx.request.params;
+ *     const user = await getUserById(id);
+ *     return user;
+ *   },
+ *   options: {
+ *     beforeHooks: [authMiddleware],
+ *     afterHooks: [loggingMiddleware]
+ *   },
+ *   params: { id: ':id' }
+ * };
+ * ```
+ *
+ * @see {@link InternalRouteRegistryOptions} for hook configuration
+ * @see {@link HandlerCallback} for handler function signature
+ * @see {@link InternalHttpMethod} for available HTTP methods
+ */
 export interface InternalRouteRegistry {
+	/**
+	 * Optional path prefix for route groups.
+	 *
+	 * When routes are registered in groups, this contains the group prefix.
+	 * The full route path is constructed by combining prefix + path.
+	 *
+	 * @example
+	 * ```typescript
+	 * // For a route in group '/api/v1'
+	 * prefix: '/api/v1'
+	 * path: '/users'
+	 * // Full route: /api/v1/users
+	 * ```
+	 */
 	prefix?: string;
+	/**
+	 * The route path pattern.
+	 *
+	 * Can contain static segments and dynamic parameters (e.g., ':id').
+	 *
+	 * @example
+	 * ```typescript
+	 * path: '/users/:id/posts/:postId'
+	 * // Matches: /users/123/posts/456
+	 * // Extracts: { id: '123', postId: '456' }
+	 * ```
+	 */
 	path: string;
+	/**
+	 * HTTP method this route responds to.
+	 *
+	 * @example
+	 * ```typescript
+	 * method: 'POST' // Only responds to POST requests
+	 * ```
+	 */
 	method: InternalHttpMethod;
+	/**
+	 * The function that handles requests to this route.
+	 *
+	 * Receives the request context and returns the response data.
+	 *
+	 * @example
+	 * ```typescript
+	 * handler: async (ctx) => {
+	 *   const { id } = ctx.request.params;
+	 *   const user = await getUserById(id);
+	 *   return { user, timestamp: new Date() };
+	 * }
+	 * ```
+	 */
 	handler: HandlerCallback;
+	/**
+	 * Configuration options including hooks and middleware.
+	 *
+	 * @example
+	 * ```typescript
+	 * options: {
+	 *   beforeHooks: [authMiddleware, validationMiddleware],
+	 *   afterHooks: [loggingMiddleware]
+	 * }
+	 * ```
+	 */
 	options: InternalRouteRegistryOptions;
+	/**
+	 * Parameter placeholders extracted from the path.
+	 *
+	 * Maps parameter names to their placeholder values (e.g., ':id').
+	 *
+	 * @example
+	 * ```typescript
+	 * // For path '/users/:id/posts/:postId'
+	 * params: {
+	 *   id: ':id',
+	 *   postId: ':postId'
+	 * }
+	 * ```
+	 */
 	params: Record<string, string>;
 }
 /**
- * Pre-compiled route with regex pattern for efficient runtime matching
+ * Pre-compiled route with regex pattern for efficient runtime matching.
  *
  * We compile route patterns into regexes at registration time (server startup)
  * rather than at request time for performance reasons:
  * - Registration: O(1) one-time cost per route
  * - Runtime: O(1) for exact routes, O(n) for parameterized routes with pre-compiled regex
  *
- * Example: "/users/:id/posts/:postId" becomes:
- * - pattern: /^\/users\/([^\/]+)\/posts\/([^\/]+)$/
- * - paramNames: ["id", "postId"]
+ * @example
+ * ```typescript
+ * // Route: "/users/:id/posts/:postId"
+ * const compiledRoute: InternalPreCompiledRoute = {
+ *   pattern: /^\/users\/([^\/]+)\/posts\/([^\/]+)$/,
+ *   paramNames: ["id", "postId"],
+ *   isParameterized: true,
+ *   path: "/users/:id/posts/:postId",
+ *   method: "GET",
+ *   handler: getUserPostsHandler,
+ *   options: { beforeHooks: [authMiddleware] },
+ *   params: { id: ":id", postId: ":postId" }
+ * };
+ *
+ * // Runtime matching
+ * const match = "/users/123/posts/456".match(compiledRoute.pattern);
+ * if (match) {
+ *   const params = {
+ *     [compiledRoute.paramNames[0]]: match[1], // id: "123"
+ *     [compiledRoute.paramNames[1]]: match[2]  // postId: "456"
+ *   };
+ * }
+ * ```
+ *
+ * @see {@link InternalRouteRegistry} for base route structure
  */
 export interface InternalPreCompiledRoute extends InternalRouteRegistry {
+	/**
+	 * Pre-compiled regex pattern for matching this route.
+	 *
+	 * The regex is created once at registration time and reused
+	 * for all subsequent requests to this route.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Path: "/users/:id"
+	 * pattern: /^\/users\/([^\/]+)$/
+	 *
+	 * // Path: "/posts/:category/:id"
+	 * pattern: /^\/posts\/([^\/]+)\/([^\/]+)$/
+	 * ```
+	 */
 	pattern: RegExp;
+	/**
+	 * Names of parameters in the order they appear in the path.
+	 *
+	 * Used to map regex capture groups to parameter names.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Path: "/users/:id/posts/:postId"
+	 * paramNames: ["id", "postId"]
+	 *
+	 * // Regex: /^\/users\/([^\/]+)\/posts\/([^\/]+)$/
+	 * // match[1] = "123" -> params.id = "123"
+	 * // match[2] = "456" -> params.postId = "456"
+	 * ```
+	 */
 	paramNames: Array<string>;
+	/**
+	 * Flag indicating this route has dynamic parameters.
+	 *
+	 * Always true for InternalPreCompiledRoute since these are
+	 * specifically for parameterized routes.
+	 *
+	 * @example
+	 * ```typescript
+	 * isParameterized: true // Always true for this interface
+	 * ```
+	 */
 	isParameterized: boolean;
 }
 declare const logLevels: {
@@ -585,18 +1922,279 @@ export interface InternalServerConfiguration {
 	 */
 	autoGracefulShutdown: boolean;
 }
-export type RouteGroup = Record<Lowercase<InternalHttpMethod>, InternalSetupMethod>;
-export interface Setup {
-	get: InternalSetupMethod;
-	post: InternalSetupMethod;
-	put: InternalSetupMethod;
-	patch: InternalSetupMethod;
-	delete: InternalSetupMethod;
-	options: InternalSetupMethod;
-	group: (prefix: string, callback: (group: RouteGroup) => void, options?: InternalRouteRegistryOptions) => void;
+export type HttpMethodHandlers = Record<Lowercase<keyof typeof httpMethod>, InternalSetupMethod>;
+export type RouteGroupMethod = (prefix: string, callback: (group: InternalGroupApp) => void, options?: InternalRouteRegistryOptions) => InternalGroupApp;
+export interface InternalGroupApp extends HttpMethodHandlers {
+	readonly group: RouteGroupMethod;
+}
+/**
+ * Main setup interface for configuring YinzerFlow routes, hooks, and middleware.
+ *
+ * The Setup interface provides methods for:
+ * - **Route Registration**: HTTP method handlers (GET, POST, PUT, etc.)
+ * - **Route Grouping**: Organized route prefixes with shared hooks
+ * - **Global Hooks**: beforeAll/afterAll hooks that run for all routes
+ * - **Error Handling**: Custom error and not-found handlers
+ *
+ * @example
+ * ```typescript
+ * import { YinzerFlow } from 'yinzerflow';
+ *
+ * const app = new YinzerFlow({ port: 3000 });
+ *
+ * // Register routes
+ * app.get('/api/users', async (ctx) => {
+ *   return { users: ['John', 'Jane'] };
+ * });
+ *
+ * app.post('/api/users', async (ctx) => {
+ *   const userData = ctx.request.body;
+ *   return { message: 'User created', data: userData };
+ * });
+ *
+ * // Set up global hooks
+ * app.beforeAll([
+ *   async (ctx) => {
+ *     ctx.state.requestId = generateRequestId();
+ *     ctx.state.timestamp = Date.now();
+ *   }
+ * ]);
+ *
+ * app.afterAll([
+ *   async (ctx, result) => {
+ *     ctx.response.addHeaders({
+ *       'X-Request-ID': ctx.state.requestId,
+ *       'X-Processing-Time': `${Date.now() - ctx.state.timestamp}ms`
+ *     });
+ *   }
+ * ]);
+ *
+ * // Create route groups
+ * app.group('/api/v1', (api) => {
+ *   api.group('/admin', (admin) => {
+ *     admin.get('/users', async (ctx) => {
+ *       return { adminUsers: ['Admin1', 'Admin2'] };
+ *     });
+ *   });
+ * });
+ *
+ * // Custom error handlers
+ * app.onError(async (ctx, error) => {
+ *   ctx.response.setStatusCode(500);
+ *   return { error: 'Internal server error', message: error.message };
+ * });
+ *
+ * app.onNotFound(async (ctx) => {
+ *   ctx.response.setStatusCode(404);
+ *   return { error: 'Not found', path: ctx.request.url };
+ * });
+ * ```
+ *
+ * @see {@link HttpMethodHandlers} for HTTP method registration methods
+ * @see {@link RouteGroupMethod} for route group creation method
+ * @see {@link InternalGlobalHookOptions} for global hook configuration options
+ * @see {@link HandlerCallback} for route handler function signature
+ */
+export interface Setup extends HttpMethodHandlers {
+	/**
+	 * Creates a route group with a shared prefix and optional shared hooks.
+	 *
+	 * Route groups allow you to organize related routes under a common path
+	 * prefix and apply shared hooks to all routes within the group.
+	 *
+	 * @param prefix - The URL prefix for all routes in this group (e.g., '/api/v1')
+	 * @param callback - Function that receives the group instance for registering routes
+	 * @param options - Optional shared hooks and configuration for the group
+	 *
+	 * @example
+	 * ```typescript
+	 * // Basic route group
+	 * app.group('/api', (api) => {
+	 *   api.get('/users', () => ({ users: [] }));
+	 *   api.post('/users', () => ({ created: true }));
+	 * });
+	 *
+	 * // Route group with shared hooks
+	 * app.group('/api/v1', (api) => {
+	 *   api.get('/users', () => ({ users: [] }));
+	 *   api.post('/users', () => ({ created: true }));
+	 * }, {
+	 *   beforeHooks: [
+	 *     async (ctx) => {
+	 *       ctx.state.apiVersion = 'v1';
+	 *       ctx.state.requiresAuth = true;
+	 *     }
+	 *   ]
+	 * });
+	 *
+	 * // Nested route groups
+	 * app.group('/api/v1', (api) => {
+	 *   api.group('/admin', (admin) => {
+	 *     admin.get('/users', () => ({ adminUsers: [] }));
+	 *     admin.get('/stats', () => ({ stats: {} }));
+	 *   });
+	 * });
+	 * ```
+	 *
+	 * @see {@link RouteGroupMethod} for method signature details
+	 * @see {@link InternalGroupApp} for group instance interface
+	 */
+	group: RouteGroupMethod;
+	/**
+	 * Registers global hooks that run before all route handlers.
+	 *
+	 * These hooks execute for every request before any route-specific hooks
+	 * or the route handler itself. They're perfect for setting up global
+	 * state, authentication, logging, or request preprocessing.
+	 *
+	 * @param handlers - Array of hook functions to execute
+	 * @param options - Optional configuration for hook execution scope
+	 *
+	 * @example
+	 * ```typescript
+	 * // Global authentication hook
+	 * app.beforeAll([
+	 *   async (ctx) => {
+	 *     const token = ctx.request.headers.authorization;
+	 *     if (token) {
+	 *       const user = await validateToken(token);
+	 *       ctx.state.user = user;
+	 *       ctx.state.isAuthenticated = true;
+	 *     }
+	 *   }
+	 * ]);
+	 *
+	 * // Global logging hook
+	 * app.beforeAll([
+	 *   async (ctx) => {
+	 *     ctx.state.requestId = generateRequestId();
+	 *     ctx.state.startTime = Date.now();
+	 *
+	 *     console.log(`Request ${ctx.state.requestId} to ${ctx.request.url}`);
+	 *   }
+	 * ], {
+	 *   routesToExclude: ['/health', '/metrics'] // Skip logging for health checks
+	 * });
+	 * ```
+	 *
+	 * @see {@link InternalGlobalHookOptions} for hook configuration options
+	 * @see {@link HandlerCallback} for hook function signature
+	 */
 	beforeAll: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	/**
+	 * Registers global hooks that run after all route handlers.
+	 *
+	 * These hooks execute for every request after the route handler completes
+	 * and after any route-specific after hooks. They're perfect for response
+	 * modification, logging, cleanup, or adding response headers.
+	 *
+	 * @param handlers - Array of hook functions to execute
+	 * @param options - Optional configuration for hook execution scope
+	 *
+	 * @example
+	 * ```typescript
+	 * // Global response modification hook
+	 * app.afterAll([
+	 *   async (ctx, result) => {
+	 *     // Add response headers based on state
+	 *     if (ctx.state.requestId) {
+	 *       ctx.response.addHeaders({
+	 *         'X-Request-ID': ctx.state.requestId,
+	 *         'X-Processing-Time': `${Date.now() - ctx.state.startTime}ms`
+	 *       });
+	 *     }
+	 *
+	 *     // Log response
+	 *     console.log(`Request ${ctx.state.requestId} completed with status ${ctx.response.statusCode}`);
+	 *   }
+	 * ]);
+	 *
+	 * // Global CORS hook
+	 * app.afterAll([
+	 *   async (ctx) => {
+	 *     ctx.response.addHeaders({
+	 *       'Access-Control-Allow-Origin': '*',
+	 *       'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+	 *       'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+	 *     });
+	 *   }
+	 * ]);
+	 * ```
+	 *
+	 * @see {@link InternalGlobalHookOptions} for hook configuration options
+	 * @see {@link HandlerCallback} for hook function signature
+	 */
 	afterAll: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	/**
+	 * Registers a custom error handler for all routes.
+	 *
+	 * This handler is called when any route throws an error or returns
+	 * a rejected promise. It receives the context and the error object,
+	 * allowing you to customize error responses and logging.
+	 *
+	 * @param handler - Function to handle errors
+	 *
+	 * @example
+	 * ```typescript
+	 * // Custom error handler
+	 * app.onError(async (ctx, error) => {
+	 *   // Log the error
+	 *   console.error(`Error in ${ctx.request.method} ${ctx.request.url}:`, error);
+	 *
+	 *   // Set appropriate status code
+	 *   if (error.name === 'ValidationError') {
+	 *     ctx.response.setStatusCode(400);
+	 *     return { error: 'Validation failed', details: error.message };
+	 *   }
+	 *
+	 *   if (error.name === 'UnauthorizedError') {
+	 *     ctx.response.setStatusCode(401);
+	 *     return { error: 'Unauthorized', message: error.message };
+	 *   }
+	 *
+	 *   // Default error response
+	 *   ctx.response.setStatusCode(500);
+	 *   return {
+	 *     error: 'Internal server error',
+	 *     message: process.env.NODE_ENV === 'production' ? 'Something went wrong' : error.message
+	 *   };
+	 * });
+	 * ```
+	 *
+	 * @see {@link HandlerCallback} for error handler function signature
+	 */
 	onError: (handler: HandlerCallback) => void;
+	/**
+	 * Registers a custom not-found handler for unmatched routes.
+	 *
+	 * This handler is called when a request doesn't match any registered
+	 * route. It receives the context and allows you to customize the
+	 * 404 response.
+	 *
+	 * @param handler - Function to handle not-found requests
+	 *
+	 * @example
+	 * ```typescript
+	 * // Custom not-found handler
+	 * app.onNotFound(async (ctx) => {
+	 *   ctx.response.setStatusCode(404);
+	 *
+	 *   // Return helpful error message
+	 *   return {
+	 *     error: 'Not found',
+	 *     message: `The requested resource '${ctx.request.url}' was not found`,
+	 *     availableEndpoints: [
+	 *       '/api/users',
+	 *       '/api/posts',
+	 *       '/health'
+	 *     ],
+	 *     documentation: 'https://api.example.com/docs'
+	 *   };
+	 * });
+	 * ```
+	 *
+	 * @see {@link HandlerCallback} for not-found handler function signature
+	 */
 	onNotFound: (handler: HandlerCallback) => void;
 }
 export type InternalSetupMethod = (path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions) => void;
@@ -623,10 +2221,60 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
 	_addOnNotFound(handler: HandlerCallback): void;
 }
 /**
- * User-facing configuration interface where all properties are optional
- * Users only need to specify what they want to override from defaults
+ * User-facing configuration interface where all properties are optional.
+ *
+ * Users only need to specify what they want to override from defaults.
+ * This is created by making the complete internal ServerConfigurationShape
+ * partially optional using DeepPartial.
+ *
+ * ## Configuration Options
+ *
+ * - **Server Settings**: Port, host, and network configuration
+ * - **Logging**: Log levels and custom logger configuration
+ * - **CORS**: Cross-origin resource sharing settings
+ * - **Performance**: Request handling and timeout settings
+ * - **Security**: Headers and security-related options
+ *
+ * @example
+ * ```typescript
+ * import { YinzerFlow } from 'yinzerflow';
+ *
+ * // Minimal configuration - only specify what you need
+ * const app = new YinzerFlow({ port: 3000 });
+ *
+ * // Basic configuration with logging
+ * const app = new YinzerFlow({
+ *   port: 8080,
+ *   logLevel: 'info',
+ *   networkLogs: true
+ * });
+ *
+ * // Full configuration example
+ * const app = new YinzerFlow({
+ *   port: 9000,
+ *   host: '0.0.0.0',
+ *   logLevel: 'debug',
+ *   networkLogs: true,
+ *   autoGracefulShutdown: true,
+ *   cors: {
+ *     enabled: true,
+ *     origin: ['https://example.com', 'https://app.example.com'],
+ *     methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *     headers: ['Content-Type', 'Authorization'],
+ *     credentials: true
+ *   },
+ *   logger: {
+ *     info: (message, ...args) => console.log(`[APP] ${message}`, ...args),
+ *     warn: (message, ...args) => console.warn(`[APP] ${message}`, ...args),
+ *     error: (message, ...args) => console.error(`[APP] ${message}`, ...args),
+ *     debug: (message, ...args) => console.debug(`[APP] ${message}`, ...args)
+ *   }
+ * });
+ * ```
  *
- * This is created by making the complete internal ServerConfigurationShape partially optional
+ * @see {@link InternalServerConfiguration} for complete internal configuration
+ * @see {@link DeepPartial} for how optional properties are created
+ * @see {@link CorsConfiguration} for CORS configuration options
  */
 export type ServerConfiguration = DeepPartial<InternalServerConfiguration>;
 declare class RouteRegistryImpl implements InternalRouteRegistryImpl {
@@ -651,7 +2299,7 @@ declare class SetupImpl implements InternalSetupImpl {
 	patch(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	delete(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	options(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
-	group(prefix: string, callback: (group: Record<Lowercase<InternalHttpMethod>, InternalSetupMethod>) => void, options?: InternalRouteRegistryOptions): void;
+	group(prefix: string, callback: (group: InternalGroupApp) => void, options?: InternalRouteRegistryOptions): InternalGroupApp;
 	beforeAll(handlers: Array<HandlerCallback<any>>, options?: InternalGlobalHookOptions): void;
 	afterAll(handlers: Array<HandlerCallback<any>>, options?: InternalGlobalHookOptions): void;
 	onError(handler: HandlerCallback<any>): void;