@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/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/cjs/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/cjs/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/cjs/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;
+}

package/lib/cjs/types/provider/logger/transports/http-server.d.ts

@@ -0,0 +1,88 @@
+import { LogEntry } from "../utils/log-entry.js";
+import { LogLevel } from "../utils/log-levels.js";
+/**
+ * Log query options for HTTP server.
+ * @public API
+ * @deprecated Use LogQueryOptions from logger.query instead
+ */
+export interface HttpLogQueryOptions {
+    /** Filter by log level */
+    level?: LogLevel;
+    /** Filter by context */
+    context?: string;
+    /** Start time (timestamp) */
+    startTime?: number;
+    /** End time (timestamp) */
+    endTime?: number;
+    /** Search term (searches message and data) */
+    search?: string;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Log statistics.
+ * @public API
+ */
+export interface LogStats {
+    total: number;
+    byLevel: Record<string, number>;
+    byContext: Record<string, number>;
+    oldest: number | null;
+    newest: number | null;
+}
+/**
+ * HTTP server configuration for log querying and streaming.
+ * @public API
+ */
+export interface HttpServerConfig {
+    /** Port to run the server on (default: 3001) */
+    port?: number;
+    /** Maximum number of logs to keep in memory (default: 1000) */
+    maxLogs?: number;
+    /** Enable WebSocket streaming (default: true) */
+    enableWebSocket?: boolean;
+    /** Enable REST API (default: true) */
+    enableRestApi?: boolean;
+    /** API path prefix (default: /api/logs) */
+    apiPath?: string;
+}
+/**
+ * HTTP server for log querying and streaming.
+ * This is a basic implementation that can be extended.
+ * @public API
+ */
+export declare class HttpLogServer {
+    private buffer;
+    private config;
+    private server;
+    constructor(config?: HttpServerConfig);
+    /**
+     * Add a log entry to the buffer.
+     * @param entry - Log entry to add
+     */
+    addLog(entry: LogEntry): void;
+    /**
+     * Query logs.
+     * @param options - Query options
+     * @returns Array of log entries
+     */
+    queryLogs(options: HttpLogQueryOptions): Array<LogEntry>;
+    /**
+     * Get log statistics.
+     * @returns Log statistics
+     */
+    getStats(): LogStats;
+    /**
+     * Clear all logs.
+     */
+    clearLogs(): void;
+    /**
+     * Start the HTTP server.
+     * Note: This is a placeholder - actual server implementation would require Express or similar.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server.
+     */
+    stop(): Promise<void>;
+}

package/lib/cjs/types/provider/logger/transports/http.transport.d.ts

@@ -0,0 +1,74 @@
+import { ILogTransport } from "./transport.interface.js";
+import { LogEntry } from "../utils/log-entry.js";
+import { LogLevel } from "../utils/log-levels.js";
+/**
+ * HTTP transport options.
+ * @public API
+ */
+export interface HttpTransportOptions {
+    /** HTTP endpoint URL to send logs to */
+    endpoint: string;
+    /** Minimum log level */
+    level?: LogLevel;
+    /** Whether transport is enabled */
+    enabled?: boolean;
+    /** Number of logs to batch before sending (default: 10) */
+    batchSize?: number;
+    /** Maximum time to wait before flushing batch in milliseconds (default: 5000) */
+    flushInterval?: number;
+    /** Maximum number of retries on failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** HTTP method to use (default: POST) */
+    method?: "POST" | "PUT" | "PATCH";
+    /** Timeout for HTTP requests in milliseconds (default: 10000) */
+    timeout?: number;
+}
+/**
+ * HTTP transport for sending logs to remote endpoints with batching and retry.
+ * @public API
+ */
+export declare class HttpTransport implements ILogTransport {
+    readonly name = "Http";
+    level: LogLevel;
+    enabled: boolean;
+    private readonly endpoint;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly headers;
+    private readonly method;
+    private readonly timeout;
+    private buffer;
+    private flushTimer;
+    private isFlushing;
+    constructor(options: HttpTransportOptions);
+    /**
+     * Create an HTTP transport with default settings.
+     * @param endpoint - HTTP endpoint URL
+     * @param options - Additional options
+     * @returns HttpTransport instance
+     * @public API
+     */
+    static create(endpoint: string, options?: Omit<HttpTransportOptions, "endpoint">): HttpTransport;
+    /**
+     * Create an HTTP transport with batching enabled.
+     * @param endpoint - HTTP endpoint URL
+     * @param batchSize - Number of logs per batch
+     * @param options - Additional options
+     * @returns HttpTransport instance
+     * @public API
+     */
+    static withBatching(endpoint: string, batchSize?: number, options?: Omit<HttpTransportOptions, "endpoint" | "batchSize">): HttpTransport;
+    log(entry: LogEntry): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private sendBatch;
+    private delay;
+}

package/lib/cjs/types/provider/logger/transports/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./transport.interface.js";
+export * from "./console.transport.js";
+export * from "./file.transport.js";
+export * from "./http.transport.js";
+export * from "./http-server.js";

package/lib/cjs/types/provider/logger/transports/transport.interface.d.ts

@@ -0,0 +1,31 @@
+import { LogEntry } from "../utils/log-entry.js";
+import { LogLevel } from "../utils/log-levels.js";
+/**
+ * Log transport interface for pluggable log destinations.
+ * @public API
+ */
+export interface ILogTransport {
+    /** Transport name for identification */
+    readonly name: string;
+    /** Minimum log level this transport accepts */
+    level: LogLevel;
+    /** Whether this transport is enabled */
+    enabled: boolean;
+    /**
+     * Log an entry.
+     * @param entry - The log entry to transport
+     * @returns Promise if async, void if sync
+     */
+    log(entry: LogEntry): void | Promise<void>;
+    /**
+     * Flush any buffered logs (optional).
+     * Useful for transports that batch logs.
+     * @returns Promise that resolves when flush is complete
+     */
+    flush?(): Promise<void>;
+    /**
+     * Close the transport and cleanup resources (optional).
+     * @returns Promise that resolves when close is complete
+     */
+    close?(): Promise<void>;
+}

package/lib/cjs/types/provider/logger/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./log-levels.js";
+export * from "./log-entry.js";