fsevents

fsevents

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.

Installation

Supports only Node.js v8.16 and higher.

npm install fsevents

Usage

const fsevents = require('fsevents'); const stop = fsevents.watch(__dirname, (path, flags, id) => { const info = fsevents.getInfo(path, flags, id); }); // To start observation stop(); // To end observation

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 changed
• flags: number - a numeric value describing what the change was
• id: string - an unique-id identifying this specific event

Returns 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): FsEventInfo

The 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 }

Changelog

• v2.3 supports Apple Silicon ARM CPUs
• v2 supports node 8.16+ and reduces package size massively
• v1.2.8 supports node 6+
• v1.2.7 supports node 4+

Troubleshooting

• I'm getting EBADPLATFORM Unsupported platform for fsevents error.
• It's fine, nothing is broken. fsevents is macos-only. Other platforms are skipped. If you want to hide this warning, report a bug to NPM bugtracker asking them to hide ebadplatform warnings by default.

License

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