@revealui/core 0.0.1-pre.3 → 0.2.0

package/dist/monitoring/alerts.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Alert System
+ *
+ * Manages alert channels (logger, Sentry, console) and alert delivery.
+ * Provides configurable thresholds and aggregation for production.
+ */
+import type { Alert } from './types.js';
+/**
+ * Sentry interface for dependency injection and testing
+ */
+interface SentryClient {
+    captureMessage: (message: string, context?: unknown) => void;
+    setUser: (user: unknown) => void;
+}
+/**
+ * Alert channel type
+ */
+type AlertChannel = 'logger' | 'sentry' | 'console';
+/**
+ * Alert configuration
+ */
+interface AlertConfig {
+    /** Enabled channels */
+    channels: AlertChannel[];
+    /** Aggregate alerts in production (log every N minutes instead of immediately) */
+    aggregateInProduction: boolean;
+    /** Aggregation interval in milliseconds */
+    aggregationInterval: number;
+    /** Enable Sentry in production only */
+    sentryProductionOnly: boolean;
+}
+/**
+ * Alert manager class
+ */
+declare class AlertManager {
+    private config;
+    private alertQueue;
+    private aggregationTimer;
+    private lastAggregationTime;
+    private sentryClient;
+    constructor(config?: Partial<AlertConfig>, sentryClient?: SentryClient | null);
+    /**
+     * Send an alert through configured channels
+     */
+    sendAlert(alert: Alert): void;
+    /**
+     * Send multiple alerts
+     */
+    sendAlerts(alerts: Alert[]): void;
+    /**
+     * Deliver an alert to configured channels
+     */
+    private deliverAlert;
+    /**
+     * Send alert to logger
+     */
+    private sendToLogger;
+    /**
+     * Send alert to console (uses logger for structured output)
+     */
+    private sendToConsole;
+    /**
+     * Send alert to Sentry
+     */
+    private sendToSentry;
+    /**
+     * Start aggregation timer
+     */
+    private startAggregation;
+    /**
+     * Flush aggregated alerts
+     */
+    private flushAlerts;
+    /**
+     * Stop aggregation timer
+     */
+    stopAggregation(): void;
+    /**
+     * Check if running in production
+     */
+    private isProduction;
+    /**
+     * Get alert queue stats
+     */
+    getStats(): {
+        queueSize: number;
+        lastAggregationTime: number;
+        aggregationEnabled: boolean;
+    };
+    /**
+     * Configure alert channels
+     */
+    setChannels(channels: AlertChannel[]): void;
+    /**
+     * Cleanup resources
+     */
+    dispose(): void;
+}
+/**
+ * Singleton instance
+ */
+export declare const alertManager: AlertManager;
+/**
+ * Export AlertManager class for testing
+ */
+export { AlertManager };
+/**
+ * Export types for testing
+ */
+export type { AlertChannel, SentryClient };
+/**
+ * Convenience functions
+ */
+export declare function sendAlert(alert: Alert): void;
+export declare function sendAlerts(alerts: Alert[]): void;
+export declare function getAlertStats(): ReturnType<typeof alertManager.getStats>;
+export declare function setAlertChannels(channels: AlertChannel[]): void;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/monitoring/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../src/monitoring/alerts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;GAEG;AACH,UAAU,YAAY;IACpB,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAC5D,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;CACjC;AAsCD;;GAEG;AACH,KAAK,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEnD;;GAEG;AACH,UAAU,WAAW;IACnB,uBAAuB;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAA;IAExB,kFAAkF;IAClF,qBAAqB,EAAE,OAAO,CAAA;IAE9B,2CAA2C;IAC3C,mBAAmB,EAAE,MAAM,CAAA;IAE3B,uCAAuC;IACvC,oBAAoB,EAAE,OAAO,CAAA;CAC9B;AAYD;;GAEG;AACH,cAAM,YAAY;IAChB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,YAAY,CAA4B;gBAEpC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAUjF;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAU7B;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAMjC;;OAEG;IACH,OAAO,CAAC,YAAY;IAoBpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAuBpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,YAAY;IAmEpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAwCnB;;OAEG;IACH,eAAe,IAAI,IAAI;IAOvB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAA;QACjB,mBAAmB,EAAE,MAAM,CAAA;QAC3B,kBAAkB,EAAE,OAAO,CAAA;KAC5B;IAQD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IAI3C;;OAEG;IACH,OAAO,IAAI,IAAI;CAIhB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,cAAqB,CAAA;AAE9C;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,CAAA;AAEvB;;GAEG;AACH,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,CAAA;AAE1C;;GAEG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAE5C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAEhD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAAC,OAAO,YAAY,CAAC,QAAQ,CAAC,CAExE;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,CAE/D"}

