ESLint custom rule execution blocking the main event loop

Answer the exact question first

What are the recommended patterns for managing high‑complexity logic in custom rules to avoid blocking the event loop? Is there a documented way to implement a timeout for a specific rule’s execution within the ESLint engine?

ESLint’s rule visitor functions run synchronously on the main Node.js thread. Because the engine does not support async visitors or cancellation tokens, a rule that performs heavy computation will block the event loop until it finishes. ESLint provides no built‑in timeout or cancellation mechanism for an individual rule.

Confirmed facts

• Rule visitors must be synchronous; async or await inside a rule has no effect on traversal timing.
• Heavy logic inside a visitor blocks the main thread until the function returns.
• There is no documented API to impose a per‑rule timeout or to cancel execution once a rule has started.

Recommended mitigation patterns

1. Offload to a worker thread or child process

   Move the expensive calculation into a worker_threads worker or a child_process. The rule’s visitor should synchronously return a placeholder (or nothing) and, after the worker finishes, trigger a second lint run or write the result to a cache file.

   // rule.js
   const { Worker } = require('worker_threads');
   module.exports = {
     create(context) {
       const heavyWorker = new Worker('./heavyWorker.js');
       heavyWorker.on('message', result => {
         // Store result in a shared cache for later use
         context.settings['heavyCache'] = result;
       });
       heavyWorker.postMessage(context.getSourceCode().text);
       return {
         Program(node) {
           // Use cached result if available
           const data = context.settings['heavyCache'];
           if (data) { /* report based on data */ }
         }
       };
     }
   };

2. Cache expensive computations across files

   Persist the result of heavy analysis (e.g., in a JSON file or in-memory Map keyed by file path + hash). Subsequent lint runs can read the cache instead of recomputing.

   • Use context.settings or a module‑level cache.
   • Invalidate the cache when the source file changes.
3. Split the rule into smaller, focused rules or multiple passes

   Decompose a monolithic rule into several simpler rules that each perform a subset of the analysis. ESLint’s --cache flag will skip unchanged files, reducing overall runtime.

4. Leverage ESLint’s built‑in file‑level cache

   Run eslint --cache to avoid re‑linting files that haven’t changed. This is orthogonal to rule design but often yields the biggest speed gains.

5. Avoid I/O inside the rule

   File reads, network calls, or other asynchronous operations should be performed outside the visitor, or in a worker, to keep the main thread free.

When to consider a timeout (outside ESLint)

Because ESLint cannot cancel a rule mid‑execution, the only practical way to enforce a time limit is to run the rule in a separate process and kill it if it exceeds a threshold. This is a heavy‑handed approach and should only be used for truly rogue rules.

Follow‑up diagnostic question

Do you need the rule to perform any I/O (file reads, network requests) that might be offloaded to a worker, or is the heavy logic purely CPU‑bound?

Summary

ESLint’s synchronous visitor pattern means that any heavy computation will block the main thread. The recommended strategy is to move expensive work into worker threads or child processes, cache results, split complex rules, and use ESLint’s cache flag. There is no built‑in timeout or cancellation API for individual rules.