https://github.com/samthor/sents
Cross-platform filesystem watcher with zero dependencies
https://github.com/samthor/sents
filesystem library nodejs watch
Last synced: 6 months ago
JSON representation
Cross-platform filesystem watcher with zero dependencies
- Host: GitHub
- URL: https://github.com/samthor/sents
- Owner: samthor
- License: apache-2.0
- Created: 2020-11-29T04:17:40.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-07-31T01:47:42.000Z (almost 5 years ago)
- Last Synced: 2024-04-24T04:29:19.429Z (about 2 years ago)
- Topics: filesystem, library, nodejs, watch
- Language: JavaScript
- Homepage:
- Size: 163 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/samthor/sents)
Filesystem watcher that uses `fs.watch` and friends (i.e., no polling).
⚠️ **This is the library—check out [sents-cli](https://npmjs.com/package/sents-cli) to use this on the command-line.**
# Features
* Zero dependencies 🍩 and no native code
* Supports macOS, Linux, Windows (and probably others) via the same API
* Supports hard links (announces changes at all places inode is found)
* Handles awkward renames on case-insensitive filesystems ("foo" => "FOO" is announced)
It does not support some features:
* Following symlinks
* Renames (instead announce delete/add—what do renames mean in a world of hard links?)
* Watching across volumes
* And it should not be used on network shares (they need polling, every watcher hates these)
# Usage
Basic usage:
```js
import buildWatcher from 'sents';
// Create a watcher by passing a directory name ("." for the current dir).
const watcher = buildWatcher('.');
// Type can be 'add', 'change', or 'remove'.
watcher.on('raw', (filename, type, ino) => {
console.warn(type.toUpperCase(), filename, ino);
});
// If the watcher emits an error, it's no longer usable.
watcher.on('error', (e) => {
console.warn('got error', e);
});
// Call .close() to shut down the watcher.
setTimeout(() => {
watcher.close();
}, 60 * 1000);
```
Note that this watches a single _directory_, and directly watching files is not supported.
The only events emitted by `sents` are "ready", "raw", and "error".
# Options
This also supports some options:
```js
const watcher = buildWatcher('.', {
dotfiles: false,
filter: (rel) => true,
delay: 1000,
});
```
* `dotfiles` controls whether files starting with '.' are returned (default `false`)
* `filter` allows filtering of the results (return `true` to include, default includes all)
- When directories are passed, they'll end with `path.sep` (i.e., "/" most places); if you filter them, you'll _never_ be asked or notified about their subdirectories
- This should be a pure function—don't change results over time—otherwise, you're gonna have a bad time
* `delay` allows you to delay and aggregate changes by ms (if unset, uses a microtask)
# Notes
On macOS and Windows, watching a whole directory subtree is fairly cheap.
On Linux and other platforms, this package installs a watcher on every subdirectory.
Keep this in mind when building tools using `sents`—be sure to use `filter` to limit what you're watching.
## Ready Check
If you don't want to get all initial updates (i.e., the first scan of files) then you do either of:
```js
await watcher.ready;
watcher.once('ready', () => {...});
```
## Glob Support
This doesn't have glob support or any built-in filtering aside the controls above.
If you want to write a command-line tool or similar, you should build a `filter` function that supports globs.
Check out [sents-cli](https://npmjs.com/package/sents-cli).
## Files Only
Technically this package isn't a _file_ watcher, it's a _directory_ watcher (most files watchers are).
It's not more efficient to watch single files than it is a whole directory (since it has to be watched in case the file is removed).
If you just want to watch a small number of files for changes, be sure to allow them specifically in `filter`, while ignoring all other files or directories.