clear-router 2.1.12 → 2.3.0

package/dist/router-DLmimm_U.d.cts

@@ -0,0 +1,320 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { NextFunction, Request, Response as Response$1 } from "express";
+import { H3, H3Event, Middleware, TypedServerRequest } from "h3";
+
+//#region types/basic.d.ts
+/**
+ * Controller method reference
+ */
+type ControllerHandler = [any, string];
+/**
+ * HTTP methods supported by the router
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * Common controller action names
+ */
+type ControllerAction = 'index' | 'show' | 'create' | 'update' | 'destroy';
+/**
+ * Generic Object type for request data
+ */
+type RequestData = Record<string, any>;
+type ApiResourceMiddleware<M = any> = M | M[] | { [K in ControllerAction]?: M | M[] };
+interface RouterConfig {
+  /**
+   * Configuration for method override functionality, allowing clients to use a
+   * specific header or body parameter to override the HTTP method.
+   */
+  methodOverride?: {
+    /** Whether method override is enabled */enabled?: boolean; /** Keys in the request body to check for method override */
+    bodyKeys?: string[] | string; /** Keys in the request headers to check for method override */
+    headerKeys?: string[] | string;
+  };
+}
+//#endregion
+//#region types/express.d.ts
+interface RequestWithGetBody extends Request {
+  getBody: () => Record<string, any>;
+}
+/**
+ * HTTP context passed to route handlers
+ */
+interface HttpContext$1 {
+  req: RequestWithGetBody;
+  res: Response$1;
+  next: NextFunction;
+}
+/**
+ * Route handler function type
+ */
+type RouteHandler$1 = (
+/**
+ * Express context object containing req, res, and next
+ */
+
+ctx: HttpContext$1,
+/**
+ * ClearRequest instance
+ */
+
+req: ClearRequest) => any | Promise<any>;
+/**
+ * Handler can be either a function or controller reference
+ */
+type Handler$1 = RouteHandler$1 | ControllerHandler;
+/**
+ * Middleware function type
+ */
+type Middleware$1 = (req: Request, res: Response$1, next: NextFunction) => any | Promise<any>;
+//#endregion
+//#region types/h3.d.ts
+type H3App = Omit<H3['fetch'], 'fetch'> & {
+  fetch: (request: TypedServerRequest) => Promise<Response>;
+};
+type HttpRequest = H3Event['req'] & {
+  getBody: () => Record<string, any>;
+};
+/**
+ * HTTP context passed to route handlers
+ */
+type HttpContext = Omit<H3Event, 'req'> & {
+  req: HttpRequest;
+};
+/**
+ * Route handler function type
+ */
+type RouteHandler = (
+/**
+ * H3 event context
+ */
+
+ctx: HttpContext,
+/**
+ * ClearRequest instance
+ */
+
+req: ClearRequest) => any | Promise<any>;
+/**
+ * Handler can be either a function or controller reference
+ */
+type Handler = RouteHandler | ControllerHandler;
+//#endregion
+//#region src/Route.d.ts
+declare class Route<X = any, M = Middleware | Middleware$1, H = any> {
+  ctx: X;
+  body: RequestData;
+  query: RequestData;
+  params: RequestData;
+  clearRequest: ClearRequest;
+  methods: HttpMethod[];
+  path: string;
+  handler: H;
+  middlewares: M[];
+  controllerName?: string;
+  actionName?: string;
+  handlerType: 'function' | 'controller';
+  middlewareCount: number;
+  constructor(methods: HttpMethod[], path: string, handler: H, middlewares?: M[]);
+}
+//#endregion
+//#region src/ClearRequest.d.ts
+declare class ClearRequest<X = any, M = Middleware | Middleware$1> {
+  [key: string]: any;
+  /**
+   * @param body - Parsed request body
+   */
+  body: RequestData;
+  /**
+   * @param query - Parsed query parameters
+   */
+  query: RequestData;
+  /**
+   * @param params - Parsed route parameters
+   */
+  params: RequestData;
+  route: Route<X, M>;
+  constructor(init?: Partial<ClearRequest>);
+}
+//#endregion
+//#region src/Controller.d.ts
+declare abstract class Controller<X = any> {
+  [x: string]: any;
+  ctx: X;
+  body: RequestData;
+  query: RequestData;
+  params: RequestData;
+  clearRequest: ClearRequest;
+}
+//#endregion
+//#region src/core/router.d.ts
+/**
+ * @class clear-router CoreRouter
+ * @description Core routing logic for clear-router, shared between all supported adapters (Express.js, H3, etc.)
+ * @author 3m1n3nc3
+ * @repository https://github.com/toneflix/clear-router
+ */
+declare abstract class CoreRouter {
+  protected static createDefaultOptionsHandler(): any;
+  static config: RouterConfig;
+  protected static groupContext: AsyncLocalStorage<{
+    prefix: string;
+    groupMiddlewares: any[];
+  }>;
+  static routes: Array<Route<any, any, any>>;
+  static routesByPathMethod: Record<string, Route<any, any, any>>;
+  static routesByMethod: { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> };
+  static prefix: string;
+  static groupMiddlewares: any[];
+  static globalMiddlewares: any[];
+  protected static ensureState(this: any): void;
+  /**
+   * Normalizes a path by ensuring it starts with a single slash and does not have trailing
+   * slashes, while preserving dynamic segments and parameters.
+   *
+   * @param path  The path to normalize.
+   * @returns     The normalized path.
+   */
+  static normalizePath(path: string): string;
+  /**
+   * Configures the router with the given options, such as method override settings.
+   *
+   * @param this
+   * @param options
+   * @returns
+   */
+  static configure(this: any, options?: RouterConfig): void;
+  protected static resolveMethodOverride(this: any, method: string, headers: Headers | Record<string, any>, body: unknown): HttpMethod | null;
+  /**
+   * Adds a new route to the router with the specified methods, path, handler, and middlewares.
+   *
+   * @param this
+   * @param methods
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static add(this: any, methods: HttpMethod | HttpMethod[], path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new API resource route to the router for the specified base path and controller, with
+   * options to include/exclude specific actions and apply middlewares.
+   *
+   * @param this
+   * @param basePath
+   * @param controller
+   * @param options
+   */
+  static apiResource(this: any, basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+    middlewares?: ApiResourceMiddleware<any>;
+  }): void;
+  /**
+   * Adds a new GET route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this          The router instance.
+   * @param path          The path for the GET route.
+   * @param handler       The handler function for the GET route.
+   * @param middlewares   Optional middlewares to apply to the GET route.
+   */
+  static get(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new POST route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static post(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new PUT route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static put(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new DELETE route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static delete(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new PATCH route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static patch(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new OPTIONS route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static options(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new HEAD route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static head(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Defines a group of routes with a common prefix and optional middlewares, allowing for better
+   * organization and reuse of route configurations.
+   *
+   * @param this
+   * @param prefix
+   * @param callback
+   * @param middlewares
+   */
+  static group(this: any, prefix: string, callback: () => void | Promise<void>, middlewares?: any[]): Promise<void>;
+  /**
+   * Adds global middlewares to the router, which will be applied to all routes.
+   *
+   * @param this
+   * @param middlewares
+   * @param callback
+   */
+  static middleware(this: any, middlewares: any[], callback: () => void): void;
+  /**
+   * Retrieves all registered routes in the router, optionally organized by path or method
+   * for easier access and management.
+   *
+   * @param this
+   */
+  static allRoutes(this: any): Array<Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'path' to get routes organized by path
+   */
+  static allRoutes(this: any, type: 'path'): Record<string, Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'method' to get routes organized by method
+   */
+  static allRoutes(this: any, type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> };
+  protected static resolveHandler(route: Route<any, any, any>): {
+    handlerFunction: ((ctx: any, req: ClearRequest) => any | Promise<any>) | null;
+    instance: Controller<any> | null;
+  };
+  protected static bindRequestToInstance(ctx: any, instance: Controller<any> | Route<any, any, any> | null, route: Route<any, any, any>, payload: {
+    body: Record<string, any>;
+    query: Record<string, any>;
+    params: Record<string, any>;
+  }): void;
+}
+//#endregion
+export { Handler as a, Handler$1 as c, ApiResourceMiddleware as d, ControllerAction as f, H3App as i, HttpContext$1 as l, HttpMethod as m, ClearRequest as n, HttpContext as o, ControllerHandler as p, Route as r, Middleware as s, CoreRouter as t, Middleware$1 as u };

package/dist/router-cWYmcfTX.d.mts

@@ -0,0 +1,320 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { H3, H3Event, Middleware, TypedServerRequest } from "h3";
+import { NextFunction, Request, Response as Response$1 } from "express";
+
+//#region types/basic.d.ts
+/**
+ * Controller method reference
+ */
+type ControllerHandler = [any, string];
+/**
+ * HTTP methods supported by the router
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * Common controller action names
+ */
+type ControllerAction = 'index' | 'show' | 'create' | 'update' | 'destroy';
+/**
+ * Generic Object type for request data
+ */
+type RequestData = Record<string, any>;
+type ApiResourceMiddleware<M = any> = M | M[] | { [K in ControllerAction]?: M | M[] };
+interface RouterConfig {
+  /**
+   * Configuration for method override functionality, allowing clients to use a
+   * specific header or body parameter to override the HTTP method.
+   */
+  methodOverride?: {
+    /** Whether method override is enabled */enabled?: boolean; /** Keys in the request body to check for method override */
+    bodyKeys?: string[] | string; /** Keys in the request headers to check for method override */
+    headerKeys?: string[] | string;
+  };
+}
+//#endregion
+//#region types/express.d.ts
+interface RequestWithGetBody extends Request {
+  getBody: () => Record<string, any>;
+}
+/**
+ * HTTP context passed to route handlers
+ */
+interface HttpContext$1 {
+  req: RequestWithGetBody;
+  res: Response$1;
+  next: NextFunction;
+}
+/**
+ * Route handler function type
+ */
+type RouteHandler$1 = (
+/**
+ * Express context object containing req, res, and next
+ */
+
+ctx: HttpContext$1,
+/**
+ * ClearRequest instance
+ */
+
+req: ClearRequest) => any | Promise<any>;
+/**
+ * Handler can be either a function or controller reference
+ */
+type Handler$1 = RouteHandler$1 | ControllerHandler;
+/**
+ * Middleware function type
+ */
+type Middleware$1 = (req: Request, res: Response$1, next: NextFunction) => any | Promise<any>;
+//#endregion
+//#region types/h3.d.ts
+type H3App = Omit<H3['fetch'], 'fetch'> & {
+  fetch: (request: TypedServerRequest) => Promise<Response>;
+};
+type HttpRequest = H3Event['req'] & {
+  getBody: () => Record<string, any>;
+};
+/**
+ * HTTP context passed to route handlers
+ */
+type HttpContext = Omit<H3Event, 'req'> & {
+  req: HttpRequest;
+};
+/**
+ * Route handler function type
+ */
+type RouteHandler = (
+/**
+ * H3 event context
+ */
+
+ctx: HttpContext,
+/**
+ * ClearRequest instance
+ */
+
+req: ClearRequest) => any | Promise<any>;
+/**
+ * Handler can be either a function or controller reference
+ */
+type Handler = RouteHandler | ControllerHandler;
+//#endregion
+//#region src/Route.d.ts
+declare class Route<X = any, M = Middleware | Middleware$1, H = any> {
+  ctx: X;
+  body: RequestData;
+  query: RequestData;
+  params: RequestData;
+  clearRequest: ClearRequest;
+  methods: HttpMethod[];
+  path: string;
+  handler: H;
+  middlewares: M[];
+  controllerName?: string;
+  actionName?: string;
+  handlerType: 'function' | 'controller';
+  middlewareCount: number;
+  constructor(methods: HttpMethod[], path: string, handler: H, middlewares?: M[]);
+}
+//#endregion
+//#region src/ClearRequest.d.ts
+declare class ClearRequest<X = any, M = Middleware | Middleware$1> {
+  [key: string]: any;
+  /**
+   * @param body - Parsed request body
+   */
+  body: RequestData;
+  /**
+   * @param query - Parsed query parameters
+   */
+  query: RequestData;
+  /**
+   * @param params - Parsed route parameters
+   */
+  params: RequestData;
+  route: Route<X, M>;
+  constructor(init?: Partial<ClearRequest>);
+}
+//#endregion
+//#region src/Controller.d.ts
+declare abstract class Controller<X = any> {
+  [x: string]: any;
+  ctx: X;
+  body: RequestData;
+  query: RequestData;
+  params: RequestData;
+  clearRequest: ClearRequest;
+}
+//#endregion
+//#region src/core/router.d.ts
+/**
+ * @class clear-router CoreRouter
+ * @description Core routing logic for clear-router, shared between all supported adapters (Express.js, H3, etc.)
+ * @author 3m1n3nc3
+ * @repository https://github.com/toneflix/clear-router
+ */
+declare abstract class CoreRouter {
+  protected static createDefaultOptionsHandler(): any;
+  static config: RouterConfig;
+  protected static groupContext: AsyncLocalStorage<{
+    prefix: string;
+    groupMiddlewares: any[];
+  }>;
+  static routes: Array<Route<any, any, any>>;
+  static routesByPathMethod: Record<string, Route<any, any, any>>;
+  static routesByMethod: { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> };
+  static prefix: string;
+  static groupMiddlewares: any[];
+  static globalMiddlewares: any[];
+  protected static ensureState(this: any): void;
+  /**
+   * Normalizes a path by ensuring it starts with a single slash and does not have trailing
+   * slashes, while preserving dynamic segments and parameters.
+   *
+   * @param path  The path to normalize.
+   * @returns     The normalized path.
+   */
+  static normalizePath(path: string): string;
+  /**
+   * Configures the router with the given options, such as method override settings.
+   *
+   * @param this
+   * @param options
+   * @returns
+   */
+  static configure(this: any, options?: RouterConfig): void;
+  protected static resolveMethodOverride(this: any, method: string, headers: Headers | Record<string, any>, body: unknown): HttpMethod | null;
+  /**
+   * Adds a new route to the router with the specified methods, path, handler, and middlewares.
+   *
+   * @param this
+   * @param methods
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static add(this: any, methods: HttpMethod | HttpMethod[], path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new API resource route to the router for the specified base path and controller, with
+   * options to include/exclude specific actions and apply middlewares.
+   *
+   * @param this
+   * @param basePath
+   * @param controller
+   * @param options
+   */
+  static apiResource(this: any, basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+    middlewares?: ApiResourceMiddleware<any>;
+  }): void;
+  /**
+   * Adds a new GET route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this          The router instance.
+   * @param path          The path for the GET route.
+   * @param handler       The handler function for the GET route.
+   * @param middlewares   Optional middlewares to apply to the GET route.
+   */
+  static get(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new POST route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static post(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new PUT route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static put(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new DELETE route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static delete(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new PATCH route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static patch(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new OPTIONS route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static options(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Adds a new HEAD route to the router with the specified path, handler, and optional middlewares.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static head(this: any, path: string, handler: any, middlewares?: any[] | any): void;
+  /**
+   * Defines a group of routes with a common prefix and optional middlewares, allowing for better
+   * organization and reuse of route configurations.
+   *
+   * @param this
+   * @param prefix
+   * @param callback
+   * @param middlewares
+   */
+  static group(this: any, prefix: string, callback: () => void | Promise<void>, middlewares?: any[]): Promise<void>;
+  /**
+   * Adds global middlewares to the router, which will be applied to all routes.
+   *
+   * @param this
+   * @param middlewares
+   * @param callback
+   */
+  static middleware(this: any, middlewares: any[], callback: () => void): void;
+  /**
+   * Retrieves all registered routes in the router, optionally organized by path or method
+   * for easier access and management.
+   *
+   * @param this
+   */
+  static allRoutes(this: any): Array<Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'path' to get routes organized by path
+   */
+  static allRoutes(this: any, type: 'path'): Record<string, Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'method' to get routes organized by method
+   */
+  static allRoutes(this: any, type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> };
+  protected static resolveHandler(route: Route<any, any, any>): {
+    handlerFunction: ((ctx: any, req: ClearRequest) => any | Promise<any>) | null;
+    instance: Controller<any> | null;
+  };
+  protected static bindRequestToInstance(ctx: any, instance: Controller<any> | Route<any, any, any> | null, route: Route<any, any, any>, payload: {
+    body: Record<string, any>;
+    query: Record<string, any>;
+    params: Record<string, any>;
+  }): void;
+}
+//#endregion
+export { Handler as a, Handler$1 as c, ApiResourceMiddleware as d, ControllerAction as f, H3App as i, HttpContext$1 as l, HttpMethod as m, ClearRequest as n, HttpContext as o, ControllerHandler as p, Route as r, Middleware as s, CoreRouter as t, Middleware$1 as u };

package/dist/types/ClearRequest.d.mts

@@ -1,7 +1,7 @@
+import { RequestData } from "../types/basic.mjs";
 import { Middleware } from "../types/h3.mjs";
 import { Route } from "./Route.mjs";
 import { Middleware as Middleware$1 } from "../types/express.mjs";
-import { RequestData } from "../types/basic.mjs";
 
 //#region src/ClearRequest.d.ts
 declare class ClearRequest<X = any, M = Middleware | Middleware$1> {

package/dist/types/Route.d.mts

@@ -1,10 +1,10 @@
-import { Handler, Middleware } from "../types/h3.mjs";
+import { HttpMethod, RequestData } from "../types/basic.mjs";
+import { Middleware } from "../types/h3.mjs";
 import { ClearRequest } from "./ClearRequest.mjs";
 import { Middleware as Middleware$1 } from "../types/express.mjs";
-import { HttpMethod, RequestData } from "../types/basic.mjs";
 
 //#region src/Route.d.ts
-declare class Route<X = any, M = Middleware | Middleware$1> {
+declare class Route<X = any, M = Middleware | Middleware$1, H = any> {
   ctx: X;
   body: RequestData;
   query: RequestData;
@@ -12,13 +12,13 @@ declare class Route<X = any, M = Middleware | Middleware$1> {
   clearRequest: ClearRequest;
   methods: HttpMethod[];
   path: string;
-  handler: Handler;
+  handler: H;
   middlewares: M[];
   controllerName?: string;
   actionName?: string;
   handlerType: 'function' | 'controller';
   middlewareCount: number;
-  constructor(methods: HttpMethod[], path: string, handler: Handler, middlewares?: M[]);
+  constructor(methods: HttpMethod[], path: string, handler: H, middlewares?: M[]);
 }
 //#endregion
 export { Route };

package/dist/types/basic.d.mts

@@ -1,6 +1,3 @@
-import { Middleware } from "./h3.mjs";
-import { Middleware as Middleware$1 } from "./express.mjs";
-
 //#region types/basic.d.ts
 /**
  * Controller method reference
@@ -18,7 +15,7 @@ type ControllerAction = 'index' | 'show' | 'create' | 'update' | 'destroy';
  * Generic Object type for request data
  */
 type RequestData = Record<string, any>;
-type ApiResourceMiddleware<M extends Middleware$1 | Middleware> = M | M[] | { [K in ControllerAction]?: M | M[] };
+type ApiResourceMiddleware<M = any> = M | M[] | { [K in ControllerAction]?: M | M[] };
 interface RouterConfig {
   /**
    * Configuration for method override functionality, allowing clients to use a

package/dist/types/express.d.mts

@@ -1,5 +1,5 @@
-import { ClearRequest } from "./ClearRequest.mjs";
 import { ControllerHandler } from "./basic.mjs";
+import { ClearRequest } from "./ClearRequest.mjs";
 import { NextFunction, Request, Response } from "express";
 
 //#region types/express.d.ts