@jagilber-org/index-server 1.19.1

package/dist/utils/BufferRing.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Configurable Buffer Ring - Generic circular buffer implementation
+ *
+ * Provides a high-performance, memory-efficient circular buffer with configurable
+ * size limits, overflow strategies, and optional persistence support.
+ *
+ * Features:
+ * - Configurable capacity with automatic overflow handling
+ * - Multiple overflow strategies (drop-oldest, drop-newest, resize)
+ * - Optional persistence to disk with atomic writes
+ * - Type-safe generic implementation
+ * - Memory usage tracking and cleanup
+ * - Event notifications for buffer state changes
+ */
+import { EventEmitter } from 'events';
+/**
+ * Buffer overflow strategies
+ */
+export declare enum OverflowStrategy {
+    /** Drop the oldest entries when buffer is full (default) */
+    DROP_OLDEST = "drop-oldest",
+    /** Drop the newest entry when buffer is full */
+    DROP_NEWEST = "drop-newest",
+    /** Resize the buffer to accommodate new entries */
+    RESIZE = "resize",
+    /** Throw an error when buffer is full */
+    ERROR = "error"
+}
+/**
+ * Buffer ring configuration
+ */
+export interface BufferRingConfig {
+    /** Maximum number of entries in the buffer */
+    capacity: number;
+    /** Strategy to use when buffer overflows */
+    overflowStrategy: OverflowStrategy;
+    /** Optional file path for persistence */
+    persistPath?: string;
+    /** Enable automatic persistence on changes */
+    autoPersist: boolean;
+    /** Maximum entries to persist (0 = all) */
+    maxPersistEntries: number;
+    /** Enable integrity checking with checksums */
+    enableIntegrityCheck: boolean;
+    /** Custom serializer for entries */
+    serializer?: <U>(entry: U) => U;
+    /** Custom deserializer for entries */
+    deserializer?: <U>(data: U) => U;
+    /** Suppress persist/load info logs (for high-frequency buffers) */
+    suppressPersistLog?: boolean;
+    /** Append mode (JSONL incremental writes instead of full snapshot rewrites) */
+    appendMode?: boolean;
+}
+/**
+ * Buffer ring statistics
+ */
+export interface BufferRingStats {
+    /** Current number of entries */
+    count: number;
+    /** Maximum capacity */
+    capacity: number;
+    /** Total entries added (including dropped) */
+    totalAdded: number;
+    /** Total entries dropped due to overflow */
+    totalDropped: number;
+    /** Number of buffer resizes */
+    resizeCount: number;
+    /** Memory usage estimate in bytes */
+    memoryUsage: number;
+    /** Last operation timestamp */
+    lastModified: Date;
+    /** Buffer utilization percentage */
+    utilization: number;
+}
+/**
+ * Buffer ring events
+ */
+export interface BufferRingEvents<T> {
+    'entry-added': (entry: T, index: number) => void;
+    'entry-dropped': (entry: T, reason: 'overflow' | 'clear') => void;
+    'buffer-resized': (oldCapacity: number, newCapacity: number) => void;
+    'buffer-full': (capacity: number) => void;
+    'persisted': (path: string, entryCount: number) => void;
+    'loaded': (path: string, entryCount: number) => void;
+    'error': (error: Error, operation: string) => void;
+}
+/**
+ * Generic configurable buffer ring implementation
+ */
+export declare class BufferRing<T = unknown> extends EventEmitter {
+    private buffer;
+    private writeIndex;
+    private isFull;
+    private config;
+    private stats;
+    /** Sequence counter for append mode records */
+    private appendSeq;
+    /** Track whether append mode file has been lazily loaded */
+    private appendLoaded;
+    constructor(config?: Partial<BufferRingConfig>);
+    /**
+     * Add an entry to the buffer
+     */
+    add(entry: T): boolean;
+    /**
+     * Get all entries in chronological order (oldest first)
+     */
+    getAll(): T[];
+    /**
+     * Get the last N entries (newest first)
+     */
+    getLast(n: number): T[];
+    /**
+     * Get the first N entries (oldest first)
+     */
+    getFirst(n: number): T[];
+    /**
+     * Get entries within a range
+     */
+    getRange(start: number, end: number): T[];
+    /**
+     * Filter entries based on predicate
+     */
+    filter(predicate: (entry: T, index: number) => boolean): T[];
+    /**
+     * Find first entry matching predicate
+     */
+    find(predicate: (entry: T, index: number) => boolean): T | undefined;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Resize the buffer capacity
+     */
+    resize(newCapacity: number): void;
+    /**
+     * Get buffer statistics
+     */
+    getStats(): BufferRingStats;
+    /**
+     * Get buffer configuration
+     */
+    getConfig(): BufferRingConfig;
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: Partial<BufferRingConfig>): void;
+    /**
+     * Save buffer to disk
+     */
+    saveToDisk(): Promise<void>;
+    /**
+     * Load buffer from disk
+     */
+    loadFromDisk(): Promise<void>;
+    /**
+     * Append a single entry (JSONL) instead of rewriting full snapshot.
+     * Record shape: { t: ISO timestamp, i: sequence, v: serializedEntry }
+     */
+    private appendToDisk;
+    /**
+     * Synchronous load for append mode (reads JSONL file)
+     */
+    private loadFromAppendSync;
+    /**
+     * Get memory usage estimate
+     */
+    getMemoryUsage(): number;
+    /**
+     * Compact buffer by removing undefined entries
+     */
+    compact(): void;
+    /**
+     * Private helper methods
+     */
+    private deserializeEntry;
+    private updateStats;
+    private estimateMemoryUsage;
+    private computeChecksum;
+}
+/**
+ * Factory function for creating commonly used buffer rings
+ */
+export declare class BufferRingFactory {
+    /**
+     * Create a log buffer ring
+     */
+    static createLogBuffer(capacity?: number, persistPath?: string): BufferRing<string>;
+    /**
+     * Create a metrics buffer ring
+     */
+    static createMetricsBuffer(capacity?: number, persistPath?: string): BufferRing<Record<string, unknown>>;
+    /**
+     * Create an event buffer ring
+     */
+    static createEventBuffer(capacity?: number): BufferRing<Record<string, unknown>>;
+    /**
+     * Create a resizable buffer ring
+     */
+    static createResizableBuffer<T>(initialCapacity?: number, _maxCapacity?: number): BufferRing<T>;
+}
+export default BufferRing;