safe-memory-layer 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,650 @@
+/**
+ * Core type definitions for safe-memory-layer.
+ *
+ * @module types
+ */
+/** Strategy to use when the store reaches its maximum entry limit. */
+type MaxEntriesStrategy = "reject" | "FIFO" | "LRU";
+/** Options for setting an individual entry. */
+interface SetOptions {
+    /** Time-to-live in milliseconds. After this duration, the entry expires. */
+    ttl?: number;
+}
+/** Configuration options for creating a MemoryStore. */
+interface MemoryStoreOptions<K, V> {
+    /** Default TTL in milliseconds for all entries (default: no expiration). */
+    defaultTTL?: number;
+    /** Interval in milliseconds between automatic cleanup runs (default: 10000). */
+    cleanupInterval?: number;
+    /** Whether to automatically run cleanup on an interval (default: true). */
+    autoCleanup?: boolean;
+    /** Whether to automatically dispose the store after being empty for a configurable time (default: false). */
+    autoDispose?: boolean;
+    /** Time in milliseconds to wait after empty before auto-disposing (default: 60000). */
+    autoDisposeDelay?: number;
+    /** Maximum number of entries allowed in the store (default: no limit). */
+    maxEntries?: number;
+    /** Strategy when max entries is reached (default: "reject"). */
+    maxEntriesStrategy?: MaxEntriesStrategy;
+    /** Callback invoked when an entry expires. */
+    onExpire?: (key: K, value: V) => void;
+    /** Callback invoked when an entry is deleted. */
+    onDelete?: (key: K, value: V) => void;
+    /** Callback invoked after a cleanup cycle completes. */
+    onCleanup?: (stats: CleanupStats) => void;
+}
+/** Statistics about a cleanup cycle. */
+interface CleanupStats {
+    /** Number of entries removed during cleanup. */
+    removed: number;
+    /** Total number of entries before cleanup. */
+    totalBefore: number;
+    /** Total number of entries after cleanup. */
+    totalAfter: number;
+    /** Duration of the cleanup cycle in milliseconds. */
+    duration: number;
+}
+/** Statistics about the store. */
+interface StoreStats {
+    /** Current number of entries in the store. */
+    entries: number;
+    /** Total number of entries that have expired. */
+    expired: number;
+    /** Total number of entries that have been deleted. */
+    deleted: number;
+    /** Total number of cleanup cycles completed. */
+    cleaned: number;
+    /** Uptime of the store in milliseconds. */
+    uptime: number;
+    /** Estimated memory usage in bytes (approximate). */
+    memoryEstimate: number;
+}
+/** Internal entry stored in the map. */
+interface InternalEntry<K, V> {
+    /** The stored value. */
+    value: V;
+    /** The key (stored for cleanup callbacks). */
+    key: K;
+    /** Expiration timestamp (ms since epoch), or undefined if no expiration. */
+    expiresAt: number | undefined;
+    /** Timestamp of last access (for LRU). */
+    lastAccessed: number;
+    /** Timestamp of creation. */
+    createdAt: number;
+}
+/** Internal options for the MemoryStore constructor. */
+interface InternalStoreOptions<K, V> {
+    defaultTTL: number | undefined;
+    cleanupInterval: number;
+    autoCleanup: boolean;
+    autoDispose: boolean;
+    autoDisposeDelay: number;
+    maxEntries: number | undefined;
+    maxEntriesStrategy: MaxEntriesStrategy;
+    onExpire: ((key: K, value: V) => void) | undefined;
+    onDelete: ((key: K, value: V) => void) | undefined;
+    onCleanup: ((stats: CleanupStats) => void) | undefined;
+}
+/** Options for WeakMemoryStore. */
+interface WeakMemoryStoreOptions<V> {
+    /** Callback invoked when an entry is deleted. */
+    onDelete?: (value: V) => void;
+}
+/** Feature detection result for FinalizationRegistry. */
+interface FeatureSupport {
+    /** Whether FinalizationRegistry is available. */
+    finalizationRegistry: boolean;
+}
+
+/**
+ * Main MemoryStore implementation for safe-memory-layer.
+ *
+ * Provides a secure, lightweight, dependency-free abstraction for storing
+ * temporary in-memory data with TTL support, automatic cleanup, and
+ * memory leak prevention.
+ *
+ * @module MemoryStore
+ */
+
+/**
+ * A secure, high-performance in-memory store with TTL support,
+ * automatic cleanup, and memory leak prevention.
+ *
+ * @typeParam K - The type of keys stored in the map.
+ * @typeParam V - The type of values stored in the map.
+ *
+ * @example
+ * ```ts
+ * const store = new MemoryStore<string, User>();
+ *
+ * // Set with TTL
+ * store.set("user:123", user, { ttl: 60000 });
+ *
+ * // Get
+ * const user = store.get("user:123");
+ * ```
+ */
+declare class MemoryStore<K, V> implements Iterable<[K, V]> {
+    #private;
+    /**
+     * Creates a new MemoryStore instance.
+     *
+     * @param options - Configuration options for the store.
+     *
+     * @example
+     * ```ts
+     * const store = new MemoryStore({
+     *   defaultTTL: 60000,
+     *   cleanupInterval: 5000,
+     *   autoCleanup: true,
+     *   maxEntries: 1000,
+     *   maxEntriesStrategy: "LRU"
+     * });
+     * ```
+     */
+    constructor(options?: MemoryStoreOptions<K, V>);
+    /**
+     * Stores a value with the given key.
+     *
+     * @param key - The key to store the value under.
+     * @param value - The value to store.
+     * @param options - Optional settings (e.g., TTL).
+     * @returns True if the value was stored, false if rejected (e.g., max entries reached).
+     *
+     * @example
+     * ```ts
+     * store.set("token", token, { ttl: 60000 });
+     * ```
+     */
+    set(key: K, value: V, options?: SetOptions): boolean;
+    /**
+     * Retrieves a value by key.
+     *
+     * @param key - The key to look up.
+     * @returns The value if found and not expired, undefined otherwise.
+     *
+     * @example
+     * ```ts
+     * const user = store.get("user:123");
+     * ```
+     */
+    get(key: K): V | undefined;
+    /**
+     * Checks if a key exists in the store and is not expired.
+     *
+     * @param key - The key to check.
+     * @returns True if the key exists and is not expired.
+     */
+    has(key: K): boolean;
+    /**
+     * Deletes a value by key.
+     *
+     * @param key - The key to delete.
+     * @returns True if the key was present, false otherwise.
+     */
+    delete(key: K): boolean;
+    /**
+     * Removes all entries from the store.
+     */
+    clear(): void;
+    /**
+     * Returns the number of entries in the store.
+     * Excludes expired entries.
+     */
+    get size(): number;
+    /**
+     * Returns an iterator of all keys.
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterator of all values.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Returns an iterator of all [key, value] pairs.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterator for the store (for...of support).
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Runs a cleanup cycle, removing all expired entries.
+     *
+     * @returns The number of entries removed.
+     */
+    cleanup(): number;
+    /**
+     * Compacts the store by removing expired entries.
+     * Alias for cleanup().
+     */
+    compact(): number;
+    /**
+     * Returns statistics about the store.
+     *
+     * @returns A snapshot of the current statistics.
+     */
+    stats(): StoreStats;
+    /**
+     * Disposes the store, stopping all timers and releasing references.
+     * After disposal, the store cannot be used.
+     */
+    dispose(): void;
+    /**
+     * Checks if the store has been disposed.
+     */
+    get disposed(): boolean;
+}
+
+/**
+ * WeakMemoryStore implementation for safe-memory-layer.
+ *
+ * Provides an object-only storage layer using WeakMap internally.
+ * Objects disappear automatically after garbage collection.
+ * No iteration, no manual cleanup required.
+ *
+ * @module WeakMemoryStore
+ */
+
+/**
+ * A memory store that uses WeakMap for object-only storage.
+ *
+ * Keys must be objects. Values are held weakly and will be
+ * automatically garbage collected when no longer referenced elsewhere.
+ *
+ * **Limitations:**
+ * - Keys must be objects (not primitives)
+ * - No iteration support (WeakMap is not iterable)
+ * - No size property
+ * - No TTL support
+ * - No automatic cleanup needed
+ *
+ * @typeParam V - The type of values stored in the map.
+ *
+ * @example
+ * ```ts
+ * const weakStore = new WeakMemoryStore<User>();
+ *
+ * const user = { id: 1, name: "Alice" };
+ * weakStore.set(user, userData);
+ *
+ * // When 'user' is no longer referenced, the entry is automatically removed
+ * ```
+ */
+declare class WeakMemoryStore<V> {
+    #private;
+    /**
+     * Creates a new WeakMemoryStore instance.
+     *
+     * @param options - Configuration options for the store.
+     *
+     * @example
+     * ```ts
+     * const store = new WeakMemoryStore({
+     *   onDelete: (value) => console.log("Deleted:", value)
+     * });
+     * ```
+     */
+    constructor(options?: WeakMemoryStoreOptions<V>);
+    /**
+     * Stores a value with the given object key.
+     *
+     * @param key - The object key to store the value under. Must be an object.
+     * @param value - The value to store.
+     * @returns True if the value was stored.
+     *
+     * @example
+     * ```ts
+     * const obj = { id: 1 };
+     * weakStore.set(obj, { name: "Alice" });
+     * ```
+     */
+    set(key: object, value: V): boolean;
+    /**
+     * Retrieves a value by object key.
+     *
+     * @param key - The object key to look up.
+     * @returns The value if found, undefined otherwise.
+     *
+     * @example
+     * ```ts
+     * const user = weakStore.get(obj);
+     * ```
+     */
+    get(key: object): V | undefined;
+    /**
+     * Checks if a key exists in the store.
+     *
+     * @param key - The object key to check.
+     * @returns True if the key exists.
+     */
+    has(key: object): boolean;
+    /**
+     * Deletes a value by object key.
+     *
+     * @param key - The object key to delete.
+     * @returns True if the key was present, false otherwise.
+     */
+    delete(key: object): boolean;
+    /**
+     * Removes all entries from the store.
+     * Note: This does not prevent garbage collection of the keys.
+     */
+    clear(): void;
+    /**
+     * Returns the number of deleted entries.
+     * Note: Cannot return current size (WeakMap limitation).
+     */
+    get deleted(): number;
+    /**
+     * Returns statistics about the store.
+     * Note: entries count is not available for WeakMap.
+     *
+     * @returns A snapshot of the current statistics.
+     */
+    stats(): {
+        deleted: number;
+        uptime: number;
+    };
+    /**
+     * Disposes the store, releasing the WeakMap reference.
+     * After disposal, the store cannot be used.
+     */
+    dispose(): void;
+    /**
+     * Checks if the store has been disposed.
+     */
+    get disposed(): boolean;
+}
+
+/**
+ * Scheduler for automatic cleanup of expired entries.
+ *
+ * Design:
+ * - Single interval timer for all cleanup operations
+ * - Automatically stops when the store is empty to save CPU
+ * - Restarts when new entries are added
+ * - Very low CPU usage with configurable interval
+ *
+ * @module Scheduler
+ */
+/**
+ * Function type for cleanup callbacks.
+ * Returns the number of entries that were cleaned up.
+ */
+type CleanupFn = () => number;
+/**
+ * Manages a periodic cleanup scheduler.
+ * Stops automatically when empty, restarts when needed.
+ */
+declare class Scheduler {
+    #private;
+    /**
+     * Creates a new Scheduler.
+     *
+     * @param cleanupFn - Function to call for cleanup. Should return count of removed entries.
+     * @param interval - Interval in milliseconds between cleanup runs.
+     * @param onEmpty - Optional callback when cleanup finds the store empty.
+     */
+    constructor(cleanupFn: CleanupFn, interval: number, onEmpty?: () => void);
+    /**
+     * Starts the scheduler if it's not already running.
+     * Does nothing if already started.
+     */
+    start(): void;
+    /**
+     * Stops the scheduler if running.
+     * Safe to call multiple times.
+     */
+    stop(): void;
+    /**
+     * Restarts the scheduler (stops then starts).
+     */
+    restart(): void;
+    /**
+     * Whether the scheduler is currently running.
+     */
+    get running(): boolean;
+    /**
+     * Disposes the scheduler, stopping it and releasing all references.
+     */
+    dispose(): void;
+}
+
+/**
+ * Statistics tracking for safe-memory-layer.
+ *
+ * Tracks store metrics including entry counts, expiration counts,
+ * deletion counts, cleanup cycles, uptime, and memory estimates.
+ *
+ * @module Stats
+ */
+
+/**
+ * Tracks statistics for a MemoryStore instance.
+ *
+ * All counters are monotonically increasing (except entries).
+ */
+declare class Stats {
+    #private;
+    /**
+     * Creates a new Stats instance.
+     *
+     * @param createdAt - Timestamp when the store was created.
+     */
+    constructor(createdAt: number);
+    /**
+     * Increments the expired counter.
+     */
+    incrementExpired(): void;
+    /**
+     * Increments the deleted counter.
+     */
+    incrementDeleted(): void;
+    /**
+     * Increments the cleaned counter.
+     */
+    incrementCleaned(): void;
+    /**
+     * Sets the current number of entries.
+     *
+     * @param count - The current entry count.
+     */
+    setEntries(count: number): void;
+    /**
+     * Returns the current statistics snapshot.
+     *
+     * @param currentEntries - Current number of entries (overrides internal count).
+     * @returns A snapshot of the current statistics.
+     */
+    snapshot(currentEntries?: number): StoreStats;
+    /**
+     * Creates a cleanup stats object.
+     *
+     * @param removed - Number of entries removed.
+     * @param totalBefore - Total entries before cleanup.
+     * @param totalAfter - Total entries after cleanup.
+     * @param duration - Duration of cleanup in ms.
+     * @returns A CleanupStats object.
+     */
+    createCleanupStats(removed: number, totalBefore: number, totalAfter: number, duration: number): CleanupStats;
+    /**
+     * Estimates memory usage based on entry count.
+     * This is a rough approximation for monitoring purposes.
+     *
+     * @param entryCount - Number of entries.
+     * @returns Estimated memory usage in bytes.
+     */
+    estimateMemory(entryCount: number): number;
+    /**
+     * Resets all statistics.
+     */
+    reset(): void;
+}
+
+/**
+ * Event handling utilities for safe-memory-layer.
+ *
+ * Provides type-safe event emission with error isolation.
+ * All callbacks are wrapped to prevent crashes from propagating.
+ *
+ * @module Events
+ */
+
+/**
+ * Type-safe event emitter for store events.
+ * All callbacks are error-isolated.
+ */
+declare class EventEmitter<K, V> {
+    #private;
+    /**
+     * Registers a listener for the expire event.
+     *
+     * @param callback - Function to call when an entry expires.
+     */
+    onExpire(callback: (key: K, value: V) => void): void;
+    /**
+     * Registers a listener for the delete event.
+     *
+     * @param callback - Function to call when an entry is deleted.
+     */
+    onDelete(callback: (key: K, value: V) => void): void;
+    /**
+     * Registers a listener for the cleanup event.
+     *
+     * @param callback - Function to call after cleanup completes.
+     */
+    onCleanup(callback: (stats: CleanupStats) => void): void;
+    /**
+     * Emits an expire event to all registered listeners.
+     * Errors in callbacks are isolated and logged.
+     *
+     * @param key - The key of the expired entry.
+     * @param value - The value of the expired entry.
+     */
+    emitExpire(key: K, value: V): void;
+    /**
+     * Emits a delete event to all registered listeners.
+     * Errors in callbacks are isolated and logged.
+     *
+     * @param key - The key of the deleted entry.
+     * @param value - The value of the deleted entry.
+     */
+    emitDelete(key: K, value: V): void;
+    /**
+     * Emits a cleanup event to all registered listeners.
+     * Errors in callbacks are isolated and logged.
+     *
+     * @param stats - The cleanup statistics.
+     */
+    emitCleanup(stats: CleanupStats): void;
+    /**
+     * Removes all event listeners.
+     */
+    removeAllListeners(): void;
+    /**
+     * Disposes the event emitter, removing all listeners.
+     */
+    dispose(): void;
+}
+
+/**
+ * Entry type and factory for safe-memory-layer.
+ *
+ * Represents a single entry in the memory store with expiration tracking.
+ *
+ * @module Entry
+ */
+
+/**
+ * Creates a new internal entry with the given value and options.
+ *
+ * @param key - The key for this entry.
+ * @param value - The value to store.
+ * @param options - Optional settings including TTL.
+ * @param now - Current timestamp (for testability).
+ * @returns A new InternalEntry instance.
+ */
+declare function createEntry<K, V>(key: K, value: V, options?: SetOptions, now?: number): InternalEntry<K, V>;
+/**
+ * Checks whether an entry has expired.
+ *
+ * @param entry - The entry to check.
+ * @param now - Current timestamp (for testability).
+ * @returns True if the entry has expired.
+ */
+declare function isExpired<K, V>(entry: InternalEntry<K, V>, now?: number): boolean;
+/**
+ * Updates the last accessed timestamp on an entry.
+ * Uses a monotonic counter to ensure unique LRU ordering.
+ *
+ * @param entry - The entry to update.
+ * @param now - Current timestamp (for testability).
+ */
+declare function touchEntry<K, V>(entry: InternalEntry<K, V>, now?: number): void;
+/**
+ * Calculates the remaining TTL in milliseconds.
+ *
+ * @param entry - The entry to check.
+ * @param now - Current timestamp (for testability).
+ * @returns Remaining milliseconds, or undefined if no expiration.
+ */
+declare function getRemainingTTL<K, V>(entry: InternalEntry<K, V>, now?: number): number | undefined;
+
+/**
+ * Safe timer utilities for safe-memory-layer.
+ *
+ * Provides platform-agnostic timer creation and cleanup.
+ * Uses only Web-compatible APIs (setTimeout/clearTimeout).
+ *
+ * @module utils/timer
+ */
+/** Represents a timer handle that can be cancelled. */
+interface TimerHandle {
+    /** Cancels the timer. Safe to call multiple times. */
+    cancel: () => void;
+    /** Whether the timer has been cancelled. */
+    readonly cancelled: boolean;
+}
+/**
+ * Creates a safe timer that can be cancelled.
+ * Uses setTimeout internally for maximum compatibility.
+ *
+ * @param fn - The function to execute after the delay.
+ * @param delay - The delay in milliseconds.
+ * @returns A TimerHandle that can be used to cancel the timer.
+ */
+declare function createTimer(fn: () => void, delay: number): TimerHandle;
+/**
+ * Creates an interval timer that runs a function repeatedly.
+ *
+ * @param fn - The function to execute on each interval.
+ * @param interval - The interval in milliseconds.
+ * @returns A TimerHandle that can be used to cancel the interval.
+ */
+declare function createInterval(fn: () => void, interval: number): TimerHandle;
+
+/**
+ * Feature detection utilities for safe-memory-layer.
+ *
+ * Detects available platform features and provides graceful fallbacks.
+ *
+ * @module utils/featureDetection
+ */
+
+/**
+ * Detects which platform features are available.
+ * This is called once at module load time and cached.
+ */
+declare function detectFeatures(): FeatureSupport;
+/**
+ * Returns the cached feature support flags, detecting them on first call.
+ */
+declare function getFeatures(): FeatureSupport;
+/**
+ * Creates a FinalizationRegistry if available, otherwise returns null.
+ * Never throws if FinalizationRegistry is unavailable.
+ */
+declare function createSafeFinalizationRegistry<T>(cleanup: (heldValue: T) => void): FinalizationRegistry<T> | null;
+
+export { type CleanupFn, type CleanupStats, EventEmitter, type FeatureSupport, type InternalEntry, type InternalStoreOptions, type MaxEntriesStrategy, MemoryStore, type MemoryStoreOptions, Scheduler, type SetOptions, Stats, type StoreStats, type TimerHandle, WeakMemoryStore, type WeakMemoryStoreOptions, createEntry, createInterval, createSafeFinalizationRegistry, createTimer, detectFeatures, getFeatures, getRemainingTTL, isExpired, touchEntry };