@gravito/core 1.6.0 → 1.6.1

package/dist/engine/index.d.cts

@@ -52,6 +52,9 @@ interface FastContext$1 {
     /** Context Variables */
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /** Request Scope Management */
+    requestScope(): any;
+    scoped<T>(key: string | symbol, factory: () => T): T;
     /** Lifecycle helpers */
     route: (name: string, params?: any, query?: any) => string;
     readonly native: any;
@@ -180,7 +183,6 @@ declare class Gravito {
     staticRoutes: Map<string, RouteMetadata>;
     private isPureStaticApp;
     private compiledDynamicRoutes;
-    private middlewareVersion;
     /**
      * Create a new Gravito instance
      *
@@ -329,7 +331,12 @@ declare class AOTRouter {
     private dynamicRoutePatterns;
     private middlewareCache;
     private cacheMaxSize;
-    private version;
+    private _version;
+    /**
+     * Get the current version for cache invalidation
+     * Incremented whenever middleware or routes are modified
+     */
+    get version(): number;
     /**
      * Register a route
      *
@@ -414,6 +421,177 @@ declare class AOTRouter {
     }>;
 }
 
+/**
+ * ServiceMap interface for type-safe IoC resolution.
+ *
+ * Extend this interface via module augmentation to get type inference:
+ * @example
+ * ```typescript
+ * declare module '@gravito/core' {
+ *   interface ServiceMap {
+ *     logger: Logger
+ *     db: DatabaseConnection
+ *   }
+ * }
+ * ```
+ */
+type ServiceMap = {};
+/**
+ * ServiceKey represents the allowed keys for service resolution.
+ * Includes keys from ServiceMap, generic strings, or symbols.
+ */
+type ServiceKey = keyof ServiceMap | (string & {}) | symbol;
+
+/**
+ * RequestScopeMetrics - Observability for RequestScope lifecycle
+ *
+ * Tracks cleanup execution time, scope size, and service counts
+ * for performance monitoring and diagnostics.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new RequestScopeMetrics()
+ * metrics.recordCleanupStart()
+ * await scope.cleanup()
+ * metrics.recordCleanupEnd()
+ *
+ * console.log(metrics.toJSON())
+ * // { cleanupDuration: 2.5, scopeSize: 3, servicesCleaned: 3 }
+ * ```
+ */
+declare class RequestScopeMetrics {
+    private cleanupStartTime;
+    private cleanupDuration;
+    private scopeSize;
+    private servicesCleaned;
+    private errorsOccurred;
+    /**
+     * Record start of cleanup operation
+     */
+    recordCleanupStart(): void;
+    /**
+     * Record end of cleanup operation
+     *
+     * @param scopeSize - Number of services in the scope
+     * @param servicesCleaned - Number of services that had cleanup called
+     * @param errorsOccurred - Number of cleanup errors
+     */
+    recordCleanupEnd(scopeSize: number, servicesCleaned: number, errorsOccurred?: number): void;
+    /**
+     * Get cleanup duration in milliseconds
+     *
+     * @returns Duration in ms, or null if cleanup not completed
+     */
+    getCleanupDuration(): number | null;
+    /**
+     * Check if cleanup took longer than threshold (default 2ms)
+     * Useful for detecting slow cleanups
+     *
+     * @param thresholdMs - Threshold in milliseconds
+     * @returns True if cleanup exceeded threshold
+     */
+    isSlowCleanup(thresholdMs?: number): boolean;
+    /**
+     * Export metrics as JSON for logging/monitoring
+     */
+    toJSON(): {
+        cleanupDuration: number | null;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    };
+    /**
+     * Export metrics as compact string for logging
+     */
+    toString(): string;
+}
+/**
+ * RequestScopeObserver - Hook for monitoring RequestScope lifecycle
+ *
+ * Implement this interface to receive callbacks during scope operations
+ */
+interface RequestScopeObserver {
+    /**
+     * Called when a service is resolved in the scope
+     */
+    onServiceResolved?(key: string | symbol, isFromCache: boolean): void;
+    /**
+     * Called when cleanup starts
+     */
+    onCleanupStart?(): void;
+    /**
+     * Called when cleanup completes
+     */
+    onCleanupEnd?(metrics: RequestScopeMetrics): void;
+    /**
+     * Called when cleanup encounters an error
+     */
+    onCleanupError?(error: Error): void;
+}
+
+/**
+ * Manages request-scoped service instances within a single HTTP request.
+ *
+ * Each request gets its own RequestScopeManager instance with isolated state.
+ * Services are cached within the request and automatically cleaned up when
+ * the request ends.
+ *
+ * @example
+ * ```typescript
+ * const scope = new RequestScopeManager()
+ * const cache = scope.resolve('productCache', () => new ProductCache())
+ * // ... use cache ...
+ * await scope.cleanup() // Called automatically by Gravito engine
+ * ```
+ */
+declare class RequestScopeManager {
+    private scoped;
+    private metadata;
+    private metrics;
+    private observer;
+    constructor(observer?: RequestScopeObserver);
+    /**
+     * Set observer for monitoring scope lifecycle
+     */
+    setObserver(observer: RequestScopeObserver): void;
+    /**
+     * Get metrics for this scope
+     */
+    getMetrics(): RequestScopeMetrics;
+    /**
+     * Resolve or retrieve a request-scoped service instance.
+     *
+     * If the service already exists in this scope, returns the cached instance.
+     * Otherwise, calls the factory function to create a new instance and caches it.
+     *
+     * Automatically detects and records services with cleanup methods.
+     *
+     * @template T - The type of the service.
+     * @param key - The service key (for caching).
+     * @param factory - Factory function to create the instance if not cached.
+     * @returns The cached or newly created instance.
+     */
+    resolve<T>(key: ServiceKey, factory: () => T): T;
+    /**
+     * Clean up all request-scoped instances.
+     *
+     * Calls the cleanup() method on each service that has one.
+     * Silently ignores cleanup errors to prevent cascading failures.
+     * Called automatically by the Gravito engine in the request finally block.
+     *
+     * @returns Promise that resolves when all cleanup is complete.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get the number of services in this scope (for monitoring).
+     *
+     * @returns The count of cached services.
+     */
+    size(): number;
+}
+
 /**
  * @fileoverview FastContext - Pooled Request Context
  *
@@ -439,6 +617,11 @@ declare class FastRequestImpl implements FastRequest {
     private _headers;
     private _cachedJson;
     private _jsonParsed;
+    private _cachedText;
+    private _textParsed;
+    private _cachedFormData;
+    private _formDataParsed;
+    private _cachedQueries;
     private _ctx;
     constructor(ctx: FastContext);
     /**
@@ -476,6 +659,7 @@ declare class FastContext implements FastContext$1 {
     readonly req: FastRequestImpl;
     private _headers;
     _isReleased: boolean;
+    private _requestScope;
     /**
      * Initialize context for a new request
      *
@@ -510,6 +694,22 @@ declare class FastContext implements FastContext$1 {
     private _store;
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     * @throws Error if called before init() or after reset().
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
 }
@@ -537,6 +737,10 @@ declare class MinimalRequest implements FastRequest {
     private readonly _path;
     private readonly _routePattern?;
     private _searchParams;
+    private _cachedQueries;
+    private _cachedJsonPromise;
+    private _cachedTextPromise;
+    private _cachedFormDataPromise;
     constructor(_request: Request, _params: Record<string, string>, _path: string, _routePattern?: string | undefined);
     get url(): string;
     get method(): string;
@@ -569,6 +773,7 @@ declare class MinimalRequest implements FastRequest {
 declare class MinimalContext implements FastContext$1 {
     readonly req: MinimalRequest;
     private _resHeaders;
+    private _requestScope;
     constructor(request: Request, params: Record<string, string>, path: string, routePattern?: string);
     private getHeaders;
     json<T>(data: T, status?: number): Response;
@@ -587,6 +792,21 @@ declare class MinimalContext implements FastContext$1 {
     forward(target: string, _options?: any): Promise<Response>;
     get<T>(_key: string): T;
     set(_key: string, _value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
     init(_request: Request, _params?: Record<string, string>, _path?: string): this;

package/dist/engine/index.d.ts

@@ -52,6 +52,9 @@ interface FastContext$1 {
     /** Context Variables */
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /** Request Scope Management */
+    requestScope(): any;
+    scoped<T>(key: string | symbol, factory: () => T): T;
     /** Lifecycle helpers */
     route: (name: string, params?: any, query?: any) => string;
     readonly native: any;
@@ -180,7 +183,6 @@ declare class Gravito {
     staticRoutes: Map<string, RouteMetadata>;
     private isPureStaticApp;
     private compiledDynamicRoutes;
-    private middlewareVersion;
     /**
      * Create a new Gravito instance
      *
@@ -329,7 +331,12 @@ declare class AOTRouter {
     private dynamicRoutePatterns;
     private middlewareCache;
     private cacheMaxSize;
-    private version;
+    private _version;
+    /**
+     * Get the current version for cache invalidation
+     * Incremented whenever middleware or routes are modified
+     */
+    get version(): number;
     /**
      * Register a route
      *
@@ -414,6 +421,177 @@ declare class AOTRouter {
     }>;
 }
 
+/**
+ * ServiceMap interface for type-safe IoC resolution.
+ *
+ * Extend this interface via module augmentation to get type inference:
+ * @example
+ * ```typescript
+ * declare module '@gravito/core' {
+ *   interface ServiceMap {
+ *     logger: Logger
+ *     db: DatabaseConnection
+ *   }
+ * }
+ * ```
+ */
+type ServiceMap = {};
+/**
+ * ServiceKey represents the allowed keys for service resolution.
+ * Includes keys from ServiceMap, generic strings, or symbols.
+ */
+type ServiceKey = keyof ServiceMap | (string & {}) | symbol;
+
+/**
+ * RequestScopeMetrics - Observability for RequestScope lifecycle
+ *
+ * Tracks cleanup execution time, scope size, and service counts
+ * for performance monitoring and diagnostics.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new RequestScopeMetrics()
+ * metrics.recordCleanupStart()
+ * await scope.cleanup()
+ * metrics.recordCleanupEnd()
+ *
+ * console.log(metrics.toJSON())
+ * // { cleanupDuration: 2.5, scopeSize: 3, servicesCleaned: 3 }
+ * ```
+ */
+declare class RequestScopeMetrics {
+    private cleanupStartTime;
+    private cleanupDuration;
+    private scopeSize;
+    private servicesCleaned;
+    private errorsOccurred;
+    /**
+     * Record start of cleanup operation
+     */
+    recordCleanupStart(): void;
+    /**
+     * Record end of cleanup operation
+     *
+     * @param scopeSize - Number of services in the scope
+     * @param servicesCleaned - Number of services that had cleanup called
+     * @param errorsOccurred - Number of cleanup errors
+     */
+    recordCleanupEnd(scopeSize: number, servicesCleaned: number, errorsOccurred?: number): void;
+    /**
+     * Get cleanup duration in milliseconds
+     *
+     * @returns Duration in ms, or null if cleanup not completed
+     */
+    getCleanupDuration(): number | null;
+    /**
+     * Check if cleanup took longer than threshold (default 2ms)
+     * Useful for detecting slow cleanups
+     *
+     * @param thresholdMs - Threshold in milliseconds
+     * @returns True if cleanup exceeded threshold
+     */
+    isSlowCleanup(thresholdMs?: number): boolean;
+    /**
+     * Export metrics as JSON for logging/monitoring
+     */
+    toJSON(): {
+        cleanupDuration: number | null;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    };
+    /**
+     * Export metrics as compact string for logging
+     */
+    toString(): string;
+}
+/**
+ * RequestScopeObserver - Hook for monitoring RequestScope lifecycle
+ *
+ * Implement this interface to receive callbacks during scope operations
+ */
+interface RequestScopeObserver {
+    /**
+     * Called when a service is resolved in the scope
+     */
+    onServiceResolved?(key: string | symbol, isFromCache: boolean): void;
+    /**
+     * Called when cleanup starts
+     */
+    onCleanupStart?(): void;
+    /**
+     * Called when cleanup completes
+     */
+    onCleanupEnd?(metrics: RequestScopeMetrics): void;
+    /**
+     * Called when cleanup encounters an error
+     */
+    onCleanupError?(error: Error): void;
+}
+
+/**
+ * Manages request-scoped service instances within a single HTTP request.
+ *
+ * Each request gets its own RequestScopeManager instance with isolated state.
+ * Services are cached within the request and automatically cleaned up when
+ * the request ends.
+ *
+ * @example
+ * ```typescript
+ * const scope = new RequestScopeManager()
+ * const cache = scope.resolve('productCache', () => new ProductCache())
+ * // ... use cache ...
+ * await scope.cleanup() // Called automatically by Gravito engine
+ * ```
+ */
+declare class RequestScopeManager {
+    private scoped;
+    private metadata;
+    private metrics;
+    private observer;
+    constructor(observer?: RequestScopeObserver);
+    /**
+     * Set observer for monitoring scope lifecycle
+     */
+    setObserver(observer: RequestScopeObserver): void;
+    /**
+     * Get metrics for this scope
+     */
+    getMetrics(): RequestScopeMetrics;
+    /**
+     * Resolve or retrieve a request-scoped service instance.
+     *
+     * If the service already exists in this scope, returns the cached instance.
+     * Otherwise, calls the factory function to create a new instance and caches it.
+     *
+     * Automatically detects and records services with cleanup methods.
+     *
+     * @template T - The type of the service.
+     * @param key - The service key (for caching).
+     * @param factory - Factory function to create the instance if not cached.
+     * @returns The cached or newly created instance.
+     */
+    resolve<T>(key: ServiceKey, factory: () => T): T;
+    /**
+     * Clean up all request-scoped instances.
+     *
+     * Calls the cleanup() method on each service that has one.
+     * Silently ignores cleanup errors to prevent cascading failures.
+     * Called automatically by the Gravito engine in the request finally block.
+     *
+     * @returns Promise that resolves when all cleanup is complete.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get the number of services in this scope (for monitoring).
+     *
+     * @returns The count of cached services.
+     */
+    size(): number;
+}
+
 /**
  * @fileoverview FastContext - Pooled Request Context
  *
@@ -439,6 +617,11 @@ declare class FastRequestImpl implements FastRequest {
     private _headers;
     private _cachedJson;
     private _jsonParsed;
+    private _cachedText;
+    private _textParsed;
+    private _cachedFormData;
+    private _formDataParsed;
+    private _cachedQueries;
     private _ctx;
     constructor(ctx: FastContext);
     /**
@@ -476,6 +659,7 @@ declare class FastContext implements FastContext$1 {
     readonly req: FastRequestImpl;
     private _headers;
     _isReleased: boolean;
+    private _requestScope;
     /**
      * Initialize context for a new request
      *
@@ -510,6 +694,22 @@ declare class FastContext implements FastContext$1 {
     private _store;
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     * @throws Error if called before init() or after reset().
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
 }
@@ -537,6 +737,10 @@ declare class MinimalRequest implements FastRequest {
     private readonly _path;
     private readonly _routePattern?;
     private _searchParams;
+    private _cachedQueries;
+    private _cachedJsonPromise;
+    private _cachedTextPromise;
+    private _cachedFormDataPromise;
     constructor(_request: Request, _params: Record<string, string>, _path: string, _routePattern?: string | undefined);
     get url(): string;
     get method(): string;
@@ -569,6 +773,7 @@ declare class MinimalRequest implements FastRequest {
 declare class MinimalContext implements FastContext$1 {
     readonly req: MinimalRequest;
     private _resHeaders;
+    private _requestScope;
     constructor(request: Request, params: Record<string, string>, path: string, routePattern?: string);
     private getHeaders;
     json<T>(data: T, status?: number): Response;
@@ -587,6 +792,21 @@ declare class MinimalContext implements FastContext$1 {
     forward(target: string, _options?: any): Promise<Response>;
     get<T>(_key: string): T;
     set(_key: string, _value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
     init(_request: Request, _params?: Record<string, string>, _path?: string): this;