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.

133 lines
6.0 KiB

6 months ago
  1. # watchpack
  2. Wrapper library for directory and file watching.
  3. [![Test](https://github.com/webpack/watchpack/actions/workflows/test.yml/badge.svg)](https://github.com/webpack/watchpack/actions/workflows/test.yml)
  4. [![Codecov](https://codecov.io/gh/webpack/watchpack/graph/badge.svg?token=8xk2OrrxWm)](https://codecov.io/gh/webpack/watchpack)
  5. [![Downloads](https://img.shields.io/npm/dm/watchpack.svg)](https://www.npmjs.com/package/watchpack)
  6. ## Concept
  7. watchpack high level API doesn't map directly to watchers. Instead a three level architecture ensures that for each directory only a single watcher exists.
  8. - The high level API requests `DirectoryWatchers` from a `WatcherManager`, which ensures that only a single `DirectoryWatcher` per directory is created.
  9. - A user-faced `Watcher` can be obtained from a `DirectoryWatcher` and provides a filtered view on the `DirectoryWatcher`.
  10. - Reference-counting is used on the `DirectoryWatcher` and `Watcher` to decide when to close them.
  11. - The real watchers are created by the `DirectoryWatcher`.
  12. - Files are never watched directly. This should keep the watcher count low.
  13. - Watching can be started in the past. This way watching can start after file reading.
  14. - Symlinks are not followed, instead the symlink is watched.
  15. ## API
  16. ```javascript
  17. var Watchpack = require("watchpack");
  18. var wp = new Watchpack({
  19. // options:
  20. aggregateTimeout: 1000,
  21. // fire "aggregated" event when after a change for 1000ms no additional change occurred
  22. // aggregated defaults to undefined, which doesn't fire an "aggregated" event
  23. poll: true,
  24. // poll: true - use polling with the default interval
  25. // poll: 10000 - use polling with an interval of 10s
  26. // poll defaults to undefined, which prefer native watching methods
  27. // Note: enable polling when watching on a network path
  28. // When WATCHPACK_POLLING environment variable is set it will override this option
  29. followSymlinks: true,
  30. // true: follows symlinks and watches symlinks and real files
  31. // (This makes sense when symlinks has not been resolved yet, comes with a performance hit)
  32. // false (default): watches only specified item they may be real files or symlinks
  33. // (This makes sense when symlinks has already been resolved)
  34. ignored: "**/.git"
  35. // ignored: "string" - a glob pattern for files or folders that should not be watched
  36. // ignored: ["string", "string"] - multiple glob patterns that should be ignored
  37. // ignored: /regexp/ - a regular expression for files or folders that should not be watched
  38. // ignored: (entry) => boolean - an arbitrary function which must return truthy to ignore an entry
  39. // For all cases expect the arbitrary function the path will have path separator normalized to '/'.
  40. // All subdirectories are ignored too
  41. });
  42. // Watchpack.prototype.watch({
  43. // files: Iterable<string>,
  44. // directories: Iterable<string>,
  45. // missing: Iterable<string>,
  46. // startTime?: number
  47. // })
  48. wp.watch({
  49. files: listOfFiles,
  50. directories: listOfDirectories,
  51. missing: listOfNotExistingItems,
  52. startTime: Date.now() - 10000
  53. });
  54. // starts watching these files and directories
  55. // calling this again will override the files and directories
  56. // files: can be files or directories, for files: content and existence changes are tracked
  57. // for directories: only existence and timestamp changes are tracked
  58. // directories: only directories, directory content (and content of children, ...) and
  59. // existence changes are tracked.
  60. // assumed to exist, when directory is not found without further information a remove event is emitted
  61. // missing: can be files or directorees,
  62. // only existence changes are tracked
  63. // expected to not exist, no remove event is emitted when not found initially
  64. // files and directories are assumed to exist, when they are not found without further information a remove event is emitted
  65. // missing is assumed to not exist and no remove event is emitted
  66. wp.on("change", function(filePath, mtime, explanation) {
  67. // filePath: the changed file
  68. // mtime: last modified time for the changed file
  69. // explanation: textual information how this change was detected
  70. });
  71. wp.on("remove", function(filePath, explanation) {
  72. // filePath: the removed file or directory
  73. // explanation: textual information how this change was detected
  74. });
  75. wp.on("aggregated", function(changes, removals) {
  76. // changes: a Set of all changed files
  77. // removals: a Set of all removed files
  78. // watchpack gives up ownership on these Sets.
  79. });
  80. // Watchpack.prototype.pause()
  81. wp.pause();
  82. // stops emitting events, but keeps watchers open
  83. // next "watch" call can reuse the watchers
  84. // The watcher will keep aggregating events
  85. // which can be received with getAggregated()
  86. // Watchpack.prototype.close()
  87. wp.close();
  88. // stops emitting events and closes all watchers
  89. // Watchpack.prototype.getAggregated(): { changes: Set<string>, removals: Set<string> }
  90. const { changes, removals } = wp.getAggregated();
  91. // returns the current aggregated info and removes that from the watcher
  92. // The next aggregated event won't include that info and will only emitted
  93. // when futher changes happen
  94. // Can also be used when paused.
  95. // Watchpack.prototype.collectTimeInfoEntries(fileInfoEntries: Map<string, Entry>, directoryInfoEntries: Map<string, Entry>)
  96. wp.collectTimeInfoEntries(fileInfoEntries, directoryInfoEntries);
  97. // collects time info objects for all known files and directories
  98. // this include info from files not directly watched
  99. // key: absolute path, value: object with { safeTime, timestamp }
  100. // safeTime: a point in time at which it is safe to say all changes happened before that
  101. // timestamp: only for files, the mtime timestamp of the file
  102. // Watchpack.prototype.getTimeInfoEntries()
  103. var fileTimes = wp.getTimeInfoEntries();
  104. // returns a Map with all known time info objects for files and directories
  105. // similar to collectTimeInfoEntries but returns a single map with all entries
  106. // (deprecated)
  107. // Watchpack.prototype.getTimes()
  108. var fileTimes = wp.getTimes();
  109. // returns an object with all known change times for files
  110. // this include timestamps from files not directly watched
  111. // key: absolute path, value: timestamp as number
  112. ```