switch to chokidar (#25)

* switch to chokidar for watcher, add debouce, queueing, async-done

* add tests for chokidar wrapper

* normalize repo structure

* normalize readme, add new docs

* clarify docs

.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": "gulp"
+}

.gitignore

@@ -1,6 +1,30 @@
-.DS_Store
+# Logs
+logs
 *.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
-build
-*.node
-components
+
+# Artifacts
+test/fixtures

.jscsrc

@@ -0,0 +1,3 @@
+{
+  "preset": "gulp"
+}

.travis.yml

@@ -1,7 +1,8 @@
 language: node_js
 node_js:
-  - "0.10"
-  - "0.12"
-  - "iojs"
+  - 'stable'
+  - '4'
+  - '0.12'
+  - '0.10'
 after_script:
   - npm run coveralls

LICENSE

@@ -1,20 +1,21 @@
-Copyright (c) 2013 Fractal <contact@wearefractal.com>
+The MIT License (MIT)
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Copyright (c) 2015 Blaine Bublitz, Eric Schoffstall and other contributors
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,57 +1,126 @@
-# glob-watcher [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status][david-image]][david-url]
-
-## Information
-
-<table>
-<tr>
-<td>Package</td><td>glob-watcher</td>
-</tr>
-<tr>
-<td>Description</td>
-<td>Watch globs</td>
-</tr>
-<tr>
-<td>Node Version</td>
-<td>>= 0.10</td>
-</tr>
-</table>
-
-## Usage
-
-```javascript
+<p align="center">
+  <a href="http://gulpjs.com">
+    <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
+  </a>
+</p>
+
+# glob-watcher
+
+[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url]
+
+Watch globs and execute a function upon change, with intelligent defaults for debouncing and queueing.
+
+## Example
+
+```js
 var watch = require('glob-watcher');
 
