@mxweb/core 1.0.0

package/dist/execute.d.ts

@@ -0,0 +1,469 @@
+/**
+ * @fileoverview Execution context and request-scoped state management.
+ *
+ * This module provides:
+ * - {@link ExecuteContext}: Request-scoped context using AsyncLocalStorage
+ * - {@link Reflect}: Route metadata and decorator access
+ * - Guard, Filter, Interceptor interfaces for request pipeline
+ *
+ * @module execute
+ */
+import { NextRequest } from "next/server";
+import { ServerResponse } from "./response";
+import { Feature } from "./feature";
+import { ApplicationInject, CallHandler, FeatureInject, Pipe, RouteMethod, RouteNextHandler } from "./common";
+/**
+ * Container for route-level metadata, guards, filters, interceptors, and pipes.
+ * Created from decorator results and attached to each route.
+ *
+ * @example
+ * ```ts
+ * // Access in a guard or interceptor
+ * const roles = context.getReflect()?.getMetadata<string[]>("roles");
+ * const guards = context.getReflect()?.getGuards();
+ * ```
+ */
+export declare class Reflect {
+    private readonly metadata;
+    private readonly guards;
+    private readonly filters;
+    private readonly interceptors;
+    private readonly pipes;
+    /**
+     * Creates a new Reflect instance with the specified metadata and decorators.
+     *
+     * @param metadata - Map of metadata key-value pairs from SetMetadata
+     * @param guards - Set of guard classes from UseGuards
+     * @param filters - Set of filter classes from UseFilters
+     * @param interceptors - Set of interceptor classes from UseInterceptors
+     * @param pipes - Set of pipe classes from UsePipes
+     */
+    constructor(metadata: Map<string, unknown>, guards: Set<Guard>, filters: Set<Filter>, interceptors: Set<Interceptor>, pipes: Set<Pipe>);
+    /**
+     * Returns the set of guard classes attached to this route.
+     * @returns Set of guard class constructors
+     */
+    getGuards(): Set<Guard>;
+    /**
+     * Returns the set of exception filter classes attached to this route.
+     * @returns Set of filter class constructors
+     */
+    getFilters(): Set<Filter<unknown>>;
+    /**
+     * Returns the set of interceptor classes attached to this route.
+     * @returns Set of interceptor class constructors
+     */
+    getInterceptors(): Set<Interceptor<unknown>>;
+    /**
+     * Returns the set of pipe classes attached to this route.
+     * @returns Set of pipe class constructors
+     */
+    getPipes(): Set<Pipe>;
+    /**
+     * Retrieves a metadata value by key.
+     *
+     * @template T - Expected type of the metadata value
+     * @param key - The metadata key to retrieve
+     * @returns The metadata value or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const roles = reflect.getMetadata<string[]>("roles");
+     * ```
+     */
+    getMetadata<T = unknown>(key: string): T | undefined;
+    /**
+     * Returns all metadata as a Map.
+     * @returns Map of all metadata key-value pairs
+     */
+    getAllMetadata(): Map<string, unknown>;
+}
+/**
+ * Context object containing all request-related data.
+ * Created for each request and available throughout the request lifecycle.
+ */
+export interface RequestContext {
+    /** The incoming Next.js request */
+    req: NextRequest;
+    /** The response builder */
+    res: ServerResponse;
+    /** HTTP method of the request */
+    method: RouteMethod;
+    /** The matched path (without base API path) */
+    path: string;
+    /** Route parameters extracted from the path */
+    params: Record<string, string>;
+    /** Wildcard segments from the path */
+    wildcards: string[];
+    /** Route metadata and decorators */
+    reflect: Reflect;
+    /** The feature that matched this request */
+    feature: Feature;
+}
+/**
+ * Request-scoped execution context using AsyncLocalStorage.
+ *
+ * This class provides access to request data and global injects from anywhere
+ * in the application without explicitly passing context through function parameters.
+ *
+ * Uses the singleton pattern - access via {@link ExecuteContext.instance}.
+ *
+ * @remarks
+ * - Uses Node.js AsyncLocalStorage to maintain request scope across async operations
+ * - Manages both request-scoped context and global application injects
+ * - Provides HTTP helpers similar to NestJS's ExecutionContext
+ *
+ * @example
+ * ```ts
+ * // In a service (accessed via executeContext singleton)
+ * const params = this.context.switchHttp().params();
+ * const body = await this.context.switchHttp().json<CreateDto>();
+ *
+ * // Access global injects
+ * const db = this.context.getInject<Database>("db");
+ *
+ * // Access feature-local injects
+ * const repo = this.context.getLocalInject<Repository>("productRepo");
+ * ```
+ */
+export declare class ExecuteContext {
+    /** Singleton instance */
+    private static _instance;
+    /** AsyncLocalStorage for request-scoped context */
+    private storage;
+    /** Map of global application injects */
+    private _injections;
+    /**
+     * Private constructor to enforce singleton pattern.
+     * @private
+     */
+    private constructor();
+    /**
+     * Returns the singleton ExecuteContext instance.
+     * Creates the instance on first access.
+     *
+     * @returns The singleton ExecuteContext instance
+     */
+    static get instance(): ExecuteContext;
+    /**
+     * Returns the map of global application injects.
+     * Injects are set by Application.loadInjects() during initialization.
+     *
+     * @returns Map of inject name to instance
+     */
+    get injections(): Map<string, ApplicationInject>;
+    /**
+     * Registers a global inject by name.
+     *
+     * @param name - The name to register the inject under
+     * @param instance - The inject instance
+     */
+    setInject(name: string, instance: ApplicationInject): void;
+    /**
+     * Retrieves a global inject by name.
+     *
+     * @template T - Expected type of the inject (must extend ApplicationInject)
+     * @param name - The name of the inject to retrieve
+     * @returns The inject instance or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const db = context.getInject<DatabaseConnection>("db");
+     * const config = context.getInject<Config>("config");
+     * ```
+     */
+    getInject<T extends ApplicationInject = ApplicationInject>(name: string): T | undefined;
+    /**
+     * Checks if a global inject exists by name.
+     *
+     * @param name - The inject name to check
+     * @returns true if the inject exists, false otherwise
+     */
+    hasInject(name: string): boolean;
+    /**
+     * Clears all global injects.
+     * Primarily used for testing to ensure clean state between tests.
+     */
+    clearInjections(): void;
+    /**
+     * Runs a callback within the scope of a request context.
+     * All code executed within the callback can access the context
+     * via getContext() or switchHttp().
+     *
+     * @template T - Return type of the callback
+     * @param context - The request context to make available
+     * @param callback - The callback to execute within the context scope
+     * @returns The result of the callback (sync or async)
+     *
+     * @example
+     * ```ts
+     * await executeContext.run(requestContext, async () => {
+     *   // context is available here
+     *   const ctx = executeContext.getContext();
+     *   return await handler();
+     * });
+     * ```
+     */
+    run<T>(context: RequestContext, callback: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Retrieves the current request context.
+     * Returns undefined if called outside of a request scope.
+     *
+     * @returns The current RequestContext or undefined
+     */
+    getContext(): RequestContext | undefined;
+    /**
+     * Retrieves the current request context or throws an error.
+     * Use this when you expect to always be within a request scope.
+     *
+     * @returns The current RequestContext
+     * @throws {Error} If called outside of a request scope
+     */
+    getContextOrThrow(): RequestContext;
+    /**
+     * Returns an object with helper methods for accessing HTTP request data.
+     * Similar to NestJS's switchToHttp() but as a function factory.
+     *
+     * @returns Object with HTTP helper methods
+     * @throws {Error} If called outside of a request scope
+     *
+     * @example
+     * ```ts
+     * const http = context.switchHttp();
+     *
+     * // Access request/response
+     * const request = http.getRequest();
+     * const response = http.getResponse();
+     *
+     * // Access route info
+     * const method = http.getMethod();
+     * const path = http.getPath();
+     * const params = http.params();
+     *
+     * // Access request data
+     * const query = http.query();
+     * const headers = http.headers();
+     * const body = await http.json<MyDto>();
+     * const formData = await http.formData();
+     * ```
+     */
+    switchHttp(): {
+        /** Returns the Next.js request object */
+        getRequest: () => NextRequest;
+        /** Returns the ServerResponse builder */
+        getResponse: () => ServerResponse;
+        /** Returns the HTTP method */
+        getMethod: () => RouteMethod;
+        /** Returns the matched path */
+        getPath: () => string;
+        /** Returns route parameters */
+        params: () => Record<string, string>;
+        /** Returns wildcard segments */
+        wildcards: () => string[];
+        /** Returns query parameters as object */
+        query: () => {
+            [k: string]: string;
+        };
+        /** Returns headers as object */
+        headers: () => {
+            [k: string]: string;
+        };
+        /** Returns the raw body ReadableStream */
+        body: () => ReadableStream<Uint8Array<ArrayBuffer>> | null;
+        /** Parses and returns the JSON body */
+        json: <T = unknown>() => Promise<T>;
+        /** Returns the body as text */
+        text: () => Promise<string>;
+        /** Parses and returns FormData */
+        formData: () => Promise<FormData>;
+        /** Returns the body as Blob */
+        blob: () => Promise<Blob>;
+        /** Returns the body as ArrayBuffer */
+        arrayBuffer: () => Promise<ArrayBuffer>;
+    };
+    /**
+     * Returns the Reflect instance for the current route.
+     * Contains metadata and decorator information.
+     *
+     * @returns The Reflect instance or undefined if no context
+     */
+    getReflect(): Reflect | undefined;
+    /**
+     * Retrieves route metadata by key.
+     * Shorthand for getReflect()?.getMetadata().
+     *
+     * @template T - Expected type of the metadata value
+     * @param key - The metadata key to retrieve
+     * @returns The metadata value or undefined
+     */
+    getMetadata<T>(key: string): T | undefined;
+    /**
+     * Returns the Feature that matched the current request.
+     *
+     * @returns The Feature instance or undefined if no context
+     */
+    getFeature(): Feature | undefined;
+    /**
+     * Retrieves a feature-local inject by name.
+     * Falls back to global injects if not found in the feature.
+     *
+     * @template T - Expected type of the inject (must extend FeatureInject)
+     * @param name - The name of the inject to retrieve
+     * @returns The inject instance or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // First checks feature injects, then global injects
+     * const repo = context.getLocalInject<ProductRepository>("productRepo");
+     * ```
+     */
+    getLocalInject<T extends FeatureInject>(name: string): T | undefined;
+}
+/**
+ * Interface for guard classes that determine if a request should proceed.
+ * Guards are used for authorization, authentication, and access control.
+ *
+ * @example
+ * ```ts
+ * class AuthGuard implements CanActivate {
+ *   canActivate(context: ExecuteContext): boolean {
+ *     const token = context.switchHttp().headers()["authorization"];
+ *     return !!token && isValidToken(token);
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate {
+    /**
+     * Determines if the request should be allowed to proceed.
+     *
+     * @param context - The execution context for the current request
+     * @returns true to allow, false to deny (results in 403 Forbidden)
+     */
+    canActivate(context: ExecuteContext): boolean | Promise<boolean>;
+}
+/**
+ * Constructor type for guard classes.
+ */
+export type Guard = new (...args: unknown[]) => CanActivate;
+/**
+ * Function type for route action handlers (inline handlers).
+ *
+ * RouteHandler is used when defining routes with inline functions instead of
+ * controller method names. The handler receives the ExecuteContext and returns
+ * data that will be serialized as the JSON response.
+ *
+ * @template Data - The type of data returned by the handler
+ * @param context - The ExecuteContext providing access to request, response, params, etc.
+ * @returns Data to be serialized as JSON response, or a Promise resolving to data
+ *
+ * @example
+ * ```ts
+ * // Inline handler in route definition
+ * Route.get("/health", async (context) => {
+ *   return context.response.success({ status: "ok", timestamp: Date.now() });
+ * });
+ *
+ * // With typed response
+ * const handler: RouteHandler<{ message: string }> = (ctx) => {
+ *   return { message: "Hello World" };
+ * };
+ * Route.get("/hello", handler);
+ * ```
+ */
+export type RouteHandler<Data = unknown> = (context: ExecuteContext) => Data;
+/**
+ * Function type for route middlewares.
+ * Middlewares can perform actions before the handler and must call next() to continue.
+ *
+ * @example
+ * ```ts
+ * const loggingMiddleware: RouteMiddleware = (context, next) => {
+ *   console.log(`Request: ${context.switchHttp().getMethod()} ${context.switchHttp().getPath()}`);
+ *   next();
+ * };
+ * ```
+ */
+export type RouteMiddleware = (context: ExecuteContext, next: RouteNextHandler) => void | Promise<void>;
+/**
+ * Interface for exception filter classes that handle errors.
+ * Filters can transform exceptions into custom responses.
+ *
+ * @template Response - The type of response the filter returns
+ *
+ * @example
+ * ```ts
+ * class HttpExceptionFilter implements ExceptionFilter<Response> {
+ *   catch(exception: unknown, context: ExecuteContext): Response {
+ *     if (exception instanceof HttpError) {
+ *       return new Response(JSON.stringify({ error: exception.message }), {
+ *         status: exception.statusCode,
+ *       });
+ *     }
+ *     throw exception; // Re-throw if not handled
+ *   }
+ * }
+ * ```
+ */
+export interface ExceptionFilter<Response = unknown> {
+    /**
+     * Handles an exception and optionally returns a response.
+     *
+     * @param exception - The thrown exception
+     * @param context - The execution context for the current request
+     * @returns A response to send, or re-throw to pass to next filter
+     */
+    catch(exception: unknown, context: ExecuteContext): Response | Promise<Response>;
+}
+/**
+ * Constructor type for exception filter classes.
+ *
+ * @template Response - The type of response the filter returns
+ */
+export type Filter<Response = unknown> = new (...args: unknown[]) => ExceptionFilter<Response>;
+/**
+ * Interface for interceptor classes that wrap handler execution.
+ * Interceptors can transform requests/responses, add caching, logging, etc.
+ *
+ * @template T - The type of the handler result
+ *
+ * @example
+ * ```ts
+ * class LoggingInterceptor implements InterceptorHandler {
+ *   async intercept(context: ExecuteContext, next: CallHandler): Promise<unknown> {
+ *     const start = Date.now();
+ *     const result = await next();
+ *     console.log(`Request took ${Date.now() - start}ms`);
+ *     return result;
+ *   }
+ * }
+ *
+ * class CacheInterceptor implements InterceptorHandler {
+ *   async intercept(context: ExecuteContext, next: CallHandler): Promise<unknown> {
+ *     const key = getCacheKey(context);
+ *     const cached = await cache.get(key);
+ *     if (cached) return cached;
+ *
+ *     const result = await next();
+ *     await cache.set(key, result);
+ *     return result;
+ *   }
+ * }
+ * ```
+ */
+export interface InterceptorHandler<T = unknown> {
+    /**
+     * Intercepts the handler execution.
+     *
+     * @param context - The execution context for the current request
+     * @param next - Function to call the next interceptor or handler
+     * @returns The (possibly transformed) result
+     */
+    intercept(context: ExecuteContext, next: CallHandler<T>): Promise<T>;
+}
+/**
+ * Constructor type for interceptor classes.
+ *
+ * @template T - The type of the handler result
+ */
+export type Interceptor<T = unknown> = new (...args: unknown[]) => InterceptorHandler<T>;

