You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

89 lines
3.1 KiB

6 months ago
  1. # fsevents
  2. Native access to MacOS FSEvents in [Node.js](https://nodejs.org/)
  3. The FSEvents API in MacOS allows applications to register for notifications of
  4. changes to a given directory tree. It is a very fast and lightweight alternative
  5. to kqueue.
  6. This is a low-level library. For a cross-platform file watching module that
  7. uses fsevents, check out [Chokidar](https://github.com/paulmillr/chokidar).
  8. ## Usage
  9. ```sh
  10. npm install fsevents
  11. ```
  12. Supports only **Node.js v8.16 and higher**.
  13. ```js
  14. const fsevents = require('fsevents');
  15. // To start observation
  16. const stop = fsevents.watch(__dirname, (path, flags, id) => {
  17. const info = fsevents.getInfo(path, flags);
  18. });
  19. // To end observation
  20. stop();
  21. ```
  22. > **Important note:** The API behaviour is slightly different from typical JS APIs. The `stop` function **must** be
  23. > retrieved and stored somewhere, even if you don't plan to stop the watcher. If you forget it, the garbage collector
  24. > will eventually kick in, the watcher will be unregistered, and your callbacks won't be called anymore.
  25. The callback passed as the second parameter to `.watch` get's called whenever the operating system detects a
  26. a change in the file system. It takes three arguments:
  27. ###### `fsevents.watch(dirname: string, (path: string, flags: number, id: string) => void): () => Promise<undefined>`
  28. * `path: string` - the item in the filesystem that have been changed
  29. * `flags: number` - a numeric value describing what the change was
  30. * `id: string` - an unique-id identifying this specific event
  31. Returns closer callback which when called returns a Promise resolving when the watcher process has been shut down.
  32. ###### `fsevents.getInfo(path: string, flags: number, id: string): FsEventInfo`
  33. The `getInfo` function takes the `path`, `flags` and `id` arguments and converts those parameters into a structure
  34. that is easier to digest to determine what the change was.
  35. The `FsEventsInfo` has the following shape:
  36. ```js
  37. /**
  38. * @typedef {'created'|'modified'|'deleted'|'moved'|'root-changed'|'cloned'|'unknown'} FsEventsEvent
  39. * @typedef {'file'|'directory'|'symlink'} FsEventsType
  40. */
  41. {
  42. "event": "created", // {FsEventsEvent}
  43. "path": "file.txt",
  44. "type": "file", // {FsEventsType}
  45. "changes": {
  46. "inode": true, // Had iNode Meta-Information changed
  47. "finder": false, // Had Finder Meta-Data changed
  48. "access": false, // Had access permissions changed
  49. "xattrs": false // Had xAttributes changed
  50. },
  51. "flags": 0x100000000
  52. }
  53. ```
  54. ## Changelog
  55. - v2.3 supports Apple Silicon ARM CPUs
  56. - v2 supports node 8.16+ and reduces package size massively
  57. - v1.2.8 supports node 6+
  58. - v1.2.7 supports node 4+
  59. ## Troubleshooting
  60. - I'm getting `EBADPLATFORM` `Unsupported platform for fsevents` error.
  61. - 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.
  62. ## License
  63. The MIT License Copyright (C) 2010-2020 by Philipp Dunkel, Ben Noordhuis, Elan Shankar, Paul Miller — see LICENSE file.
  64. Visit our [GitHub page](https://github.com/fsevents/fsevents) and [NPM Page](https://npmjs.org/package/fsevents)