add README

README.md

@@ -1,3 +1,65 @@
-# batchasync.js
+# [batchasync.js](https://git.coolaj86.com/coolaj86/batchasync.js)
 
-Like forEachAsync, or Promise.all(), but handling a bounded number of items at any given time.
+Like forEachAsync, or Promise.all(), but handling a bounded number of items at any given time.
+
+## Install
+
+```bash
+npm install --save batchasync
+```
+
+## Usage
+
+```js
+// Browsers
+var batchAsync = window.batchAsync;
+```
+
+```js
+// Node
+var batchAsync = require('batchasync').batchAsync;
+```
+
+```js
+var batchSize = 4;
+var things = ['apples', 'bananas', 'pears'];
+
+function doStuff() {
+	// ... go fetch things
+}
+
+batchAsync(batchSize, things, doStuff).then(function(results) {
+	// all results, in order, just like Promise.all()
+	console.log(results[0]);
+});
+```
+
+### Returning 'undefined'
+
+Returning `undefined` will cause an exception to be thrown
+(because it looks like a skipped promise). Return `null` instead.
+
+**Example (bad)**:
+
+```js
+function doStuff(thing) {
+	// Oops! forgot to return
+	request('https://searchallthe.pictures/api/' + thing);
+}
+```
+
+**Example (good)**:
+
+```js
+function doStuff(thing) {
+	return request('https://searchallthe.pictures/api/' + thing);
+}
+```
+
+**Example (good)**:
+
+```js
+function doStuff(thing) {
+	return null;
+}
+```