package/dist/execute.js

@@ -0,0 +1 @@
+"use strict";var t=require("async_hooks");class e{constructor(){this.storage=new t.AsyncLocalStorage,this._injections=new Map}static get instance(){return e._instance||(e._instance=new e),e._instance}get injections(){return this._injections}setInject(t,e){this._injections.set(t,e)}getInject(t){return this._injections.get(t)}hasInject(t){return this._injections.has(t)}clearInjections(){this._injections.clear()}run(t,e){return this.storage.run(t,e)}getContext(){return this.storage.getStore()}getContextOrThrow(){const t=this.storage.getStore();if(!t)throw new Error("[ExecuteContext] No context available. Make sure you're inside a request handler.");return t}switchHttp(){const t=this.getContextOrThrow();return{getRequest:()=>t.req,getResponse:()=>t.res,getMethod:()=>t.method,getPath:()=>t.path,params:()=>t.params,wildcards:()=>t.wildcards,query:()=>Object.fromEntries(t.req.nextUrl.searchParams),headers:()=>Object.fromEntries(t.req.headers),body:()=>t.req.body,json:()=>t.req.json(),text:()=>t.req.text(),formData:()=>t.req.formData(),blob:()=>t.req.blob(),arrayBuffer:()=>t.req.arrayBuffer()}}getReflect(){return this.getContext()?.reflect}getMetadata(t){return this.getContext()?.reflect.getMetadata(t)}getFeature(){return this.getContext()?.feature}getLocalInject(t){const e=this.getContext()?.feature;return e?.hasInject(t)?e.getInject(t):this._injections.get(t)}}e._instance=null,exports.ExecuteContext=e,exports.Reflect=class{constructor(t,e,r,s,n){this.metadata=t,this.guards=e,this.filters=r,this.interceptors=s,this.pipes=n}getGuards(){return this.guards}getFilters(){return this.filters}getInterceptors(){return this.interceptors}getPipes(){return this.pipes}getMetadata(t){return this.metadata.get(t)}getAllMetadata(){return this.metadata}};

