undici 7.13.0 → 7.14.0

package/lib/mock/snapshot-recorder.js

@@ -2,13 +2,93 @@
 
 const { writeFile, readFile, mkdir } = require('node:fs/promises')
 const { dirname, resolve } = require('node:path')
+const { setTimeout, clearTimeout } = require('node:timers')
 const { InvalidArgumentError, UndiciError } = require('../core/errors')
+const { hashId, isUrlExcludedFactory, normalizeHeaders, createHeaderFilters } = require('./snapshot-utils')
+
+/**
+ * @typedef {Object} SnapshotRequestOptions
+ * @property {string} method - HTTP method (e.g. 'GET', 'POST', etc.)
+ * @property {string} path - Request path
+ * @property {string} origin - Request origin (base URL)
+ * @property {import('./snapshot-utils').Headers|import('./snapshot-utils').UndiciHeaders} headers - Request headers
+ * @property {import('./snapshot-utils').NormalizedHeaders} _normalizedHeaders - Request headers as a lowercase object
+ * @property {string|Buffer} [body] - Request body (optional)
+ */
+
+/**
+ * @typedef {Object} SnapshotEntryRequest
+ * @property {string} method - HTTP method (e.g. 'GET', 'POST', etc.)
+ * @property {string} url - Full URL of the request
+ * @property {import('./snapshot-utils').NormalizedHeaders} headers - Normalized headers as a lowercase object
+ * @property {string|Buffer} [body] - Request body (optional)
+ */
+
+/**
+ * @typedef {Object} SnapshotEntryResponse
+ * @property {number} statusCode - HTTP status code of the response
+ * @property {import('./snapshot-utils').NormalizedHeaders} headers - Normalized response headers as a lowercase object
+ * @property {string} body - Response body as a base64url encoded string
+ * @property {Object} [trailers] - Optional response trailers
+ */
+
+/**
+ * @typedef {Object} SnapshotEntry
+ * @property {SnapshotEntryRequest} request - The request object
+ * @property {Array<SnapshotEntryResponse>} responses - Array of response objects
+ * @property {number} callCount - Number of times this snapshot has been called
+ * @property {string} timestamp - ISO timestamp of when the snapshot was created
+ */
+
+/**
+ * @typedef {Object} SnapshotRecorderMatchOptions
+ * @property {Array<string>} [matchHeaders=[]] - Headers to match (empty array means match all headers)
+ * @property {Array<string>} [ignoreHeaders=[]] - Headers to ignore for matching
+ * @property {Array<string>} [excludeHeaders=[]] - Headers to exclude from matching
+ * @property {boolean} [matchBody=true] - Whether to match request body
+ * @property {boolean} [matchQuery=true] - Whether to match query properties
+ * @property {boolean} [caseSensitive=false] - Whether header matching is case-sensitive
+ */
+
+/**
+ * @typedef {Object} SnapshotRecorderOptions
+ * @property {string} [snapshotPath] - Path to save/load snapshots
+ * @property {import('./snapshot-utils').SnapshotMode} [mode='record'] - Mode: 'record' or 'playback'
+ * @property {number} [maxSnapshots=Infinity] - Maximum number of snapshots to keep
+ * @property {boolean} [autoFlush=false] - Whether to automatically flush snapshots to disk
+ * @property {number} [flushInterval=30000] - Auto-flush interval in milliseconds (default: 30 seconds)
+ * @property {Array<string|RegExp>} [excludeUrls=[]] - URLs to exclude from recording
+ * @property {function} [shouldRecord=null] - Function to filter requests for recording
+ * @property {function} [shouldPlayback=null] - Function to filter requests
+ */
+
+/**
+ * @typedef {Object} SnapshotFormattedRequest
+ * @property {string} method - HTTP method (e.g. 'GET', 'POST', etc.)
+ * @property {string} url - Full URL of the request (with query parameters if matchQuery is true)
+ * @property {import('./snapshot-utils').NormalizedHeaders} headers - Normalized headers as a lowercase object
+ * @property {string} body - Request body (optional, only if matchBody is true)
+ */
+
+/**
+ * @typedef {Object} SnapshotInfo
+ * @property {string} hash - Hash key for the snapshot
+ * @property {SnapshotEntryRequest} request - The request object
+ * @property {number} responseCount - Number of responses recorded for this request
+ * @property {number} callCount - Number of times this snapshot has been called
+ * @property {string} timestamp - ISO timestamp of when the snapshot was created
+ */
 
 /**
  * Formats a request for consistent snapshot storage
  * Caches normalized headers to avoid repeated processing
+ *
+ * @param {SnapshotRequestOptions} opts - Request options
+ * @param {import('./snapshot-utils').HeaderFilters} headerFilters - Cached header sets for performance
+ * @param {SnapshotRecorderMatchOptions} [matchOptions] - Matching options for headers and body
+ * @returns {SnapshotFormattedRequest} - Formatted request object
  */
