@gravito/core 1.6.0 → 2.0.0

package/dist/events/aggregation/AggregationWindow.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Aggregation window with backpressure awareness (FS-102)
+ *
+ * Adjusts batching window based on backpressure state:
+ * - NORMAL: 200ms (optimal aggregation)
+ * - WARNING: 150ms (accelerate processing)
+ * - CRITICAL: 100ms (fast drain)
+ * - OVERFLOW: 50ms (minimum latency)
+ *
+ * FS-103 增強：
+ * - 與 BackpressureManager 雙向反饋
+ * - 窗口調整通知機制
+ */
+import type { BackpressureManager } from '../BackpressureManager';
+import { BackpressureState } from '../BackpressureManager';
+import type { WindowStats } from './types';
+/**
+ * Aggregation window manager with backpressure awareness.
+ */
+export declare class AggregationWindow {
+    private currentWindowMs;
+    private readonly minWindowMs;
+    private readonly maxWindowMs;
+    private stats;
+    private backpressureManager?;
+    /**
+     * Create an aggregation window.
+     *
+     * @param initialWindowMs - Initial window size (default 200ms)
+     */
+    constructor(initialWindowMs?: number);
+    /**
+     * Set the BackpressureManager for feedback loop (FS-103).
+     *
+     * @param manager - BackpressureManager instance
+     */
+    setBackpressureManager(manager: BackpressureManager): void;
+    /**
+     * Adjust window based on backpressure state.
+     *
+     * @param state - Current backpressure state
+     */
+    adjustWindow(state: BackpressureState): number;
+    /**
+     * Notify BackpressureManager of window adjustment (FS-103).
+     * Part of the backpressure feedback loop for automatic state recovery.
+     *
+     * @param oldWindowMs - Previous window size
+     * @param newWindowMs - New window size
+     * @private
+     */
+    private notifyBackpressureManager;
+    /**
+     * Get current window size.
+     */
+    getCurrentWindow(): number;
+    /**
+     * Get minimum window size.
+     */
+    getMinWindow(): number;
+    /**
+     * Get maximum window size.
+     */
+    getMaxWindow(): number;
+    /**
+     * Get statistics.
+     */
+    getStats(): WindowStats;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Reset window to initial size.
+     */
+    reset(windowMs?: number): void;
+}

package/dist/events/aggregation/DeduplicationManager.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Event deduplication manager (FS-102)
+ *
+ * Merges events with the same pattern/idempotency key to reduce duplicates.
+ * - Pattern-based deduplication
+ * - Priority-aware merge strategy
+ * - Wildcard pattern aggregation
+ * - Deduplication rate tracking
+ *
+ * Ported from: examples/flash-sale-fullstack/src/cache/events/EventDeduplicator.ts
+ */
+import type { EventTask } from '../types';
+import type { AggregationConfig, DeduplicationStats } from './types';
+/**
+ * Event deduplication manager using pattern matching.
+ */
+export declare class DeduplicationManager {
+    private patternMap;
+    private stats;
+    private regexCache;
+    private cachedDeduplicated;
+    private deduplicatedDirty;
+    private config;
+    private patternTimestamps;
+    private cleanupTimer;
+    /**
+     * Create a deduplication manager.
+     */
+    constructor(config?: Partial<AggregationConfig>);
+    /**
+     * Add an event for deduplication.
+     *
+     * Rules:
+     * 1. Events with same pattern are merged into one
+     * 2. Higher priority events are kept, lower priority removed
+     * 3. If new event has higher priority, it replaces old event
+     */
+    addEvent(event: EventTask): void;
+    /**
+     * Add multiple events.
+     */
+    addEvents(events: EventTask[]): void;
+    /**
+     * Get all deduplicated events.
+     * Result is cached until next addEvent() call.
+     */
+    getDeduplicated(): EventTask[];
+    /**
+     * Optimize patterns by merging overlapping patterns.
+     *
+     * Example: ['product:1', 'product:2', 'product:3'] -> ['product:*']
+     */
+    optimizePatterns(patterns: string[]): string[];
+    /**
+     * Clear the deduplication manager.
+     */
+    clear(): void;
+    /**
+     * Get statistics.
+     */
+    getStats(): DeduplicationStats;
+    /**
+     * Reset statistics (but keep deduplication data).
+     */
+    resetStats(): void;
+    /**
+     * Get deduplication rate percentage.
+     */
+    getDeduplicationRate(): number;
+    /**
+     * Get pattern count.
+     */
+    getPatternCount(): number;
+    /**
+     * Get event for specific pattern.
+     */
+    getEventForPattern(pattern: string): EventTask | undefined;
+    /**
+     * Check if pattern exists.
+     */
+    hasPattern(pattern: string): boolean;
+    /**
+     * Remove specific pattern.
+     */
+    removePattern(pattern: string): boolean;
+    /**
+     * Remove patterns by prefix.
+     */
+    removePatternByPrefix(prefix: string): number;
+    /**
+     * Get all patterns.
+     */
+    getPatterns(): string[];
+    /**
+     * Find events matching invalidation pattern.
+     * Supports wildcard patterns.
+     */
+    findEventsByPattern(invalidationPattern: string): EventTask[];
+    /**
+     * Shutdown the manager (cleanup resources).
+     */
+    shutdown(): void;
+    /**
+     * Generate deduplication pattern from event.
+     */
+    private generatePattern;
+    /**
+     * Get pattern regex (cached).
+     */
+    private getPatternRegex;
+    /**
+     * Convert pattern to regex.
+     */
+    private patternToRegex;
+    /**
+     * Update deduplication rate.
+     */
+    private updateDeduplicationRate;
+    /**
+     * Start automatic cleanup timer.
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup timer.
+     */
+    private stopCleanup;
+    /**
+     * Perform TTL-based cleanup.
+     */
+    private performCleanup;
+    /**
+     * Internal method for testing.
+     */
+    __getPatternMap(): Map<string, EventTask>;
+}

