@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/provider/logger/logger.query.d.ts

@@ -0,0 +1,232 @@
+import { LogEntry } from "./utils/log-entry.js";
+import { LogLevel } from "./utils/log-levels.js";
+/**
+ * Configuration for log query and export features.
+ * @public API
+ */
+export interface QueryConfig {
+    /** Enable in-memory log buffer (default: true in dev, false in prod) */
+    enabled?: boolean;
+    /** Maximum number of logs to keep in buffer (default: 1000) */
+    bufferSize?: number;
+    /** Enable markdown export (default: true) */
+    enableExport?: boolean;
+}
+/**
+ * Log query options for filtering logs.
+ * @public API
+ */
+export interface LogQueryOptions {
+    /** Filter by log level */
+    level?: LogLevel | Array<LogLevel>;
+    /** Filter by context (exact match or regex) */
+    context?: string | RegExp;
+    /** Start time (timestamp or Date) */
+    startTime?: number | Date;
+    /** End time (timestamp or Date) */
+    endTime?: number | Date;
+    /** Search term (searches message and data) */
+    search?: string;
+    /** Regex pattern for message matching */
+    messageRegex?: RegExp | string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Sort order: 'asc' (oldest first) or 'desc' (newest first, default) */
+    sort?: "asc" | "desc";
+}
+/**
+ * Log query builder for chainable queries.
+ * @public API
+ */
+export declare class LogQuery {
+    private entries;
+    private results;
+    constructor(entries: Array<LogEntry>);
+    /**
+     * Filter by log level(s).
+     * @param level - Single level or array of levels
+     * @returns Query builder instance
+     * @public API
+     */
+    level(level: LogLevel | Array<LogLevel>): LogQuery;
+    /**
+     * Filter by context (exact match or regex).
+     * @param context - Context string or regex pattern
+     * @returns Query builder instance
+     * @public API
+     */
+    context(context: string | RegExp): LogQuery;
+    /**
+     * Filter by time range.
+     * @param start - Start time (timestamp or Date)
+     * @param end - End time (timestamp or Date)
+     * @returns Query builder instance
+     * @public API
+     */
+    timeRange(start?: number | Date, end?: number | Date): LogQuery;
+    /**
+     * Search in message and data fields.
+     * @param term - Search term (case-insensitive)
+     * @returns Query builder instance
+     * @public API
+     */
+    search(term: string): LogQuery;
+    /**
+     * Filter by regex pattern on message.
+     * @param pattern - Regex pattern (string or RegExp)
+     * @returns Query builder instance
+     * @public API
+     */
+    messageRegex(pattern: RegExp | string): LogQuery;
+    /**
+     * Limit the number of results.
+     * @param limit - Maximum number of results
+     * @returns Query builder instance
+     * @public API
+     */
+    limit(limit: number): LogQuery;
+    /**
+     * Sort results by timestamp.
+     * @param order - Sort order: 'asc' (oldest first) or 'desc' (newest first)
+     * @returns Query builder instance
+     * @public API
+     */
+    sort(order?: "asc" | "desc"): LogQuery;
+    /**
+     * Execute the query and return results.
+     * @returns Array of log entries matching the query
+     * @public API
+     */
+    execute(): Array<LogEntry>;
+    /**
+     * Get the count of matching results.
+     * @returns Number of matching entries
+     * @public API
+     */
+    count(): number;
+    /**
+     * Get statistics about the query results.
+     * @returns Query statistics
+     * @public API
+     */
+    stats(): QueryStats;
+}
+/**
+ * Query statistics.
+ * @public API
+ */
+export interface QueryStats {
+    total: number;
+    byLevel: Record<string, number>;
+    byContext: Record<string, number>;
+    oldest: number | null;
+    newest: number | null;
+}
+/**
+ * Circular buffer for storing log entries in memory.
+ * Thread-safe for single-threaded Node.js (no concurrent access needed).
+ * @public API
+ */
+export declare class LogBuffer {
+    private buffer;
+    private maxSize;
+    private writeIndex;
+    constructor(maxSize?: number);
+    /**
+     * Add a log entry to the buffer.
+     * Uses circular buffer logic for efficient memory usage.
+     * @param entry - Log entry to add
+     */
+    add(entry: LogEntry): void;
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options?: LogQueryOptions): Array<LogEntry>;
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery(): LogQuery;
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries in chronological order (oldest first)
+     */
+    getAll(): Array<LogEntry>;
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats(): QueryStats;
+    /**
+     * Get the current buffer size.
+     * @returns Number of entries in buffer
+     */
+    size(): number;
+}
+/**
+ * Log query manager for managing in-memory log buffer and queries.
+ * @public API
+ */
+export declare class LogQueryManager {
+    private buffer;
+    private config;
+    constructor(config?: Partial<QueryConfig>);
+    /**
+     * Add a log entry to the buffer (if enabled).
+     * @param entry - Log entry to add
+     */
+    addEntry(entry: LogEntry): void;
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options?: LogQueryOptions): Array<LogEntry>;
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery(): LogQuery;
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries
+     */
+    getAll(): Array<LogEntry>;
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats(): QueryStats;
+    /**
+     * Check if query features are enabled.
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Configure the query manager.
+     * @param config - Partial configuration
+     */
+    configure(config: Partial<QueryConfig>): void;
+}
+/**
+ * Export logs to markdown format.
+ * @param entries - Log entries to export
+ * @param options - Export options
+ * @returns Markdown string
+ * @public API
+ */
+export declare function exportToMarkdown(entries: Array<LogEntry>, options?: {
+    title?: string;
+    includeStats?: boolean;
+    groupBy?: "level" | "context" | "none";
+}): string;

