@mxweb/core 1.0.0

package/dist/route.d.ts

@@ -0,0 +1,298 @@
+/**
+ * @fileoverview Route definition for mapping HTTP methods and paths to handlers.
+ *
+ * This module provides the `Route` class which represents a single route definition
+ * in the application. Routes are created using static factory methods and can include:
+ * - HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
+ * - Path pattern with dynamic segments (e.g., "/users/:id")
+ * - Handler (controller method name or function)
+ * - Decorators (guards, filters, interceptors, pipes)
+ * - Middlewares
+ *
+ * @module route
+ *
+ * @example
+ * ```ts
+ * import { Route, applyDecorators, UseGuards } from "@mxweb/core";
+ *
+ * // Simple routes
+ * Route.get("/users", "findAll")
+ * Route.post("/users", "create")
+ * Route.get("/users/:id", "findOne")
+ *
+ * // Route with decorators
+ * Route.delete(
+ *   "/users/:id",
+ *   "remove",
+ *   applyDecorators(UseGuards(AuthGuard, AdminGuard))
+ * )
+ *
+ * // Route with inline handler
+ * Route.get("/health", async (ctx) => {
+ *   return ctx.response.success({ status: "ok" });
+ * })
+ * ```
+ */
+import { RouteMethod } from "./common";
+import { DecoratorResult } from "./decorator";
+import { Reflect, RouteHandler, RouteMiddleware } from "./execute";
+/**
+ * Represents a single route definition in the application.
+ *
+ * A Route encapsulates all information needed to match and handle an HTTP request:
+ * - The HTTP method (GET, POST, etc.)
+ * - The URL path pattern
+ * - The handler (controller method name or function)
+ * - Route-level guards, filters, interceptors, and pipes
+ * - Custom middlewares
+ *
+ * Routes are created using static factory methods (`get`, `post`, etc.)
+ * and are typically grouped together in a Router.
+ *
+ * @remarks
+ * The constructor is private - always use static factory methods to create routes.
+ *
+ * @example
+ * ```ts
+ * // Creating routes for a product feature
+ * const routes = [
+ *   Route.get("/", "findAll"),
+ *   Route.get("/:id", "findOne"),
+ *   Route.post("/", "create", applyDecorators(UseGuards(AuthGuard))),
+ *   Route.put("/:id", "update", applyDecorators(UseGuards(AuthGuard))),
+ *   Route.delete("/:id", "remove", applyDecorators(UseGuards(AuthGuard, AdminGuard))),
+ * ];
+ * ```
+ */
+export declare class Route {
+    private readonly method;
+    private readonly path;
+    private readonly action;
+    private readonly reflect;
+    private readonly middlewares;
+    /**
+     * Private constructor to enforce factory method usage.
+     *
+     * @param method - The HTTP method for this route
+     * @param path - The URL path pattern (can include dynamic segments like :id)
+     * @param action - Controller method name or inline handler function
+     * @param reflect - Reflect instance containing guards, filters, interceptors, pipes
+     * @param middlewares - Array of middleware functions for this route
+     */
+    private constructor();
+    /**
+     * Gets the HTTP method for this route.
+     *
+     * @returns The RouteMethod enum value
+     *
+     * @example
+     * ```ts
+     * const route = Route.get("/users", "findAll");
+     * console.log(route.getMethod()); // RouteMethod.GET
+     * ```
+     */
+    getMethod(): RouteMethod;
+    /**
+     * Gets the URL path pattern for this route.
+     *
+     * @returns The path string (e.g., "/users/:id")
+     *
+     * @example
+     * ```ts
+     * const route = Route.get("/users/:id", "findOne");
+     * console.log(route.getPath()); // "/users/:id"
+     * ```
+     */
+    getPath(): string;
+    /**
+     * Gets the action (handler) for this route.
+     *
+     * @returns The controller method name (string) or handler function
+     *
+     * @example
+     * ```ts
+     * const route = Route.get("/users", "findAll");
+     * console.log(route.getAction()); // "findAll"
+     * ```
+     */
+    getAction(): string | RouteHandler;
+    /**
+     * Gets the Reflect instance containing route-level decorators.
+     *
+     * @returns The Reflect instance with guards, filters, interceptors, pipes, and metadata
+     */
+    getReflect(): Reflect;
+    /**
+     * Gets the middleware functions for this route.
+     *
+     * @returns Array of middleware functions
+     */
+    getMiddlewares(): RouteMiddleware[];
+    /**
+     * Normalizes decorator/middleware arguments into a consistent format.
+     *
+     * This method handles the flexible API where the third parameter can be either
+     * a DecoratorResult (from applyDecorators) or a middleware function.
+     *
+     * @param decoratorsOrMiddleware - Either a DecoratorResult or a middleware function
+     * @param middlewares - Additional middleware functions
+     * @returns Tuple of [Reflect instance, middlewares array]
+     * @internal
+     */
+    private static normalize;
+    /**
+     * Creates a route with the specified HTTP method.
+     *
+     * This is the base factory method used by all HTTP method shortcuts.
+     *
+     * @param method - The HTTP method
+     * @param path - The URL path pattern
+     * @param action - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance
+     *
+     * @example
+     * ```ts
+     * Route.route(RouteMethod.GET, "/custom", "handler")
+     * ```
+     */
+    static route(method: RouteMethod, path: string, action: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, middlewares?: RouteMiddleware[]): Route;
+    /**
+     * Creates a GET route.
+     *
+     * Used for retrieving resources without side effects.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for GET requests
+     *
+     * @example
+     * ```ts
+     * // Simple GET route
+     * Route.get("/users", "findAll")
+     *
+     * // GET with path parameter
+     * Route.get("/users/:id", "findOne")
+     *
+     * // GET with guards
+     * Route.get("/profile", "getProfile", applyDecorators(UseGuards(AuthGuard)))
+     *
+     * // GET with inline handler
+     * Route.get("/ping", async () => ({ pong: true }))
+     * ```
+     */
+    static get(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates a POST route.
+     *
+     * Used for creating new resources.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for POST requests
+     *
+     * @example
+     * ```ts
+     * // Create resource
+     * Route.post("/users", "create")
+     *
+     * // With validation pipe
+     * Route.post("/users", "create", applyDecorators(UsePipes(ValidationPipe)))
+     * ```
+     */
+    static post(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates a PUT route.
+     *
+     * Used for replacing an entire resource.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for PUT requests
+     *
+     * @example
+     * ```ts
+     * // Replace entire resource
+     * Route.put("/users/:id", "replace")
+     * ```
+     */
+    static put(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates a PATCH route.
+     *
+     * Used for partial updates to a resource.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for PATCH requests
+     *
+     * @example
+     * ```ts
+     * // Partial update
+     * Route.patch("/users/:id", "update")
+     * ```
+     */
+    static patch(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates a DELETE route.
+     *
+     * Used for removing resources.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for DELETE requests
+     *
+     * @example
+     * ```ts
+     * // Delete resource (usually requires auth)
+     * Route.delete("/users/:id", "remove", applyDecorators(UseGuards(AuthGuard)))
+     * ```
+     */
+    static delete(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates a HEAD route.
+     *
+     * Used for retrieving headers without body (like GET but without response body).
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for HEAD requests
+     *
+     * @example
+     * ```ts
+     * Route.head("/users/:id", "checkExists")
+     * ```
+     */
+    static head(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+    /**
+     * Creates an OPTIONS route.
+     *
+     * Used for describing available communication options for a resource.
+     * Typically handled automatically by CORS middleware.
+     *
+     * @param path - The URL path pattern
+     * @param handle - Controller method name or handler function
+     * @param decoratorsOrMiddleware - Optional decorators or first middleware
+     * @param middlewares - Additional middlewares
+     * @returns A new Route instance for OPTIONS requests
+     *
+     * @example
+     * ```ts
+     * Route.options("/users", "corsOptions")
+     * ```
+     */
+    static options(path: string, handle: string | RouteHandler, decoratorsOrMiddleware?: DecoratorResult | RouteMiddleware, ...middlewares: RouteMiddleware[]): Route;
+}

package/dist/route.js

@@ -0,0 +1 @@
+"use strict";var t=require("./common.js"),e=require("./execute.js");class r{constructor(t,e,r,s,i=[]){this.method=t,this.path=e,this.action=r,this.reflect=s,this.middlewares=i}getMethod(){return this.method}getPath(){return this.path}getAction(){return this.action}getReflect(){return this.reflect}getMiddlewares(){return this.middlewares}static normalize(t,r){let s={guards:new Set,filters:new Set,interceptors:new Set,pipes:new Set,metadata:new Map};"function"==typeof t?r.unshift(t):t&&(s=t);return[new e.Reflect(s.metadata,s.guards,s.filters,s.interceptors,s.pipes),r]}static route(t,e,s,i,o=[]){return new r(t,e,s,...this.normalize(i,o))}static get(e,r,s,...i){return this.route(t.RouteMethod.GET,e,r,s,i)}static post(e,r,s,...i){return this.route(t.RouteMethod.POST,e,r,s,i)}static put(e,r,s,...i){return this.route(t.RouteMethod.PUT,e,r,s,i)}static patch(e,r,s,...i){return this.route(t.RouteMethod.PATCH,e,r,s,i)}static delete(e,r,s,...i){return this.route(t.RouteMethod.DELETE,e,r,s,i)}static head(e,r,s,...i){return this.route(t.RouteMethod.HEAD,e,r,s,i)}static options(e,r,s,...i){return this.route(t.RouteMethod.OPTIONS,e,r,s,i)}}exports.Route=r;

package/dist/route.mjs

@@ -0,0 +1 @@
+import{RouteMethod as t}from"./common.mjs";import{Reflect as e}from"./execute.mjs";class r{constructor(t,e,r,i,s=[]){this.method=t,this.path=e,this.action=r,this.reflect=i,this.middlewares=s}getMethod(){return this.method}getPath(){return this.path}getAction(){return this.action}getReflect(){return this.reflect}getMiddlewares(){return this.middlewares}static normalize(t,r){let i={guards:new Set,filters:new Set,interceptors:new Set,pipes:new Set,metadata:new Map};"function"==typeof t?r.unshift(t):t&&(i=t);return[new e(i.metadata,i.guards,i.filters,i.interceptors,i.pipes),r]}static route(t,e,i,s,n=[]){return new r(t,e,i,...this.normalize(s,n))}static get(e,r,i,...s){return this.route(t.GET,e,r,i,s)}static post(e,r,i,...s){return this.route(t.POST,e,r,i,s)}static put(e,r,i,...s){return this.route(t.PUT,e,r,i,s)}static patch(e,r,i,...s){return this.route(t.PATCH,e,r,i,s)}static delete(e,r,i,...s){return this.route(t.DELETE,e,r,i,s)}static head(e,r,i,...s){return this.route(t.HEAD,e,r,i,s)}static options(e,r,i,...s){return this.route(t.OPTIONS,e,r,i,s)}}export{r as Route};

package/dist/router.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Router for registering routes and matching incoming requests.
+ *
+ * This module provides the `Router` class which manages a collection of routes
+ * and matches incoming requests to the appropriate route handler. Features:
+ * - Path parameter extraction (e.g., `/users/:id` → `{ id: "123" }`)
+ * - Optional parameters (e.g., `/posts/:id?`)
+ * - Wildcard patterns (e.g., `/files/*` captures remaining path segments)
+ * - HTTP method matching
+ *
+ * @module router
+ *
+ * @example
+ * ```ts
+ * import { Router, Route } from "@mxweb/core";
+ *
+ * // Create a router with routes
+ * const router = Router.register(
+ *   Route.get("/", "index"),
+ *   Route.get("/:id", "findOne"),
+ *   Route.post("/", "create"),
+ *   Route.put("/:id", "update"),
+ *   Route.delete("/:id", "remove"),
+ * );
+ *
+ * // Match a request
+ * const matched = router.match(RouteMethod.GET, "/123");
+ * // matched = { route: ..., params: { id: "123" }, wildcards: [] }
+ * ```
+ */
+import { RouteMethod } from "./common";
+import { Route } from "./route";
+/**
+ * Result of a successful route match.
+ *
+ * Contains the matched route, extracted path parameters, and any
+ * wildcard segments captured from the URL.
+ *
+ * @example
+ * ```ts
+ * // For pattern "/users/:id" and path "/users/123"
+ * const matched: RouteMatched = {
+ *   route: Route.get("/users/:id", "findOne"),
+ *   params: { id: "123" },
+ *   wildcards: []
+ * };
+ *
+ * // For pattern "/files/*" and path "/files/images/photo.jpg"
+ * const matched: RouteMatched = {
+ *   route: Route.get("/files/*", "serveFile"),
+ *   params: {},
+ *   wildcards: ["images", "photo.jpg"]
+ * };
+ * ```
+ */
+export interface RouteMatched {
+    /** The matched Route instance */
+    route: Route;
+    /** Extracted path parameters (e.g., { id: "123" }) */
+    params: Record<string, string>;
+    /** Wildcard segments captured after a `*` pattern */
+    wildcards: string[];
+}
+/**
+ * Internal structure for registered routes.
+ *
+ * @internal
+ */
+export interface RouteRegister {
+    /** The HTTP method for this route */
+    method: RouteMethod;
+    /** The Route instance */
+    route: Route;
+}
+/**
+ * Router for managing and matching HTTP routes.
+ *
+ * The Router class provides route registration and URL matching capabilities.
+ * It supports:
+ * - **Path parameters**: `/users/:id` extracts `id` from the URL
+ * - **Optional parameters**: `/posts/:id?` makes `id` optional
+ * - **Wildcards**: `/files/*` captures all remaining segments
+ * - **Literal segments**: `/api/v1/users` matches exactly
+ *
+ * @remarks
+ * The constructor is private - use `Router.register()` to create instances.
+ * Each Feature typically has one Router that groups related routes.
+ *
+ * @example
+ * ```ts
+ * // Product feature router
+ * export const productRouter = Router.register(
+ *   Route.get("/", "findAll"),
+ *   Route.get("/:id", "findOne"),
+ *   Route.post("/", "create", applyDecorators(UseGuards(AuthGuard))),
+ *   Route.patch("/:id", "update", applyDecorators(UseGuards(AuthGuard))),
+ *   Route.delete("/:id", "remove", applyDecorators(UseGuards(AuthGuard, AdminGuard))),
+ * );
+ *
+ * // Feature with router
+ * export const productFeature = Feature.create({
+ *   path: "/products",
+ *   controller: ProductController,
+ *   router: productRouter,
+ * });
+ * ```
+ */
+export declare class Router {
+    private readonly registered;
+    /**
+     * Private constructor to enforce factory method usage.
+     *
+     * @param registered - Set of registered routes
+     */
+    private constructor();
+    /**
+     * Creates a new Router with the specified routes.
+     *
+     * This is the primary way to create a Router instance. Routes are
+     * registered in order and will be matched in that order.
+     *
+     * @param routes - One or more Route instances to register
+     * @returns A new Router instance
+     *
+     * @example
+     * ```ts
+     * const router = Router.register(
+     *   Route.get("/", "index"),
+     *   Route.get("/search", "search"),
+     *   Route.get("/:id", "findOne"),
+     *   Route.post("/", "create"),
+     * );
+     * ```
+     */
+    static register(...routes: Route[]): Router;
+    /**
+     * Matches an incoming request to a registered route.
+     *
+     * Iterates through registered routes in order and returns the first
+     * match. If no route matches, returns `null`.
+     *
+     * @param method - The HTTP method of the request
+     * @param path - The URL path to match (e.g., "/users/123")
+     * @returns RouteMatched object if found, null otherwise
+     *
+     * @example
+     * ```ts
+     * const router = Router.register(
+     *   Route.get("/:id", "findOne"),
+     * );
+     *
+     * const matched = router.match(RouteMethod.GET, "/456");
+     * if (matched) {
+     *   console.log(matched.params.id); // "456"
+     *   console.log(matched.route.getAction()); // "findOne"
+     * }
+     * ```
+     */
+    match(method: RouteMethod, path: string): {
+        route: Route;
+        params: Record<string, string>;
+        wildcards: string[];
+    } | null;
+    /**
+     * Matches a URL path against a route pattern.
+     *
+     * This static method performs the actual pattern matching logic.
+     * It supports:
+     * - **Literal segments**: Must match exactly
+     * - **Path parameters**: `:param` captures a single segment
+     * - **Optional parameters**: `:param?` matches zero or one segment
+     * - **Wildcards**: `*` at the end captures all remaining segments
+     *
+     * @param pattern - The route pattern (e.g., "/users/:id")
+     * @param target - The actual URL path (e.g., "/users/123")
+     * @returns Object with params and wildcards if matched, null otherwise
+     *
+     * @example
+     * ```ts
+     * // Basic parameter
+     * Router.match("/users/:id", "/users/123");
+     * // { params: { id: "123" }, wildcards: [] }
+     *
+     * // Optional parameter (present)
+     * Router.match("/posts/:id?", "/posts/456");
+     * // { params: { id: "456" }, wildcards: [] }
+     *
+     * // Optional parameter (absent)
+     * Router.match("/posts/:id?", "/posts");
+     * // { params: { id: "" }, wildcards: [] }
+     *
+     * // Wildcard
+     * Router.match("/files/*", "/files/docs/readme.md");
+     * // { params: {}, wildcards: ["docs", "readme.md"] }
+     *
+     * // No match
+     * Router.match("/users/:id", "/products/123");
+     * // null
+     * ```
+     */
+    static match(pattern: string, target: string): {
+        params: Record<string, string>;
+        wildcards: string[];
+    } | null;
+}

package/dist/router.js

@@ -0,0 +1 @@
+"use strict";class t{constructor(t){this.registered=t}static register(...e){return new t(new Set(e.map(t=>({method:t.getMethod(),route:t}))))}match(e,r){const s=this.registered;for(const n of s){if(n.method!==e)continue;const s=t.match(n.route.getPath(),r);if(s)return{route:n.route,params:s.params,wildcards:s.wildcards}}return null}static match(t,e){const r=t.trim().replace(/^\/+/,"").replace(/\/+$/,""),s=e.trim().replace(/^\/+/,"").replace(/\/+$/,""),n=r.split("/"),i=s.split("/"),l={},c=[],o="*"===n[n.length-1],h=o?n.slice(0,-1):n;let a=0;for(const t of h)t.startsWith(":")&&t.endsWith("?")||a++;if(o){if(i.length<a)return null}else if(i.length<a||i.length>n.length)return null;let u=0;for(let t=0;t<h.length;t++){const e=h[t],r=i[u];if(e.startsWith(":")){let s=e.substring(1);const n=s.endsWith("?");if(n&&(s=s.slice(0,-1)),void 0!==r){if(n&&t+1<h.length){const e=h[t+1];if(!e.startsWith(":")&&e===r){l[s]="";continue}if(e.startsWith(":")){const e=i.length-u;let r=0;for(let e=t;e<h.length;e++){const t=h[e];t.startsWith(":")&&t.endsWith("?")||r++}if(e===r){l[s]="";continue}}}l[s]=r,u++}else{if(!n)return null;l[s]=""}}else{if(e!==r)return null;u++}}return o&&c.push(...i.slice(h.length)),{params:l,wildcards:c}}}exports.Router=t;

package/dist/router.mjs

@@ -0,0 +1 @@
+class t{constructor(t){this.registered=t}static register(...e){return new t(new Set(e.map(t=>({method:t.getMethod(),route:t}))))}match(e,r){const s=this.registered;for(const n of s){if(n.method!==e)continue;const s=t.match(n.route.getPath(),r);if(s)return{route:n.route,params:s.params,wildcards:s.wildcards}}return null}static match(t,e){const r=t.trim().replace(/^\/+/,"").replace(/\/+$/,""),s=e.trim().replace(/^\/+/,"").replace(/\/+$/,""),n=r.split("/"),i=s.split("/"),l={},c=[],o="*"===n[n.length-1],h=o?n.slice(0,-1):n;let a=0;for(const t of h)t.startsWith(":")&&t.endsWith("?")||a++;if(o){if(i.length<a)return null}else if(i.length<a||i.length>n.length)return null;let u=0;for(let t=0;t<h.length;t++){const e=h[t],r=i[u];if(e.startsWith(":")){let s=e.substring(1);const n=s.endsWith("?");if(n&&(s=s.slice(0,-1)),void 0!==r){if(n&&t+1<h.length){const e=h[t+1];if(!e.startsWith(":")&&e===r){l[s]="";continue}if(e.startsWith(":")){const e=i.length-u;let r=0;for(let e=t;e<h.length;e++){const t=h[e];t.startsWith(":")&&t.endsWith("?")||r++}if(e===r){l[s]="";continue}}}l[s]=r,u++}else{if(!n)return null;l[s]=""}}else{if(e!==r)return null;u++}}return o&&c.push(...i.slice(h.length)),{params:l,wildcards:c}}}export{t as Router};