package/dist/events/aggregation/EventAggregationManager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Event aggregation manager (FS-102)
+ *
+ * Coordinates deduplication and batching for optimal event processing:
+ * - Event deduplication (pattern-based or idempotency-key based)
+ * - Micro-batching (time and size dual-trigger)
+ * - Backpressure-aware window adjustment
+ * - Complete statistics tracking
+ *
+ * Ported from: examples/flash-sale-fullstack/src/cache/events/EventAggregator.ts
+ */
+import type { BackpressureManager } from '../BackpressureManager';
+import type { EventTask } from '../types';
+import { AggregationWindow } from './AggregationWindow';
+import { DeduplicationManager } from './DeduplicationManager';
+import { EventBatcher } from './EventBatcher';
+import type { AggregationConfig, AggregationStats } from './types';
+/**
+ * Event aggregation manager.
+ */
+export declare class EventAggregationManager {
+    private deduplicator;
+    private batcher;
+    private window;
+    private config;
+    private backpressureManager?;
+    private submitToQueueFn?;
+    private disabled;
+    /**
+     * Create an event aggregation manager.
+     */
+    constructor(config?: Partial<AggregationConfig>);
+    /**
+     * Set backpressure manager for window adjustment.
+     * FS-103：Also sets BackpressureManager on AggregationWindow for feedback loop.
+     */
+    setBackpressureManager(backpressure: BackpressureManager): void;
+    /**
+     * Set the actual queue submission function.
+     */
+    setSubmitToQueueFn(fn: (tasks: EventTask[]) => Promise<void>): void;
+    /**
+     * Submit an event for aggregation.
+     *
+     * Returns true if accepted, false if rejected due to backpressure.
+     */
+    submit(task: EventTask): Promise<boolean>;
+    /**
+     * Submit multiple events.
+     */
+    submitBatch(tasks: EventTask[]): Promise<number>;
+    /**
+     * Flush current batch to queue.
+     */
+    flush(): Promise<EventTask[]>;
+    /**
+     * Get aggregation statistics.
+     */
+    getStats(): AggregationStats;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Clear aggregation state.
+     */
+    clear(): void;
+    /**
+     * Check if there are pending events.
+     */
+    hasPending(): boolean;
+    /**
+     * Get pending event count.
+     */
+    getPendingCount(): number;
+    /**
+     * Disable the aggregation manager.
+     */
+    disable(): void;
+    /**
+     * Enable the aggregation manager.
+     */
+    enable(): void;
+    /**
+     * Check if aggregation manager is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Shutdown the aggregation manager.
+     */
+    shutdown(): Promise<EventTask[]>;
+    /**
+     * Submit deduplicated events to queue.
+     */
+    private submitToQueue;
+    /**
+     * Get deduplication manager (for testing).
+     */
+    __getDeduplicator(): DeduplicationManager;
+    /**
+     * Get event batcher (for testing).
+     */
+    __getBatcher(): EventBatcher;
+    /**
+     * Get aggregation window (for testing).
+     */
+    __getWindow(): AggregationWindow;
+}

