@gravito/echo 3.1.1 → 4.0.0

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

@@ -1,63 +0,0 @@
-/**
- * @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

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,215 +0,0 @@
-/**
- * @fileoverview Application - Enterprise Application Container
- *
- * A high-level application class that orchestrates the entire framework.
- * Provides a centralized entry point for enterprise applications with
- * auto-discovery of providers, config loading, and lifecycle management.
- *
- * @module @gravito/core
- * @since 2.0.0
- */
-import { ConfigManager } from './ConfigManager';
-import { Container } from './Container';
-import type { EventManager } from './EventManager';
-import type { Logger } from './Logger';
-import { PlanetCore } from './PlanetCore';
-import type { ServiceProvider } from './ServiceProvider';
-/**
- * Application Config options for the Application class.
- * @public
- */
-export interface ApplicationConfig {
-    /**
-     * Base path of the application
-     */
-    basePath: string;
-    /**
-     * Path to the config directory (relative to basePath)
-     * @default 'config'
-     */
-    configPath?: string;
-    /**
-     * Path to the providers directory (relative to basePath)
-     * @default 'src/Providers'
-     */
-    providersPath?: string;
-    /**
-     * Environment (development, production, testing)
-     */
-    env?: 'development' | 'production' | 'testing';
-    /**
-     * Logger instance
-     */
-    logger?: Logger;
-    /**
-     * Initial configuration values
-     */
-    config?: Record<string, unknown>;
-    /**
-     * Service providers to register
-     */
-    providers?: ServiceProvider[];
-    /**
-     * Whether to auto-discover providers from providersPath
-     * @default true
-     */
-    autoDiscoverProviders?: boolean;
-}
-/**
- * Application - Enterprise-grade application container.
- *
- * Provides a higher-level abstraction over PlanetCore for building
- * enterprise applications with convention-over-configuration patterns.
- *
- * @example
- * ```typescript
- * // Create application
- * const app = new Application({
- *   basePath: import.meta.dir,
- *   env: process.env.NODE_ENV as 'development' | 'production',
- * });
- *
- * // Boot the application
- * await app.boot();
- *
- * // Access core
- * export default app.core.liftoff();
- * ```
- */
-export declare class Application {
-    /**
-     * The underlying PlanetCore instance.
-     */
-    readonly core: PlanetCore;
-    /**
-     * The IoC container.
-     */
-    readonly container: Container;
-    /**
-     * The configuration manager.
-     */
-    readonly config: ConfigManager;
-    /**
-     * The event manager.
-     */
-    readonly events: EventManager;
-    /**
-     * The logger instance.
-     */
-    readonly logger: Logger;
-    /**
-     * Application base path.
-     */
-    readonly basePath: string;
-    /**
-     * Environment mode.
-     */
-    readonly env: 'development' | 'production' | 'testing';
-    /**
-     * Configuration options.
-     */
-    private readonly options;
-    /**
-     * Whether the application has been booted.
-     */
-    private booted;
-    constructor(options: ApplicationConfig);
-    /**
-     * Boot the application and its dependencies.
-     *
-     * 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 to the application instance for chaining.
-     *
-     * @example
-     * ```typescript
-     * const app = new Application({ basePath: import.meta.dir });
-     * await app.boot();
-     * ```
-     */
-    boot(): Promise<this>;
-    /**
-     * Load configuration files from the config directory.
-     *
-     * @internal
-     */
-    private loadConfiguration;
-    /**
-     * Discover and register providers from the providers directory.
-     *
-     * @internal
-     */
-    private discoverProviders;
-    /**
-     * Resolve a service instance from the IoC container.
-     *
-     * 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;
-    /**
-     * Check if a service is bound.
-     *
-     * @param key - The service key
-     * @returns True if bound
-     */
-    has(key: string): boolean;
-    /**
-     * 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.
-     *
-     * @example
-     * ```typescript
-     * const port = app.getConfig<number>('app.port', 3000);
-     * ```
-     */
-    getConfig<T>(key: string, defaultValue?: T): T;
-    /**
-     * 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.
-     *
-     * @example
-     * ```typescript
-     * const storagePath = app.path('storage', 'logs');
-     * ```
-     */
-    path(...segments: string[]): string;
-    /**
-     * Get the config path.
-     *
-     * @param segments - Additional path segments
-     * @returns Absolute path to config directory
-     */
-    configPath(...segments: string[]): string;
-    /**
-     * Check if running in production.
-     */
-    isProduction(): boolean;
-    /**
-     * Check if running in development.
-     */
-    isDevelopment(): boolean;
-    /**
-     * Check if running in testing.
-     */
-    isTesting(): boolean;
-}

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

@@ -1,33 +0,0 @@
-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,65 +0,0 @@
-/**
- * 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.
- * @public
- */
-export declare class ConfigManager {
-    private config;
-    private schema;
-    constructor(initialConfig?: Record<string, unknown>);
-    /**
-     * Load all environment variables from the active runtime.
-     */
-    private loadEnv;
-    /**
-     * Get a configuration value (generic return type supported).
-     * Supports dot notation for deep access (e.g. 'app.name').
-     */
-    get<T = unknown>(key: string, defaultValue?: T): T;
-    /**
-     * Set a configuration value.
-     */
-    set(key: string, value: unknown): void;
-    /**
-     * 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

@@ -1,62 +0,0 @@
-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

@@ -1,144 +0,0 @@
-/**
- * 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;
-    }[];
-}