package/lib/esm/types/provider/logger/logger.redaction.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @file logger.redaction.ts
+ * @description Automatic sensitive data redaction for logs
+ * @module @expressots/core/provider/logger
+ *
+ * Features:
+ * - Pattern-based field name redaction
+ * - Regex-based value redaction (credit cards, SSN, tokens)
+ * - Partial redaction (show last N characters)
+ * - Deep object scanning with circular reference handling
+ * - Fully configurable patterns and behavior
+ *
+ * @example
+ * ```typescript
+ * const redactor = new Redactor();
+ *
+ * // Redacts password field
+ * redactor.redact({ password: "secret123" });
+ * // Result: { password: "••••••••" }
+ *
+ * // Partial redaction for credit cards
+ * redactor.redact({ card: "4532015112830366" });
+ * // Result: { card: "••••••••••••0366" }
+ * ```
+ */
+/**
+ * Configuration for sensitive data redaction.
+ * @public API
+ */
+export interface RedactionConfig {
+    /** Enable/disable redaction globally */
+    enabled: boolean;
+    /** Replacement string for redacted values */
+    replacement: string;
+    /** Field name patterns to redact (case-insensitive) */
+    fieldPatterns: Array<string>;
+    /** Regex patterns to detect and redact in values */
+    valuePatterns: Array<RedactionPattern>;
+    /** Enable partial redaction (show last N chars) */
+    partialRedaction: boolean;
+    /** Number of characters to reveal at end (for partial redaction) */
+    revealLastChars: number;
+    /** Maximum object depth to scan (prevent infinite recursion) */
+    maxDepth: number;
+    /** Fields to never redact (whitelist) */
+    whitelist: Array<string>;
+}
+/**
+ * A regex pattern with optional partial redaction settings.
+ * @public API
+ */
+export interface RedactionPattern {
+    /** Name of the pattern (for debugging/configuration) */
+    name: string;
+    /** Regex pattern to match */
+    pattern: RegExp;
+    /** Override partial redaction for this pattern */
+    partialRedaction?: boolean;
+    /** Override reveal count for this pattern */
+    revealLastChars?: number;
+    /** Custom replacement for this pattern */
+    replacement?: string;
+}
+/**
+ * Default field name patterns that indicate sensitive data.
+ * Case-insensitive matching.
+ */
+export declare const DEFAULT_FIELD_PATTERNS: Array<string>;
+/**
+ * Default regex patterns for detecting sensitive values.
+ * These patterns match common formats regardless of field name.
+ */
+export declare const DEFAULT_VALUE_PATTERNS: Array<RedactionPattern>;
+/**
+ * Get default redaction configuration.
+ */
+export declare function getDefaultRedactionConfig(): RedactionConfig;
+/**
+ * Redactor class for automatic sensitive data redaction.
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * const redactor = new Redactor();
+ *
+ * // Basic usage
+ * const safe = redactor.redact(sensitiveObject);
+ *
+ * // Custom configuration
+ * const customRedactor = new Redactor({
+ *   fieldPatterns: ['mySecretField'],
+ *   partialRedaction: true,
+ *   revealLastChars: 4,
+ * });
+ * ```
+ */
+export declare class Redactor {
+    private config;
+    private fieldPatternSet;
+    constructor(config?: Partial<RedactionConfig>);
+    /**
+     * Update redaction configuration.
+     * @param config - Partial configuration to merge
+     */
+    configure(config: Partial<RedactionConfig>): void;
+    /**
+     * Add custom field patterns to redact.
+     * @param patterns - Field name patterns to add
+     */
+    addFieldPatterns(...patterns: Array<string>): void;
+    /**
+     * Add custom value patterns to redact.
+     * @param patterns - Regex patterns to add
+     */
+    addValuePatterns(...patterns: Array<RedactionPattern>): void;
+    /**
+     * Add fields to whitelist (never redact).
+     * @param fields - Field names to whitelist
+     */
+    addWhitelist(...fields: Array<string>): void;
+    /**
+     * Redact sensitive data from an object or value.
+     * Creates a deep copy with sensitive data replaced.
+     *
+     * @param value - The value to redact
+     * @returns A new value with sensitive data redacted
+     */
+    redact<T>(value: T): T;
+    /**
+     * Redact a string value using regex patterns.
+     * @param value - String to redact
+     * @returns Redacted string
+     */
+    redactString(value: string): string;
+    /**
+     * Check if a field name should be redacted.
+     * @param fieldName - Field name to check
+     * @returns true if field should be redacted
+     */
+    shouldRedactField(fieldName: string): boolean;
+    /**
+     * Internal recursive redaction method.
+     */
+    private redactValue;
+    /**
+     * Create a redacted value string with optional partial reveal.
+     */
+    private createRedactedValue;
+    /**
+     * Apply a regex pattern to redact values in a string.
+     */
+    private applyValuePattern;
+}
+/**
+ * Get or create the global redactor instance.
+ */
+export declare function getGlobalRedactor(): Redactor;
+/**
+ * Configure the global redactor.
+ * @param config - Configuration to apply
+ */
+export declare function configureGlobalRedactor(config: Partial<RedactionConfig>): void;
+/**
+ * Redact sensitive data using the global redactor.
+ * Convenience function for quick redaction.
+ * @param value - Value to redact
+ * @returns Redacted value
+ */
+export declare function redact<T>(value: T): T;

