@loglayer/transport-pretty-terminal 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+import { LoggerlessTransportConfig, LoggerlessTransport, LogLayerTransportParams } from '@loglayer/transport';
+import { ChalkInstance } from 'chalk';
+import * as chalk from 'chalk';
+export { chalk };
+
+/**
+ * Represents a single log entry in the storage system.
+ * Each entry contains metadata and the actual log content.
+ */
+interface LogEntry {
+    /** Unique identifier for the log entry */
+    id: string;
+    /** Unix timestamp in milliseconds when the log was created */
+    timestamp: number;
+    /** Log level (trace, debug, info, warn, error, fatal) */
+    level: string;
+    /** Main log message content */
+    message: string;
+    /** Optional structured data associated with the log, stored as JSON string */
+    data: string | null;
+}
+/**
+ * Configuration for log level colors.
+ * Each log level can have its own chalk styling.
+ */
+interface ColorConfig {
+    /** Style for trace level logs - lowest severity */
+    trace?: ChalkInstance;
+    /** Style for debug level logs */
+    debug?: ChalkInstance;
+    /** Style for info level logs - normal operation */
+    info?: ChalkInstance;
+    /** Style for warning level logs */
+    warn?: ChalkInstance;
+    /** Style for error level logs */
+    error?: ChalkInstance;
+    /** Style for fatal level logs - highest severity */
+    fatal?: ChalkInstance;
+}
+/**
+ * Base configuration for log view styling.
+ * Defines colors and styles for different log elements.
+ */
+interface ViewConfig {
+    /** Color configuration for different log levels */
+    colors?: ColorConfig;
+    /** Style for log entry IDs */
+    logIdColor?: ChalkInstance;
+    /** Style for data values in structured data */
+    dataValueColor?: ChalkInstance;
+    /** Style for data keys in structured data */
+    dataKeyColor?: ChalkInstance;
+    /** Style for selection indicators in interactive mode */
+    selectorColor?: ChalkInstance;
+}
+/**
+ * Extended view configuration for detailed/interactive mode.
+ * Includes additional styling options for the detailed view UI.
+ */
+interface DetailedViewConfig extends ViewConfig {
+    /** Style for section headers in detailed view */
+    headerColor?: ChalkInstance;
+    /** Style for field labels in detailed view */
+    labelColor?: ChalkInstance;
+    /** Style for visual separators between sections */
+    separatorColor?: ChalkInstance;
+    /** Configuration for JSON data formatting colors */
+    jsonColors?: {
+        /** Style for object property names */
+        keysColor?: ChalkInstance;
+        /** Style for array bullets */
+        dashColor?: ChalkInstance;
+        /** Default style for numbers */
+        numberColor?: ChalkInstance;
+        /** Style for single-line strings */
+        stringColor?: ChalkInstance;
+        /** Style for multi-line strings */
+        multilineStringColor?: ChalkInstance;
+        /** Style for positive numbers */
+        positiveNumberColor?: ChalkInstance;
+        /** Style for negative numbers */
+        negativeNumberColor?: ChalkInstance;
+        /** Style for boolean values */
+        booleanColor?: ChalkInstance;
+        /** Style for null and undefined values */
+        nullUndefinedColor?: ChalkInstance;
+        /** Style for date objects */
+        dateColor?: ChalkInstance;
+    };
+}
+/**
+ * Theme configuration for the pretty terminal transport.
+ * Defines styling for both simple and detailed view modes.
+ */
+interface PrettyTerminalTheme {
+    /** Styling configuration for real-time log output mode */
+    simpleView: ViewConfig;
+    /** Styling configuration for interactive/detailed view mode */
+    detailedView: DetailedViewConfig;
+}
+/**
+ * Main configuration interface for PrettyTerminalTransport.
+ * Extends the base transport configuration with pretty terminal specific options.
+ */
+interface PrettyTerminalConfig extends LoggerlessTransportConfig {
+    /** Maximum depth for inline data display before collapsing */
+    maxInlineDepth?: number;
+    /** Maximum length for inline data display before truncating */
+    maxInlineLength?: number;
+    /** Custom theme configuration for log display */
+    theme?: PrettyTerminalTheme;
+    /** Path to SQLite file for persistent storage. If not provided, uses in-memory database */
+    logFile?: string;
+    /** Whether the transport is enabled. If false, all operations will no-op. Defaults to true */
+    enabled?: boolean;
+}
+
+/**
+ * A transport for LogLayer that provides a pretty terminal output with interactive features.
+ * This transport implements an interactive terminal UI for viewing and filtering logs.
+ *
+ * Features:
+ * - Real-time log display with color-coded levels
+ * - Interactive selection mode for browsing logs
+ * - Detailed view for inspecting individual log entries
+ * - Search/filter functionality
+ * - JSON data pretty printing
+ * - Configurable themes and colors
+ *
+ * The transport uses a singleton pattern to ensure only one instance exists,
+ * as it manages terminal input and output which cannot be shared.
+ */
+
+/**
+ * Main transport class that handles pretty terminal output and interactive features.
+ * This class coordinates between different components:
+ * - LogStorage: Handles persistence of logs in SQLite
+ * - LogRenderer: Manages all rendering and formatting
+ * - UIManager: Handles user interaction and view state
+ *
+ * The transport supports two main view modes:
+ * 1. Simple View: Real-time log output with basic formatting
+ * 2. Interactive View: Full-screen mode with navigation and filtering
+ *
+ * Usage:
+ * ```typescript
+ * const transport = PrettyTerminalTransport.getInstance({
+ *   maxInlineDepth: 4,
+ *   maxInlineLength: 120,
+ *   theme: customTheme
+ * });
+ * ```
+ */
+declare class PrettyTerminalTransport extends LoggerlessTransport {
+    /** Singleton instance of the transport */
+    private static instance;
+    /** Handles all rendering and formatting of logs */
+    private renderer;
+    /** Manages log persistence in SQLite database */
+    private storage;
+    /** Manages user interaction and view state */
+    private uiManager;
+    /** Configuration options */
+    private config;
+    /**
+     * Creates a new PrettyTerminalTransport instance.
+     * This is a singleton class - only one instance can exist at a time.
+     * Use getInstance() instead of constructor directly.
+     *
+     * @param config - Configuration options for the transport
+     * @throws Error if attempting to create multiple instances
+     */
+    constructor(config?: PrettyTerminalConfig);
+    /**
+     * Gets or creates the singleton instance of PrettyTerminalTransport.
+     * This is the recommended way to obtain a transport instance.
+     *
+     * @param config - Configuration options for the transport
+     * @returns The singleton instance of PrettyTerminalTransport
+     */
+    static getInstance(config?: PrettyTerminalConfig): PrettyTerminalTransport;
+    /**
+     * Generates a random ID for each log entry.
+     * Uses base36 encoding for compact, readable IDs.
+     *
+     * @returns A 6-character string ID
+     * @example
+     * "a1b2c3" // Example generated ID
+     */
+    private generateId;
+    /**
+     * Main transport method that receives logs from LogLayer.
+     * This method is called for each log event and handles:
+     * - Generating a unique ID for the log
+     * - Converting the log data to a storable format
+     * - Storing the log in the database
+     * - Rendering the log if not in selection mode
+     *
+     * @param logLevel - The severity level of the log
+     * @param messages - Array of message strings to be joined
+     * @param data - Additional structured data to be logged
+     * @param hasData - Whether the log includes additional data
+     * @returns The original messages array
+     */
+    shipToLogger({ logLevel, messages, data, hasData }: LogLayerTransportParams): any[];
+}
+
+/**
+ * Moonlight - A dark theme with cool blue tones
+ * Inspired by moonlit nights and modern IDEs
+ *
+ * Color Palette:
+ * - Primary: Cool blues and soft greens
+ * - Accents: Warm yellows and soft reds
+ * - Background: Assumes dark terminal (black or very dark grey)
+ *
+ * Best used with:
+ * - Dark terminal themes
+ * - Night-time coding sessions
+ * - Environments where eye strain is a concern
+ */
+declare const moonlight: PrettyTerminalTheme;
+/**
+ * Sunlight - A light theme with warm tones
+ * Inspired by daylight reading and paper documentation
+ *
+ * Color Palette:
+ * - Primary: Deep, rich colors that contrast well with white
+ * - Accents: Earth tones and deep jewel tones
+ * - Background: Assumes light terminal (white or very light grey)
+ *
+ * Best used with:
+ * - Light terminal themes
+ * - Daytime coding sessions
+ * - High-glare environments
+ * - Printed documentation
+ */
+declare const sunlight: PrettyTerminalTheme;
+/**
+ * Neon - A dark theme with vibrant cyberpunk colors
+ * Inspired by neon-lit cityscapes and retro-futuristic aesthetics
+ *
+ * Color Palette:
+ * - Primary: Electric blues and hot pinks
+ * - Accents: Bright purples and cyber greens
+ * - Background: Assumes dark terminal (black or very dark grey)
+ *
+ * Best used with:
+ * - Dark terminal themes
+ * - High-contrast preferences
+ * - Modern, tech-focused applications
+ */
+declare const neon: PrettyTerminalTheme;
+/**
+ * Nature - A light theme with organic, earthy colors
+ * Inspired by forest landscapes and natural elements
+ *
+ * Color Palette:
+ * - Primary: Deep forest greens and rich browns
+ * - Accents: Autumn reds and golden yellows
+ * - Background: Assumes light terminal (white or very light grey)
+ *
+ * Best used with:
+ * - Light terminal themes
+ * - Nature-inspired interfaces
+ * - Applications focusing on readability
+ */
+declare const nature: PrettyTerminalTheme;
+/**
+ * Pastel - A soft, calming theme with gentle colors
+ * Inspired by watercolor paintings and cotton candy skies
+ *
+ * Color Palette:
+ * - Primary: Soft pinks and lavenders
+ * - Accents: Mint greens and baby blues
+ * - Background: Assumes dark terminal (black or very dark grey)
+ *
+ * Best used with:
+ * - Dark terminal themes
+ * - Long coding sessions where eye comfort is priority
+ * - Environments where a gentler aesthetic is preferred
+ * - Applications focusing on reduced visual stress
+ */
+declare const pastel: PrettyTerminalTheme;
+
+declare function getPrettyTerminal(config?: PrettyTerminalConfig): PrettyTerminalTransport;
+
+export { type ColorConfig, type DetailedViewConfig, type LogEntry, type PrettyTerminalConfig, type PrettyTerminalTheme, PrettyTerminalTransport, type ViewConfig, getPrettyTerminal, moonlight, nature, neon, pastel, sunlight };