package/dist/events/aggregation/EventBatcher.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Event batcher for microbatching optimization (FS-102)
+ *
+ * Implements dual-trigger batching:
+ * - Time window trigger (default 50ms)
+ * - Batch size trigger (default 50 events)
+ *
+ * Expected improvements: 10-15% throughput increase
+ *
+ * Ported from: examples/flash-sale-fullstack/src/cache/events/BatchSubmitter.ts
+ */
+import type { EventTask } from '../types';
+import type { BatchStats } from './types';
+/**
+ * Event batcher for optimizing submission throughput.
+ */
+export declare class EventBatcher {
+    private queue;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private flushTimer;
+    private stats;
+    private submitFn;
+    /**
+     * Create an event batcher.
+     *
+     * @param batchSize - Batch size threshold (default 50)
+     * @param flushIntervalMs - Time window (ms, default 50)
+     * @param submitFn - Function to submit batches
+     */
+    constructor(batchSize: number, flushIntervalMs: number, submitFn: (tasks: EventTask[]) => Promise<void>);
+    /**
+     * Enqueue an event.
+     *
+     * Automatically triggers flush if:
+     * 1. Batch size is reached
+     * 2. Time window expires
+     */
+    enqueue(task: EventTask): Promise<void>;
+    /**
+     * Enqueue multiple events.
+     */
+    enqueueBatch(tasks: EventTask[]): Promise<void>;
+    /**
+     * Flush queued events.
+     *
+     * @param auto - Whether this is an auto-triggered flush
+     * @returns Array of flushed events
+     */
+    flush(auto?: boolean): Promise<EventTask[]>;
+    /**
+     * Get statistics.
+     */
+    getStats(): BatchStats;
+    /**
+     * Get pending event count.
+     */
+    getPendingCount(): number;
+    /**
+     * Check if there are pending events.
+     */
+    hasPending(): boolean;
+    /**
+     * Clear the queue.
+     */
+    clear(): void;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Stop the batcher and flush remaining events.
+     */
+    stop(): Promise<EventTask[]>;
+    /**
+     * Start time-window timer.
+     */
+    private startTimer;
+    /**
+     * Clear timer.
+     */
+    private clearTimer;
+    /**
+     * Adjust batch size.
+     */
+    setBatchSize(newSize: number): void;
+    /**
+     * Adjust flush interval.
+     */
+    setFlushInterval(_newIntervalMs: number): void;
+    /**
+     * Get batch size.
+     */
+    getBatchSize(): number;
+    /**
+     * Get flush interval.
+     */
+    getFlushInterval(): number;
+}

package/dist/events/aggregation/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Event aggregation and deduplication module (FS-102)
+ * @public
+ */
+export { AggregationWindow } from './AggregationWindow';
+export { DeduplicationManager } from './DeduplicationManager';
+export { EventAggregationManager } from './EventAggregationManager';
+export { EventBatcher } from './EventBatcher';
+export type { AggregationConfig, AggregationStats, BatchStats, DeduplicationStats, WindowAdjustmentConfig, WindowStats, } from './types';
+export { DEFAULT_AGGREGATION_CONFIG, DEFAULT_WINDOW_ADJUSTMENT, getSuggestedWindow, PRIORITY_ORDER, } from './types';