package/dist/execute.mjs

@@ -0,0 +1 @@
+import{AsyncLocalStorage as t}from"async_hooks";class e{constructor(t,e,r,s,n){this.metadata=t,this.guards=e,this.filters=r,this.interceptors=s,this.pipes=n}getGuards(){return this.guards}getFilters(){return this.filters}getInterceptors(){return this.interceptors}getPipes(){return this.pipes}getMetadata(t){return this.metadata.get(t)}getAllMetadata(){return this.metadata}}class r{constructor(){this.storage=new t,this._injections=new Map}static get instance(){return r._instance||(r._instance=new r),r._instance}get injections(){return this._injections}setInject(t,e){this._injections.set(t,e)}getInject(t){return this._injections.get(t)}hasInject(t){return this._injections.has(t)}clearInjections(){this._injections.clear()}run(t,e){return this.storage.run(t,e)}getContext(){return this.storage.getStore()}getContextOrThrow(){const t=this.storage.getStore();if(!t)throw new Error("[ExecuteContext] No context available. Make sure you're inside a request handler.");return t}switchHttp(){const t=this.getContextOrThrow();return{getRequest:()=>t.req,getResponse:()=>t.res,getMethod:()=>t.method,getPath:()=>t.path,params:()=>t.params,wildcards:()=>t.wildcards,query:()=>Object.fromEntries(t.req.nextUrl.searchParams),headers:()=>Object.fromEntries(t.req.headers),body:()=>t.req.body,json:()=>t.req.json(),text:()=>t.req.text(),formData:()=>t.req.formData(),blob:()=>t.req.blob(),arrayBuffer:()=>t.req.arrayBuffer()}}getReflect(){return this.getContext()?.reflect}getMetadata(t){return this.getContext()?.reflect.getMetadata(t)}getFeature(){return this.getContext()?.feature}getLocalInject(t){const e=this.getContext()?.feature;return e?.hasInject(t)?e.getInject(t):this._injections.get(t)}}r._instance=null;export{r as ExecuteContext,e as Reflect};