@gravito/echo 3.0.1 → 3.1.1

package/dist/atlas/src/utils/CursorEncoding.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @gravito/atlas - Cursor Encoding Utility
+ * @description Base64 encode/decode for cursor-based pagination cursors.
+ *
+ * Cursor format: base64(JSON({ id, sortValue, sortColumn, direction }))
+ * This enables O(1) pagination using tuple comparison SQL:
+ *   WHERE (sort_col, id) > (val, id_val)
+ */
+export interface CursorPayload {
+    /**
+     * Primary key value of the last/first record in the current page
+     */
+    id: unknown;
+    /**
+     * Value of the sort column at the cursor boundary
+     */
+    sortValue: unknown;
+    /**
+     * Column name used for sorting
+     */
+    sortColumn: string;
+    /**
+     * Sort direction
+     */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Encode a cursor payload to an opaque base64 string.
+ *
+ * @param payload - Cursor data to encode
+ * @returns Base64-encoded cursor string
+ *
+ * @example
+ * const cursor = encodeCursor({ id: 42, sortValue: '2026-01-01', sortColumn: 'created_at', direction: 'asc' })
+ */
+export declare function encodeCursor(payload: CursorPayload): string;
+/**
+ * Decode a cursor string back to its payload.
+ *
+ * @param cursor - Base64 cursor string
+ * @returns Decoded cursor payload
+ * @throws {Error} If the cursor is malformed or tampered with
+ *
+ * @example
+ * const payload = decodeCursor(cursor)
+ * // payload.id, payload.sortValue, etc.
+ */
+export declare function decodeCursor(cursor: string): CursorPayload;
+/**
+ * Build the WHERE clause raw SQL and bindings for cursor pagination.
+ *
+ * For ascending sort: WHERE (sort_col, id) > (sort_val, id_val)
+ * For descending sort: WHERE (sort_col, id) < (sort_val, id_val)
+ *
+ * Uses tuple comparison which is O(1) on indexed columns in Postgres & MySQL.
+ *
+ * @param payload - Decoded cursor payload
+ * @returns { sql, bindings } ready for whereRaw()
+ */
+export declare function buildCursorWhereClause(payload: CursorPayload, idColumn?: string): {
+    sql: string;
+    bindings: unknown[];
+};

package/dist/atlas/src/utils/levenshtein.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "Did you mean?" suggestions
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Find similar strings from a list
+ */
+export declare function findSimilar(target: string, candidates: string[], maxDistance?: number, maxResults?: number): string[];

package/dist/core/src/Application.d.ts

@@ -115,15 +115,21 @@ export declare class Application {
     private booted;
     constructor(options: ApplicationConfig);
     /**
-     * Boot the application.
+     * Boot the application and its dependencies.
      *
-     * This will:
-     * 1. Load configuration files
-     * 2. Auto-discover providers (if enabled)
-     * 3. Register all providers
-     * 4. Bootstrap the core
+     * This method orchestrates the full application lifecycle:
+     * 1. Configuration: Loads all config files from the config directory.
+     * 2. Discovery: Auto-discovers ServiceProviders from the providers directory.
+     * 3. Registration: Registers all discovered and explicit providers.
+     * 4. Bootstrapping: Triggers the PlanetCore bootstrap sequence.
      *
-     * @returns Promise that resolves when boot is complete
+     * @returns Promise that resolves to the application instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * const app = new Application({ basePath: import.meta.dir });
+     * await app.boot();
+     * ```
      */
     boot(): Promise<this>;
     /**
@@ -139,10 +145,19 @@ export declare class Application {
      */
     private discoverProviders;
     /**
-     * Get a service from the container.
+     * Resolve a service instance from the IoC container.
      *
-     * @param key - The service key
-     * @returns The resolved service
+     * This is a convenience wrapper around `container.make()`.
+     *
+     * @template T - The expected type of the service.
+     * @param key - The unique identifier or class name of the service.
+     * @returns The resolved service instance.
+     * @throws Error if the service is not bound in the container.
+     *
+     * @example
+     * ```typescript
+     * const db = app.make<Database>('db');
+     * ```
      */
     make<T>(key: string): T;
     /**
@@ -153,18 +168,29 @@ export declare class Application {
      */
     has(key: string): boolean;
     /**
-     * Get a configuration value.
+     * Retrieve a configuration value using dot notation.
+     *
+     * @template T - The expected type of the configuration value.
+     * @param key - The configuration key (e.g., 'app.name', 'database.connections.mysql').
+     * @param defaultValue - Optional value to return if the key is not found.
+     * @returns The configuration value or the default value.
      *
-     * @param key - The config key (supports dot notation)
-     * @param defaultValue - Default value if not found
-     * @returns The config value
+     * @example
+     * ```typescript
+     * const port = app.getConfig<number>('app.port', 3000);
+     * ```
      */
     getConfig<T>(key: string, defaultValue?: T): T;
     /**
-     * Create application path helper.
+     * Resolve an absolute path relative to the application base path.
+     *
+     * @param segments - Path segments to join with the base path.
+     * @returns The absolute path string.
      *
-     * @param segments - Path segments relative to base path
-     * @returns Absolute path
+     * @example
+     * ```typescript
+     * const storagePath = app.path('storage', 'logs');
+     * ```
      */
     path(...segments: string[]): string;
     /**

package/dist/core/src/CommandKernel.d.ts

@@ -0,0 +1,33 @@
+import type { Container } from './Container';
+/**
+ * CommandHandler type for custom CLI commands.
+ */
+export type CommandHandler = (args: string[], container: Container) => Promise<void> | void;
+/**
+ * CommandKernel - Structured CLI Command handling.
+ *
+ * Manages registration and execution of custom CLI commands that can
+ * reuse the application container and providers.
+ *
+ * @example
+ * ```typescript
+ * const kernel = new CommandKernel(container);
+ * kernel.register('greet', (args) => console.log('Hello', args[0]));
+ * await kernel.handle(['greet', 'Universe']);
+ * ```
+ */
+export declare class CommandKernel {
+    private container;
+    private commands;
+    constructor(container: Container);
+    /**
+     * Register a new command handler.
+     */
+    register(name: string, handler: CommandHandler): void;
+    /**
+     * Handle an incoming CLI command.
+     *
+     * @param argv - Array of command line arguments (e.g. process.argv.slice(2))
+     */
+    handle(argv: string[]): Promise<void>;
+}

package/dist/core/src/ConfigManager.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Configuration manager (ConfigManager)
+ *
+ * Unifies environment variables and application configuration access.
+ */
+import type { ZodSchema } from 'zod';
 /**
  * ConfigManager - Central configuration store.
  * Supports loading from environment variables and initial objects.
@@ -5,6 +11,7 @@
  */
 export declare class ConfigManager {
     private config;
+    private schema;
     constructor(initialConfig?: Record<string, unknown>);
     /**
      * Load all environment variables from the active runtime.
@@ -23,4 +30,36 @@ export declare class ConfigManager {
      * Check whether a key exists.
      */
     has(key: string): boolean;
+    /**
+     * Define a Zod schema for configuration validation.
+     *
+     * @param schema - Zod schema for validation
+     *
+     * @example
+     * ```typescript
+     * config.defineSchema(z.object({
+     *   DATABASE_URL: z.string().url(),
+     *   PORT: z.number().default(3000),
+     * }))
+     * ```
+     */
+    defineSchema(schema: ZodSchema): void;
+    /**
+     * Validate configuration against the defined schema.
+     *
+     * Should be called during bootstrap to catch configuration errors early.
+     *
+     * @throws Error if validation fails with details about missing/invalid fields
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   config.validate()
+     * } catch (error) {
+     *   console.error('Config validation failed:', error.message)
+     *   process.exit(1)
+     * }
+     * ```
+     */
+    validate(): void;
 }

package/dist/core/src/Container/RequestScopeManager.d.ts

@@ -0,0 +1,62 @@
+import type { ServiceKey } from '../Container';
+import { RequestScopeMetrics, type RequestScopeObserver } from './RequestScopeMetrics';
+/**
+ * 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
+ * ```
+ */
+export 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;
+}

package/dist/core/src/Container/RequestScopeMetrics.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 }
+ * ```
+ */
+export 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
+ */
+export 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;
+}
+/**
+ * RequestScopeMetricsCollector - Aggregates metrics across multiple scopes
+ *
+ * Used for application-level monitoring and performance tracking
+ *
+ * @example
+ * ```typescript
+ * const collector = new RequestScopeMetricsCollector()
+ *
+ * // Record metrics from multiple requests
+ * collector.record(metrics1)
+ * collector.record(metrics2)
+ * collector.record(metrics3)
+ *
+ * // Get aggregated stats
+ * const stats = collector.getStats()
+ * console.log(stats.averageCleanupTime) // 3.5ms
+ * ```
+ */
+export declare class RequestScopeMetricsCollector {
+    private metrics;
+    /**
+     * Record metrics from a request scope
+     */
+    record(metrics: RequestScopeMetrics): void;
+    /**
+     * Get aggregated statistics
+     */
+    getStats(): {
+        count: number;
+        averageCleanupTime: number | null;
+        maxCleanupTime: number | null;
+        minCleanupTime: number | null;
+        totalErrorCount: number;
+        errorRate: number;
+    };
+    /**
+     * Clear collected metrics
+     */
+    clear(): void;
+    /**
+     * Get number of recorded metrics
+     */
+    size(): number;
+    /**
+     * Export metrics as JSON array
+     */
+    toJSON(): {
+        cleanupDuration: number | null;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    }[];
+}

package/dist/core/src/Container.d.ts

@@ -1,8 +1,28 @@
+import type { RequestScopeManager } from './Container/RequestScopeManager';
 /**
  * Factory type for creating service instances
  */
 export type Factory<T> = (container: Container) => T;
-export type BindingKey = string | symbol;
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+export type ServiceMap = {};
+/**
+ * ServiceKey represents the allowed keys for service resolution.
+ * Includes keys from ServiceMap, generic strings, or symbols.
+ */
+export type ServiceKey = keyof ServiceMap | (string & {}) | symbol;
 /**
  * Container - Simple Dependency Injection Container.
  * Manages service bindings and singleton instances.
@@ -11,34 +31,123 @@ export type BindingKey = string | symbol;
 export declare class Container {
     private bindings;
     private instances;
+    private resolutionStack;
+    /**
+     * Run a function within a request scope context.
+     *
+     * All service resolutions within the function will use the provided scope,
+     * enabling request-scoped service instances to be properly isolated.
+     *
+     * @template T - The return type of the function.
+     * @param scope - The RequestScopeManager for this request.
+     * @param fn - The function to execute within the scope.
+     * @returns The result of the function.
+     *
+     * @example
+     * ```typescript
+     * const scope = new RequestScopeManager()
+     * const result = await Container.runWithScope(scope, async () => {
+     *   const service = container.make('requestScoped')
+     *   return service.doSomething()
+     * })
+     * ```
+     */
+    static runWithScope<T>(scope: RequestScopeManager, fn: () => T | Promise<T>): T | Promise<T>;
     /**
      * Bind a service to the container.
-     * New instance will be created on each resolution.
+     *
+     * A new instance will be created by the factory function every time the
+     * service is resolved from the container.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.bind('logger', (c) => new ConsoleLogger());
+     * ```
      */