package/dist/events/aggregation/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Event aggregation and deduplication types (FS-102)
+ * @internal
+ */
+import { BackpressureState } from '../BackpressureManager';
+/**
+ * Deduplication statistics.
+ */
+export interface DeduplicationStats {
+    /** Total events submitted */
+    totalEvents: number;
+    /** Events after deduplication */
+    deduplicatedEvents: number;
+    /** Events removed by deduplication */
+    removedCount: number;
+    /** Number of patterns aggregated */
+    patternsAggregated: number;
+    /** Deduplication rate (%) */
+    deduplicationRate: number;
+}
+/**
+ * Batch submission statistics.
+ */
+export interface BatchStats {
+    /** Total batches submitted */
+    totalBatches: number;
+    /** Total events submitted */
+    totalEvents: number;
+    /** Average batch size */
+    averageBatchSize: number;
+    /** Average batch latency (ms) */
+    averageBatchLatency: number;
+    /** Last flush timestamp */
+    lastFlushTime: number;
+    /** Pending events in queue */
+    pendingEvents: number;
+    /** Auto-triggered flushes */
+    autoFlushCount: number;
+    /** Manual flushes */
+    manualFlushCount: number;
+}
+/**
+ * Aggregation window statistics.
+ */
+export interface WindowStats {
+    /** Current window size (ms) */
+    currentWindowMs: number;
+    /** Minimum window size (ms) */
+    minWindowMs: number;
+    /** Maximum window size (ms) */
+    maxWindowMs: number;
+    /** Last window adjustment reason */
+    lastAdjustmentReason?: string;
+    /** Window adjustment count */
+    adjustmentCount: number;
+}
+/**
+ * Complete aggregation statistics.
+ */
+export interface AggregationStats {
+    deduplication: DeduplicationStats;
+    batching: BatchStats;
+    window: WindowStats;
+    timestamp: number;
+}
+/**
+ * Aggregation configuration options.
+ */
+export interface AggregationConfig {
+    /** Enable aggregation (default: false) */
+    enabled: boolean;
+    /** Window size in milliseconds (default: 200) */
+    windowMs?: number;
+    /** Batch size threshold (default: 50) */
+    batchSize?: number;
+    /** Deduplication strategy */
+    deduplication?: 'pattern' | 'idempotencyKey' | 'off';
+    /** Deduplication pattern (string or function) */
+    pattern?: string | ((args: unknown) => string);
+    /** Merge priority when deduplicating */
+    mergePriority?: 'highest' | 'earliest' | 'latest';
+    /** Enable background cleanup (default: true) */
+    enableCleanup?: boolean;
+    /** Cleanup interval (ms, default: 5 minutes) */
+    cleanupIntervalMs?: number;
+    /** TTL for deduplication entries (ms, default: 10 minutes) */
+    ttlMs?: number;
+}
+/**
+ * Default aggregation configuration.
+ */
+export declare const DEFAULT_AGGREGATION_CONFIG: Required<AggregationConfig>;
+/**
+ * Priority order for merge decisions.
+ */
+export declare const PRIORITY_ORDER: Record<string, number>;
+/**
+ * Backpressure-aware window configuration.
+ */
+export interface WindowAdjustmentConfig {
+    /** Window for NORMAL backpressure state */
+    normalMs: number;
+    /** Window for WARNING backpressure state */
+    warningMs: number;
+    /** Window for CRITICAL backpressure state */
+    criticalMs: number;
+    /** Window for OVERFLOW backpressure state */
+    overflowMs: number;
+}
+/**
+ * Default window adjustment configuration based on backpressure.
+ */
+export declare const DEFAULT_WINDOW_ADJUSTMENT: WindowAdjustmentConfig;
+/**
+ * Get suggested window size based on backpressure state.
+ */
+export declare function getSuggestedWindow(state: BackpressureState, config?: WindowAdjustmentConfig): number;

package/dist/events/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Event system exports for async event dispatch.
+ * @packageDocumentation
+ */
+export * from './EventBackend';
+export type { EventOptions } from './EventOptions';
+export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
+export type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';
+export type { BackpressureConfig, BackpressureDecision, BackpressureMetricsSnapshot, } from './BackpressureManager';
+export { BackpressureManager, BackpressureState } from './BackpressureManager';
+export type { CircuitBreakerMetrics, CircuitBreakerMetricsRecorder, CircuitBreakerOptions, } from './CircuitBreaker';
+export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
+export type { DLQEntry, DLQEntryCallback, DLQEntrySource, DLQFilter } from './DeadLetterQueue';
+export { DeadLetterQueue } from './DeadLetterQueue';
+export { EventPriorityQueue } from './EventPriorityQueue';
+export * from './FlowControlStrategy';
+export { IdempotencyCache } from './IdempotencyCache';
+export { MessageQueueBridge } from './MessageQueueBridge';
+export type { PriorityStatistics } from './PriorityEscalationManager';
+export { PriorityEscalationManager } from './PriorityEscalationManager';
+export type { RetrySchedulerConfig } from './RetryScheduler';
+export { RetryScheduler } from './RetryScheduler';
+export type { DeadLetterDecision, MultiPriorityQueueDepth, WindowAdjustment } from './types';
+export { WorkerPool } from './WorkerPool';
+export type { WorkerPoolConfig, WorkerPoolStats, WorkerStats } from './WorkerPoolConfig';
+export { WorkerPoolMetrics } from './WorkerPoolMetrics';

