devlog-ui 0.1.0

package/dist/noop.d.ts

@@ -0,0 +1,682 @@
+/**
+ * DevLogger - No-Op Export for Production
+ *
+ * Import this instead of the main export in production builds
+ * to completely eliminate logging code via tree-shaking.
+ *
+ * Usage in vite.config.ts:
+ * ```ts
+ * resolve: {
+ *   alias: {
+ *     'devlogger': process.env.NODE_ENV === 'production'
+ *       ? 'devlogger/noop'
+ *       : 'devlogger'
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export declare const computeDiff: () => readonly [];
+
+/**
+ * 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;
+}
+
+export declare const createDiffResult: () => {
+    changes: readonly [];
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+};
+
+export declare const createTimeline: () => NoopTimeline;
+
+export declare const DevLoggerUI: {
+    init: () => void;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    popout: () => void;
+    closePopout: () => void;
+    isPopoutOpen: () => boolean;
+    setFilter: () => void;
+    getFilter: () => {
+        levels: Set<"debug" | "info" | "warn" | "error">;
+        search: string;
+        file: string;
+    };
+    clearFilter: () => void;
+    destroy: () => void;
+    isVisible: () => boolean;
+    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;
+    };
+}
+
+export declare const ErrorCapture: {
+    install: () => void;
+    uninstall: () => void;
+    isActive: () => boolean;
+    getConfig: () => {
+        captureErrors: boolean;
+        captureRejections: boolean;
+        errorPrefix: string;
+        rejectionPrefix: string;
+    };
+};
+
+/**
+ * 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;
+}
+
+export declare const formatValue: (v: unknown) => string;
+
+export declare const hasChanges: () => 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;
+}
+
+/**
+ * DevLogger - No-Op Export for Production
+ *
+ * Import this instead of the main export in production builds
+ * to completely eliminate logging code via tree-shaking.
+ *
+ * Usage in vite.config.ts:
+ * ```ts
+ * resolve: {
+ *   alias: {
+ *     'devlogger': process.env.NODE_ENV === 'production'
+ *       ? 'devlogger/noop'
+ *       : 'devlogger'
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export declare const logger: {
+    info: () => void;
+    warn: () => void;
+    error: () => void;
+    debug: () => void;
+    configure: () => void;
+    clear: () => void;
+    importLogs: () => void;
+    getLogs: () => readonly [];
+    subscribe: () => () => void;
+    getSessionId: () => string;
+    getConfig: () => {
+        maxLogs: number;
+        persist: boolean;
+        minLevel: "debug";
+        enabled: boolean;
+    };
+    isEnabled: () => boolean;
+    span: () => {
+        id: string;
+        event: never;
+        ended: boolean;
+        debug: () => void;
+        info: () => void;
+        warn: () => void;
+        error: () => void;
+        span: () => /*elided*/ any;
+        end: () => void;
+        fail: () => void;
+    };
+    getSpans: () => readonly [];
+    getSpan: () => undefined;
+    getSpanLogs: () => readonly [];
+    subscribeSpans: () => () => void;
+    setGlobalContext: () => void;
+    updateGlobalContext: () => void;
+    getGlobalContext: () => {};
+    clearGlobalContext: () => void;
+    withContext: () => {
+        debug: () => void;
+        info: () => void;
+        warn: () => void;
+        error: () => void;
+        span: () => {
+            id: string;
+            event: never;
+            ended: boolean;
+            debug: () => void;
+            info: () => void;
+            warn: () => void;
+            error: () => void;
+            span: () => /*elided*/ any;
+            end: () => void;
+            fail: () => void;
+        };
+        withContext: () => /*elided*/ any;
+    };
+    exportLogs: () => string;
+    copyLogs: () => Promise<boolean>;
+    diff: () => {
+        changes: readonly [];
+        summary: {
+            added: number;
+            removed: number;
+            changed: number;
+            unchanged: number;
+        };
+    };
+    computeDiff: () => {
+        changes: readonly [];
+        summary: {
+            added: number;
+            removed: number;
+            changed: number;
+            unchanged: number;
+        };
+    };
+};
+
+/**
+ * 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';
+
+export declare const LogPersistence: {
+    enable: () => void;
+    disable: () => void;
+    isActive: () => boolean;
+    hadCrash: () => boolean;
+    getPersistedLogs: () => readonly [];
+    rehydrate: () => number;
+    clear: () => void;
+    getConfig: () => {
+        storage: "session";
+        maxPersisted: number;
+        debounceMs: number;
+    };
+};
+
+/**
+ * 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;
+
+export declare const NetworkCapture: {
+    install: () => void;
+    uninstall: () => void;
+    isActive: () => boolean;
+    getConfig: () => {
+        captureFetch: boolean;
+        captureXHR: boolean;
+        includeHeaders: boolean;
+        includeBody: boolean;
+        includeResponse: boolean;
+        maxResponseLength: number;
+        ignorePatterns: readonly [];
+        context: {};
+    };
+    addIgnorePattern: () => 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;
+}
+
+declare class NoopTimeline {
+    setTimeWindow: () => void;
+    destroy: () => void;
+}
+
+/** 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;
+}
+
+/**
+ * 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;
+
+export declare const Timeline: typeof NoopTimeline;
+
+/**
+ * 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;
+}
+
+/**
+ * Function to unsubscribe from log events
+ */
+export declare type Unsubscribe = () => void;
+
+export declare const VERSION = "0.1.0";
+
+export { }