{"id":13526922,"url":"https://github.com/webpack/watchpack","last_synced_at":"2025-05-13T19:09:05.516Z","repository":{"id":20833493,"uuid":"24119524","full_name":"webpack/watchpack","owner":"webpack","description":"Wrapper library for directory and file watching.","archived":false,"fork":false,"pushed_at":"2024-11-20T13:19:53.000Z","size":531,"stargazers_count":381,"open_issues_count":14,"forks_count":107,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-16T02:28:04.206Z","etag":null,"topics":["watch","watcher"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"webpack"}},"created_at":"2014-09-16T22:01:04.000Z","updated_at":"2025-03-22T02:57:35.000Z","dependencies_parsed_at":"2023-02-09T23:15:24.289Z","dependency_job_id":"5acdb6a6-26ff-4e3f-bc3d-60105d0a091f","html_url":"https://github.com/webpack/watchpack","commit_stats":{"total_commits":309,"total_committers":32,"mean_commits":9.65625,"dds":0.2621359223300971,"last_synced_commit":"1a1feae5db7d7955cfdb32d7457a0454820fa38c"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack%2Fwatchpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack%2Fwatchpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack%2Fwatchpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack%2Fwatchpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack","download_url":"https://codeload.github.com/webpack/watchpack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250711045,"owners_count":21474742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["watch","watcher"],"created_at":"2024-08-01T06:01:37.542Z","updated_at":"2025-04-25T18:28:28.648Z","avatar_url":"https://github.com/webpack.png","language":"JavaScript","readme":"# watchpack\n\nWrapper library for directory and file watching.\n\n[![Test](https://github.com/webpack/watchpack/actions/workflows/test.yml/badge.svg)](https://github.com/webpack/watchpack/actions/workflows/test.yml)\n[![Codecov](https://codecov.io/gh/webpack/watchpack/graph/badge.svg?token=8xk2OrrxWm)](https://codecov.io/gh/webpack/watchpack)\n[![Downloads](https://img.shields.io/npm/dm/watchpack.svg)](https://www.npmjs.com/package/watchpack)\n\n## Concept\n\nwatchpack high level API doesn't map directly to watchers. Instead a three level architecture ensures that for each directory only a single watcher exists.\n\n- The high level API requests `DirectoryWatchers` from a `WatcherManager`, which ensures that only a single `DirectoryWatcher` per directory is created.\n- A user-faced `Watcher` can be obtained from a `DirectoryWatcher` and provides a filtered view on the `DirectoryWatcher`.\n- Reference-counting is used on the `DirectoryWatcher` and `Watcher` to decide when to close them.\n- The real watchers are created by the `DirectoryWatcher`.\n- Files are never watched directly. This should keep the watcher count low.\n- Watching can be started in the past. This way watching can start after file reading.\n- Symlinks are not followed, instead the symlink is watched.\n\n## API\n\n```javascript\nvar Watchpack = require(\"watchpack\");\n\nvar wp = new Watchpack({\n\t// options:\n\taggregateTimeout: 1000,\n\t// fire \"aggregated\" event when after a change for 1000ms no additional change occurred\n\t// aggregated defaults to undefined, which doesn't fire an \"aggregated\" event\n\n\tpoll: true,\n\t// poll: true - use polling with the default interval\n\t// poll: 10000 - use polling with an interval of 10s\n\t// poll defaults to undefined, which prefer native watching methods\n\t// Note: enable polling when watching on a network path\n\t// When WATCHPACK_POLLING environment variable is set it will override this option\n\n\tfollowSymlinks: true,\n\t// true: follows symlinks and watches symlinks and real files\n\t//   (This makes sense when symlinks has not been resolved yet, comes with a performance hit)\n\t// false (default): watches only specified item they may be real files or symlinks\n\t//   (This makes sense when symlinks has already been resolved)\n\n\tignored: \"**/.git\"\n\t// ignored: \"string\" - a glob pattern for files or folders that should not be watched\n\t// ignored: [\"string\", \"string\"] - multiple glob patterns that should be ignored\n\t// ignored: /regexp/ - a regular expression for files or folders that should not be watched\n\t// ignored: (entry) =\u003e boolean - an arbitrary function which must return truthy to ignore an entry\n\t// For all cases expect the arbitrary function the path will have path separator normalized to '/'.\n\t// All subdirectories are ignored too\n});\n\n// Watchpack.prototype.watch({\n//   files: Iterable\u003cstring\u003e,\n//   directories: Iterable\u003cstring\u003e,\n//   missing: Iterable\u003cstring\u003e,\n//   startTime?: number\n// })\nwp.watch({\n\tfiles: listOfFiles,\n\tdirectories: listOfDirectories,\n\tmissing: listOfNotExistingItems,\n\tstartTime: Date.now() - 10000\n});\n// starts watching these files and directories\n// calling this again will override the files and directories\n// files: can be files or directories, for files: content and existence changes are tracked\n//        for directories: only existence and timestamp changes are tracked\n// directories: only directories, directory content (and content of children, ...) and\n//              existence changes are tracked.\n//              assumed to exist, when directory is not found without further information a remove event is emitted\n// missing: can be files or directories,\n//          only existence changes are tracked\n//          expected to not exist, no remove event is emitted when not found initially\n// files and directories are assumed to exist, when they are not found without further information a remove event is emitted\n// missing is assumed to not exist and no remove event is emitted\n\nwp.on(\"change\", function(filePath, mtime, explanation) {\n\t// filePath: the changed file\n\t// mtime: last modified time for the changed file\n\t// explanation: textual information how this change was detected\n});\n\nwp.on(\"remove\", function(filePath, explanation) {\n\t// filePath: the removed file or directory\n\t// explanation: textual information how this change was detected\n});\n\nwp.on(\"aggregated\", function(changes, removals) {\n\t// changes: a Set of all changed files\n\t// removals: a Set of all removed files\n\t// watchpack gives up ownership on these Sets.\n});\n\n// Watchpack.prototype.pause()\nwp.pause();\n// stops emitting events, but keeps watchers open\n// next \"watch\" call can reuse the watchers\n// The watcher will keep aggregating events\n// which can be received with getAggregated()\n\n// Watchpack.prototype.close()\nwp.close();\n// stops emitting events and closes all watchers\n\n// Watchpack.prototype.getAggregated(): { changes: Set\u003cstring\u003e, removals: Set\u003cstring\u003e }\nconst { changes, removals } = wp.getAggregated();\n// returns the current aggregated info and removes that from the watcher\n// The next aggregated event won't include that info and will only emitted\n// when futher changes happen\n// Can also be used when paused.\n\n// Watchpack.prototype.collectTimeInfoEntries(fileInfoEntries: Map\u003cstring, Entry\u003e, directoryInfoEntries: Map\u003cstring, Entry\u003e)\nwp.collectTimeInfoEntries(fileInfoEntries, directoryInfoEntries);\n// collects time info objects for all known files and directories\n// this include info from files not directly watched\n// key: absolute path, value: object with { safeTime, timestamp }\n// safeTime: a point in time at which it is safe to say all changes happened before that\n// timestamp: only for files, the mtime timestamp of the file\n\n// Watchpack.prototype.getTimeInfoEntries()\nvar fileTimes = wp.getTimeInfoEntries();\n// returns a Map with all known time info objects for files and directories\n// similar to collectTimeInfoEntries but returns a single map with all entries\n\n// (deprecated)\n// Watchpack.prototype.getTimes()\nvar fileTimes = wp.getTimes();\n// returns an object with all known change times for files\n// this include timestamps from files not directly watched\n// key: absolute path, value: timestamp as number\n```\n","funding_links":["https://opencollective.com/webpack"],"categories":["JavaScript","Repository"],"sub_categories":["Filesystem"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack%2Fwatchpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack%2Fwatchpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack%2Fwatchpack/lists"}