aicodeman 0.2.8

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

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Centralized resource cleanup manager.
+ *
+ * Tracks timers, intervals, watchers, and other resources that need explicit
+ * cleanup. Provides a unified dispose() method that safely cleans up all
+ * registered resources, even on partial failures.
+ *
+ * @module utils/cleanup-manager
+ */
+import type { Disposable, CleanupRegistration, CleanupResourceType } from '../types.js';
+/**
+ * Options for setTimeout/setInterval with automatic cleanup.
+ */
+export interface TimerOptions {
+    /** Human-readable description for debugging */
+    description?: string;
+}
+/**
+ * Centralized manager for tracking and disposing resources.
+ *
+ * Implements the Disposable interface for hierarchical cleanup.
+ * All registered resources are cleaned up when dispose() is called.
+ *
+ * Features:
+ * - Tracks timers, intervals, watchers, and custom cleanup functions
+ * - isStopped guard to prevent callbacks firing after disposal
+ * - Safe disposal that continues even if individual cleanups fail
+ * - Debug logging for resource tracking
+ *
+ * @example
+ * ```typescript
+ * class MyService implements Disposable {
+ *   private cleanup = new CleanupManager();
+ *
+ *   start() {
+ *     // Timer automatically cleared on dispose
+ *     this.cleanup.setTimeout(() => {
+ *       if (this.cleanup.isStopped) return;  // Guard
+ *       this.doWork();
+ *     }, 5000, { description: 'work timer' });
+ *   }
+ *
+ *   dispose() {
+ *     this.cleanup.dispose();
+ *   }
+ *
+ *   get isDisposed() { return this.cleanup.isDisposed; }
+ * }
+ * ```
+ */
+export declare class CleanupManager implements Disposable {
+    private registrations;
+    private _isDisposed;
+    private readonly debugMode;
+    /**
+     * Creates a new CleanupManager.
+     *
+     * @param debug - Enable debug logging for resource tracking
+     */
+    constructor(debug?: boolean);
+    /**
+     * Whether this manager has been disposed.
+     * Check this before executing callbacks to prevent zombie operations.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Alias for isDisposed - check before executing async callbacks.
+     */
+    get isStopped(): boolean;
+    /**
+     * Number of currently registered resources.
+     */
+    get resourceCount(): number;
+    /**
+     * Get counts by resource type for metrics/debugging.
+     */
+    get resourceCounts(): Record<CleanupResourceType, number>;
+    /**
+     * Schedule a timeout that will be automatically cleared on dispose.
+     *
+     * @param callback - Function to call when timeout fires
+     * @param delay - Delay in milliseconds
+     * @param options - Optional configuration
+     * @returns Timer ID for manual clearing if needed
+     */
+    setTimeout(callback: () => void, delay: number, options?: TimerOptions): string;
+    /**
+     * Schedule an interval that will be automatically cleared on dispose.
+     *
+     * @param callback - Function to call on each interval
+     * @param delay - Interval in milliseconds
+     * @param options - Optional configuration
+     * @returns Interval ID for manual clearing if needed
+     */
+    setInterval(callback: () => void, delay: number, options?: TimerOptions): string;
+    /**
+     * Register a custom cleanup function.
+     *
+     * @param type - Type of resource for categorization
+     * @param cleanup - Function to call on dispose
+     * @param description - Human-readable description
+     * @returns Registration ID for manual removal if needed
+     */
+    registerCleanup(type: CleanupResourceType, cleanup: () => void, description: string): string;
+    /**
+     * Register a file system watcher for cleanup.
+     *
+     * @param watcher - Object with close() method (FSWatcher, chokidar, etc.)
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerWatcher(watcher: {
+        close: () => void;
+    }, description: string): string;
+    /**
+     * Register an event listener for cleanup.
+     *
+     * @param emitter - Object with removeListener/off method
+     * @param event - Event name
+     * @param listener - Listener function
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerListener<T extends {
+        removeListener?: (event: string, listener: () => void) => void;
+        off?: (event: string, listener: () => void) => void;
+    }>(emitter: T, event: string, listener: () => void, description: string): string;
+    /**
+     * Register a stream for cleanup.
+     *
+     * @param stream - Object with destroy() or close() method
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerStream(stream: {
+        destroy?: () => void;
+        close?: () => void;
+    }, description: string): string;
+    /**
+     * Manually remove a registered resource.
+     *
+     * @param id - Registration ID returned from register methods
+     * @returns True if resource was found and removed
+     */
+    unregister(id: string): boolean;
+    /**
+     * Dispose all registered resources.
+     * Safe to call multiple times (idempotent).
+     * Continues cleanup even if individual resources fail.
+     */
+    dispose(): void;
+    /**
+     * Get all current registrations for debugging.
+     */
+    getRegistrations(): CleanupRegistration[];
+    /**
+     * Internal: Register a cleanup entry.
+     */
+    private register;
+    /**
+     * Internal: Debug logging.
+     */
+    private debug;
+}
+//# sourceMappingURL=cleanup-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-manager.d.ts","sourceRoot":"","sources":["../../src/utils/cleanup-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAExF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC;;;;OAIG;gBACS,KAAK,UAAQ;IAIzB;;;OAGG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAcxD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM;IAqB/E;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM;IAmBhF;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAY5F;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAI5E;;;;;;;;OAQG;IACH,gBAAgB,CACd,CAAC,SAAS;QACR,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;QAC/D,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;KACrD,EACD,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAc/E;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAcjG;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAc/B;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA0Bf;;OAEG;IACH,gBAAgB,IAAI,mBAAmB,EAAE;IAIzC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAKhB;;OAEG;IACH,OAAO,CAAC,KAAK;CAKd"}

