# fsevents

> Native Access to MacOS FSEvents

Latest version **2.3.3** (published 2023-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install fsevents
pnpm add fsevents
yarn add fsevents
bun add fsevents
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.3.3 |
| Published | 2023-08-21 |
| First published | 2013-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^8.16.0 \|\| ^10.6.0 \|\| >=11.0.0 |
| Dependencies | 0 |
| Unpacked size | 169.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 569 |
| Maintainers | pipobscure, paulmillr |
| Keywords | fsevents, mac |

## Links

- npm: https://www.npmjs.com/package/fsevents
- Repository: https://github.com/fsevents/fsevents
- Issues: https://github.com/fsevents/fsevents/issues
- npm.io page: https://npm.io/package/fsevents

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 2.3.3 (latest) — 2023-08-21
- 1.2.13 (nan) — 2020-05-05
- 2.3.2 — 2021-02-05
- 2.3.1 — 2021-01-05
- 2.3.0 — 2021-01-05
- 2.2.2 — 2021-01-05
- 2.2.1 — 2020-11-05
- 2.2.0 — 2020-11-03
- 2.1.3 — 2020-04-22
- 1.2.12 — 2020-03-19
- 1.2.11 — 2019-12-14
- 1.2.10 — 2019-12-13
- 2.1.2 — 2019-11-09
- 2.1.1 — 2019-10-14
- 2.1.0 — 2019-10-01
- … 52 more at https://npm.io/package/fsevents/versions

## README

# fsevents

Native access to MacOS FSEvents in [Node.js](https://nodejs.org/)

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](https://github.com/paulmillr/chokidar).

## Usage

```sh
npm install fsevents
```

Supports only **Node.js v8.16 and higher**.

```js
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:

```js
/**
 * @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](https://github.com/fsevents/fsevents) and [NPM Page](https://npmjs.org/package/fsevents)

---
_Source: https://npm.io/package/fsevents · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._