-    bind<T>(key: BindingKey, factory: Factory<T>): void;
+    bind<T>(key: ServiceKey, factory: Factory<T>): void;
     /**
      * Bind a shared service to the container (Singleton).
-     * Same instance will be returned on each resolution.
+     *
+     * The factory function will be called only once, and the same instance
+     * will be returned on every subsequent resolution.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.singleton('db', (c) => new DatabaseConnection());
+     * ```
+     */
+    singleton<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Bind a request-scoped service to the container.
+     *
+     * A new instance will be created for each request and cached within that request.
+     * The service is automatically cleaned up when the request ends.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.scoped('requestCache', (c) => new RequestProductCache());
+     * ```
+     */
+    scoped<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Register an existing instance as a shared service.
+     *
+     * @param key - The unique identifier for the service.
+     * @param instance - The instance to register.
      */
-    singleton<T>(key: BindingKey, factory: Factory<T>): void;
+    instance<T>(key: ServiceKey, instance: T): void;
     /**
-     * Register an existing instance as shared service.
+     * Check if a service is request-scoped.
+     *
+     * @param key - The service key to check.
+     * @returns True if the service is request-scoped.
      */
-    instance<T>(key: BindingKey, instance: T): void;
+    isRequestScoped(key: ServiceKey): boolean;
     /**
-     * Resolve a service from the container.
+     * Resolve a service instance from the container.
+     *
+     * Automatically handles singleton caching and factory execution.
+     *
+     * @template T - The expected type of the service.
+     * @param key - The unique identifier for the service.
+     * @returns The resolved service instance.
+     * @throws Error if the service key is not found in the container.
+     *
+     * @example
+     * ```typescript
+     * const logger = container.make<Logger>('logger');
+     * ```
      */
-    make<T>(key: BindingKey): T;
+    make<K extends keyof ServiceMap>(key: K): ServiceMap[K];
+    make<T>(key: ServiceKey): T;
     /**
-     * Check if a service is bound.
+     * Check if a service is bound or has an instance in the container.
+     *
+     * @param key - The service key to check.
+     * @returns True if the service exists.
      */
-    has(key: BindingKey): boolean;
+    has(key: ServiceKey): boolean;
     /**
-     * Flush all instances and bindings.
+     * Flush all instances and bindings from the container.
+     * Resets the container to an empty state.
      */
     flush(): void;
     /**
-     * Forget a specific instance (but keep binding)
+     * Forget a specific instance while keeping its binding.
+     *
+     * @param key - The service key to forget.
      */
-    forget(key: BindingKey): void;
+    forget(key: ServiceKey): void;
 }

package/dist/core/src/ErrorHandler.d.ts

@@ -42,6 +42,9 @@ export declare class ErrorHandler {
     constructor(deps: ErrorHandlerDeps);
     /**
      * Handle application errors
+     *
+     * Integrates RequestScope cleanup to ensure proper resource management
+     * even when errors occur during request processing.
      */
     handleError(err: unknown, c: GravitoContext): Promise<Response>;
     /**