package/lib/esm/types/provider/logger/logger.suggestions.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file logger.suggestions.ts
+ * @description Smart error suggestions system
+ * @module @expressots/core/provider/logger
+ *
+ * Features:
+ * - Route suggestions for 404 errors
+ * - Common error hints (database, port, module, auth, validation)
+ * - String similarity matching for route suggestions
+ * - Configurable suggestion display
+ */
+/**
+ * Route information for suggestions.
+ */
+export interface RouteInfo {
+    method: string;
+    path: string;
+    fullPath?: string;
+}
+/**
+ * Route suggestion result.
+ */
+export interface RouteSuggestion {
+    route: RouteInfo;
+    similarity: number;
+    reason?: string;
+}
+/**
+ * Error suggestion result.
+ */
+export interface ErrorSuggestion {
+    type: "route" | "hint" | "common";
+    title: string;
+    message: string;
+    actions?: Array<string>;
+    routes?: Array<RouteSuggestion>;
+}
+/**
+ * Configuration for error suggestions.
+ * @public API
+ */
+export interface SuggestionsConfig {
+    /** Enable error suggestions (default: true in dev, false in prod) */
+    enabled: boolean;
+    /** Show route suggestions for 404 errors (default: true) */
+    showRouteSuggestions: boolean;
+    /** Show common error hints (default: true) */
+    showErrorHints: boolean;
+    /** Maximum number of route suggestions to show (default: 3) */
+    maxRouteSuggestions: number;
+    /** Minimum similarity threshold for route suggestions (0-1, default: 0.3) */
+    minSimilarityThreshold: number;
+    /** Show routes with same prefix (default: true) */
+    showPrefixMatches: boolean;
+}
+/**
+ * Default suggestions configuration.
+ * @returns Default config
+ * @public API
+ */
+export declare function getDefaultSuggestionsConfig(): SuggestionsConfig;
+/**
+ * Route registry for tracking all registered routes.
+ * Used by the suggestion engine to provide route suggestions.
+ */
+declare class RouteRegistry {
+    private routes;
+    /**
+     * Register a route.
+     */
+    register(method: string, path: string, fullPath?: string): void;
+    /**
+     * Get all registered routes.
+     */
+    getAll(): Array<RouteInfo>;
+    /**
+     * Get routes by method.
+     */
+    getByMethod(method: string): Array<RouteInfo>;
+    /**
+     * Clear all routes.
+     */
+    clear(): void;
+    /**
+     * Get routes matching a prefix.
+     */
+    getByPrefix(prefix: string): Array<RouteInfo>;
+}
+/**
+ * Get the global route registry.
+ * @returns Route registry instance
+ * @public API
+ */
+export declare function getRouteRegistry(): RouteRegistry;
+/**
+ * Suggest similar routes for a 404 error.
+ * @param requestedPath - The path that was requested (404)
+ * @param requestedMethod - The HTTP method used
+ * @param config - Suggestions configuration
+ * @returns Array of route suggestions
+ * @public API
+ */
+export declare function suggestRoutes(requestedPath: string, requestedMethod?: string, config?: SuggestionsConfig): Array<RouteSuggestion>;
+/**
+ * Get common error hints based on error message and type.
+ * @param error - The error object
+ * @param context - Additional context (request path, method, etc.)
+ * @param config - Optional suggestions configuration (uses default if not provided)
+ * @returns Array of error hints
+ * @public API
+ */
+export declare function getErrorHints(error: Error, context?: {
+    path?: string;
+    method?: string;
+    statusCode?: number;
+}, config?: Partial<SuggestionsConfig>): Array<ErrorSuggestion>;
+/**
+ * Format suggestions for display in logs.
+ * @param suggestions - Array of error suggestions
+ * @returns Formatted string
+ * @public API
+ */
+export declare function formatSuggestions(suggestions: Array<ErrorSuggestion>): string;
+export {};

