Socket
Socket
Sign inDemoInstall

fsevents

Package Overview
Dependencies
0
Maintainers
2
Versions
67
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

fsevents

Native Access to MacOS FSEvents


Version published
Maintainers
2
Weekly downloads
23,406,720
decreased by-9.49%

Weekly downloads

Package description

What is fsevents?

The fsevents npm package is a Node.js module that provides native and efficient file system event watching on macOS. It is designed to be used by Node.js applications to receive notifications when the contents of a directory change, including file creations, modifications, and deletions. It leverages the macOS FSEvents API for optimal performance and accuracy.

What are fsevents's main functionalities?

Watching for file changes

This feature allows you to watch a directory for changes and execute a callback function whenever a change is detected. The callback receives the path of the changed file, flags that describe the change, and an event ID.

const fsevents = require('fsevents');
const watcher = fsevents.watch('/path/to/dir', (path, flags, id) => {
  console.log('File changed:', path);
});
watcher.start();

Stopping the watcher

This feature allows you to stop watching for file changes. It is useful when you no longer need to monitor a directory or when your application is shutting down.

watcher.stop();

Other packages similar to fsevents

Readme

Source

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.

Usage

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 stop function 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 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

Keywords

FAQs

Last updated on 21 Aug 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc