https://github.com/fabiospampinato/pollex
A tiny polling-based filesystem watcher that tries to be efficient.
https://github.com/fabiospampinato/pollex
esbuild filesystem poll polling tiny watcher
Last synced: 3 months ago
JSON representation
A tiny polling-based filesystem watcher that tries to be efficient.
- Host: GitHub
- URL: https://github.com/fabiospampinato/pollex
- Owner: fabiospampinato
- License: mit
- Created: 2023-07-02T22:41:33.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-04-04T23:03:36.000Z (over 1 year ago)
- Last Synced: 2024-11-27T13:03:44.235Z (11 months ago)
- Topics: esbuild, filesystem, poll, polling, tiny, watcher
- Language: TypeScript
- Homepage:
- Size: 12.7 KB
- Stars: 27
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# Pollex
A tiny polling-based filesystem watcher that tries to be efficient.
This is a port of the idea behind [`esbuild`](https://esbuild.github.io/api/#watch)'s filesystem watcher, which uses polling but more efficiently than using it naively.
## Features
Unless you really want this I'd recommend using a [normal](https://github.com/fabiospampinato/watcher) filesystem watcher instead, since polling can get expensive.
- Changes happening inside the root folder should get picked up roughly within `options.pollingIntervalCold / 2` milliseconds on average.
- Changes happening inside files that the watcher already saw changing should get picked up roughly within `options.pollingIntervalHot / 2` milliseconds on average.
- Basically files that changed already are considered hot and polled frequently, while random subsets of the other files are polled infrequently.
- This should be roughly `options.pollingIntervalCold / options.pollingIntervalHot` times cheaper than just polling every file on a `options.pollingIntervalHot` interval.
In some niche scenarios a filesystem watcher that works like this could be useful:
- It doesn't rely on potentially buggy native filesystem watching APIs, it just needs to be able to fire `stat` syscalls.
- It works even over filesystems for which a native watching API is not available.
- It doesn't run out of file descriptors, because it doesn't keep any open indefinitely.
- It can potentially be used to react to filesystem events quicker than it's possible with `fs.watch` in Node, which is weirdly slow.
- It's about 20x smaller than [`chokidar`](https://github.com/paulmillr/chokidar), with no third-party dependencies, and a way simpler implementation.
## Install
```sh
npm install --save pollex
```
## Usage
```ts
import pollex from 'pollex';
// Let's define some options
const pollexOptions = {
depth: 20, // Maximum depth to look at
limit: 1_000_000, // Maximum number of files explored, useful as a stop gap in some edge cases
followSymlinks: true, // Whether to follow symlinks or not
ignore: targetPath => /node_modules/.test ( targetPath ), // Function that if returns true will ignore this particular file or a directory and its descendants
ignoreInitial: true, // Ignore the initial "add" and "addDir" events while the folder is being scanned the first time
ignoreReady: true, // Ignore the "ready" event, useful in combination with "ignoreInitial: true" to only get notified about actual changes
pollingIntervalCold: 2000, // Poll all cold files, in different random subsets, within this amount of time, roughly
pollingIntervalHot: 50 // Poll all hot files within this amount of time, roughly
};
// Let's listen for events
pollex ( process.cwd (), ( event, targetPath ) => {
if ( event === 'add' ) {
// The file at "targetPath" got added
} else if ( event === 'addDir' ) {
// The folder at "targetPath" got added
} else if ( event === 'change' ) {
// The file at "targetPath" changed
} else if ( event === 'ready' ) {
// The initial scan has been done and all initial events have been emitted
} else if ( event === 'unlink' ) {
// The file at "targetPath" got deleted
} else if ( event === 'unlinkDir' ) {
// The folder at "targetPath" got deleted
}
}, pollexOptions );
```
## License
MIT © Fabio Spampinato