-function formatRequestKey (opts, cachedSets, matchOptions = {}) {
+function formatRequestKey (opts, headerFilters, matchOptions = {}) {
   const url = new URL(opts.path, opts.origin)
 
   // Cache normalized headers if not already done
@@ -20,37 +100,40 @@ function formatRequestKey (opts, cachedSets, matchOptions = {}) {
   return {
     method: opts.method || 'GET',
     url: matchOptions.matchQuery !== false ? url.toString() : `${url.origin}${url.pathname}`,
-    headers: filterHeadersForMatching(normalized, cachedSets, matchOptions),
-    body: matchOptions.matchBody !== false && opts.body ? String(opts.body) : undefined
+    headers: filterHeadersForMatching(normalized, headerFilters, matchOptions),
+    body: matchOptions.matchBody !== false && opts.body ? String(opts.body) : ''
   }
 }
 
 /**
  * Filters headers based on matching configuration
+ *
+ * @param {import('./snapshot-utils').Headers} headers - Headers to filter
+ * @param {import('./snapshot-utils').HeaderFilters} headerFilters - Cached sets for ignore, exclude, and match headers
+ * @param {SnapshotRecorderMatchOptions} [matchOptions] - Matching options for headers
  */
-function filterHeadersForMatching (headers, cachedSets, matchOptions = {}) {
+function filterHeadersForMatching (headers, headerFilters, matchOptions = {}) {
   if (!headers || typeof headers !== 'object') return {}
 
   const {
-    matchHeaders = null,
     caseSensitive = false
   } = matchOptions
 
   const filtered = {}
-  const { ignoreSet, excludeSet, matchSet } = cachedSets
+  const { ignore, exclude, match } = headerFilters
 
   for (const [key, value] of Object.entries(headers)) {
     const headerKey = caseSensitive ? key : key.toLowerCase()
 
     // Skip if in exclude list (for security)
-    if (excludeSet.has(headerKey)) continue
+    if (exclude.has(headerKey)) continue
 
     // Skip if in ignore list (for matching)
-    if (ignoreSet.has(headerKey)) continue
+    if (ignore.has(headerKey)) continue
 
     // If matchHeaders is specified, only include those headers
-    if (matchHeaders && Array.isArray(matchHeaders)) {
-      if (!matchSet.has(headerKey)) continue
+    if (match.size !== 0) {
+      if (!match.has(headerKey)) continue
     }
 
     filtered[headerKey] = value
@@ -61,17 +144,20 @@ function filterHeadersForMatching (headers, cachedSets, matchOptions = {}) {
 
 /**
  * Filters headers for storage (only excludes sensitive headers)
+ *
+ * @param {import('./snapshot-utils').Headers} headers - Headers to filter
+ * @param {import('./snapshot-utils').HeaderFilters} headerFilters - Cached sets for ignore, exclude, and match headers
+ * @param {SnapshotRecorderMatchOptions} [matchOptions] - Matching options for headers
  */
-function filterHeadersForStorage (headers, matchOptions = {}) {
+function filterHeadersForStorage (headers, headerFilters, matchOptions = {}) {
   if (!headers || typeof headers !== 'object') return {}
 
   const {
-    excludeHeaders = [],
     caseSensitive = false
   } = matchOptions
 
   const filtered = {}
-  const excludeSet = new Set(excludeHeaders.map(h => caseSensitive ? h : h.toLowerCase()))
+  const { exclude: excludeSet } = headerFilters
 
   for (const [key, value] of Object.entries(headers)) {
     const headerKey = caseSensitive ? key : key.toLowerCase()
@@ -86,106 +172,81 @@ function filterHeadersForStorage (headers, matchOptions = {}) {
 }
 
 /**
- * Creates cached header sets for performance
+ * Creates a hash key for request matching
+ * Properly orders headers to avoid conflicts and uses crypto hashing when available
+ *
+ * @param {SnapshotFormattedRequest} formattedRequest - Request object
+ * @returns {string} - Base64url encoded hash of the request
  */
-function createHeaderSetsCache (matchOptions = {}) {
-  const { ignoreHeaders = [], excludeHeaders = [], matchHeaders = null, caseSensitive = false } = matchOptions
+function createRequestHash (formattedRequest) {
+  const parts = [
+    formattedRequest.method,
+    formattedRequest.url
+  ]
 
-  return {
-    ignoreSet: new Set(ignoreHeaders.map(h => caseSensitive ? h : h.toLowerCase())),
-    excludeSet: new Set(excludeHeaders.map(h => caseSensitive ? h : h.toLowerCase())),
-    matchSet: matchHeaders && Array.isArray(matchHeaders)
-      ? new Set(matchHeaders.map(h => caseSensitive ? h : h.toLowerCase()))
-      : null
-  }
-}
+  // Process headers in a deterministic way to avoid conflicts
+  if (formattedRequest.headers && typeof formattedRequest.headers === 'object') {
+    const headerKeys = Object.keys(formattedRequest.headers).sort()
+    for (const key of headerKeys) {
+      const values = Array.isArray(formattedRequest.headers[key])
+        ? formattedRequest.headers[key]
+        : [formattedRequest.headers[key]]
 
-/**
- * Normalizes headers for consistent comparison
- */
-function normalizeHeaders (headers) {
-  if (!headers) return {}
-
-  const normalized = {}
-
-  // Handle array format (undici internal format: [name, value, name, value, ...])
-  if (Array.isArray(headers)) {
-    for (let i = 0; i < headers.length; i += 2) {
-      const key = headers[i]
-      const value = headers[i + 1]
-      if (key && value !== undefined) {
-        // Convert Buffers to strings if needed
-        const keyStr = Buffer.isBuffer(key) ? key.toString() : String(key)
-        const valueStr = Buffer.isBuffer(value) ? value.toString() : String(value)
-        normalized[keyStr.toLowerCase()] = valueStr
-      }
-    }
-    return normalized
-  }
+      // Add header name
+      parts.push(key)
 
-  // Handle object format
-  if (headers && typeof headers === 'object') {
-    for (const [key, value] of Object.entries(headers)) {
-      if (key && typeof key === 'string') {
-        normalized[key.toLowerCase()] = Array.isArray(value) ? value.join(', ') : String(value)
+      // Add all values for this header, sorted for consistency
+      for (const value of values.sort()) {
+        parts.push(String(value))
       }
     }
   }
 
-  return normalized
-}
+  // Add body
+  parts.push(formattedRequest.body)
 
-/**
- * Creates a hash key for request matching
- */
-function createRequestHash (request) {
-  const parts = [
-    request.method,
-    request.url,
-    JSON.stringify(request.headers, Object.keys(request.headers).sort()),
-    request.body || ''
-  ]
-  return Buffer.from(parts.join('|')).toString('base64url')
-}
+  const content = parts.join('|')
 
-/**
- * Checks if a URL matches any of the exclude patterns
- */
-function isUrlExcluded (url, excludePatterns = []) {
-  if (!excludePatterns.length) return false
-
-  for (const pattern of excludePatterns) {
-    if (typeof pattern === 'string') {
-      // Simple string match (case-insensitive)
-      if (url.toLowerCase().includes(pattern.toLowerCase())) {
-        return true
-      }
-    } else if (pattern instanceof RegExp) {
-      // Regex pattern match
-      if (pattern.test(url)) {
-        return true
-      }
-    }
-  }
-
-  return false
+  return hashId(content)
 }
 
 class SnapshotRecorder {
+  /** @type {NodeJS.Timeout | null} */
+  #flushTimeout
+
+  /** @type {import('./snapshot-utils').IsUrlExcluded} */
+  #isUrlExcluded
+
+  /** @type {Map<string, SnapshotEntry>} */
+  #snapshots = new Map()
+
+  /** @type {string|undefined} */
+  #snapshotPath
+
+  /** @type {number} */
+  #maxSnapshots = Infinity
+
+  /** @type {boolean} */
+  #autoFlush = false
+
+  /** @type {import('./snapshot-utils').HeaderFilters} */
+  #headerFilters
+
+  /**
+   * Creates a new SnapshotRecorder instance
+   * @param {SnapshotRecorderOptions&SnapshotRecorderMatchOptions} [options={}] - Configuration options for the recorder
+   */
   constructor (options = {}) {
-    this.snapshots = new Map()
-    this.snapshotPath = options.snapshotPath
-    this.mode = options.mode || 'record'
-    this.loaded = false
-    this.maxSnapshots = options.maxSnapshots || Infinity
-    this.autoFlush = options.autoFlush || false
+    this.#snapshotPath = options.snapshotPath
+    this.#maxSnapshots = options.maxSnapshots || Infinity
+    this.#autoFlush = options.autoFlush || false
     this.flushInterval = options.flushInterval || 30000 // 30 seconds default
     this._flushTimer = null
-    this._flushTimeout = null
 
     // Matching configuration
+    /** @type {Required<SnapshotRecorderMatchOptions>} */
     this.matchOptions = {
-      matchHeaders: options.matchHeaders || null, // null means match all headers
+      matchHeaders: options.matchHeaders || [], // empty means match all headers
       ignoreHeaders: options.ignoreHeaders || [],
       excludeHeaders: options.excludeHeaders || [],
       matchBody: options.matchBody !== false, // default: true
@@ -194,46 +255,49 @@ class SnapshotRecorder {
     }
 
     // Cache processed header sets to avoid recreating them on every request
-    this._headerSetsCache = createHeaderSetsCache(this.matchOptions)
+    this.#headerFilters = createHeaderFilters(this.matchOptions)
 
     // Request filtering callbacks
-    this.shouldRecord = options.shouldRecord || null // function(requestOpts) -> boolean
-    this.shouldPlayback = options.shouldPlayback || null // function(requestOpts) -> boolean
+    this.shouldRecord = options.shouldRecord || (() => true) // function(requestOpts) -> boolean
+    this.shouldPlayback = options.shouldPlayback || (() => true) // function(requestOpts) -> boolean
 
     // URL pattern filtering
-    this.excludeUrls = options.excludeUrls || [] // Array of regex patterns or strings
+    this.#isUrlExcluded = isUrlExcludedFactory(options.excludeUrls) // Array of regex patterns or strings
 
     // Start auto-flush timer if enabled
-    if (this.autoFlush && this.snapshotPath) {
-      this._startAutoFlush()
+    if (this.#autoFlush && this.#snapshotPath) {
+      this.#startAutoFlush()
     }
   }
 
   /**
    * Records a request-response interaction
+   * @param {SnapshotRequestOptions} requestOpts - Request options
+   * @param {SnapshotEntryResponse} response - Response data to record
+   * @return {Promise<void>} - Resolves when the recording is complete
    */
   async record (requestOpts, response) {
     // Check if recording should be filtered out
-    if (this.shouldRecord && typeof this.shouldRecord === 'function') {
-      if (!this.shouldRecord(requestOpts)) {
-        return // Skip recording
-      }
+    if (!this.shouldRecord(requestOpts)) {
+      return // Skip recording
     }
 
     // Check URL exclusion patterns
     const url = new URL(requestOpts.path, requestOpts.origin).toString()
-    if (isUrlExcluded(url, this.excludeUrls)) {
+    if (this.#isUrlExcluded(url)) {
       return // Skip recording
     }
 
-    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const request = formatRequestKey(requestOpts, this.#headerFilters, this.matchOptions)
     const hash = createRequestHash(request)
 
     // Extract response data - always store body as base64
     const normalizedHeaders = normalizeHeaders(response.headers)
+
+    /** @type {SnapshotEntryResponse} */
     const responseData = {
       statusCode: response.statusCode,
-      headers: filterHeadersForStorage(normalizedHeaders, this.matchOptions),
+      headers: filterHeadersForStorage(normalizedHeaders, this.#headerFilters, this.matchOptions),
       body: Buffer.isBuffer(response.body)
         ? response.body.toString('base64')
         : Buffer.from(String(response.body || '')).toString('base64'),
@@ -241,18 +305,18 @@ class SnapshotRecorder {
     }
 
     // Remove oldest snapshot if we exceed maxSnapshots limit
-    if (this.snapshots.size >= this.maxSnapshots && !this.snapshots.has(hash)) {
-      const oldestKey = this.snapshots.keys().next().value
-      this.snapshots.delete(oldestKey)
+    if (this.#snapshots.size >= this.#maxSnapshots && !this.#snapshots.has(hash)) {
+      const oldestKey = this.#snapshots.keys().next().value
+      this.#snapshots.delete(oldestKey)
     }
 
     // Support sequential responses - if snapshot exists, add to responses array
-    const existingSnapshot = this.snapshots.get(hash)
+    const existingSnapshot = this.#snapshots.get(hash)
     if (existingSnapshot && existingSnapshot.responses) {
       existingSnapshot.responses.push(responseData)
       existingSnapshot.timestamp = new Date().toISOString()
     } else {
-      this.snapshots.set(hash, {
+      this.#snapshots.set(hash, {
         request,
         responses: [responseData], // Always store as array for consistency
         callCount: 0,
@@ -261,67 +325,54 @@ class SnapshotRecorder {
     }
 
     // Auto-flush if enabled
-    if (this.autoFlush && this.snapshotPath) {
-      this._scheduleFlush()
+    if (this.#autoFlush && this.#snapshotPath) {
+      this.#scheduleFlush()
     }
   }
 
   /**
    * Finds a matching snapshot for the given request
    * Returns the appropriate response based on call count for sequential responses
+   *
+   * @param {SnapshotRequestOptions} requestOpts - Request options to match
+   * @returns {SnapshotEntry&Record<'response', SnapshotEntryResponse>|undefined} - Matching snapshot response or undefined if not found
    */
   findSnapshot (requestOpts) {
     // Check if playback should be filtered out
-    if (this.shouldPlayback && typeof this.shouldPlayback === 'function') {
-      if (!this.shouldPlayback(requestOpts)) {
-        return undefined // Skip playback
-      }
+    if (!this.shouldPlayback(requestOpts)) {
+      return undefined // Skip playback
     }
 
     // Check URL exclusion patterns
     const url = new URL(requestOpts.path, requestOpts.origin).toString()
-    if (isUrlExcluded(url, this.excludeUrls)) {
+    if (this.#isUrlExcluded(url)) {
       return undefined // Skip playback
     }
 
-    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const request = formatRequestKey(requestOpts, this.#headerFilters, this.matchOptions)
     const hash = createRequestHash(request)
-    const snapshot = this.snapshots.get(hash)
+    const snapshot = this.#snapshots.get(hash)
 
     if (!snapshot) return undefined
 
     // Handle sequential responses
-    if (snapshot.responses && Array.isArray(snapshot.responses)) {
-      const currentCallCount = snapshot.callCount || 0
-      const responseIndex = Math.min(currentCallCount, snapshot.responses.length - 1)
-      snapshot.callCount = currentCallCount + 1
-
-      return {
-        ...snapshot,
-        response: snapshot.responses[responseIndex]
-      }
-    }
+    const currentCallCount = snapshot.callCount || 0
+    const responseIndex = Math.min(currentCallCount, snapshot.responses.length - 1)
+    snapshot.callCount = currentCallCount + 1
 
-    // Legacy format compatibility - convert single response to array format
-    if (snapshot.response && !snapshot.responses) {
-      snapshot.responses = [snapshot.response]
-      snapshot.callCount = 1
-      delete snapshot.response
-
-      return {
-        ...snapshot,
-        response: snapshot.responses[0]
-      }
+    return {
+      ...snapshot,
+      response: snapshot.responses[responseIndex]
     }
-
-    return snapshot
   }
 
   /**
    * Loads snapshots from file
+   * @param {string} [filePath] - Optional file path to load snapshots from
+   * @return {Promise<void>} - Resolves when snapshots are loaded
    */
   async loadSnapshots (filePath) {
-    const path = filePath || this.snapshotPath
+    const path = filePath || this.#snapshotPath
     if (!path) {
       throw new InvalidArgumentError('Snapshot path is required')
     }
@@ -332,21 +383,18 @@ class SnapshotRecorder {
 
       // Convert array format back to Map
       if (Array.isArray(parsed)) {
-        this.snapshots.clear()
+        this.#snapshots.clear()
         for (const { hash, snapshot } of parsed) {
-          this.snapshots.set(hash, snapshot)
+          this.#snapshots.set(hash, snapshot)
         }
       } else {
         // Legacy object format
-        this.snapshots = new Map(Object.entries(parsed))
+        this.#snapshots = new Map(Object.entries(parsed))
       }
-
-      this.loaded = true
     } catch (error) {
       if (error.code === 'ENOENT') {
         // File doesn't exist yet - that's ok for recording mode
-        this.snapshots.clear()
-        this.loaded = true
+        this.#snapshots.clear()
       } else {
         throw new UndiciError(`Failed to load snapshots from ${path}`, { cause: error })
       }
@@ -355,9 +403,12 @@ class SnapshotRecorder {
 
   /**
    * Saves snapshots to file
+   *
+   * @param {string} [filePath] - Optional file path to save snapshots
+   * @returns {Promise<void>} - Resolves when snapshots are saved
    */
   async saveSnapshots (filePath) {
-    const path = filePath || this.snapshotPath
+    const path = filePath || this.#snapshotPath
     if (!path) {
       throw new InvalidArgumentError('Snapshot path is required')
     }
@@ -368,67 +419,75 @@ class SnapshotRecorder {
     await mkdir(dirname(resolvedPath), { recursive: true })
 
     // Convert Map to serializable format
-    const data = Array.from(this.snapshots.entries()).map(([hash, snapshot]) => ({
+    const data = Array.from(this.#snapshots.entries()).map(([hash, snapshot]) => ({
       hash,
       snapshot
     }))
 
-    await writeFile(resolvedPath, JSON.stringify(data, null, 2), 'utf8', { flush: true })
+    await writeFile(resolvedPath, JSON.stringify(data, null, 2), { flush: true })
   }
 
   /**
    * Clears all recorded snapshots
+   * @returns {void}
    */
   clear () {
-    this.snapshots.clear()
+    this.#snapshots.clear()
   }
 
   /**
    * Gets all recorded snapshots
+   * @return {Array<SnapshotEntry>} - Array of all recorded snapshots
    */
   getSnapshots () {
-    return Array.from(this.snapshots.values())
+    return Array.from(this.#snapshots.values())
   }
 
   /**
    * Gets snapshot count
+   * @return {number} - Number of recorded snapshots
    */
   size () {
-    return this.snapshots.size
+    return this.#snapshots.size
   }
 
   /**
    * Resets call counts for all snapshots (useful for test cleanup)
+   * @returns {void}
    */
   resetCallCounts () {
-    for (const snapshot of this.snapshots.values()) {
+    for (const snapshot of this.#snapshots.values()) {
       snapshot.callCount = 0
     }
   }
 
   /**
    * Deletes a specific snapshot by request options
+   * @param {SnapshotRequestOptions} requestOpts - Request options to match
+   * @returns {boolean} - True if snapshot was deleted, false if not found
    */
   deleteSnapshot (requestOpts) {
-    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const request = formatRequestKey(requestOpts, this.#headerFilters, this.matchOptions)
     const hash = createRequestHash(request)
-    return this.snapshots.delete(hash)
+    return this.#snapshots.delete(hash)
   }
 
   /**
    * Gets information about a specific snapshot
+   * @param {SnapshotRequestOptions} requestOpts - Request options to match
+   * @returns {SnapshotInfo|null} - Snapshot information or null if not found
    */
   getSnapshotInfo (requestOpts) {
-    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const request = formatRequestKey(requestOpts, this.#headerFilters, this.matchOptions)
     const hash = createRequestHash(request)
-    const snapshot = this.snapshots.get(hash)
+    const snapshot = this.#snapshots.get(hash)
 
     if (!snapshot) return null
 
     return {
       hash,
       request: snapshot.request,
-      responseCount: snapshot.responses ? snapshot.responses.length : (snapshot.response ? 1 : 0),
+      responseCount: snapshot.responses ? snapshot.responses.length : (snapshot.response ? 1 : 0), // .response for legacy snapshots
       callCount: snapshot.callCount || 0,
       timestamp: snapshot.timestamp
     }
@@ -436,76 +495,80 @@ class SnapshotRecorder {
 
   /**
    * Replaces all snapshots with new data (full replacement)
+   * @param {Array<{hash: string; snapshot: SnapshotEntry}>|Record<string, SnapshotEntry>} snapshotData - New snapshot data to replace existing ones
+   * @returns {void}
    */
   replaceSnapshots (snapshotData) {
-    this.snapshots.clear()
+    this.#snapshots.clear()
 
     if (Array.isArray(snapshotData)) {
       for (const { hash, snapshot } of snapshotData) {
-        this.snapshots.set(hash, snapshot)
+        this.#snapshots.set(hash, snapshot)
       }
     } else if (snapshotData && typeof snapshotData === 'object') {
       // Legacy object format
-      this.snapshots = new Map(Object.entries(snapshotData))
+      this.#snapshots = new Map(Object.entries(snapshotData))
     }
   }
 
   /**
    * Starts the auto-flush timer
+   * @returns {void}
    */
-  _startAutoFlush () {
-    if (!this._flushTimer) {
-      this._flushTimer = setInterval(() => {
-        this.saveSnapshots().catch(() => {
-          // Ignore flush errors - they shouldn't interrupt normal operation
-        })
-      }, this.flushInterval)
-    }
+  #startAutoFlush () {
+    return this.#scheduleFlush()
   }
 
   /**
    * Stops the auto-flush timer
+   * @returns {void}
    */
-  _stopAutoFlush () {
-    if (this._flushTimer) {
-      clearInterval(this._flushTimer)
-      this._flushTimer = null
+  #stopAutoFlush () {
+    if (this.#flushTimeout) {
+      clearTimeout(this.#flushTimeout)
+      // Ensure any pending flush is completed
+      this.saveSnapshots().catch(() => {
+      // Ignore flush errors
+      })
+      this.#flushTimeout = null
     }
   }
 
   /**
    * Schedules a flush (debounced to avoid excessive writes)
    */
-  _scheduleFlush () {
-    // Simple debouncing - clear existing timeout and set new one
-    if (this._flushTimeout) {
-      clearTimeout(this._flushTimeout)
-    }
-    this._flushTimeout = setTimeout(() => {
+  #scheduleFlush () {
+    this.#flushTimeout = setTimeout(() => {
       this.saveSnapshots().catch(() => {
         // Ignore flush errors
       })
-      this._flushTimeout = null
+      if (this.#autoFlush) {
+        this.#flushTimeout?.refresh()
+      } else {
+        this.#flushTimeout = null
+      }
     }, 1000) // 1 second debounce
   }
 
   /**
    * Cleanup method to stop timers
+   * @returns {void}
    */
   destroy () {
-    this._stopAutoFlush()
-    if (this._flushTimeout) {
-      clearTimeout(this._flushTimeout)
-      this._flushTimeout = null
+    this.#stopAutoFlush()
+    if (this.#flushTimeout) {
+      clearTimeout(this.#flushTimeout)
+      this.#flushTimeout = null
     }
   }
 
   /**
    * Async close method that saves all recordings and performs cleanup
+   * @returns {Promise<void>}
    */
   async close () {
     // Save any pending recordings if we have a snapshot path
-    if (this.snapshotPath && this.snapshots.size > 0) {
+    if (this.#snapshotPath && this.#snapshots.size !== 0) {
       await this.saveSnapshots()
     }
 
@@ -514,4 +577,4 @@ class SnapshotRecorder {
   }
 }
 
-module.exports = { SnapshotRecorder, formatRequestKey, createRequestHash, filterHeadersForMatching, filterHeadersForStorage, isUrlExcluded, createHeaderSetsCache }
+module.exports = { SnapshotRecorder, formatRequestKey, createRequestHash, filterHeadersForMatching, filterHeadersForStorage, createHeaderFilters }