package/lib/esm/types/provider/logger/transports/console.transport.d.ts

@@ -0,0 +1,56 @@
+import { ILogTransport } from "./transport.interface.js";
+import { LogEntry } from "../utils/log-entry.js";
+import { LogLevel } from "../utils/log-levels.js";
+import { Redactor } from "../logger.redaction.js";
+/**
+ * Console transport for logging to stdout/stderr.
+ * @public API
+ */
+export declare class ConsoleTransport implements ILogTransport {
+    readonly name = "Console";
+    level: LogLevel;
+    enabled: boolean;
+    private readonly structured;
+    private readonly colors;
+    private readonly pretty;
+    private readonly redact;
+    private readonly redactor?;
+    /**
+     * Create a console transport.
+     * @param options - Transport options
+     */
+    constructor(options?: {
+        level?: LogLevel;
+        enabled?: boolean;
+        structured?: boolean;
+        colors?: boolean;
+        pretty?: boolean;
+        /** Enable automatic sensitive data redaction (default: true for production) */
+        redact?: boolean;
+        /** Custom redactor instance */
+        redactor?: Redactor;
+    });
+    /**
+     * Create a console transport optimized for development.
+     *
+     * Colors are auto-detected: they're emitted when stdout is a TTY
+     * (your terminal) and disabled when stdout is piped or captured by
+     * a cloud log collector (Azure App Service, AWS CloudWatch, Heroku,
+     * Docker, Kubernetes, etc.). Respects the standard `NO_COLOR` and
+     * `FORCE_COLOR` environment variables.
+     *
+     * @param redact - Enable redaction (default: false for development)
+     * @returns ConsoleTransport configured for development
+     * @public API
+     */
+    static forDevelopment(redact?: boolean): ConsoleTransport;
+    /**
+     * Create a console transport optimized for production.
+     * @param redact - Enable redaction (default: true for production)
+     * @returns ConsoleTransport configured for production
+     * @public API
+     */
+    static forProduction(redact?: boolean): ConsoleTransport;
+    log(entry: LogEntry): void;
+    flush(): Promise<void>;
+}

