@mxweb/core 1.0.2 → 1.2.0

package/dist/common.d.ts

@@ -1,9 +1,169 @@
-import { Callback } from "@mxweb/utils";
+/**
+ * Generic callback function type.
+ * @template R - Return type
+ * @template A - Arguments tuple type
+ */
+export type Callback<R = void, A extends any[] = []> = (...args: A) => R;
 /**
  * @fileoverview Common types, interfaces, and utilities used throughout the @mxweb/core framework.
  * This module provides foundational types for dependency injection, routing, and lifecycle management.
  * @module common
  */
+/**
+ * Interface representing the feature context accessible from ExecuteContext.
+ * This abstraction allows execute.ts to work with features without importing Feature class directly,
+ * avoiding circular dependencies.
+ *
+ * @remarks
+ * Feature class implements this interface.
+ * Used in RequestContext and ExecuteContext methods.
+ */
+export interface FeatureContext {
+    /**
+     * Checks if an inject exists in this feature.
+     * @param name - The inject name to check
+     * @returns true if the inject exists
+     */
+    hasInject(name: string): boolean;
+    /**
+     * Retrieves an inject by name with lazy initialization.
+     * @template T - Expected return type
+     * @param name - The name of the inject to retrieve
+     * @returns Promise resolving to the inject or undefined
+     */
+    getInject<T = unknown>(name: string): Promise<T | undefined>;
+    /**
+     * Retrieves an inject synchronously (only if already initialized).
+     * @template T - Expected return type
+     * @param name - The name of the inject to retrieve
+     * @returns The inject or undefined
+     */
+    getInjectSync<T = unknown>(name: string): T | undefined;
+}
+/**
+ * Interface for guard classes that determine if a request should proceed.
+ * Guards are used for authorization, authentication, and access control.
+ *
+ * @template Context - The execution context type (defaults to unknown for flexibility)
+ *
+ * @example
+ * ```ts
+ * class AuthGuard implements CanActivate {
+ *   canActivate(context: ExecuteContext): boolean {
+ *     const token = context.switchHttp().headers()["authorization"];
+ *     return !!token && isValidToken(token);
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate<Context = unknown> {
+    /**
+     * 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: Context): boolean | Promise<boolean>;
+}
+/**
+ * Constructor type for guard classes.
+ *
+ * @template Context - The execution context type
+ */
+export type Guard<Context = unknown> = new (...args: unknown[]) => CanActivate<Context>;
+/**
+ * Interface for exception filter classes that handle errors.
+ * Filters can transform exceptions into custom responses.
+ *
+ * @template Response - The type of response the filter returns
+ * @template Context - The execution context type (defaults to unknown for flexibility)
+ *
+ * @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, Context = 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: Context): Response | Promise<Response>;
+}
+/**
+ * Constructor type for exception filter classes.
+ *
+ * @template Response - The type of response the filter returns
+ * @template Context - The execution context type
+ */
+export type Filter<Response = unknown, Context = unknown> = new (...args: unknown[]) => ExceptionFilter<Response, Context>;
+/**
+ * Interface for class-based response interceptors.
+ * Provides more flexibility than function interceptors with access to instance state.
+ *
+ * @template T - The type of the response data
+ * @template Response - The response type (defaults to unknown for flexibility)
+ *
+ * @example
+ * ```ts
+ * class LoggingInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     console.log(`[${response.status}] ${response.body.message}`);
+ *     return response;
+ *   }
+ * }
+ *
+ * class CacheHeaderInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     if (response.status >= 200 && response.status < 300) {
+ *       response.headers.set("Cache-Control", "max-age=3600");
+ *     }
+ *     return response;
+ *   }
+ * }
+ * ```
+ */
+export interface ResponseInterceptorHandler<Response = unknown> {
+    /**
+     * Transforms the response.
+     * Called after the handler returns, allowing post-processing of the response.
+     *
+     * @param response - The response to transform
+     * @returns The transformed response (can be the same instance or a new one)
+     */
+    transform(response: Response): Response | Promise<Response>;
+}
+/**
+ * Constructor type for response interceptor classes.
+ * Interceptors transform the response after the handler returns.
+ *
+ * @template Response - The response type
+ *
+ * @example
+ * ```ts
+ * import { ResponseInterceptorHandler, CoreResponse } from "@mxweb/core";
+ *
+ * class LoggingInterceptor implements ResponseInterceptorHandler {
+ *   transform(response: CoreResponse): CoreResponse {
+ *     console.log(`Response: ${response.status} ${response.body.message}`);
+ *     return response;
+ *   }
+ * }
+ * ```
+ */
+export type Interceptor<Response = unknown> = new (...args: unknown[]) => ResponseInterceptorHandler<Response>;
 /**
  * Interface for Application-level dependency injects.
  * All global injects must implement this interface to ensure consistent lifecycle management.
@@ -29,7 +189,46 @@ import { Callback } from "@mxweb/utils";
  * }
  * ```
  */
