Native Access to MacOS FSEvents
FSevents is an essential npm package designed specifically for Node.js developers working on MacOS environments. It provides native access to the MacOS File System Events API, enabling applications to efficiently monitor changes in the filesystem. With its direct integration, `fsevents` allows developers to listen for real-time notifications on the modifications of a directory tree, making it an invaluable tool for projects that require immediate file system updates. Its lightweight nature and speed make it a superior choice over other methods like kqueue, offering a streamlined approach to file system monitoring that enhances application responsiveness and performance.
To integrate `fsevents` into your Node.js project, simply run the command `npm install fsevents` in your project's directory. This command fetches and installs the `fsevents` package from the npm repository, ensuring that your application has direct access to the FSEvents API. Once installed, developers can easily configure their Node.js applications to react to file changes, harnessing the speed and efficiency of native MacOS filesystem notifications. This setup not only simplifies development but also significantly boosts the performance of applications that depend on file system accuracy and immediate update feedback.
By using `fsevents`, developers leverage a key advantage in building more robust and high-performing applications on MacOS. The package's ability to offer real-time, native notifications about file changes without the heavy lifting of more cumbersome alternatives transforms it into a must-have for any serious MacOS-based Node.js development project. Whether you are developing a complex media management application, a personal project, or a large-scale enterprise system, integrating `fsevents` ensures your application remains efficient and responsive to the dynamic nature of file systems, ultimately providing a seamless user experience.
Core dependencies of this npm package and its dev dependencies.
node-gyp
A README file for the fsevents code repository. View Code
Native access to MacOS FSEvents in Node.js
The FSEvents API in MacOS allows applications to register for notifications of changes to a given directory tree. It is a very fast and lightweight alternative to kqueue.
This is a low-level library. For a cross-platform file watching module that uses fsevents, check out Chokidar.
npm install fsevents
Supports only Node.js v8.16 and higher.
const fsevents = require('fsevents');
// To start observation
const stop = fsevents.watch(__dirname, (path, flags, id) => {
const info = fsevents.getInfo(path, flags);
});
// To end observation
stop();
Important note: The API behaviour is slightly different from typical JS APIs. The
stopfunction must be retrieved and stored somewhere, even if you don't plan to stop the watcher. If you forget it, the garbage collector will eventually kick in, the watcher will be unregistered, and your callbacks won't be called anymore.
The callback passed as the second parameter to .watch get's called whenever the operating system detects a
a change in the file system. It takes three arguments:
fsevents.watch(dirname: string, (path: string, flags: number, id: string) => void): () => Promise<undefined>path: string - the item in the filesystem that have been changedflags: number - a numeric value describing what the change wasid: string - an unique-id identifying this specific eventReturns closer callback which when called returns a Promise resolving when the watcher process has been shut down.
fsevents.getInfo(path: string, flags: number, id: string): FsEventInfoThe getInfo function takes the path, flags and id arguments and converts those parameters into a structure
that is easier to digest to determine what the change was.
The FsEventsInfo has the following shape:
/**
* @typedef {'created'|'modified'|'deleted'|'moved'|'root-changed'|'cloned'|'unknown'} FsEventsEvent
* @typedef {'file'|'directory'|'symlink'} FsEventsType
*/
{
"event": "created", // {FsEventsEvent}
"path": "file.txt",
"type": "file", // {FsEventsType}
"changes": {
"inode": true, // Had iNode Meta-Information changed
"finder": false, // Had Finder Meta-Data changed
"access": false, // Had access permissions changed
"xattrs": false // Had xAttributes changed
},
"flags": 0x100000000
}
EBADPLATFORM Unsupported platform for fsevents error.The MIT License Copyright (C) 2010-2020 by Philipp Dunkel, Ben Noordhuis, Elan Shankar, Paul Miller — see LICENSE file.
Visit our GitHub page and NPM Page