RFC: Persistent Filesystem Cache

[javierbrea]

Context

To potentially improve performance across multiple executions of the plugin, it is proposed to implement a persistent cache stored on the filesystem, rather than relying solely on in-memory caching. This approach aims to reduce repeated expensive computations by preserving cached data between runs, although tests are needed to verify the actual impact.

Detailed Design

Current State

In the upcoming version 6 of the plugin, the responsibility for identifying elements based on configuration and matching rules has been factored out into a new package: @boundaries/elements. This package also manages the current in-memory cache to avoid recalculating the same path or selector when configuration remains unchanged. The package exposes methods to:

• Return the serialized cache at any time.
• Restore the cache from serialized data.
• Clear the cache.

Proposal

Implement a new package, @boundaries/fs-cache, responsible for reading and writing the serialized cache to the filesystem. This package would:

• Invoke the cache serialization and restoration methods from @boundaries/elements to manage cache state.
• Store the cache data in the location node_modules/.cache/@boundaries/elements using the find-cache-directory utility. which proposes a conventional location for caching in Node.js projects, and it is used by popular tools like nyc, AVA, storybook, babel-loader, etc.
• Provide an option for cache size limits: when the maximum cache size is reached, entries not accessed for the longest time would be evicted to make room for new entries.
• Provide an option to enable or disable the persistent cache in case any unforeseen issues arise regarding functionality or performance.

By using node_modules/.cache for storage, the cache files are managed in a location automatically excluded by .gitignore in typical Node.js projects, ensuring a transparent experience for users with no additional config required.

This separation enables easier extension of caching mechanisms without coupling core element identification logic to storage concerns.

Benefits

• Potentially reduces repeated costly computations during repeated plugin runs.
• Clear separation of concerns—@boundaries/elements remains filesystem-agnostic and can be used in other environments without modification.
• Compliance with Node.js community conventions for cache storage.

Drawbacks & Considerations

• Proper cache eviction logic must be robust to avoid memory bloat or excessive disk usage.
• Users should be able to disable the filesystem cache easily to debug or workaround potential issues. Cache options should be exposed in the plugin configuration.
• Performance impact should be measured through real usage tests.

---

Feedback and further enhancement suggestions are welcome.

[javierbrea]

I've been investigating the feasibility of implementing persistent filesystem cache for plugins, and unfortunately, I've encountered some fundamental limitations in ESLint's current architecture that make this challenging to implement in a standard way.

The Core Problem

The main issue is that ESLint does not provide any hooks or lifecycle events for plugins to execute code when linting completes. The plugin API is primarily file-based and synchronous, meaning:

1. Plugins process files individually through rules or processors
2. There's no official "finalization" hook where accumulated cache data can be safely written to disk
3. When ESLint finishes execution, the process terminates immediately, potentially losing any in-memory cache data

ESLint's Lack of Async Support

Additionally, ESLint's architecture is fundamentally synchronous and does not support asynchronous operations in rules or plugins (see eslint/eslint#15394). This means:

• Rules cannot return promises or use async/await
• There's no way to guarantee that async file I/O operations complete before the process exits
• Any attempt to write cache data asynchronously may be interrupted when ESLint terminates

Moving Forward

Until ESLint adds support for:

• Plugin lifecycle hooks (initialization/finalization events)
• Async rule/plugin execution (currently tracked in eslint/eslint#15394)

Implementing persistent filesystem cache in a standard, reliable way remains technically infeasible within the plugin itself.

I believe this feature would be valuable once ESLint's architecture evolves to support these capabilities.