{"id":13506823,"url":"https://github.com/shama/gaze","last_synced_at":"2025-05-14T07:08:21.258Z","repository":{"id":4912538,"uuid":"6068826","full_name":"shama/gaze","owner":"shama","description":":crystal_ball: A globbing fs.watch wrapper built from the best parts of other fine watch libs.","archived":false,"fork":false,"pushed_at":"2019-07-11T12:46:29.000Z","size":466,"stargazers_count":1153,"open_issues_count":68,"forks_count":168,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-11T01:41:57.484Z","etag":null,"topics":["watch","watch-files"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"thoughtbot/guides","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-10-04T00:21:13.000Z","updated_at":"2025-02-11T03:12:34.000Z","dependencies_parsed_at":"2022-08-29T07:20:41.585Z","dependency_job_id":null,"html_url":"https://github.com/shama/gaze","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shama%2Fgaze","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shama%2Fgaze/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shama%2Fgaze/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shama%2Fgaze/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shama","download_url":"https://codeload.github.com/shama/gaze/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092659,"owners_count":22013290,"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","watch-files"],"created_at":"2024-08-01T01:00:58.383Z","updated_at":"2025-05-14T07:08:21.216Z","avatar_url":"https://github.com/shama.png","language":"JavaScript","funding_links":[],"categories":["Project Logo","JavaScript","Examples"],"sub_categories":[],"readme":"# gaze [![Build Status](http://img.shields.io/travis/shama/gaze.svg)](https://travis-ci.org/shama/gaze) [![Build status](https://ci.appveyor.com/api/projects/status/vtx65w9eg511tgo4)](https://ci.appveyor.com/project/shama/gaze)\n\nA globbing `fs.watch` wrapper built from the best parts of other fine watch libs.  \nCompatible with Node.js \u003e= 4.x, Windows, macOS, and Linux.\n\n![gaze](http://dontkry.com/images/repos/gaze.png)\n\n[![NPM](https://nodei.co/npm/gaze.png?downloads=true)](https://nodei.co/npm/gaze/)\n\n## Usage\nInstall the module with: `npm install gaze` or place into your `package.json`\nand run `npm install`.\n\n```javascript\nconst gaze = require('gaze');\n\n// Watch all .js files/dirs in process.cwd()\ngaze('**/*.js', (err, watcher) =\u003e {\n  // Files have all started watching\n\n  // Get all watched files\n  const watched = watcher.watched();\n\n  // On file changed\n  watcher.on('changed', filepath =\u003e {\n    console.log(filepath + ' was changed');\n  });\n\n  // On file added\n  watcher.on('added', filepath =\u003e {\n    console.log(filepath + ' was added');\n  });\n\n  // On file deleted\n  watcher.on('deleted', filepath =\u003e {\n    console.log(filepath + ' was deleted');\n  });\n\n  // On changed/added/deleted\n  watcher.on('all', (event, filepath) =\u003e {\n    console.log(filepath + ' was ' + event);\n  });\n\n  // Get watched files with relative paths\n  const files = watcher.relative();\n});\n\n// Also accepts an array of patterns\ngaze(['stylesheets/*.css', 'images/**/*.png'], () =\u003e {\n  // Add more patterns later to be watched\n  watcher.add(['js/*.js']);\n});\n```\n\n### Alternate Interface\n\n```javascript\nconst {Gaze} = require('gaze');\n\nconst gaze = new Gaze('**/*');\n\n// Files have all started watching\ngaze.on('ready', watcher =\u003e { });\n\n// A file has been added/changed/deleted has occurred\ngaze.on('all', (event, filepath) =\u003e { });\n```\n\n### Errors\n\n```javascript\ngaze('**/*', (error, watcher) =\u003e {\n  if (error) {\n    // Handle error if it occurred while starting up\n  }\n});\n\n// Or with the alternative interface\nconst gaze = new Gaze();\ngaze.on('error', error =\u003e {\n  // Handle error here\n});\ngaze.add('**/*');\n```\n\n### Minimatch / Glob\n\nSee [isaacs's `minimatch`](https://github.com/isaacs/minimatch) for more\ninformation on glob patterns.\n\n## Documentation\n\n### gaze([patterns, options, callback])\n\n* `patterns` {`String`|`Array`} File patterns to be matched\n* `options` {`Object`}\n* `callback` {`Function`}\n  * `err` {`Error` | `null`}\n  * `watcher` {`Object`} Instance of the `Gaze` watcher\n\n### Class: `gaze.Gaze`\n\nCreate a `Gaze` object by instancing the `gaze.Gaze` class.\n\n```javascript\nconst Gaze = require('gaze').Gaze;\nconst gaze = new Gaze(pattern, options, callback);\n```\n\n#### Properties\n\n* `options` The options object passed in.\n  * `interval` {integer} Interval to pass to `fs.watchFile`\n  * `debounceDelay` {integer} Delay for events called in succession for the same\n    file/event in milliseconds\n  * `mode` {string} Force the watch mode. Either `'auto'` (default), `'watch'` (force native events), or `'poll'` (force stat polling).\n  * `cwd` {string} The current working directory to base file patterns from. Default is `process.cwd()`.\n\n#### Events\n\n* `ready(watcher)` When files have been globbed and watching has begun.\n* `all(event, filepath)` When an `added`, `changed`, `renamed`, or `deleted` event occurs.\n* `added(filepath)` When a file has been added to a watch directory.\n* `changed(filepath)` When a file has been changed.\n* `deleted(filepath)` When a file has been deleted.\n* `renamed(newPath, oldPath)` When a file has been renamed.\n* `end()` When the watcher is closed and watches have been removed.\n* `error(err)` When an error occurs.\n* `nomatch` When no files have been matched.\n\n#### Methods\n\n* `emit(event, [...])` Wrapper for `EventEmitter.emit`.\n  `added`|`changed`|`renamed`|`deleted` events will also trigger the `all` event.\n* `close()` Unwatch all files and reset the watch instance.\n* `add(patterns, callback)` Adds file(s) `patterns` to be watched.\n* `remove(filepath)` Removes a file or directory from being watched. Does not\n  recurse directories.\n* `watched()` Returns the currently watched files.\n* `relative([dir, unixify])` Returns the currently watched files with relative paths.\n  * `dir` {string} Only return relative files for this directory.\n  * `unixify` {boolean} Return paths with `/` instead of `\\\\` if on Windows.\n\n## Similar Projects\n\nOther great watch libraries to try are:\n\n* [paulmillr's `chokidar`](https://github.com/paulmillr/chokidar)\n* [amasad's `sane`](https://github.com/amasad/sane)\n* [mikeal's `watch`](https://github.com/mikeal/watch)\n* [github's `pathwatcher`](https://github.com/atom/node-pathwatcher)\n* [bevry's `watchr`](https://github.com/bevry/watchr)\n\n## Contributing\nIn lieu of a formal styleguide, take care to maintain the existing coding style.\nAdd unit tests for any new or changed functionality. Lint and test your code\nusing [grunt](http://gruntjs.com/).\n\n## Release History\n* 1.1.3 - Fix for Node 10 support (@aredridel). Officially dropping support for Node \u003c 4.\n* 1.1.2 - Prevent more `ENOENT` errors from escaping (@alexgorbatchev).\n* 1.1.1 - Prevent `fs.watch` errors from escaping error handler (@rosen-vladimirov). Fix `_addToWatched` without `path.sep` (@wyicwx).\n* 1.1.0 - Update to `globule@1.0.0` with `minimatch \u003e= 3.0.0`.\n* 1.0.0 - Revert back to 0.5.2. Drop support for Node.js v0.8. Fix for `maxListeners`. Update `globule` to `0.2.0`.\n* 0.6.4 - Catch and emit `error` from `readdir` (@oconnore). Fix for `0 maxListeners`. Use `graceful-fs` to avoid `EMFILE` errors in other places `fs` is used. Better method to determine if `pathwatcher` was built. Fix keeping process alive too much, only init `pathwatcher` if a file is being watched. Set min required to Windows Vista when building on Windows (@pvolok).\n* 0.6.3 - Add support for Node.js v0.11\n* 0.6.2 - Fix argument error with `watched()`. Fix for erroneous `added` events on folders. Ignore `msvs` build error 4244.\n* 0.6.1 - Fix for absolute paths.\n* 0.6.0 - Uses native OS events (fork of `pathwatcher`) but can fall back to stat polling. Everything is async to avoid blocking, including `relative()` and `watched()`. Better error handling. Update to `globule@0.2.0`. No longer watches `cwd` by default. Added `mode` option. Better `EMFILE` message. Avoids `ENOENT` errors with symlinks. All constructor arguments are optional.\n* 0.5.2 - Fix for `ENOENT` error with non-existent symlinks [BACKPORTED].\n* 0.5.1 - Use `setImmediate` (`process.nextTick` for Node.js v0.8) to defer `ready`/`nomatch` events (@amasad).\n* 0.5.0 - Process is now kept alive while watching files. Emits a `nomatch` event when no files are matching.\n* 0.4.3 - Track file additions in newly created folders (@brett-shwom).\n* 0.4.2 - Fix `.remove()` method to remove a single file in a directory (@kaelzhang). Fixing “`Cannot call method 'call' of undefined`” (@krasimir). Track new file additions within folders (@brett-shwom).\n* 0.4.1 - Fix `watchDir` not respecting close in race condition (@chrisirhc).\n* 0.4.0 - Drop support for Node.js v0.6. Use `globule` for file matching. Avoid Node.js v0.10 `path.resolve`/`join` errors. Register new files when added to non-existent folder. Multiple instances can now poll the same files (@jpommerening).\n* 0.3.4 - Code clean up. Fix “`path must be strings`” errors (@groner). Fix incorrect `added` events (@groner).\n* 0.3.3 - Fix for multiple patterns with negate.\n* 0.3.2 - Emit `end` before `removeAllListeners`.\n* 0.3.1 - Fix `added` events within subfolder patterns.\n* 0.3.0 - Handle safewrite events, `forceWatchMethod` option removed, bug fixes and watch optimizations (@rgaskill).\n* 0.2.2 - Fix issue where subsequent `add` calls dont get watched (@samcday). `removeAllListeners` on `close`.\n* 0.2.1 - Fix issue with invalid `added` events in current working dir.\n* 0.2.0 - Support and mark folders with `path.sep`. Add `forceWatchMethod` option. Support `renamed` events.\n* 0.1.6 - Recognize the `cwd` option properly\n* 0.1.5 - Catch “`too many open file`” errors\n* 0.1.4 - Really fix the race condition with 2 watches\n* 0.1.3 - Fix race condition with 2 watches\n* 0.1.2 - Read triggering changed event fix\n* 0.1.1 - Minor fixes\n* 0.1.0 - Initial release\n\n## License\nCopyright (c) 2018 Kyle Robinson Young  \nLicensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshama%2Fgaze","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshama%2Fgaze","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshama%2Fgaze/lists"}