package/lib/esm/types/provider/logger/transports/file.transport.d.ts

@@ -0,0 +1,87 @@
+import { ILogTransport } from "./transport.interface.js";
+import { LogEntry } from "../utils/log-entry.js";
+import { LogLevel } from "../utils/log-levels.js";
+/**
+ * File transport options with advanced features.
+ * @public API
+ */
+export interface FileTransportOptions {
+    /** Directory to store log files */
+    directory?: string;
+    /** Filename pattern (supports %DATE% placeholder) */
+    filename?: string;
+    /** Minimum log level */
+    level?: LogLevel;
+    /** Whether transport is enabled */
+    enabled?: boolean;
+    /** Enable gzip compression for rotated files */
+    compress?: boolean;
+    /** Maximum file size in bytes before rotation (default: unlimited) */
+    maxSize?: number;
+    /** Maximum file age in milliseconds before deletion (default: unlimited) */
+    maxAge?: number;
+    /** Maximum number of files to keep (default: unlimited) */
+    maxFiles?: number;
+}
+/**
+ * File transport for logging to files with daily rotation and advanced features.
+ * @public API
+ */
+export declare class FileTransport implements ILogTransport {
+    readonly name = "File";
+    level: LogLevel;
+    enabled: boolean;
+    private readonly directory;
+    private readonly filenamePattern;
+    private readonly compress;
+    private readonly maxSize;
+    private readonly maxAge;
+    private readonly maxFiles;
+    private currentFilename;
+    private currentFileSize;
+    private cleanupInterval;
+    constructor(options?: FileTransportOptions);
+    /**
+     * Create a file transport with daily rotation.
+     * @param options - Transport options
+     * @returns FileTransport configured for daily rotation
+     * @public API
+     */
+    static daily(options?: Omit<FileTransportOptions, "filename">): FileTransport;
+    /**
+     * Create a file transport with compression enabled.
+     * @param options - Transport options
+     * @returns FileTransport with compression enabled
+     * @public API
+     */
+    static withCompression(options?: Omit<FileTransportOptions, "compress">): FileTransport;
+    /**
+     * Create a file transport with size-based rotation.
+     * @param maxSize - Maximum file size in bytes
+     * @param options - Transport options
+     * @returns FileTransport with size-based rotation
+     * @public API
+     */
+    static withMaxSize(maxSize: number, options?: Omit<FileTransportOptions, "maxSize">): FileTransport;
+    /**
+     * Create a file transport with retention policy.
+     * @param maxAge - Maximum file age in milliseconds
+     * @param maxFiles - Maximum number of files to keep
+     * @param options - Transport options
+     * @returns FileTransport with retention policy
+     * @public API
+     */
+    static withRetention(maxAge: number, maxFiles?: number, options?: Omit<FileTransportOptions, "maxAge" | "maxFiles">): FileTransport;
+    log(entry: LogEntry): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private getFilename;
+    private ensureDirectory;
+    private getFileSize;
+    private shouldRotate;
+    private rotateFile;
+    private getRotatedFilename;
+    private compressFile;
+    private startCleanupInterval;
+    private cleanupOldFiles;
+}