Explicit API: separate method for streams.

README.md

@@ -10,12 +10,36 @@ Merge multiple [GeoJSON](http://geojson.org/) files into one FeatureCollection.
 $ npm install --save @mapbox/geojson-merge
 ```
 
-## api
+## API
 
-### `merge([geojson, geojson2...])`
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-Merges GeoJSON objects (geometry, feature, or featurecollection) into one
-FeatureCollection.
+### merge
+
+Merge a series of GeoJSON objects into one FeatureCollection containing all
+features in all files.  The objects can be any valid GeoJSON root object,
+including FeatureCollection, Feature, and Geometry types.
+
+**Parameters**
+
+-   `inputs` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** a list of GeoJSON objects of any type
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a geojson FeatureCollection.
+
+### mergeFeatureCollectionStream
+
+Merge GeoJSON files containing GeoJSON FeatureCollections
+into a single stream of a FeatureCollection as a JSON string.
+
+This is more limited than merge - it only supports FeatureCollections
+as input - but more performant, since it can operate on GeoJSON files
+larger than what you can keep in memory at one time.
+
+**Parameters**
+
+-   `inputs` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a list of filenames of GeoJSON files
+
+Returns **[Stream](https://nodejs.org/api/stream.html)** output: a stringified JSON of a FeatureCollection.
 
 ## cli
 
@@ -31,18 +55,18 @@ $ geojson-merge file.geojson otherfile.geojson > combined.geojson
 ```
 
 ## geojson-merge (for dummies)
-  
-### Windows Instructions:  
-  
-1. Start the `node.js` application  
-2. Open `cmd.exe`  
-2. Browse to a folder where you'd like `geojson-merge` installed  
-3. In `cmd.exe` type the install string from above  
-4. Wait patiently, it could take a moment to start  
-5. Use `cd node_modules` to change directory  to the `node_modules` folder  
-5. For simplicity sake, move your .geojson files into this `node_modules` directory  
-6. Run this command to merge your files:  
-  
+
+### Windows Instructions:
+
+1.  Start the `node.js` application  
+2.  Open `cmd.exe`  
+3.  Browse to a folder where you'd like `geojson-merge` installed  
+4.  In `cmd.exe` type the install string from above  
+5.  Wait patiently, it could take a moment to start  
+6.  Use `cd node_modules` to change directory  to the `node_modules` folder  
+7.  For simplicity sake, move your .geojson files into this `node_modules` directory  
+8.  Run this command to merge your files:  
+
 ```bash
 $ node geojson-merge file1.geojson file2.geojson > merged.geojson
 ```
@@ -52,4 +76,3 @@ $ node geojson-merge file1.geojson file2.geojson > merged.geojson
 ```bash
 $ geojson-merge folder/*.geojson > combined.geojson
 ```
-

index.js

@@ -2,22 +2,39 @@ var normalize = require('geojson-normalize');
 var geojsonStream = require('geojson-stream');
 var fs = require('fs');
 
-module.exports = function(inputs, options) {
-    return (options || {}).stream
-    ? geojsonStreamMerge(inputs)
-    : geojsonMerge(inputs)
-};
-
-function geojsonMerge (inputs) {
-    return {
+/**
+ * Merge a series of GeoJSON objects into one FeatureCollection containing all
+ * features in all files.  The objects can be any valid GeoJSON root object,
+ * including FeatureCollection, Feature, and Geometry types.
+ *
+ * @param {Array<Object>} inputs a list of GeoJSON objects of any type
+ * @return {Object} a geojson FeatureCollection.
+ */
+function merge (inputs) {
+    var output = {
         type: 'FeatureCollection',
-        features: inputs.reduce(function(memo, input) {
-            return memo.concat(normalize(input).features);
-        }, [])
+        features: []
     };
+    for (var i = 0; i < inputs.length; i++) {
+        var normalized = normalize(inputs[i]);
+        for (var j = 0; j < normalized.features.length; j++) {
+            output.features.push(normalized.features[i]);
+        }
+    }
+    return output;
 }
 
-function geojsonStreamMerge (inputs) {
+/**
+ * Merge GeoJSON files containing GeoJSON FeatureCollections
+ * into a single stream of a FeatureCollection as a JSON string.
+ *
+ * This is more limited than merge - it only supports FeatureCollections
+ * as input - but more performant, since it can operate on GeoJSON files
+ * larger than what you can keep in memory at one time.
+ * @param {Array<string>} inputs a list of filenames of GeoJSON files
+ * @returns {Stream} output: a stringified JSON of a FeatureCollection.
+ */
+function mergeFeatureCollectionStream (inputs) {
     var out = geojsonStream.stringify();
     inputs.forEach(function(file) {
         fs.createReadStream(file)
@@ -26,3 +43,6 @@ function geojsonStreamMerge (inputs) {
     });
     return out;
 }
+
+module.exports.merge = merge;
+module.exports.mergeFeatureCollectionStream = mergeFeatureCollectionStream;

package.json

@@ -1,10 +1,11 @@
 {
   "name": "@mapbox/geojson-merge",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "merge multiple geojson files",
   "main": "index.js",
   "scripts": {
-    "test": "tape test.js"
+    "test": "tape test.js",
+    "doc": "documentation readme -s API"
   },
   "bin": {
     "geojson-merge": "geojson-merge"
@@ -31,5 +32,9 @@
     "minimist": "^1.2.0",
     "stream-concat": "0.1.0",
     "tape": "~2.13.4"
+  },
+  "devDependencies": {
+    "concat-stream": "^1.6.0",
+    "documentation": "^4.0.0-beta.18"
   }
-}
+}

test.js

@@ -1,16 +1,20 @@
-var merge = require('./'),
+var geojsonMerge = require('./'),
     test = require('tape'),
-    fixtures = require('geojson-fixtures');
+    fixtures = require('geojson-fixtures')
+    concat = require('concat-stream');
 
 
 test('merge', function(t) {
-    t.equal(merge([fixtures.geometry.point, fixtures.feature.one]).features.length, 2);
+    t.equal(geojsonMerge.merge([fixtures.geometry.point, fixtures.feature.one]).features.length, 2);
     t.end();
 });
 
 test('streaming merge', function (t) {
-    var stream = merge(['fixtures/featureCollection.geojson', 'fixtures/featureCollection.geojson'], { stream: true });
+    var stream = geojsonMerge.mergeFeatureCollectionStream(['fixtures/featureCollection.geojson', 'fixtures/featureCollection.geojson'], { stream: true });
     t.equal(typeof stream, 'object');
     t.equal(typeof stream.pipe,'function');
-    t.end();
+    stream.pipe(concat(function (combined) {
+        t.equal(JSON.parse(combined).features.length, 2);
+        t.end();
+    }));
 });