-export interface ApplicationInject {
+/**
+ * Interface for injects that support context switching.
+ * Implement this interface to expose a safe, controlled API via `context.switch()`.
+ *
+ * @template T - The type of object returned by the switch() method
+ *
+ * @remarks
+ * This interface is used to expose a **safe facade** instead of the raw inject instance.
+ * The switch() method should return an object that only exposes safe operations,
+ * hiding dangerous methods like close(), destroy(), or direct state manipulation.
+ *
+ * @example
+ * ```ts
+ * interface DbSwitchable {
+ *   query<T>(sql: string): Promise<T>;
+ *   getRepo<T>(entity: EntityClass<T>): Repository<T>;
+ * }
+ *
+ * class Connection implements ApplicationInject, Switchable<DbSwitchable> {
+ *   private client: DatabaseClient;
+ *
+ *   switch(): DbSwitchable {
+ *     return {
+ *       query: (sql) => this.client.query(sql),
+ *       getRepo: (entity) => this.getRepo(entity),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface Switchable<T = unknown> {
+    /**
+     * Returns a safe, controlled interface for this inject.
+     * Called by `context.switch()` to get the public API.
+     *
+     * @returns The switched context or utility object
+     */
+    switch(): T;
+}
+export interface ApplicationInject extends Partial<Switchable> {
     /**
      * Called when the inject is initialized (on first request).
      * Use this to establish connections, load resources, or perform async setup.
@@ -62,7 +261,7 @@ export interface ApplicationInject {
  * }
  * ```
  */
-export interface FeatureInject {
+export interface FeatureInject extends Partial<Switchable> {
     /**
      * Called when the feature is loaded.
      * Use this for feature-specific initialization.
@@ -192,6 +391,9 @@ export type RouteNextHandler = () => void;
  * Function type for call handlers used in interceptors.
  * Returns a promise of the handler result.
  *
+ * @deprecated Since v1.1.0, interceptors no longer wrap handlers.
+ * Use `ResponseInterceptorHandler` from `response.ts` instead.
+ *
  * @template T - The type of the resolved value
  */
 export type CallHandler<T = unknown> = () => Promise<T>;
@@ -228,6 +430,56 @@ export interface PipeTransform<Input = unknown, Output = unknown> {
  * @template Output - The type of output value the pipe produces
  */
 export type Pipe<Input = unknown, Output = unknown> = new (...args: unknown[]) => PipeTransform<Input, Output>;
+/**
+ * Generic constructor type for class instantiation.
+ */
+export type ClassConstructor<T = unknown> = new (...args: any[]) => T;
+/**
+ * Shared options for guards, filters, interceptors, and pipes.
+ * Used by both Application and Feature configurations.
+ *
+ * @remarks
+ * This interface provides a common base for decorator options across
+ * different levels of the application hierarchy (Application, Feature, Route).
+ *
+ * Execution order:
+ * - Guards: Application → Feature → Route
+ * - Filters: Route → Feature → Application (reverse for catch)
+ * - Interceptors: Route → Feature → Application (for transform)
+ * - Pipes: Application → Feature → Route
+ *
+ * @example
+ * ```ts
+ * const options: DecoratorOptions = {
+ *   guards: [AuthGuard, RolesGuard],
+ *   filters: [HttpExceptionFilter],
+ *   interceptors: [LoggingInterceptor],
+ *   pipes: [ValidationPipe],
+ * };
+ * ```
+ */
+export interface DecoratorOptions {
+    /**
+     * Guards to apply at this level.
+     * Guards determine if a request should be processed.
+     */
+    guards?: Guard[];
+    /**
+     * Exception filters to apply at this level.
+     * Filters handle exceptions thrown during request processing.
+     */
+    filters?: Filter[];
+    /**
+     * Interceptors to apply at this level.
+     * Interceptors can transform the response.
+     */
+    interceptors?: Interceptor[];
+    /**
+     * Pipes to apply at this level.
+     * Pipes transform input data before it reaches the handler.
+     */
+    pipes?: Pipe[];
+}
 /**
  * Constructor type for inject classes.
  * Used when registering injects that need to be instantiated.

package/dist/config.d.ts

@@ -272,4 +272,22 @@ export declare class Config implements ApplicationInject {
      * ```
      */
     reset(): void;
+    /**
+     * Returns the Config instance itself for context switching.
+     * Allows accessing Config via `context.switch("config")`.
+     *
+     * @template T - The expected return type (defaults to Config)
+     * @returns The Config instance
+     *
+     * @example
+     * ```ts
+     * // In a controller or service
+     * const config = await this.context.switch<Config>("config");
+     * const dbHost = config.get<string>("db.host");
+     *
+     * // Or access config values directly
+     * const port = config.get<number>("port", 3000);
+     * ```
+     */
+    switch<T = Config>(): T;
 }

package/dist/config.js

@@ -1 +1 @@
-"use strict";class t{static forRoot(r="config"){return s=>{s.set(r,()=>(t.instance||(t.instance=new t),t.instance))}}async onInit(){await t.buildAsync()}static register(r,s){return t.providers.set(r,s),t}static registerAsync(r,s){return t.asyncProviders.set(r,s),t}static build(){if(!t.built){for(const[r,s]of t.providers)t.store.has(r)||t.store.set(r,s());t.built=!0}}static async buildAsync(){if(t.build(),!t.asyncBuilt){for(const[r,s]of t.asyncProviders)t.store.has(r)||t.store.set(r,await s());t.asyncBuilt=!0}}get(r,s){return t.build(),t.store.get(r)??s}async getAsync(r,s){return await t.buildAsync(),t.store.get(r)??s}getOrThrow(r){if(t.build(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}async getAsyncOrThrow(r){if(await t.buildAsync(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}has(r){return t.store.has(r)||t.providers.has(r)||t.asyncProviders.has(r)}getAll(){return new Map(t.store)}reset(){t.instance=null,t.store.clear(),t.providers.clear(),t.asyncProviders.clear(),t.built=!1,t.asyncBuilt=!1}}t.instance=null,t.store=new Map,t.providers=new Map,t.asyncProviders=new Map,t.built=!1,t.asyncBuilt=!1,exports.Config=t;
+"use strict";class t{static forRoot(r="config"){return s=>{s.set(r,()=>(t.instance||(t.instance=new t),t.instance))}}async onInit(){await t.buildAsync()}static register(r,s){return t.providers.set(r,s),t}static registerAsync(r,s){return t.asyncProviders.set(r,s),t}static build(){if(!t.built){for(const[r,s]of t.providers)t.store.has(r)||t.store.set(r,s());t.built=!0}}static async buildAsync(){if(t.build(),!t.asyncBuilt){for(const[r,s]of t.asyncProviders)t.store.has(r)||t.store.set(r,await s());t.asyncBuilt=!0}}get(r,s){return t.build(),t.store.get(r)??s}async getAsync(r,s){return await t.buildAsync(),t.store.get(r)??s}getOrThrow(r){if(t.build(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}async getAsyncOrThrow(r){if(await t.buildAsync(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}has(r){return t.store.has(r)||t.providers.has(r)||t.asyncProviders.has(r)}getAll(){return new Map(t.store)}reset(){t.instance=null,t.store.clear(),t.providers.clear(),t.asyncProviders.clear(),t.built=!1,t.asyncBuilt=!1}switch(){return this}}t.instance=null,t.store=new Map,t.providers=new Map,t.asyncProviders=new Map,t.built=!1,t.asyncBuilt=!1,exports.Config=t;

package/dist/config.mjs

@@ -1 +1 @@
-class r{static forRoot(t="config"){return s=>{s.set(t,()=>(r.instance||(r.instance=new r),r.instance))}}async onInit(){await r.buildAsync()}static register(t,s){return r.providers.set(t,s),r}static registerAsync(t,s){return r.asyncProviders.set(t,s),r}static build(){if(!r.built){for(const[t,s]of r.providers)r.store.has(t)||r.store.set(t,s());r.built=!0}}static async buildAsync(){if(r.build(),!r.asyncBuilt){for(const[t,s]of r.asyncProviders)r.store.has(t)||r.store.set(t,await s());r.asyncBuilt=!0}}get(t,s){return r.build(),r.store.get(t)??s}async getAsync(t,s){return await r.buildAsync(),r.store.get(t)??s}getOrThrow(t){if(r.build(),!r.store.has(t))throw new Error(`[Config] Config key "${t}" not found`);return r.store.get(t)}async getAsyncOrThrow(t){if(await r.buildAsync(),!r.store.has(t))throw new Error(`[Config] Config key "${t}" not found`);return r.store.get(t)}has(t){return r.store.has(t)||r.providers.has(t)||r.asyncProviders.has(t)}getAll(){return new Map(r.store)}reset(){r.instance=null,r.store.clear(),r.providers.clear(),r.asyncProviders.clear(),r.built=!1,r.asyncBuilt=!1}}r.instance=null,r.store=new Map,r.providers=new Map,r.asyncProviders=new Map,r.built=!1,r.asyncBuilt=!1;export{r as Config};
+class t{static forRoot(r="config"){return s=>{s.set(r,()=>(t.instance||(t.instance=new t),t.instance))}}async onInit(){await t.buildAsync()}static register(r,s){return t.providers.set(r,s),t}static registerAsync(r,s){return t.asyncProviders.set(r,s),t}static build(){if(!t.built){for(const[r,s]of t.providers)t.store.has(r)||t.store.set(r,s());t.built=!0}}static async buildAsync(){if(t.build(),!t.asyncBuilt){for(const[r,s]of t.asyncProviders)t.store.has(r)||t.store.set(r,await s());t.asyncBuilt=!0}}get(r,s){return t.build(),t.store.get(r)??s}async getAsync(r,s){return await t.buildAsync(),t.store.get(r)??s}getOrThrow(r){if(t.build(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}async getAsyncOrThrow(r){if(await t.buildAsync(),!t.store.has(r))throw new Error(`[Config] Config key "${r}" not found`);return t.store.get(r)}has(r){return t.store.has(r)||t.providers.has(r)||t.asyncProviders.has(r)}getAll(){return new Map(t.store)}reset(){t.instance=null,t.store.clear(),t.providers.clear(),t.asyncProviders.clear(),t.built=!1,t.asyncBuilt=!1}switch(){return this}}t.instance=null,t.store=new Map,t.providers=new Map,t.asyncProviders=new Map,t.built=!1,t.asyncBuilt=!1;export{t as Config};

package/dist/decorator.d.ts

@@ -8,8 +8,8 @@
  *
  * @module decorator
  */
-import { ExecuteContext, Filter, Guard, Interceptor } from "./execute";
-import { FeatureInject, Pipe } from "./common";
+import { CoreRequest, ExecuteContext } from "./execute";
+import { FeatureInject, Filter, Guard, Interceptor, Pipe } from "./common";
 /**
  * Result object from decorator functions.
  * Contains sets of guards, filters, interceptors, pipes, and metadata
@@ -234,18 +234,25 @@ export declare function QueryParam(key: string): string | undefined;
 /**
  * Extracts the raw Request object.
  *
- * @returns The underlying Request object (NextRequest)
+ * @template T - The specific request type (e.g., NextRequest, Express.Request)
+ * @returns The underlying CoreRequest object, cast to the specified type
  *
  * @example
  * ```ts
+ * // Default (CoreRequest)
  * findAll() {
  *   const request = Request();
  *   const url = request.url;
- *   const method = request.method;
+ * }
+ *
+ * // With specific type (Next.js)
+ * findAll() {
+ *   const request = Request<NextRequest>();
+ *   const nextUrl = request.nextUrl; // ✅ Type-safe
  * }
  * ```
  */
-export declare function Request(): globalThis.Request;
+export declare function Request<T extends CoreRequest = CoreRequest>(): T;
 /**
  * Extracts and parses FormData from the request body.
  *