package/dist/utils/cleanup-manager.js

@@ -0,0 +1,274 @@
+/**
+ * @fileoverview Centralized resource cleanup manager.
+ *
+ * Tracks timers, intervals, watchers, and other resources that need explicit
+ * cleanup. Provides a unified dispose() method that safely cleans up all
+ * registered resources, even on partial failures.
+ *
+ * @module utils/cleanup-manager
+ */
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Centralized manager for tracking and disposing resources.
+ *
+ * Implements the Disposable interface for hierarchical cleanup.
+ * All registered resources are cleaned up when dispose() is called.
+ *
+ * Features:
+ * - Tracks timers, intervals, watchers, and custom cleanup functions
+ * - isStopped guard to prevent callbacks firing after disposal
+ * - Safe disposal that continues even if individual cleanups fail
+ * - Debug logging for resource tracking
+ *
+ * @example
+ * ```typescript
+ * class MyService implements Disposable {
+ *   private cleanup = new CleanupManager();
+ *
+ *   start() {
+ *     // Timer automatically cleared on dispose
+ *     this.cleanup.setTimeout(() => {
+ *       if (this.cleanup.isStopped) return;  // Guard
+ *       this.doWork();
+ *     }, 5000, { description: 'work timer' });
+ *   }
+ *
+ *   dispose() {
+ *     this.cleanup.dispose();
+ *   }
+ *
+ *   get isDisposed() { return this.cleanup.isDisposed; }
+ * }
+ * ```
+ */
+export class CleanupManager {
+    registrations = new Map();
+    _isDisposed = false;
+    debugMode;
+    /**
+     * Creates a new CleanupManager.
+     *
+     * @param debug - Enable debug logging for resource tracking
+     */
+    constructor(debug = false) {
+        this.debugMode = debug;
+    }
+    /**
+     * Whether this manager has been disposed.
+     * Check this before executing callbacks to prevent zombie operations.
+     */
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Alias for isDisposed - check before executing async callbacks.
+     */
+    get isStopped() {
+        return this._isDisposed;
+    }
+    /**
+     * Number of currently registered resources.
+     */
+    get resourceCount() {
+        return this.registrations.size;
+    }
+    /**
+     * Get counts by resource type for metrics/debugging.
+     */
+    get resourceCounts() {
+        const counts = {
+            timer: 0,
+            interval: 0,
+            watcher: 0,
+            listener: 0,
+            stream: 0,
+        };
+        for (const reg of this.registrations.values()) {
+            counts[reg.type]++;
+        }
+        return counts;
+    }
+    /**
+     * Schedule a timeout that will be automatically cleared on dispose.
+     *
+     * @param callback - Function to call when timeout fires
+     * @param delay - Delay in milliseconds
+     * @param options - Optional configuration
+     * @returns Timer ID for manual clearing if needed
+     */
+    setTimeout(callback, delay, options) {
+        const id = uuidv4();
+        const timeoutId = setTimeout(() => {
+            // Remove registration when timer fires naturally
+            this.registrations.delete(id);
+            // Don't execute if already stopped
+            if (this._isDisposed)
+                return;
+            callback();
+        }, delay);
+        this.register({
+            id,
+            type: 'timer',
+            description: options?.description || `setTimeout(${delay}ms)`,
+            cleanup: () => clearTimeout(timeoutId),
+            registeredAt: Date.now(),
+        });
+        return id;
+    }
+    /**
+     * Schedule an interval that will be automatically cleared on dispose.
+     *
+     * @param callback - Function to call on each interval
+     * @param delay - Interval in milliseconds
+     * @param options - Optional configuration
+     * @returns Interval ID for manual clearing if needed
+     */
+    setInterval(callback, delay, options) {
+        const id = uuidv4();
+        const intervalId = setInterval(() => {
+            // Don't execute if stopped
+            if (this._isDisposed)
+                return;
+            callback();
+        }, delay);
+        this.register({
+            id,
+            type: 'interval',
+            description: options?.description || `setInterval(${delay}ms)`,
+            cleanup: () => clearInterval(intervalId),
+            registeredAt: Date.now(),
+        });
+        return id;
+    }
+    /**
+     * Register a custom cleanup function.
+     *
+     * @param type - Type of resource for categorization
+     * @param cleanup - Function to call on dispose
+     * @param description - Human-readable description
+     * @returns Registration ID for manual removal if needed
+     */
+    registerCleanup(type, cleanup, description) {
+        const id = uuidv4();
+        this.register({
+            id,
+            type,
+            description,
+            cleanup,
+            registeredAt: Date.now(),
+        });
+        return id;
+    }
+    /**
+     * Register a file system watcher for cleanup.
+     *
+     * @param watcher - Object with close() method (FSWatcher, chokidar, etc.)
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerWatcher(watcher, description) {
+        return this.registerCleanup('watcher', () => watcher.close(), description);
+    }
+    /**
+     * Register an event listener for cleanup.
+     *
+     * @param emitter - Object with removeListener/off method
+     * @param event - Event name
+     * @param listener - Listener function
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerListener(emitter, event, listener, description) {
+        return this.registerCleanup('listener', () => {
+            if (emitter.removeListener) {
+                emitter.removeListener(event, listener);
+            }
+            else if (emitter.off) {
+                emitter.off(event, listener);
+            }
+        }, description);
+    }
+    /**
+     * Register a stream for cleanup.
+     *
+     * @param stream - Object with destroy() or close() method
+     * @param description - Human-readable description
+     * @returns Registration ID
+     */
+    registerStream(stream, description) {
+        return this.registerCleanup('stream', () => {
+            if (stream.destroy) {
+                stream.destroy();
+            }
+            else if (stream.close) {
+                stream.close();
+            }
+        }, description);
+    }
+    /**
+     * Manually remove a registered resource.
+     *
+     * @param id - Registration ID returned from register methods
+     * @returns True if resource was found and removed
+     */
+    unregister(id) {
+        const reg = this.registrations.get(id);
+        if (!reg)
+            return false;
+        try {
+            reg.cleanup();
+        }
+        catch (err) {
+            this.debug(`Error cleaning up ${reg.type} "${reg.description}": ${err}`);
+        }
+        this.registrations.delete(id);
+        return true;
+    }
+    /**
+     * Dispose all registered resources.
+     * Safe to call multiple times (idempotent).
+     * Continues cleanup even if individual resources fail.
+     */
+    dispose() {
+        if (this._isDisposed)
+            return;
+        this._isDisposed = true;
+        const errors = [];
+        for (const reg of this.registrations.values()) {
+            try {
+                reg.cleanup();
+                this.debug(`Cleaned up ${reg.type}: ${reg.description}`);
+            }
+            catch (err) {
+                errors.push({ description: reg.description, error: err });
+                this.debug(`Error cleaning up ${reg.type} "${reg.description}": ${err}`);
+            }
+        }
+        this.registrations.clear();
+        if (errors.length > 0) {
+            console.error(`[CleanupManager] ${errors.length} errors during disposal:`, errors.map((e) => e.description).join(', '));
+        }
+    }
+    /**
+     * Get all current registrations for debugging.
+     */
+    getRegistrations() {
+        return Array.from(this.registrations.values());
+    }
+    /**
+     * Internal: Register a cleanup entry.
+     */
+    register(reg) {
+        this.registrations.set(reg.id, reg);
+        this.debug(`Registered ${reg.type}: ${reg.description}`);
+    }
+    /**
+     * Internal: Debug logging.
+     */
+    debug(message) {
+        if (this.debugMode) {
+            console.log(`[CleanupManager] ${message}`);
+        }
+    }
+}
+//# sourceMappingURL=cleanup-manager.js.map

