@vercube/core 0.0.30 → 0.0.32

package/dist/index.d.mts

@@ -1127,6 +1127,78 @@ declare class StandardSchemaValidationProvider implements ValidationProvider {
   validate(schema: ValidationTypes.Schema, data: ValidationTypes.Input): ValidationTypes.Result | Promise<ValidationTypes.Result>;
 }
 //#endregion
+//#region src/Services/Router/RequestContext.d.ts
+/**
+ * Request context storage using AsyncLocalStorage.
+ * This allows storing request-specific data that is automatically cleaned up after the request completes.
+ */
+declare class RequestContext {
+  /** The storage for the request context */
+  private readonly fStorage;
+  /**
+   * Initializes the request storage.
+   */
+  constructor();
+  /**
+   * Runs a function within a request context.
+   *
+   * This initializes a new context for the request. The context is automatically cleaned up
+   * by Node.js's AsyncLocalStorage when the function completes (either successfully or with an error).
+   *
+   * The cleanup happens automatically - you don't need to manually clear the context.
+   * The context is available throughout the entire async execution chain of the function,
+   * including all nested async operations, but is automatically destroyed when the function
+   * passed to `run()` completes.
+   *
+   * @param fn - The function to run within the context
+   * @returns The result of the function
+   */
+  run<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Sets a value in the current request context.
+   *
+   * @param key - The key to store the value under
+   * @param value - The value to store
+   * @throws Error if called outside of a request context
+   */
+  set(key: string, value: unknown): void;
+  /**
+   * Gets a value from the current request context.
+   *
+   * @param key - The key to retrieve
+   * @returns The value if found, undefined otherwise
+   * @throws Error if called outside of a request context
+   */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+   * Gets a value from the current request context, or returns a default value if not found.
+   *
+   * @param key - The key to retrieve
+   * @param defaultValue - The default value to return if key is not found
+   * @returns The value if found, defaultValue otherwise
+   */
+  getOrDefault<T = unknown>(key: string, defaultValue: T): T;
+  /**
+   * Checks if a key exists in the current request context.
+   *
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key: string): boolean;
+  /**
+   * Gets all keys in the current request context.
+   *
+   * @returns Array of keys in the context
+   */
+  keys(): string[];
+  /**
+   * Gets all values in the current request context.
+   *
+   * @returns Map of all key-value pairs in the context
+   */
+  getAll(): Map<string, unknown>;
+}
+//#endregion
 //#region src/Errors/HttpError.d.ts
 /**
  * Represents an HTTP error.
@@ -1623,4 +1695,4 @@ declare function initializeMetadataMethod(target: any, propertyName: string): Me
  */
 declare function initializeMetadata(target: any): MetadataTypes.Ctx;
 //#endregion
-export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, ConfigTypes, Connect, Controller, CreateAppOptions, DeepPartial, Delete, ErrorHandlerProvider, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers, HooksService, HooksTypes, HttpError, HttpServer, HttpStatusCode, InternalServerError, Listen, MaybePromise, MetadataResolver, MetadataTypes, MethodNotAllowedError, Middleware$1 as Middleware, MiddlewareOptions, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, Post, Put, QueryParam, QueryParams, Redirect, Request$1 as Request, Response$1 as Response, Router, RouterTypes, RuntimeConfig$1 as RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, ValidationTypes, createApp, createMetadataCtx, createMetadataMethod, defineConfig, initializeMetadata, initializeMetadataMethod, loadVercubeConfig };
+export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, ConfigTypes, Connect, Controller, CreateAppOptions, DeepPartial, Delete, ErrorHandlerProvider, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers, HooksService, HooksTypes, HttpError, HttpServer, HttpStatusCode, InternalServerError, Listen, MaybePromise, MetadataResolver, MetadataTypes, MethodNotAllowedError, Middleware$1 as Middleware, MiddlewareOptions, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, Post, Put, QueryParam, QueryParams, Redirect, Request$1 as Request, RequestContext, Response$1 as Response, Router, RouterTypes, RuntimeConfig$1 as RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, ValidationTypes, createApp, createMetadataCtx, createMetadataMethod, defineConfig, initializeMetadata, initializeMetadataMethod, loadVercubeConfig };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { BaseDecorator, Container, Inject, InjectOptional, createDecorator, initializeContainer } from "@vercube/di";
 import { FastResponse, serve } from "srvx";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { addRoute, createRouter, findRoute } from "rou3";
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
@@ -332,6 +333,107 @@ var GlobalMiddlewareRegistry = class {
 	}
 };
 
