devlog-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,796 @@
+/**
+ * DevLogger - Browser-based Dev Logger with UI
+ *
+ * A lightweight, framework-agnostic dev logger with a beautiful debug UI.
+ * Zero dependencies, zero production overhead (via tree-shaking).
+ *
+ * @example
+ * ```typescript
+ * import { logger, DevLoggerUI } from 'devlogger';
+ *
+ * DevLoggerUI.init();
+ * logger.info('App started');
+ * logger.debug('Config loaded', { theme: 'dark' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Clear all persisted data
+ */
+declare function clear(): void;
+
+/**
+ * Compute diff between two objects
+ */
+export declare function computeDiff(oldObj: unknown, newObj: unknown, path?: string, includeUnchanged?: boolean): DiffEntry[];
+
+/**
+ * Context-bound logger - logs with specific context attached
+ */
+export declare class ContextLogger {
+    private logger;
+    private context;
+    constructor(logger: LoggerCore, context: LogContext);
+    debug(message: string, ...data: unknown[]): void;
+    info(message: string, ...data: unknown[]): void;
+    warn(message: string, ...data: unknown[]): void;
+    error(message: string, ...data: unknown[]): void;
+    /** Create a span with this context */
+    span(name: string, extraContext?: LogContext): LogSpan;
+    /** Create a new context logger with merged context */
+    withContext(extraContext: LogContext): ContextLogger;
+}
+
+/**
+ * Create a full diff result with summary
+ */
+export declare function createDiffResult(oldObj: unknown, newObj: unknown): DiffResult;
+
+/**
+ * Create a timeline instance
+ */
+export declare function createTimeline(config: TimelineConfig): Timeline;
+
+/**
+ * DevLogger UI Public API
+ */
+export declare const DevLoggerUI: {
+    /**
+     * Initialize the overlay UI
+     */
+    init(): void;
+    /**
+     * Open the overlay panel
+     */
+    open(): void;
+    /**
+     * Close the overlay panel
+     */
+    close(): void;
+    /**
+     * Toggle the overlay panel
+     */
+    toggle(): void;
+    /**
+     * Open logs in a separate window
+     */
+    popout(): void;
+    /**
+     * Close the pop-out window
+     */
+    closePopout(): void;
+    /**
+     * Check if pop-out window is open
+     */
+    isPopoutOpen(): boolean;
+    /**
+     * Set filter state
+     */
+    setFilter(filter: Partial<FilterState>): void;
+    /**
+     * Get current filter state
+     */
+    getFilter(): FilterState;
+    /**
+     * Clear all filters
+     */
+    clearFilter(): void;
+    /**
+     * Destroy the UI and clean up
+     */
+    destroy(): void;
+    /**
+     * Check if the UI is currently visible
+     */
+    isVisible(): boolean;
+    /**
+     * Check if the UI has been initialized
+     */
+    isInitialized(): boolean;
+};
+
+/**
+ * Diff change type
+ */
+export declare type DiffChangeType = 'added' | 'removed' | 'changed' | 'unchanged';
+
+/**
+ * A single diff entry for object comparison
+ */
+export declare interface DiffEntry {
+    /** Path to the property (e.g., "user.profile.name") */
+    path: string;
+    /** Type of change */
+    type: DiffChangeType;
+    /** Old value (for removed/changed) */
+    oldValue?: unknown;
+    /** New value (for added/changed) */
+    newValue?: unknown;
+}
+
+/**
+ * Diff result for object comparison
+ */
+export declare interface DiffResult {
+    /** All changes found */
+    changes: DiffEntry[];
+    /** Summary counts */
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+}
+
+/**
+ * Disable persistence
+ */
+declare function disable(): void;
+
+/**
+ * Enable persistence
+ */
+declare function enable(options?: PersistenceConfig): void;
+
+/**
+ * Error Capture Public API
+ */
+export declare const ErrorCapture: {
+    /**
+     * Install global error handlers
+     *
+     * @example
+     * ```typescript
+     * // Install with defaults
+     * ErrorCapture.install();
+     *
+     * // Install with custom config
+     * ErrorCapture.install({
+     *   captureErrors: true,
+     *   captureRejections: true,
+     *   errorPrefix: '[ERROR]',
+     * });
+     * ```
+     */
+    install: typeof install;
+    /**
+     * Uninstall global error handlers and restore originals
+     */
+    uninstall: typeof uninstall;
+    /**
+     * Check if error capture is currently active
+     */
+    isActive: typeof isActive;
+    /**
+     * Get current configuration
+     */
+    getConfig: typeof getConfig;
+};
+
+/**
+ * Global Error Capture Module
+ *
+ * Automatically captures uncaught errors and unhandled promise rejections
+ * and logs them through the DevLogger system.
+ *
+ * Features:
+ * - window.onerror for synchronous errors
+ * - window.onunhandledrejection for promise rejections
+ * - Preserves existing handlers (chaining)
+ * - Can be enabled/disabled at runtime
+ * - Zero-throw policy maintained
+ */
+/** Configuration for error capture */
+export declare interface ErrorCaptureConfig {
+    /** Capture synchronous errors via window.onerror */
+    captureErrors?: boolean;
+    /** Capture unhandled promise rejections */
+    captureRejections?: boolean;
+    /** Prefix for error messages */
+    errorPrefix?: string;
+    /** Prefix for rejection messages */
+    rejectionPrefix?: string;
+}
+
+/**
+ * Export format options
+ */
+export declare interface ExportOptions {
+    /** Export format: 'json' or 'text' */
+    format?: 'json' | 'text';
+    /** Include only logs from the last N milliseconds */
+    lastMs?: number;
+    /** Include only logs matching these levels */
+    levels?: LogLevel[];
+    /** Include only logs matching this search */
+    search?: string;
+    /** Pretty print JSON (default: true) */
+    pretty?: boolean;
+}
+
+/**
+ * Filter state interface
+ */
+export declare interface FilterState {
+    /** Active log levels (empty = all) */
+    levels: Set<LogLevel>;
+    /** Text search query */
+    search: string;
+    /** File filter (partial match) */
+    file: string;
+}
+
+/**
+ * Format a value for display (handles special types)
+ */
+export declare function formatValue(value: unknown): string;
+
+/**
+ * Get current configuration
+ */
+declare function getConfig(): Readonly<Required<ErrorCaptureConfig>>;
+
+/**
+ * Get current configuration
+ */
+declare function getConfig_2(): Readonly<Required<PersistenceConfig>>;
+
+/**
+ * Get persisted logs (for rehydration)
+ */
+declare function getPersistedLogs(): LogEvent[];
+
+/**
+ * Check if last session crashed
+ */
+declare function hadCrash(): boolean;
+
+/**
+ * Check if there are any changes
+ */
+export declare function hasChanges(diff: DiffResult): boolean;
+
+/**
+ * Install global error handlers
+ */
+declare function install(options?: ErrorCaptureConfig): void;
+
+/**
+ * Check if error capture is installed
+ */
+declare function isActive(): boolean;
+
+/**
+ * Check if persistence is enabled
+ */
+declare function isActive_2(): boolean;
+
+/**
+ * Context/tags for log correlation
+ */
+export declare type LogContext = Record<string, string | number | boolean>;
+
+/**
+ * A single log event with all metadata
+ */
+export declare interface LogEvent {
+    /** Unique identifier for this log entry */
+    id: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Log severity level */
+    level: LogLevel;
+    /** Primary log message */
+    message: string;
+    /** Additional data passed to the log call */
+    data: unknown[];
+    /** Source code location */
+    source: Source;
+    /** Browser session identifier */
+    sessionId: string;
+    /** Optional context/tags for filtering */
+    context?: LogContext;
+    /** Span ID if this log belongs to a span */
+    spanId?: string;
+}
+
+export declare const logger: LoggerCore;
+
+/**
+ * Logger configuration options
+ */
+export declare interface LoggerConfig {
+    /** Maximum number of logs to keep in memory (default: 1000) */
+    maxLogs?: number;
+    /** Persist logs to sessionStorage (default: false) */
+    persist?: boolean;
+    /** Minimum log level to capture (default: 'debug') */
+    minLevel?: LogLevel;
+    /** Enable/disable logging entirely (default: true) */
+    enabled?: boolean;
+}
+
+/**
+ * Core Logger Class
+ *
+ * Lifecycle of a log:
+ * 1. Log is created (info/warn/error/debug called)
+ * 2. Log is enriched (timestamp, source, sessionId added)
+ * 3. Log is stored (in-memory, with rotation)
+ * 4. Log is distributed (subscribers notified)
+ * 5. Log is displayed (by UI subscribers)
+ */
+declare class LoggerCore {
+    private logs;
+    private spans;
+    private subscribers;
+    private spanSubscribers;
+    private config;
+    private sessionId;
+    private globalContext;
+    constructor();
+    /**
+     * Core logging method - all public methods delegate to this
+     */
+    private log;
+    /**
+     * Log with context (used by ContextLogger)
+     */
+    private logWithContext;
+    /**
+     * Log with span (used by LogSpan)
+     */
+    private logWithSpan;
+    /**
+     * Notify span subscribers
+     */
+    private notifySpan;
+    /**
+     * Safely clone data to prevent mutations and handle special cases
+     */
+    private safeCloneData;
+    /**
+     * Deep clone with circular reference handling
+     */
+    private safeClone;
+    /**
+     * Store log with FIFO rotation
+     */
+    private store;
+    /**
+     * Notify all subscribers of new log
+     */
+    private notify;
+    /**
+     * Log an info message
+     */
+    info(message: string, ...data: unknown[]): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, ...data: unknown[]): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, ...data: unknown[]): void;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, ...data: unknown[]): void;
+    /**
+     * Update logger configuration
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Clear all stored logs and spans
+     */
+    clear(): void;
+    /**
+     * Import logs (used for rehydration from persistence)
+     * Imported logs are added at the beginning, preserving order
+     */
+    importLogs(logs: LogEvent[]): void;
+    /**
+     * Get all stored logs (readonly)
+     */
+    getLogs(): readonly LogEvent[];
+    /**
+     * Subscribe to new log events
+     */
+    subscribe(fn: LogSubscriber): Unsubscribe;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<Required<LoggerConfig>>;
+    /**
+     * Check if logging is currently enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Create a new span for grouping related logs
+     */
+    span(name: string, context?: LogContext): LogSpan;
+    /**
+     * Get all spans
+     */
+    getSpans(): readonly SpanEvent[];
+    /**
+     * Get a specific span by ID
+     */
+    getSpan(spanId: string): SpanEvent | undefined;
+    /**
+     * Get logs belonging to a specific span
+     */
+    getSpanLogs(spanId: string): readonly LogEvent[];
+    /**
+     * Subscribe to span events
+     */
+    subscribeSpans(fn: SpanSubscriber): Unsubscribe;
+    /**
+     * Set global context that will be attached to all logs
+     */
+    setGlobalContext(context: LogContext): void;
+    /**
+     * Update global context (merge with existing)
+     */
+    updateGlobalContext(context: LogContext): void;
+    /**
+     * Get current global context
+     */
+    getGlobalContext(): Readonly<LogContext>;
+    /**
+     * Clear global context
+     */
+    clearGlobalContext(): void;
+    /**
+     * Create a context-bound logger
+     */
+    withContext(context: LogContext): ContextLogger;
+    /**
+     * Export logs in specified format
+     */
+    exportLogs(options?: ExportOptions): string;
+    /**
+     * Format logs as human-readable text
+     */
+    private formatLogsAsText;
+    /**
+     * Copy logs to clipboard
+     */
+    copyLogs(options?: ExportOptions): Promise<boolean>;
+    /**
+     * Log a visual diff between two objects
+     */
+    diff(message: string, oldObj: unknown, newObj: unknown, level?: LogLevel): DiffResult;
+    /**
+     * Compute diff without logging (utility method)
+     */
+    computeDiff(oldObj: unknown, newObj: unknown): DiffResult;
+}
+
+/**
+ * Core type definitions for DevLogger
+ *
+ * These types define the contract for all logging operations.
+ * They are stable and should not change without major version bump.
+ */
+/**
+ * Available log levels in order of severity
+ */
+export declare type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Log Persistence Public API
+ */
+export declare const LogPersistence: {
+    /**
+     * Enable log persistence
+     *
+     * @example
+     * ```typescript
+     * LogPersistence.enable();
+     *
+     * // With options
+     * LogPersistence.enable({
+     *   storage: 'session',
+     *   maxPersisted: 500,
+     *   debounceMs: 100
+     * });
+     * ```
+     */
+    enable: typeof enable;
+    /**
+     * Disable log persistence
+     */
+    disable: typeof disable;
+    /**
+     * Check if persistence is enabled
+     */
+    isActive: typeof isActive_2;
+    /**
+     * Check if the last session had a crash (unclean shutdown)
+     */
+    hadCrash: typeof hadCrash;
+    /**
+     * Get persisted logs from previous session (without importing)
+     */
+    getPersistedLogs: typeof getPersistedLogs;
+    /**
+     * Rehydrate logs from storage into the logger
+     * Call this at app startup to restore logs from previous session
+     *
+     * @returns Number of logs rehydrated
+     *
+     * @example
+     * ```typescript
+     * // At app start
+     * LogPersistence.enable();
+     * const count = LogPersistence.rehydrate();
+     * if (LogPersistence.hadCrash()) {
+     *   console.log(`Recovered ${count} logs from crash`);
+     * }
+     * ```
+     */
+    rehydrate: typeof rehydrate;
+    /**
+     * Clear all persisted logs
+     */
+    clear: typeof clear;
+    /**
+     * Get current configuration
+     */
+    getConfig: typeof getConfig_2;
+};
+
+/**
+ * Log Span class - represents a grouped set of related logs
+ */
+export declare class LogSpan {
+    private logger;
+    private _event;
+    private _ended;
+    constructor(logger: LoggerCore, name: string, context?: LogContext, parentId?: string);
+    /** Get span ID */
+    get id(): string;
+    /** Get span event data */
+    get event(): Readonly<SpanEvent>;
+    /** Check if span has ended */
+    get ended(): boolean;
+    /** Log debug within this span */
+    debug(message: string, ...data: unknown[]): void;
+    /** Log info within this span */
+    info(message: string, ...data: unknown[]): void;
+    /** Log warn within this span */
+    warn(message: string, ...data: unknown[]): void;
+    /** Log error within this span */
+    error(message: string, ...data: unknown[]): void;
+    /** Create a child span */
+    span(name: string, context?: LogContext): LogSpan;
+    /** End the span successfully */
+    end(): void;
+    /** End the span with error status */
+    fail(error?: Error | string): void;
+    /** Internal finish method */
+    private finish;
+}
+
+/**
+ * Subscriber callback for new log events
+ */
+export declare type LogSubscriber = (event: LogEvent) => void;
+
+/**
+ * Network Capture API
+ */
+export declare const NetworkCapture: {
+    /**
+     * Install network capture hooks
+     */
+    install(userConfig?: NetworkCaptureConfig): void;
+    /**
+     * Uninstall network capture hooks
+     */
+    uninstall(): void;
+    /**
+     * Check if capture is active
+     */
+    isActive(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<Required<NetworkCaptureConfig>>;
+    /**
+     * Update ignore patterns
+     */
+    addIgnorePattern(pattern: string | RegExp): void;
+};
+
+/**
+ * Network capture configuration
+ */
+export declare interface NetworkCaptureConfig {
+    /** Capture fetch requests (default: true) */
+    captureFetch?: boolean;
+    /** Capture XHR requests (default: true) */
+    captureXHR?: boolean;
+    /** Include request headers (default: false, may contain sensitive data) */
+    includeHeaders?: boolean;
+    /** Include request body (default: false, may be large) */
+    includeBody?: boolean;
+    /** Include response body (default: false, may be large) */
+    includeResponse?: boolean;
+    /** Max response body length to capture (default: 1000) */
+    maxResponseLength?: number;
+    /** URL patterns to ignore (e.g., analytics, hot reload) */
+    ignorePatterns?: (string | RegExp)[];
+    /** Custom context to add to all network logs */
+    context?: LogContext;
+}
+
+/** Configuration for persistence */
+export declare interface PersistenceConfig {
+    /** Storage type: 'session' (sessionStorage) or 'local' (localStorage) */
+    storage?: 'session' | 'local';
+    /** Maximum logs to persist (default: 500) */
+    maxPersisted?: number;
+    /** Debounce delay in ms for batching writes (default: 100) */
+    debounceMs?: number;
+}
+
+/**
+ * Rehydrate logs from storage into the logger
+ * Returns number of logs rehydrated
+ */
+declare function rehydrate(): number;
+
+/**
+ * Source location of a log entry
+ */
+export declare interface Source {
+    /** File path or name */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based, optional) */
+    column?: number;
+    /** Function or method name (optional) */
+    function?: string;
+}
+
+/**
+ * A span (grouped logs) event
+ */
+export declare interface SpanEvent {
+    /** Unique span identifier */
+    id: string;
+    /** Span name/label */
+    name: string;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp (set when span ends) */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Current status */
+    status: SpanStatus;
+    /** Parent span ID for nesting */
+    parentId?: string;
+    /** Context inherited by all logs in this span */
+    context?: LogContext;
+    /** Source where span was created */
+    source: Source;
+    /** Session ID */
+    sessionId: string;
+}
+
+/**
+ * Span status for grouped logs
+ */
+export declare type SpanStatus = 'running' | 'success' | 'error';
+
+/**
+ * Subscriber callback for span events
+ */
+export declare type SpanSubscriber = (event: SpanEvent) => void;
+
+/**
+ * Timeline class
+ */
+export declare class Timeline {
+    private container;
+    private config;
+    private canvas;
+    private ctx;
+    private intervalId;
+    private tooltip;
+    private spanBounds;
+    private logBounds;
+    constructor(userConfig: TimelineConfig);
+    private init;
+    private resizeCanvas;
+    private startRefresh;
+    private stopRefresh;
+    setTimeWindow(ms: number): void;
+    private render;
+    private drawTimeGrid;
+    private drawSpans;
+    private drawLogs;
+    private handleMouseMove;
+    private handleMouseLeave;
+    private showTooltip;
+    private hideTooltip;
+    /**
+     * Destroy the timeline
+     */
+    destroy(): void;
+}
+
+/**
+ * Timeline / Flame-View Component
+ *
+ * Lightweight timeline visualization for logs and spans.
+ * Features:
+ * - Logs displayed on time axis
+ * - Spans visualized as bars
+ * - Zoom to last X seconds
+ * - Hover for details
+ */
+/**
+ * Timeline configuration
+ */
+export declare interface TimelineConfig {
+    /** Container element or selector */
+    container: HTMLElement | string;
+    /** Time window in milliseconds (default: 60000 = 1 minute) */
+    timeWindow?: number;
+    /** Auto-refresh interval in ms (default: 1000) */
+    refreshInterval?: number;
+    /** Show span bars (default: true) */
+    showSpans?: boolean;
+    /** Show log markers (default: true) */
+    showLogs?: boolean;
+    /** Height of timeline in pixels (default: 200) */
+    height?: number;
+}
+
+/**
+ * Uninstall global error handlers and restore originals
+ */
+declare function uninstall(): void;
+
+/**
+ * Function to unsubscribe from log events
+ */
+export declare type Unsubscribe = () => void;
+
+/** Current package version */
+export declare const VERSION = "0.1.0";
+
+export { }