package/dist/utils/cleanup-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-manager.js","sourceRoot":"","sources":["../../src/utils/cleanup-manager.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Utility module exports.
+ *
+ * This module re-exports all utility classes and functions for easy import.
+ *
+ * @module utils
+ */
+export { BufferAccumulator } from './buffer-accumulator.js';
+export { LRUMap, type LRUMapOptions } from './lru-map.js';
+export { CleanupManager, type TimerOptions } from './cleanup-manager.js';
+export { StaleExpirationMap, type StaleExpirationMapOptions } from './stale-expiration-map.js';
+export { ANSI_ESCAPE_PATTERN_FULL, ANSI_ESCAPE_PATTERN_SIMPLE, TOKEN_PATTERN, SPINNER_PATTERN, } from './regex-patterns.js';
+export { MAX_SESSION_TOKENS } from './token-validation.js';
+export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
+export { assertNever } from './type-safety.js';
+export { wrapWithNice } from './nice-wrapper.js';
+export { findClaudeDir, getAugmentedPath } from './claude-cli-resolver.js';
+export { resolveOpenCodeDir, isOpenCodeAvailable } from './opencode-cli-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Utility module exports.
+ *
+ * This module re-exports all utility classes and functions for easy import.
+ *
+ * @module utils
+ */
+export { BufferAccumulator } from './buffer-accumulator.js';
+export { LRUMap } from './lru-map.js';
+export { CleanupManager } from './cleanup-manager.js';
+export { StaleExpirationMap } from './stale-expiration-map.js';
+export { ANSI_ESCAPE_PATTERN_FULL, ANSI_ESCAPE_PATTERN_SIMPLE, TOKEN_PATTERN, SPINNER_PATTERN, } from './regex-patterns.js';
+export { MAX_SESSION_TOKENS } from './token-validation.js';
+export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
+export { assertNever } from './type-safety.js';
+export { wrapWithNice } from './nice-wrapper.js';
+export { findClaudeDir, getAugmentedPath } from './claude-cli-resolver.js';
+export { resolveOpenCodeDir, isOpenCodeAvailable } from './opencode-cli-resolver.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAsB,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAqB,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAkC,MAAM,2BAA2B,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/utils/lru-map.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview LRU (Least Recently Used) Map implementation.
+ *
+ * Extends the built-in Map with automatic eviction when a maximum size is
+ * exceeded. Uses Map's insertion-order iteration for O(1) LRU eviction.
+ *
+ * @module utils/lru-map
+ */
+/**
+ * Configuration options for LRUMap.
+ */
+export interface LRUMapOptions<K, V> {
+    /** Maximum number of entries before eviction */
+    maxSize: number;
+    /** Optional callback when an entry is evicted */
+    onEvict?: (key: K, value: V) => void;
+}
+/**
+ * A Map with automatic LRU (Least Recently Used) eviction.
+ *
+ * When the map exceeds maxSize, the oldest entries are evicted.
+ * Access via get() refreshes an entry's position (moves to most recent).
+ *
+ * Uses JavaScript Map's insertion-order guarantee for efficient LRU behavior.
+ * All operations are O(1) amortized.
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUMap<string, number>({
+ *   maxSize: 100,
+ *   onEvict: (key, value) => console.log(`Evicted ${key}`)
+ * });
+ *
+ * cache.set('a', 1);
+ * cache.set('b', 2);
+ * cache.get('a');  // Refreshes 'a', making 'b' the oldest
+ * // When full, 'b' would be evicted first
+ * ```
+ */
+export declare class LRUMap<K, V> extends Map<K, V> {
+    private readonly maxSize;
+    private readonly onEvict?;
+    /** Tracks the newest key for O(1) newest() access */
+    private _newestKey;
+    /**
+     * Creates a new LRUMap.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: LRUMapOptions<K, V>);
+    /**
+     * Set a key-value pair.
+     * If key exists, updates value and refreshes position.
+     * If adding new entry would exceed maxSize, evicts oldest entries.
+     *
+     * @param key - Key to set
+     * @param value - Value to associate
+     * @returns this (for chaining)
+     */
+    set(key: K, value: V): this;
+    /**
+     * Get a value and refresh its position (mark as most recently used).
+     *
+     * @param key - Key to look up
+     * @returns Value if found, undefined otherwise
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if a key exists WITHOUT refreshing its position.
+     * Use this when you want to check existence without affecting LRU order.
+     *
+     * @param key - Key to check
+     * @returns True if key exists
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key-value pair.
+     * Updates _newestKey if the deleted key was the newest.
+     *
+     * @param key - Key to delete
+     * @returns True if the key existed and was deleted
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries.
+     * Resets _newestKey to undefined.
+     */
+    clear(): void;
+    /**
+     * Peek at a value WITHOUT refreshing its position.
+     * Use this when you want to read without affecting LRU order.
+     *
+     * @param key - Key to peek
+     * @returns Value if found, undefined otherwise
+     */
+    peek(key: K): V | undefined;
+    /**
+     * Get the oldest entry (next to be evicted) without removing it.
+     *
+     * @returns [key, value] of oldest entry, or undefined if empty
+     */
+    oldest(): [K, V] | undefined;
+    /**
+     * Get the newest entry (most recently accessed).
+     * O(1) operation using tracked newest key.
+     *
+     * @returns [key, value] of newest entry, or undefined if empty
+     */
+    newest(): [K, V] | undefined;
+    /**
+     * Evict entries older than a specific timestamp.
+     * Assumes values have a timestamp property or are numbers representing time.
+     *
+     * @param maxAge - Maximum age in milliseconds
+     * @param getTimestamp - Function to extract timestamp from value
+     * @returns Number of entries evicted
+     */
+    expireOlderThan(maxAge: number, getTimestamp: (value: V) => number): number;
+    /**
+     * Get all keys in order from oldest to newest.
+     *
+     * @returns Array of keys
+     */
+    keysInOrder(): K[];
+    /**
+     * Get all values in order from oldest to newest.
+     *
+     * @returns Array of values
+     */
+    valuesInOrder(): V[];
+    /**
+     * Get the maximum size limit.
+     */
+    get maxEntries(): number;
+    /**
+     * Get the number of free slots before eviction would occur.
+     */
+    get freeSlots(): number;
+}
+//# sourceMappingURL=lru-map.d.ts.map

package/dist/utils/lru-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-map.d.ts","sourceRoot":"","sources":["../../src/utils/lru-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC;IACjC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,MAAM,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA6B;IACtD,qDAAqD;IACrD,OAAO,CAAC,UAAU,CAA4B;IAE9C;;;;OAIG;gBACS,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC;IAMxC;;;;;;;;OAQG;IACM,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAwBpC;;;;;OAKG;IACM,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAcnC;;;;;;OAMG;IACM,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAI7B;;;;;;OAMG;IACM,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAchC;;;OAGG;IACM,KAAK,IAAI,IAAI;IAKtB;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAI3B;;;;OAIG;IACH,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAM5B;;;;;OAKG;IACH,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAS5B;;;;;;;OAOG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM;IAkC3E;;;;OAIG;IACH,WAAW,IAAI,CAAC,EAAE;IAIlB;;;;OAIG;IACH,aAAa,IAAI,CAAC,EAAE;IAIpB;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}