@gravito/echo 3.1.1 → 3.1.2

package/dist/core/src/events/DeadLetterQueue.d.ts

@@ -1,219 +0,0 @@
-import type { EventOptions } from './EventOptions';
-/**
- * Source of DLQ entry - reason why event entered the DLQ.
- * @public
- */
-export type DLQEntrySource = 'retry_exhausted' | 'circuit_breaker' | 'backpressure_overflow' | 'manual';
-/**
- * Dead Letter Queue entry representing a failed event.
- * @public
- */
-export interface DLQEntry {
-    /**
-     * Unique identifier for this DLQ entry.
-     */
-    id: string;
-    /**
-     * Event hook name.
-     */
-    eventName: string;
-    /**
-     * Event payload.
-     */
-    payload: unknown;
-    /**
-     * Event options used when dispatching.
-     */
-    options: EventOptions;
-    /**
-     * Error that caused the event to fail.
-     */
-    error: {
-        message: string;
-        stack?: string;
-        code?: string;
-    };
-    /**
-     * Number of retry attempts made.
-     */
-    retryCount: number;
-    /**
-     * Timestamp when the event first failed.
-     */
-    firstFailedAt: number;
-    /**
-     * Timestamp when the event was added to DLQ.
-     */
-    failedAt: number;
-    /**
-     * Timestamp when the event was last retried (if any).
-     */
-    lastRetriedAt?: number;
-    /**
-     * Source of the DLQ entry - reason why event entered the DLQ.
-     */
-    source: DLQEntrySource;
-}
-/**
- * Filter options for querying DLQ entries.
- * @public
- */
-export interface DLQFilter {
-    /**
-     * Filter by event name.
-     */
-    eventName?: string;
-    /**
-     * Filter by entries failed after this timestamp.
-     */
-    from?: number;
-    /**
-     * Filter by entries failed before this timestamp.
-     */
-    to?: number;
-    /**
-     * Maximum number of entries to return.
-     */
-    limit?: number;
-}
-/**
- * Callback type for DLQ entry events.
- * @public
- */
-export type DLQEntryCallback = (entry: DLQEntry) => void;
-/**
- * Dead Letter Queue Manager for handling failed events.
- *
- * The DLQ stores events that have exceeded their retry limit,
- * allowing for manual inspection, reprocessing, or analysis.
- *
- * @public
- */
-export declare class DeadLetterQueue {
-    private entries;
-    private entryIdCounter;
-    private maxEntries?;
-    private onEntryAdded?;
-    private onEntryRemoved?;
-    /**
-     * Create a new DeadLetterQueue instance.
-     *
-     * @param maxEntries - Maximum number of entries to keep (optional, no limit if not set)
-     */
-    constructor(maxEntries?: number);
-    /**
-     * Add a failed event to the Dead Letter Queue.
-     *
-     * @param eventName - Name of the failed event
-     * @param payload - Event payload
-     * @param options - Event options
-     * @param error - Error that caused the failure
-     * @param retryCount - Number of retry attempts made
-     * @param firstFailedAt - Timestamp of first failure
-     * @param source - Source of the DLQ entry (default: 'retry_exhausted')
-     * @returns DLQ entry ID
-     */
-    add(eventName: string, payload: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number, source?: DLQEntrySource): string;
-    /**
-     * Get a specific DLQ entry by ID.
-     *
-     * @param entryId - DLQ entry ID
-     * @returns DLQ entry or undefined if not found
-     */
-    get(entryId: string): DLQEntry | undefined;
-    /**
-     * List DLQ entries with optional filtering.
-     *
-     * @param filter - Filter options
-     * @returns Array of DLQ entries
-     */
-    list(filter?: DLQFilter): DLQEntry[];
-    /**
-     * Delete a DLQ entry.
-     *
-     * @param entryId - DLQ entry ID
-     * @returns True if entry was deleted, false if not found
-     */
-    delete(entryId: string): boolean;
-    /**
-     * Delete all DLQ entries matching the filter.
-     *
-     * @param filter - Filter options
-     * @returns Number of entries deleted
-     */
-    deleteAll(filter?: DLQFilter): number;
-    /**
-     * Get the total number of entries in the DLQ.
-     *
-     * @returns Total entry count
-     */
-    getCount(): number;
-    /**
-     * Get the count of entries for a specific event.
-     *
-     * @param eventName - Event name
-     * @returns Entry count for the event
-     */
-    getCountByEvent(eventName: string): number;
-    /**
-     * Clear all entries from the DLQ.
-     */
-    clear(): void;
-    /**
-     * Update the last retried timestamp for an entry.
-     *
-     * @param entryId - DLQ entry ID
-     * @internal
-     */
-    updateLastRetried(entryId: string): void;
-    /**
-     * Evict the oldest entry from the DLQ.
-     * Used when capacity limit is reached.
-     *
-     * @private
-     */
-    private evictOldest;
-    /**
-     * Get the oldest entry in the DLQ.
-     *
-     * @returns Oldest DLQ entry or undefined if empty
-     */
-    getOldestEntry(): DLQEntry | undefined;
-    /**
-     * Get the newest entry in the DLQ.
-     *
-     * @returns Newest DLQ entry or undefined if empty
-     */
-    getNewestEntry(): DLQEntry | undefined;
-    /**
-     * Get all entries grouped by source.
-     *
-     * @param source - Source to filter by
-     * @returns Array of entries matching the source
-     */
-    getEntriesBySource(source: DLQEntrySource): DLQEntry[];
-    /**
-     * Set callback for when an entry is added to the DLQ.
-     *
-     * @param callback - Callback function or undefined to clear
-     */
-    setOnEntryAdded(callback?: DLQEntryCallback): void;
-    /**
-     * Set callback for when an entry is removed from the DLQ.
-     *
-     * @param callback - Callback function or undefined to clear
-     */
-    setOnEntryRemoved(callback?: DLQEntryCallback): void;
-    /**
-     * Get the maximum number of entries allowed in the DLQ.
-     *
-     * @returns Max entries limit or undefined if no limit
-     */
-    getMaxEntries(): number | undefined;
-    /**
-     * Set the maximum number of entries allowed in the DLQ.
-     *
-     * @param maxEntries - Maximum entries or undefined to remove limit
-     */
-    setMaxEntries(maxEntries?: number): void;
-}