+//#endregion
+//#region src/Services/Router/RequestContext.ts
+/**
+* Request context storage using AsyncLocalStorage.
+* This allows storing request-specific data that is automatically cleaned up after the request completes.
+*/
+var RequestContext = class {
+	/** The storage for the request context */
+	fStorage;
+	/**
+	* Initializes the request storage.
+	*/
+	constructor() {
+		this.fStorage = new AsyncLocalStorage();
+	}
+	/**
+	* Runs a function within a request context.
+	*
+	* This initializes a new context for the request. The context is automatically cleaned up
+	* by Node.js's AsyncLocalStorage when the function completes (either successfully or with an error).
+	*
+	* The cleanup happens automatically - you don't need to manually clear the context.
+	* The context is available throughout the entire async execution chain of the function,
+	* including all nested async operations, but is automatically destroyed when the function
+	* passed to `run()` completes.
+	*
+	* @param fn - The function to run within the context
+	* @returns The result of the function
+	*/
+	async run(fn) {
+		const context = /* @__PURE__ */ new Map();
+		return this.fStorage.run(context, fn);
+	}
+	/**
+	* Sets a value in the current request context.
+	*
+	* @param key - The key to store the value under
+	* @param value - The value to store
+	* @throws Error if called outside of a request context
+	*/
+	set(key, value) {
+		const context = this.fStorage.getStore();
+		if (!context) throw new Error("RequestContext.set() called outside of request context. The context is automatically initialized by RequestHandler.");
+		context.set(key, value);
+	}
+	/**
+	* Gets a value from the current request context.
+	*
+	* @param key - The key to retrieve
+	* @returns The value if found, undefined otherwise
+	* @throws Error if called outside of a request context
+	*/
+	get(key) {
+		const context = this.fStorage.getStore();
+		if (!context) throw new Error("RequestContext.get() called outside of request context. The context is automatically initialized by RequestHandler.");
+		return context.get(key);
+	}
+	/**
+	* Gets a value from the current request context, or returns a default value if not found.
+	*
+	* @param key - The key to retrieve
+	* @param defaultValue - The default value to return if key is not found
+	* @returns The value if found, defaultValue otherwise
+	*/
+	getOrDefault(key, defaultValue) {
+		const value = this.get(key);
+		return value === void 0 ? defaultValue : value;
+	}
+	/**
+	* Checks if a key exists in the current request context.
+	*
+	* @param key - The key to check
+	* @returns True if the key exists, false otherwise
+	*/
+	has(key) {
+		const context = this.fStorage.getStore();
+		if (!context) return false;
+		return context.has(key);
+	}
+	/**
+	* Gets all keys in the current request context.
+	*
+	* @returns Array of keys in the context
+	*/
+	keys() {
+		const context = this.fStorage.getStore();
+		if (!context) return [];
+		return [...context.keys()];
+	}
+	/**
+	* Gets all values in the current request context.
+	*
+	* @returns Map of all key-value pairs in the context
+	*/
+	getAll() {
+		const context = this.fStorage.getStore();
+		if (!context) return /* @__PURE__ */ new Map();
+		return new Map(context);
+	}
+};
+
 //#endregion
 //#region \0@oxc-project+runtime@0.95.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