package/dist/monitoring/alerts.js

@@ -0,0 +1,324 @@
+/**
+ * Alert System
+ *
+ * Manages alert channels (logger, Sentry, console) and alert delivery.
+ * Provides configurable thresholds and aggregation for production.
+ */
+import { logger } from '../utils/logger-server.js';
+import { getRequestContext } from '../utils/request-context.js';
+/**
+ * Get Sentry client if available
+ * Using dynamic import with string variable to avoid build-time resolution
+ */
+async function getSentryClient() {
+    try {
+        // Use string variable to prevent static analysis and bundler resolution
+        const moduleName = '@sentry' + '/node';
+        const sentry = await import(/* webpackIgnore: true */ moduleName);
+        return sentry;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Synchronous version that caches the client
+ */
+let sentryClientCache;
+function getSentryClientSync() {
+    if (sentryClientCache !== undefined) {
+        return sentryClientCache;
+    }
+    // Initialize asynchronously in the background
+    getSentryClient()
+        .then((client) => {
+        sentryClientCache = client;
+    })
+        .catch(() => {
+        sentryClientCache = null;
+    });
+    return null;
+}
+/**
+ * Default alert configuration
+ */
+const DEFAULT_ALERT_CONFIG = {
+    channels: ['logger', 'console'],
+    aggregateInProduction: true,
+    aggregationInterval: 5 * 60 * 1000, // 5 minutes
+    sentryProductionOnly: true,
+};
+/**
+ * Alert manager class
+ */
+class AlertManager {
+    config;
+    alertQueue = [];
+    aggregationTimer = null;
+    lastAggregationTime = 0;
+    sentryClient = null;
+    constructor(config = {}, sentryClient) {
+        this.config = { ...DEFAULT_ALERT_CONFIG, ...config };
+        this.sentryClient = sentryClient !== undefined ? sentryClient : getSentryClientSync();
+        // Start aggregation timer if enabled
+        if (this.config.aggregateInProduction && this.isProduction()) {
+            this.startAggregation();
+        }
+    }
+    /**
+     * Send an alert through configured channels
+     */
+    sendAlert(alert) {
+        if (this.config.aggregateInProduction && this.isProduction()) {
+            // In production, queue alerts for aggregation
+            this.alertQueue.push(alert);
+        }
+        else {
+            // In development, send immediately
+            this.deliverAlert(alert);
+        }
+    }
+    /**
+     * Send multiple alerts
+     */
+    sendAlerts(alerts) {
+        for (const alert of alerts) {
+            this.sendAlert(alert);
+        }
+    }
+    /**
+     * Deliver an alert to configured channels
+     */
+    deliverAlert(alert) {
+        for (const channel of this.config.channels) {
+            switch (channel) {
+                case 'logger':
+                    this.sendToLogger(alert);
+                    break;
+                case 'console':
+                    this.sendToConsole(alert);
+                    break;
+                case 'sentry':
+                    if (!this.config.sentryProductionOnly || this.isProduction()) {
+                        this.sendToSentry(alert);
+                    }
+                    break;
+            }
+        }
+    }
+    /**
+     * Send alert to logger
+     */
+    sendToLogger(alert) {
+        // Get request context for additional metadata
+        const context = getRequestContext();
+        const logData = {
+            metric: alert.metric,
+            value: alert.value,
+            threshold: alert.threshold,
+            timestamp: alert.timestamp,
+            // Include request context if available
+            ...(context?.userId && { userId: context.userId }),
+            ...(context?.path && { path: context.path }),
+            ...(context?.method && { method: context.method }),
+            ...(context?.ip && { ip: context.ip }),
+        };
+        if (alert.level === 'critical') {
+            logger.error(alert.message, logData);
+        }
+        else {
+            logger.warn(alert.message, logData);
+        }
+    }
+    /**
+     * Send alert to console (uses logger for structured output)
+     */
+    sendToConsole(alert) {
+        const logLevel = alert.level === 'critical' ? 'error' : 'warn';
+        const prefix = alert.level === 'critical' ? '🔴 CRITICAL' : '⚠️  WARNING';
+        logger[logLevel](`${prefix}: ${alert.message}`, {
+            metric: alert.metric,
+            value: alert.value,
+            threshold: alert.threshold,
+            timestamp: alert.timestamp,
+        });
+    }
+    /**
+     * Send alert to Sentry
+     */
+    sendToSentry(alert) {
+        // Only send critical alerts to Sentry
+        if (alert.level !== 'critical')
+            return;
+        // Check if Sentry is available
+        if (!this.sentryClient) {
+            logger.debug('Sentry not available for alert delivery');
+            return;
+        }
+        try {
+            // Get request context for rich tracing
+            const context = getRequestContext();
+            // Build tags (indexed, searchable fields)
+            const tags = {
+                metric: alert.metric,
+                alert_level: alert.level,
+            };
+            // Add request context to tags for better filtering
+            if (context?.requestId)
+                tags.request_id = context.requestId;
+            if (context?.userId)
+                tags.user_id = context.userId;
+            if (context?.path)
+                tags.path = context.path;
+            if (context?.method)
+                tags.method = context.method;
+            // Build extra context (non-indexed, rich data)
+            const extra = {
+                value: alert.value,
+                threshold: alert.threshold,
+                timestamp: alert.timestamp,
+            };
+            // Add full request context for debugging
+            if (context) {
+                extra.request_context = {
+                    requestId: context.requestId,
+                    startTime: context.startTime,
+                    duration: Date.now() - context.startTime,
+                    userId: context.userId,
+                    path: context.path,
+                    method: context.method,
+                    ip: context.ip,
+                    userAgent: context.userAgent,
+                };
+            }
+            // Set user context if available (for Sentry user tracking)
+            if (context?.userId) {
+                this.sentryClient.setUser({
+                    id: context.userId,
+                    ip_address: context.ip,
+                });
+            }
+            // Capture the alert as a Sentry event
+            this.sentryClient.captureMessage(alert.message, {
+                level: 'error',
+                tags,
+                extra,
+            });
+        }
+        catch (error) {
+            // Sentry error, log and continue
+            logger.debug('Sentry not available for alert delivery', { error });
+        }
+    }
+    /**
+     * Start aggregation timer
+     */
+    startAggregation() {
+        if (this.aggregationTimer)
+            return;
+        this.aggregationTimer = setInterval(() => {
+            this.flushAlerts();
+        }, this.config.aggregationInterval);
+        // Don't keep process alive
+        this.aggregationTimer.unref();
+        this.lastAggregationTime = Date.now();
+    }
+    /**
+     * Flush aggregated alerts
+     */
+    flushAlerts() {
+        if (this.alertQueue.length === 0)
+            return;
+        // Group alerts by metric and level
+        const grouped = new Map();
+        for (const alert of this.alertQueue) {
+            const key = `${alert.metric}:${alert.level}`;
+            const existing = grouped.get(key) || [];
+            existing.push(alert);
+            grouped.set(key, existing);
+        }
+        // Send aggregated alerts
+        for (const [_key, alerts] of Array.from(grouped.entries())) {
+            if (alerts.length === 0)
+                continue;
+            const first = alerts[0];
+            if (!first)
+                continue;
+            const count = alerts.length;
+            const avgValue = alerts.reduce((sum, a) => sum + a.value, 0) / count;
+            const aggregatedAlert = {
+                level: first.level,
+                metric: first.metric,
+                value: first.value,
+                threshold: first.threshold,
+                message: `${first.message} (occurred ${count} times, avg value: ${Math.round(avgValue)})`,
+                timestamp: Date.now(),
+            };
+            this.deliverAlert(aggregatedAlert);
+        }
+        // Clear queue
+        this.alertQueue = [];
+        this.lastAggregationTime = Date.now();
+    }
+    /**
+     * Stop aggregation timer
+     */
+    stopAggregation() {
+        if (this.aggregationTimer) {
+            clearInterval(this.aggregationTimer);
+            this.aggregationTimer = null;
+        }
+    }
+    /**
+     * Check if running in production
+     */
+    isProduction() {
+        return process.env.NODE_ENV === 'production';
+    }
+    /**
+     * Get alert queue stats
+     */
+    getStats() {
+        return {
+            queueSize: this.alertQueue.length,
+            lastAggregationTime: this.lastAggregationTime,
+            aggregationEnabled: this.config.aggregateInProduction && this.isProduction(),
+        };
+    }
+    /**
+     * Configure alert channels
+     */
+    setChannels(channels) {
+        this.config.channels = channels;
+    }
+    /**
+     * Cleanup resources
+     */
+    dispose() {
+        this.stopAggregation();
+        this.flushAlerts(); // Flush remaining alerts
+    }
+}
+/**
+ * Singleton instance
+ */
+export const alertManager = new AlertManager();
+/**
+ * Export AlertManager class for testing
+ */
+export { AlertManager };
+/**
+ * Convenience functions
+ */
+export function sendAlert(alert) {
+    alertManager.sendAlert(alert);
+}
+export function sendAlerts(alerts) {
+    alertManager.sendAlerts(alerts);
+}
+export function getAlertStats() {
+    return alertManager.getStats();
+}
+export function setAlertChannels(channels) {
+    alertManager.setChannels(channels);
+}

package/dist/monitoring/cleanup-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cleanup Manager
+ *
+ * Global cleanup handler registry and graceful shutdown coordination.
+ * Ensures all resources are properly released when the process exits.
+ */
+import type { CleanupHandler, CleanupRegistration } from './types.js';
+/**
+ * Cleanup manager class
+ */
+declare class CleanupManager {
+    private handlers;
+    private isShuttingDown;
+    private shutdownTimeout;
+    private signalHandlersRegistered;
+    /**
+     * Register a cleanup handler
+     */
+    register(id: string, handler: CleanupHandler, description: string, priority?: number): void;
+    /**
+     * Unregister a cleanup handler
+     */
+    unregister(id: string): void;
+    /**
+     * Execute all cleanup handlers
+     */
+    cleanup(signal?: string): Promise<void>;
+    /**
+     * Execute cleanup handlers in sequence
+     */
+    private executeHandlers;
+    /**
+     * Register signal handlers for graceful shutdown
+     */
+    private registerSignalHandlers;
+    /**
+     * Force immediate cleanup (skip timeout)
+     */
+    forceCleanup(): Promise<void>;
+    /**
+     * Get registered handlers
+     */
+    getHandlers(): CleanupRegistration[];
+    /**
+     * Check if shutdown is in progress
+     */
+    isShutdownInProgress(): boolean;
+    /**
+     * Set shutdown timeout
+     */
+    setShutdownTimeout(ms: number): void;
+    /**
+     * Clear all handlers
+     */
+    clear(): void;
+}
+/**
+ * Singleton instance
+ */
+export declare const cleanupManager: CleanupManager;
+/**
+ * Convenience functions
+ */
+export declare function registerCleanupHandler(id: string, handler: CleanupHandler, description: string, priority?: number): void;
+export declare function unregisterCleanupHandler(id: string): void;
+export declare function initiateCleanup(signal?: string): Promise<void>;
+export declare function forceCleanup(): Promise<void>;
+export declare function getCleanupHandlers(): CleanupRegistration[];
+export declare function isShutdownInProgress(): boolean;
+export {};
+//# sourceMappingURL=cleanup-manager.d.ts.map

package/dist/monitoring/cleanup-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-manager.d.ts","sourceRoot":"","sources":["../../src/monitoring/cleanup-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErE;;GAEG;AACH,cAAM,cAAc;IAClB,OAAO,CAAC,QAAQ,CAA8C;IAC9D,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,wBAAwB,CAAQ;IAExC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,IAAI;IAqBtF;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAM5B;;OAEG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD7C;;OAEG;YACW,eAAe;IAsC7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAmD9B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAWnC;;OAEG;IACH,WAAW,IAAI,mBAAmB,EAAE;IAIpC;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;OAEG;IACH,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAA;AAElD;;GAEG;AAEH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,QAAQ,SAAI,GACX,IAAI,CAEN;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,wBAAgB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAE5C;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,EAAE,CAE1D;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}