@fanboynz/network-scanner 2.0.66 → 3.0.0

package/lib/domain-cache.js

@@ -12,24 +12,33 @@ class DomainCache {
   constructor(options = {}) {
     // V8 Optimization: Initialize all properties in constructor for stable hidden class
     this.cache = new Set();
-    
+
     // V8 Optimization: Use consistent object shape (no dynamic property addition)
-    this.stats = {
-      totalDetected: 0,
-      totalSkipped: 0,
-      cacheHits: 0,
-      cacheMisses: 0
-    };
-    
+    this.stats = this._freshStats();
+
     // V8 Optimization: Store options directly instead of nested object for faster property access
     this.enableLogging = options.enableLogging || false;
     this.logPrefix = options.logPrefix || '[domain-cache]';
     this.maxCacheSize = options.maxCacheSize || 10000; // Prevent memory leaks
-    
+
     // V8 Optimization: Pre-calculate 90% target to avoid repeated Math.floor
     this.targetCacheSize = Math.floor(this.maxCacheSize * 0.9);
   }
 
+  /**
+   * Canonical stats shape. Centralized so the constructor and clear() can't
+   * drift if a new counter is added later.
+   * @private
+   */
+  _freshStats() {
+    return {
+      totalDetected: 0,
+      totalSkipped: 0,
+      cacheHits: 0,
+      cacheMisses: 0
+    };
+  }
+
   /**
    * Check if a domain was already detected in a previous scan
    * @param {string} domain - Domain to check
@@ -61,8 +70,10 @@ class DomainCache {
   }
 
   /**
-   * Mark a domain as detected for future reference
+   * Mark a domain as detected for future reference.
    * @param {string} domain - Domain to mark as detected
+   * @returns {boolean} True if the domain was newly added; false if it was
+   *   already present or the input was invalid (not a non-empty string)
    */
   markDomainAsDetected(domain) {
     if (!domain || typeof domain !== 'string') {
@@ -80,22 +91,23 @@ class DomainCache {
       }
     }
     
-    // Check size AFTER adding to prevent race where multiple threads see same size
-    // and all trigger cleanup before any adds complete
-    // V8 Optimization: Use pre-calculated targetCacheSize
+    // Check size after the add so an overflow only fires eviction once per
+    // overflowing call (using targetCacheSize precomputed in the constructor).
     if (this.cache.size > this.maxCacheSize) {
       const toRemove = this.cache.size - this.targetCacheSize;
       if (toRemove > 0) {
         this.clearOldestEntries(toRemove);
       }
     }
-    
+
     return wasNew;
   }
 
   /**
-   * Atomically check if domain was detected and mark it if new (race-condition free)
-   * This method combines isDomainAlreadyDetected + markDomainAsDetected in one atomic operation
+   * Combined check-and-mark in one pass. Functionally equivalent to
+   * isDomainAlreadyDetected() followed by markDomainAsDetected(), but with
+   * one Set.has() call instead of two. (JS is single-threaded so all three
+   * variants are individually atomic; this one is just cheaper.)
    * @param {string} domain - Domain to check and potentially mark
    * @returns {boolean} True if domain was ALREADY detected (should skip), false if NEW (should process)
    */
@@ -127,23 +139,22 @@ class DomainCache {
       console.log(formatLogMessage('debug', `${this.logPrefix} Cache MISS: ${domain} (processing and marked, cache size: ${this.cache.size})`));
     }
     
-    // Check size AFTER adding to prevent race where multiple threads see same size
-    // and all trigger cleanup before any adds complete
-    // V8 Optimization: Use pre-calculated targetCacheSize
+    // Check size after the add so an overflow only fires eviction once per
+    // overflowing call (using targetCacheSize precomputed in the constructor).
     if (this.cache.size > this.maxCacheSize) {
       const toRemove = this.cache.size - this.targetCacheSize;
       if (toRemove > 0) {
         this.clearOldestEntries(toRemove);
       }
     }
-    
+
     return false; // New domain, should process
   }
 
   /**
-   * Clear oldest entries from cache (basic LRU simulation)
-   * Note: Set doesn't maintain insertion order in all Node.js versions,
-   * so this is a simple implementation that clears a portion of the cache
+   * Clear oldest entries from cache (FIFO eviction). Set iteration order is
+   * guaranteed insertion order per ES2015, so this genuinely evicts oldest-
+   * first on every supported Node version.
    * @param {number} count - Number of entries to remove
    */
   clearOldestEntries(count) {
@@ -181,13 +192,8 @@ class DomainCache {
   clear() {
     const previousSize = this.cache.size;
     this.cache.clear();
-    this.stats = {
-      totalDetected: 0,
-      totalSkipped: 0,
-      cacheHits: 0,
-      cacheMisses: 0
-    };
-    
+    this.stats = this._freshStats();
+
     if (this.enableLogging) {
       console.log(formatLogMessage('debug', `${this.logPrefix} Cache cleared (${previousSize} entries removed)`));
     }
@@ -226,21 +232,40 @@ class DomainCache {
   }
 
   /**
-   * Add multiple domains to cache at once
+   * Add multiple domains to cache at once. Uses a single .size delta to
+   * count actually-new entries (skipping per-domain .has() calls), and
+   * runs the size-overflow eviction check once after the batch instead of
+   * per-domain. For a batch of N domains this is N .has() calls saved and
+   * up to N redundant cap checks collapsed to one.
    * @param {Array<string>} domains - Array of domains to add
    * @returns {number} Number of domains actually added (excludes duplicates)
    */
   markMultipleDomainsAsDetected(domains) {
-    if (!Array.isArray(domains)) {
+    if (!Array.isArray(domains) || domains.length === 0) {
       return 0;
     }
 
-    let addedCount = 0;
-    domains.forEach(domain => {
-      if (this.markDomainAsDetected(domain)) {
-        addedCount++;
+    const startSize = this.cache.size;
+    for (let i = 0; i < domains.length; i++) {
+      const d = domains[i];
+      if (d && typeof d === 'string') {
+        this.cache.add(d);
+      }
+    }
+    const addedCount = this.cache.size - startSize;
+    this.stats.totalDetected += addedCount;
+
+    if (this.enableLogging && addedCount > 0) {
+      console.log(formatLogMessage('debug', `${this.logPrefix} Batch added ${addedCount} new domains (cache size: ${this.cache.size})`));
+    }
+
+    // One eviction sweep at the end, mirroring the single-add overflow check.
+    if (this.cache.size > this.maxCacheSize) {
+      const toRemove = this.cache.size - this.targetCacheSize;
+      if (toRemove > 0) {
+        this.clearOldestEntries(toRemove);
       }
-    });
+    }
 
     return addedCount;
   }
@@ -267,13 +292,34 @@ class DomainCache {
 let globalDomainCache = null;
 
 /**
- * Get or create the global domain cache instance
- * @param {object} options - Cache options
+ * Get or create the global domain cache instance.
+ *
+ * NOTE: `options` is honored ONLY on the first call (the call that actually
+ * constructs the singleton). Subsequent calls return the existing instance
+ * regardless of what's passed. If you need different settings, call
+ * resetGlobalCache() first or use `new DomainCache(options)` directly.
+ *
+ * Under debug logging, a warning fires if a later caller passes options
+ * that don't match the live instance — silent drift is a recurring source
+ * of "why isn't my maxCacheSize taking effect?" confusion.
+ *
+ * @param {object} options - Cache options (first-call-only)
  * @returns {DomainCache} Global cache instance
  */
 function getGlobalDomainCache(options = {}) {
   if (!globalDomainCache) {
     globalDomainCache = new DomainCache(options);
+    return globalDomainCache;
+  }
+  // Singleton already exists — warn if the caller is trying to reconfigure it.
+  if (globalDomainCache.enableLogging) {
+    const drifted =
+      (options.maxCacheSize !== undefined && options.maxCacheSize !== globalDomainCache.maxCacheSize) ||
+      (options.enableLogging !== undefined && options.enableLogging !== globalDomainCache.enableLogging) ||
+      (options.logPrefix !== undefined && options.logPrefix !== globalDomainCache.logPrefix);
+    if (drifted) {
+      console.log(formatLogMessage('debug', `${globalDomainCache.logPrefix} getGlobalDomainCache called with options that differ from the live singleton; ignored (call resetGlobalCache() first to apply new options)`));
+    }
   }
   return globalDomainCache;
 }
@@ -323,7 +369,8 @@ function markDomainAsDetected(domain) {
 }
 
 /**
- * Atomically check and mark a domain (race-condition free)
+ * Combined check-and-mark in one pass — one Set.has() call instead of the
+ * two you'd pay for isDomainAlreadyDetected() + markDomainAsDetected().
  * @param {string} domain - Domain to check and mark
  * @returns {boolean} True if already detected (skip), false if new (process)
  */