@@ -402,35 +504,34 @@ var RequestHandler = class {
 	* @returns {Promise<Response>} The HTTP response
 	*/
 	async handlePreflight(request) {
+		return this.runWithContext(async () => {
+			return this.internalHandlePreflight(request);
+		});
+	}
+	/**
+	* Internal method that handles preflight request processing logic.
+	*
+	* @param request - The incoming HTTP request
+	* @returns {Promise<Response>} The HTTP response
+	* @private
+	*/
+	async internalHandlePreflight(request) {
 		try {
-			let fakeResponse = new FastResponse(void 0, { headers: { "Content-Type": request.headers.get("Content-Type") ?? "application/json" } });
-			const middlewares = this.gGlobalMiddlewareRegistry.middlewares.map((m) => ({
-				...m,
-				middleware: this.gContainer.resolve(m.middleware)
-			}));
-			for await (const hook of middlewares) try {
-				let hookResponse = await hook.middleware.onRequest?.(request, fakeResponse, {
-					middlewareArgs: hook.args,
-					methodArgs: []
-				});
-				if (hookResponse instanceof Response) return hookResponse;
-				else if (hookResponse !== null) fakeResponse = this.processOverrideResponse(hookResponse, fakeResponse);
-				hookResponse = await hook.middleware.onResponse?.(request, fakeResponse, {
-					middlewareArgs: hook.args,
-					methodArgs: []
-				});
-				if (hookResponse instanceof Response) return hookResponse;
-				else if (hookResponse !== null) fakeResponse = this.processOverrideResponse(hookResponse, fakeResponse);
-			} catch (error) {
-				return await Promise.resolve(this.gContainer.get(ErrorHandlerProvider).handleError(error));
-			}
-			return new Response(null, {
-				status: fakeResponse.status ?? 204,
-				statusText: fakeResponse.statusText ?? "No Content",
-				headers: fakeResponse.headers
+			let fakeResponse = this.createInitialResponse(request);
+			const globalMiddlewares = this.gGlobalMiddlewareRegistry.middlewares;
+			const resolvedMiddlewares = this.resolveMiddlewares(globalMiddlewares);
+			const result = await this.executeMiddlewares(resolvedMiddlewares, {
+				request,
+				response: fakeResponse,
+				methodArgs: [],
+				handlerResponse: void 0,
+				executeRequest: true,
+				executeResponse: true
 			});
+			if (result.earlyReturn) return result.earlyReturn;
+			return this.createFinalResponse(result.response, null, 204, "No Content");
 		} catch (error) {
-			return this.gContainer.get(ErrorHandlerProvider).handleError(error);
+			return await this.handleError(error);
 		}
 	}
 	/**
@@ -449,48 +550,196 @@ var RequestHandler = class {
 	* @returns {Promise<Response>} The HTTP response
 	*/
 	async handleRequest(request, route) {
+		return this.runWithContext(async () => {
+			return this.internalHandleRequest(request, route);
+		});
+	}
+	/**
+	* Internal method that handles the request processing logic.
+	* This is separated from handleRequest to allow running with or without request context.
+	*
+	* @param {Request} request - The incoming HTTP request
+	* @param {RouterTypes.RouteMatched<RouterTypes.RouterHandler>} route - The matched route with handler data
+	* @returns {Promise<Response>} The HTTP response
+	* @private
+	*/
+	async internalHandleRequest(request, route) {
 		try {
 			const { instance, propertyName, actions = [], args = [], middlewares = {
 				beforeMiddlewares: [],
 				afterMiddlewares: []
 			} } = route.data;
-			let fakeResponse = new FastResponse(void 0, { headers: { "Content-Type": request.headers.get("Content-Type") ?? "application/json" } });
+			let fakeResponse = this.createInitialResponse(request);
 			const resolvedArgs = args.length > 0 ? await this.gMetadataResolver.resolveArgs(args, {
 				...route,
 				request,
 				response: fakeResponse
 			}) : [];
-			if (middlewares.beforeMiddlewares.length > 0) for await (const hook of middlewares.beforeMiddlewares) try {
-				const hookResponse = await hook.middleware.onRequest?.(request, fakeResponse, {
-					middlewareArgs: hook.args,
-					methodArgs: resolvedArgs
-				});
-				if (hookResponse instanceof Response) return hookResponse;
-			} catch (error) {
-				return await Promise.resolve(this.gContainer.get(ErrorHandlerProvider).handleError(error));
-			}
+			const beforeResult = await this.executeMiddlewares(middlewares.beforeMiddlewares, {
+				request,
+				response: fakeResponse,
+				methodArgs: resolvedArgs,
+				handlerResponse: void 0,
+				executeRequest: true,
+				executeResponse: false
+			});
+			if (beforeResult.earlyReturn) return beforeResult.earlyReturn;
+			fakeResponse = beforeResult.response;
 			for (const action of actions) {
 				const actionResponse = action.handler(request, fakeResponse);
-				if (actionResponse !== null) fakeResponse = this.processOverrideResponse(actionResponse, fakeResponse);
+				if (actionResponse != null) fakeResponse = this.processOverrideResponse(actionResponse, fakeResponse);
 			}
 			let handlerResponse = instance[propertyName].call(instance, ...resolvedArgs?.map((a) => a.resolved) ?? []);
 			if (handlerResponse instanceof Promise) handlerResponse = await handlerResponse;
-			if (middlewares.afterMiddlewares.length > 0) for await (const hook of middlewares.afterMiddlewares) try {
-				const hookResponse = await hook.middleware.onResponse?.(request, fakeResponse, handlerResponse);
-				if (hookResponse !== null) fakeResponse = this.processOverrideResponse(hookResponse, fakeResponse);
-			} catch (error) {
-				return await Promise.resolve(this.gContainer.get(ErrorHandlerProvider).handleError(error));
-			}
-			if (handlerResponse instanceof Response) return handlerResponse;
-			const body = fakeResponse?.body ?? JSON.stringify(handlerResponse);
-			return new Response(body, {
-				status: fakeResponse.status ?? 200,
-				statusText: fakeResponse.statusText ?? "OK",
-				headers: fakeResponse.headers
+			const afterResult = await this.executeMiddlewares(middlewares.afterMiddlewares, {
+				request,
+				response: fakeResponse,
+				methodArgs: resolvedArgs,
+				handlerResponse,
+				executeRequest: false,
+				executeResponse: true
 			});
+			if (afterResult.earlyReturn) return afterResult.earlyReturn;
+			fakeResponse = afterResult.response;
+			if (handlerResponse instanceof Response) return handlerResponse;
+			return this.createFinalResponse(fakeResponse, handlerResponse, 200, "OK");
 		} catch (error) {
-			return this.gContainer.get(ErrorHandlerProvider).handleError(error);
+			return await this.handleError(error);
+		}
+	}
+	/**
+	* Runs a function within a request context if available, otherwise runs it directly
+	*
+	* @param fn - The function to run
+	* @returns The result of the function
+	* @private
+	*/
+	async runWithContext(fn) {
+		const requestContext = this.gContainer.getOptional(RequestContext);
+		if (requestContext) return requestContext.run(fn);
+		return fn();
+	}
+	/**
+	* Creates an initial FastResponse with Content-Type header from the request
+	*
+	* @param request - The incoming HTTP request
+	* @returns The initial FastResponse
+	* @private
+	*/
+	createInitialResponse(request) {
+		return new FastResponse(void 0, { headers: { "Content-Type": request.headers.get("Content-Type") ?? "application/json" } });
+	}
+	/**
+	* Handles errors by delegating to ErrorHandlerProvider
+	*
+	* @param error - The error to handle
+	* @returns The error response
+	* @private
+	*/
+	async handleError(error) {
+		return this.gContainer.get(ErrorHandlerProvider).handleError(error);
+	}
+	/**
+	* Resolves middleware instances from middleware definitions
+	*
+	* @param middlewares - Array of middleware definitions
+	* @returns Array of resolved middleware definitions
+	* @private
+	*/
+	resolveMiddlewares(middlewares) {
+		return middlewares.map((m) => ({
+			...m,
+			middleware: this.gContainer.resolve(m.middleware)
+		}));
+	}
+	/**
+	* Executes a middleware's onRequest hook
+	*
+	* @param hook - The middleware definition
+	* @param request - The HTTP request
+	* @param response - The current response
+	* @param methodArgs - Resolved method arguments
+	* @returns Response if middleware returns one, or updated response, or null
+	* @private
+	*/
+	async executeMiddlewareRequest(hook, request, response, methodArgs) {
+		const hookResponse = await hook.middleware.onRequest?.(request, response, {
+			middlewareArgs: hook.args,
+			methodArgs
+		});
+		if (hookResponse instanceof Response) return hookResponse;
+		if (hookResponse !== null && hookResponse !== void 0) return this.processOverrideResponse(hookResponse, response);
+		return null;
+	}
+	/**
+	* Executes a middleware's onResponse hook
+	*
+	* @param hook - The middleware definition
+	* @param request - The HTTP request
+	* @param response - The current response
+	* @param payload - The handler response payload
+	* @returns Response if middleware returns one, or updated response, or null
+	* @private
+	*/
+	async executeMiddlewareResponse(hook, request, response, payload) {
+		const hookResponse = await hook.middleware.onResponse?.(request, response, payload);
+		if (hookResponse instanceof Response) return hookResponse;
+		if (hookResponse !== null && hookResponse !== void 0) return this.processOverrideResponse(hookResponse, response);
+		return null;
+	}
+	/**
+	* Executes middlewares with configurable hooks (onRequest, onResponse, or both)
+	*
+	* @param middlewares - Array of middleware definitions
+	* @param options - Options for executing middlewares
+	* @returns Object with earlyReturn if middleware returns Response, or updated response
+	* @private
+	*/
+	async executeMiddlewares(middlewares, options) {
+		const { request, response, methodArgs, handlerResponse, executeRequest, executeResponse } = options;
+		let currentResponse = response;
+		for await (const hook of middlewares) try {
+			if (executeRequest) {
+				const requestResult = await this.executeMiddlewareRequest(hook, request, currentResponse, methodArgs);
+				if (requestResult instanceof Response) return {
+					earlyReturn: requestResult,
+					response: currentResponse
+				};
+				if (requestResult !== null && requestResult !== currentResponse) currentResponse = requestResult;
+			}
+			if (executeResponse) {
+				const responseResult = await this.executeMiddlewareResponse(hook, request, currentResponse, handlerResponse);
+				if (responseResult instanceof Response) return {
+					earlyReturn: responseResult,
+					response: currentResponse
+				};
+				if (responseResult !== null && responseResult !== currentResponse) currentResponse = responseResult;
+			}
+		} catch (error) {
+			return {
+				earlyReturn: await this.handleError(error),
+				response: currentResponse
+			};
 		}
+		return { response: currentResponse };
+	}
+	/**
+	* Creates the final Response object from the processed fakeResponse and handler response
+	*
+	* @param fakeResponse - The processed FastResponse
+	* @param handlerResponse - The handler response payload (used if fakeResponse.body is not set)
+	* @param defaultStatus - Default status code if not set
+	* @param defaultStatusText - Default status text if not set
+	* @returns The final Response object
+	* @private
+	*/
+	createFinalResponse(fakeResponse, handlerResponse, defaultStatus, defaultStatusText) {
+		const body = ("body" in fakeResponse && fakeResponse.body != null ? fakeResponse.body : null) ?? JSON.stringify(handlerResponse);
+		return new Response(body, {
+			status: fakeResponse.status ?? defaultStatus,
+			statusText: fakeResponse.statusText ?? defaultStatusText,
+			headers: fakeResponse.headers
+		});
 	}
 	/**
 	* Processes and merges response overrides from middlewares or actions
@@ -1163,6 +1412,7 @@ function createContainer(config) {
 	container.bind(RequestHandler);
 	container.bind(RuntimeConfig);
 	container.bind(GlobalMiddlewareRegistry);
+	container.bind(RequestContext);
 	container.bind(ValidationProvider, StandardSchemaValidationProvider);
 	return container;
 }
@@ -2900,4 +3150,4 @@ let HttpStatusCode = /* @__PURE__ */ function(HttpStatusCode$1) {
 }({});
 
 //#endregion
-export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, Connect, Controller, Delete, ErrorHandlerProvider, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers$1 as Headers, HooksService, HttpError, HttpServer, HttpStatusCode, InternalServerError, Listen, MetadataResolver, MethodNotAllowedError, Middleware, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, Post, Put, QueryParam, QueryParams, Redirect, Request, Response$1 as Response, Router, RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, createApp, createMetadataCtx, createMetadataMethod, defineConfig, initializeMetadata, initializeMetadataMethod, loadVercubeConfig };
+export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, Connect, Controller, Delete, ErrorHandlerProvider, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers$1 as Headers, HooksService, HttpError, HttpServer, HttpStatusCode, InternalServerError, Listen, MetadataResolver, MethodNotAllowedError, Middleware, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, Post, Put, QueryParam, QueryParams, Redirect, Request, RequestContext, Response$1 as Response, Router, RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, createApp, createMetadataCtx, createMetadataMethod, defineConfig, initializeMetadata, initializeMetadataMethod, loadVercubeConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/core",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "Core module for Vercube framework",
   "repository": {
     "type": "git",
@@ -28,8 +28,8 @@
     "pathe": "2.0.3",
     "rou3": "0.7.9",
     "srvx": "0.9.4",
-    "@vercube/di": "0.0.30",
-    "@vercube/logger": "0.0.30"
+    "@vercube/di": "0.0.32",
+    "@vercube/logger": "0.0.32"
   },
   "devDependencies": {
     "rolldown": "1.0.0-beta.45",