package/dist/events/observability/EventMetrics.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @gravito/core - Event System Metrics
+ *
+ * Manages metric collection for event dispatch and listener execution.
+ */
+import type { EventMetricGauge, EventMetricHistogram } from './metrics-types';
+/**
+ * Event metrics collector for monitoring and observability.
+ *
+ * Collects 6 core metrics:
+ * - Event dispatch latency (Histogram)
+ * - Listener execution time (Histogram)
+ * - Queue depth by priority (Gauge)
+ * - Failure count by error type (Counter)
+ * - Timeout count (Counter)
+ * - Processed event count by status (Counter)
+ *
+ * @public
+ */
+export declare class EventMetrics {
+    private dispatchLatency;
+    private listenerExecutionTime;
+    private queueDepthGauge;
+    private failureCounter;
+    private timeoutCounter;
+    private processedCounter;
+    private circuitBreakerStateGauge;
+    private circuitBreakerTransitionsCounter;
+    private circuitBreakerFailuresCounter;
+    private circuitBreakerSuccessesCounter;
+    private circuitBreakerOpenDurationHistogram;
+    /**
+     * Create a new EventMetrics instance.
+     *
+     * @param registry - MetricsRegistry from @gravito/monitor
+     * @param prefix - Metric name prefix (default: 'gravito_event_')
+     */
+    constructor(registry: any, // MetricsRegistry type
+    prefix?: string);
+    /**
+     * Record event dispatch latency.
+     *
+     * @param eventName - Name of the event
+     * @param priority - Priority level (high, normal, low)
+     * @param seconds - Duration in seconds
+     */
+    recordDispatchLatency(eventName: string, priority: string, seconds: number): void;
+    /**
+     * Record listener execution time.
+     *
+     * @param eventName - Name of the event
+     * @param index - Index of the listener in the callback list
+     * @param seconds - Duration in seconds
+     */
+    recordListenerExecution(eventName: string, index: number, seconds: number): void;
+    /**
+     * Update queue depth gauge for a specific priority.
+     *
+     * @param priority - Priority level (high, normal, low)
+     * @param depth - Current queue depth
+     */
+    updateQueueDepth(priority: string, depth: number): void;
+    /**
+     * Record event processing failure.
+     *
+     * @param eventName - Name of the event
+     * @param errorType - Type of error (e.g., 'TypeError', 'TimeoutError')
+     */
+    recordFailure(eventName: string, errorType: string): void;
+    /**
+     * Record event processing timeout.
+     *
+     * @param eventName - Name of the event
+     */
+    recordTimeout(eventName: string): void;
+    /**
+     * Record processed event (success or failure).
+     *
+     * @param eventName - Name of the event
+     * @param status - Processing status ('success' or 'failure')
+     */
+    recordProcessed(eventName: string, status: 'success' | 'failure'): void;
+    /**
+     * Get reference to dispatch latency histogram.
+     * @internal
+     */
+    getDispatchLatencyHistogram(): EventMetricHistogram;
+    /**
+     * Get reference to listener execution time histogram.
+     * @internal
+     */
+    getListenerExecutionHistogram(): EventMetricHistogram;
+    /**
+     * Get reference to queue depth gauge.
+     * @internal
+     */
+    getQueueDepthGauge(): EventMetricGauge;
+    /**
+     * Record circuit breaker state change.
+     *
+     * @param eventName - Name of the event
+     * @param state - Circuit breaker state (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
+     */
+    recordCircuitBreakerState(eventName: string, state: number): void;
+    /**
+     * Record circuit breaker state transition.
+     *
+     * @param eventName - Name of the event
+     * @param fromState - Previous state
+     * @param toState - New state
+     */
+    recordCircuitBreakerTransition(eventName: string, fromState: string, toState: string): void;
+    /**
+     * Record circuit breaker failure.
+     *
+     * @param eventName - Name of the event
+     */
+    recordCircuitBreakerFailure(eventName: string): void;
+    /**
+     * Record circuit breaker success.
+     *
+     * @param eventName - Name of the event
+     */
+    recordCircuitBreakerSuccess(eventName: string): void;
+    /**
+     * Record circuit breaker OPEN duration.
+     *
+     * @param eventName - Name of the event
+     * @param seconds - Duration in seconds
+     */
+    recordCircuitBreakerOpenDuration(eventName: string, seconds: number): void;
+}