-// callback interface
-watch(['./*.js', '!./something.js'], function(){
-  // this function will be called each time a globbed
-  // file is changed
+watch(['./*.js', '!./something.js'], function(done){
+  // This function will be called each time a globbed file is changed
+  // but is debounced with a 200ms delay (default) and queues subsequent calls
 
-  // if you need access to the `evt` object, listen
+  // Make sure to signal async completion with the callback
+  // or by returning a stream, promise, observable or child process
+  done();
+
+  // if you need access to the `path` or `stat` object, listen
   // for the `change` event (see below)
+
+  // if you need to listen to specific events, use the returned
+  // watcher instance (see below)
 });
 
-// EE interface
+// Raw chokidar instance
 var watcher = watch(['./*.js', '!./something.js']);
-watcher.on('change', function(evt) {
-  // evt has what file changed and all that jazz
+
+// Listen for the 'change' event to get `path`/`stat`
+// No async completion available because this is the raw chokidar instance
+watcher.on('change', function(path, stat) {
+  // `path` is the path of the changed file
+  // `stat` is an `fs.Stat` object (not always available)
 });
 
-// add files after it has been created
-watcher.add('./somefolder/somefile.js');
+// Listen for other events
+// No async completion available because this is the raw chokidar instance
+watcher.on('add', function(path, stat) {
+  // `path` is the path of the changed file
+  // `stat` is an `fs.Stat` object (not always available)
+});
 ```
 
+## API
+
+### `watch(globs[, options][, fn])`
+
+Takes a path string, an array of path strings, a [glob][node-glob] string or an array of [glob][node-glob] strings as `globs` to watch on the filesystem. Also optionally takes `options` to configure the watcher and a `fn` to execute when a file changes.
+
+Returns an instance of [chokidar][chokidar].
+
+#### `fn([callback])`
+
+If the `fn` is passed, it will be called when the watcher emits a `change`, `add` or `unlink` event. It is automatically debounced with a default delay of 200 milliseconds and subsequent calls will be queued and called upon completion. These defaults can be changed using the `options`.
+
+The `fn` is passed a single argument, `callback`, which is a function that must be called when work in the `fn` is complete. Instead of calling the `callback` function, [async completion][async-completion] can be signalled by:
+  * Returning a `Stream` or `EventEmitter`
+  * Returning a `Child Process`
+  * Returning a `Promise`
+  * Returning an `Observable`
+
+Once async completion is signalled, if another run is queued, it will be executed.
+
+#### `options`
+
+##### `options.ignoreInitial`
+
+If set to `false` the `fn` is called during [chokidar][chokidar] instantiation as it discovers the file paths. Useful if it is desirable to trigger the `fn` during startup.
+
+__Passed through to [chokidar][chokidar], but defaulted to `true` instead of `false`.__
+
+Type: `Boolean`
+
+Default: `true`
+
+##### `options.delay`
+
+The delay to wait before triggering the `fn`. Useful for waiting on many changes before doing the work on changed files, e.g. find-and-replace on many files.
+
+Type: `Number`
+
+Default: `200` (milliseconds)
+
+##### `options.queue`
+
+Whether or not a file change should queue the `fn` execution if the `fn` is already running. Useful for a long running `fn`.
+
+Type: `Boolean`
+
+Default: `true`
+
+##### other
+
+Options are passed directly to [lodash.debounce][lodash-debounce] and [chokidar][chokidar], so all their options are supported. Any debounce-related options are documented in [lodash.debounce][lodash-debounce]. Any chokidar-related options are documented in [chokidar][chokidar].
+
+## License
+
+MIT
+
+[downloads-image]: http://img.shields.io/npm/dm/glob-watcher.svg
+[npm-url]: https://npmjs.com/package/glob-watcher
+[npm-image]: http://img.shields.io/npm/v/glob-watcher.svg
 
-[npm-url]: https://npmjs.org/package/glob-watcher
-[npm-image]: https://badge.fury.io/js/glob-watcher.png
+[travis-url]: https://travis-ci.org/gulpjs/glob-watcher
+[travis-image]: http://img.shields.io/travis/gulpjs/glob-watcher.svg?label=travis-ci
 
-[travis-url]: https://travis-ci.org/wearefractal/glob-watcher
-[travis-image]: https://travis-ci.org/wearefractal/glob-watcher.png?branch=master
+[appveyor-url]: https://ci.appveyor.com/project/gulpjs/glob-watcher
+[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/glob-watcher.svg?label=appveyor
 
-[coveralls-url]: https://coveralls.io/r/wearefractal/glob-watcher
-[coveralls-image]: https://coveralls.io/repos/wearefractal/glob-watcher/badge.png
+[coveralls-url]: https://coveralls.io/r/gulpjs/glob-watcher
+[coveralls-image]: http://img.shields.io/coveralls/gulpjs/glob-watcher/master.svg
 
-[depstat-url]: https://david-dm.org/wearefractal/glob-watcher
-[depstat-image]: https://david-dm.org/wearefractal/glob-watcher.png
+[gitter-url]: https://gitter.im/gulpjs/gulp
+[gitter-image]: https://badges.gitter.im/gulpjs/gulp.png
 
-[david-url]: https://david-dm.org/wearefractal/glob-watcher
-[david-image]: https://david-dm.org/wearefractal/glob-watcher.png?theme=shields.io
+[glob]: https://github.com/isaacs/node-glob
+[async-completion]: https://github.com/gulpjs/async-done#completion-and-error-resolution
+[chokidar]: https://github.com/paulmillr/chokidar
+[lodash-debounce]: https://lodash.com/docs#debounce

appveyor.yml

@@ -0,0 +1,24 @@
+# http://www.appveyor.com/docs/appveyor-yml
+# http://www.appveyor.com/docs/lang/nodejs-iojs
+
+environment:
+  matrix:
+    # node.js
+    - nodejs_version: "0.10"
+    - nodejs_version: "0.12"
+    - nodejs_version: "4"
+    - nodejs_version: "5"
+
+install:
+  - ps: Install-Product node $env:nodejs_version
+  - npm install
+
+test_script:
+  - node --version
+  - npm --version
+  - cmd: npm test
+
+build: off
+
+# build version format
+version: "{build}"