package/dist/core/src/events/EventBackend.d.ts

@@ -1,12 +0,0 @@
-import type { EventTask } from './types';
-/**
- * Interface for event dispatch backends.
- */
-export interface EventBackend {
-    /**
-     * Enqueue an event for processing.
-     * @param task - The event task to process
-     * @returns Task ID or 'dropped' if event was rejected (can be async for some backends)
-     */
-    enqueue(task: EventTask): string | Promise<void>;
-}

package/dist/core/src/events/EventOptions.d.ts

@@ -1,204 +0,0 @@
-/**
- * Event dispatch options for async event handling.
- * @public
- */
-export interface EventOptions {
-    /**
-     * Whether to dispatch the event asynchronously.
-     * @default false
-     */
-    async?: boolean;
-    /**
-     * Priority level for event processing.
-     * - 'critical': Immediate processing, bypass queue (< 1ms)
-     * - 'high': High priority events (< 50ms)
-     * - 'normal': Standard events (< 200ms)
-     * - 'low': Non-critical events (< 500ms)
-     * @default 'normal'
-     */
-    priority?: 'critical' | 'high' | 'normal' | 'low';
-    /**
-     * Automatic priority escalation configuration.
-     * Events can be automatically upgraded to higher priority based on wait time.
-     */
-    escalation?: {
-        /**
-         * Whether to enable automatic priority escalation.
-         * @default true
-         */
-        enabled?: boolean;
-        /**
-         * Escalation thresholds in milliseconds.
-         * Events exceeding these wait times are promoted.
-         */
-        thresholds?: {
-            /**
-             * Wait time before LOW events are promoted to NORMAL.
-             * @default 200
-             */
-            lowToNormal?: number;
-            /**
-             * Wait time before NORMAL events are promoted to HIGH.
-             * @default 100
-             */
-            normalToHigh?: number;
-            /**
-             * Wait time before HIGH events are promoted to CRITICAL.
-             * @default 50
-             */
-            highToCritical?: number;
-        };
-        /**
-         * Maximum wait time before forcing CRITICAL priority.
-         * @default 500
-         */
-        maxWaitTimeMs?: number;
-    };
-    /**
-     * Execution timeout in milliseconds.
-     * If a listener exceeds this timeout, it will be terminated.
-     * @default 5000
-     */
-    timeout?: number;
-    /**
-     * Ordering guarantee strategy.
-     * - 'strict': Global strict ordering (slow, serialized)
-     * - 'partition': Partition-based ordering (recommended, balanced)
-     * - 'none': No ordering guarantee (fastest, parallel)
-     * @default 'none'
-     */
-    ordering?: 'strict' | 'partition' | 'none';
-    /**
-     * Partition key for partition-based ordering.
-     * Events with the same partition key are processed in order.
-     * Only used when ordering is 'partition'.
-     * @example 'order:123' or 'user:456'
-     */
-    partitionKey?: string;
-    /**
-     * Idempotency key for deduplication.
-     * Events with the same idempotency key within the TTL window
-     * will be processed only once.
-     * @example 'order:123:created'
-     */
-    idempotencyKey?: string;
-    /**
-     * Time-to-live for idempotency key in milliseconds.
-     * @default 3600000 (1 hour)
-     */
-    ttl?: number;
-    /**
-     * Retry policy for failed event processing.
-     */
-    retry?: {
-        /**
-         * Maximum number of retry attempts.
-         * @default 0
-         */
-        maxRetries?: number;
-        /**
-         * Backoff strategy for retries.
-         * - 'exponential': Delay doubles with each retry (1s, 2s, 4s, 8s...)
-         * - 'linear': Fixed delay between retries
-         * @default 'exponential'
-         */
-        backoff?: 'exponential' | 'linear';
-        /**
-         * Initial delay in milliseconds before first retry.
-         * @default 1000
-         */
-        initialDelayMs?: number;
-        /**
-         * Maximum delay in milliseconds between retries.
-         * @default 30000
-         */
-        maxDelayMs?: number;
-        /**
-         * Whether to send failed events to Dead Letter Queue after max retries.
-         * @default false
-         */
-        dlqAfterMaxRetries?: boolean;
-    };
-    /**
-     * Circuit breaker options for this event.
-     */
-    circuitBreaker?: {
-        /**
-         * Number of consecutive failures before opening the circuit.
-         * @default 5
-         */
-        failureThreshold?: number;
-        /**
-         * Time in milliseconds to wait before attempting to close the circuit.
-         * @default 30000
-         */
-        resetTimeout?: number;
-        /**
-         * Number of test requests to allow in half-open state.
-         * @default 3
-         */
-        halfOpenRequests?: number;
-    };
-    /**
-     * Event aggregation configuration (FS-102).
-     * Enables deduplication and micro-batching for improved throughput.
-     * @default undefined (disabled)
-     */
-    aggregation?: {
-        /**
-         * Enable event aggregation.
-         * @default false
-         */
-        enabled?: boolean;
-        /**
-         * Aggregation window size in milliseconds.
-         * Backpressure-aware adjustment: 50-500ms
-         * @default 200
-         */
-        windowMs?: number;
-        /**
-         * Batch size threshold for auto-flush.
-         * @default 50
-         */
-        batchSize?: number;
-        /**
-         * Deduplication strategy.
-         * @default 'pattern'
-         */
-        deduplication?: 'pattern' | 'idempotencyKey' | 'off';
-        /**
-         * Deduplication pattern (string or function).
-         * String: hook-based pattern
-         * Function: custom pattern from event args
-         */
-        pattern?: string | ((args: unknown) => string);
-        /**
-         * Priority merge strategy.
-         * - 'highest': keep highest priority event
-         * - 'earliest': keep earliest event
-         * - 'latest': keep latest event
-         * @default 'highest'
-         */
-        mergePriority?: 'highest' | 'earliest' | 'latest';
-        /**
-         * Enable automatic cleanup of expired entries.
-         * @default true
-         */
-        enableCleanup?: boolean;
-        /**
-         * Cleanup interval in milliseconds.
-         * @default 300000 (5 minutes)
-         */
-        cleanupIntervalMs?: number;
-        /**
-         * TTL for entries in milliseconds.
-         * @default 600000 (10 minutes)
-         */
-        ttlMs?: number;
-    };
-}
-/**
- * Default event options.
- * @internal
- */
-export declare const DEFAULT_EVENT_OPTIONS: Required<EventOptions>;