New @turf/clusters module (getCluster, clusterEach, clusterReduce)

packages/turf-clusters/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TurfJS
+
+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 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.

packages/turf-clusters/README.md

@@ -0,0 +1,55 @@
+# @turf/clusters
+
+# getCluster
+
+Get Cluster
+
+**Parameters**
+
+-   `geojson` **([FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Feature](http://geojson.org/geojson-spec.html#feature-objects)>)** GeoJSON Features
+-   `filter` **Any** Filter used on GeoJSON properties to get Cluster
+
+**Examples**
+
+```javascript
+var geojson = turf.featureCollection([
+    turf.point([0, 0], {cluster: 0, foo: 'null'}),
+    turf.point([2, 4], {cluster: 1, foo: 'bar'}),
+    turf.point([3, 6], {cluster: 1}),
+    turf.point([5, 1], {0: 'foo'}),
+    turf.point([4, 2], {'bar': 'foo'})
+]);
+// Create a cluster by Object
+var cluster1 = getCluster(geojson, {cluster: 1});
+// Create a cluster by String
+var cluster2 = getCluster(geojson, 'cluster');
+// Create a cluster by an Array of Strings
+var cluster3 = getCluster(geojson, ['cluster', 'foo']);
+```
+
+Returns **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** Single Cluster filtered by GeoJSON Properties
+
+<!-- This file is automatically generated. Please don't edit it directly:
+if you find an error, edit the source file (likely index.js), and re-run
+./scripts/generate-readmes in the turf project. -->
+
+---
+
+This module is part of the [Turfjs project](http://turfjs.org/), an open source
+module collection dedicated to geographic algorithms. It is maintained in the
+[Turfjs/turf](https://github.com/Turfjs/turf) repository, where you can create
+PRs and issues.
+
+### Installation
+
+Install this module individually:
+
+```sh
+$ npm install @turf/clusters
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-clusters/bench.js

@@ -0,0 +1,46 @@
+const Benchmark = require('benchmark');
+const {featureCollection, point} = require('@turf/helpers');
+const {getCluster, clusterEach, clusterReduce} = require('./');
+const {propertiesContainsFilter, filterProperties, applyFilter, createBins} = require('./'); // Testing Purposes
+
+const geojson = featureCollection([
+    point([0, 0], {cluster: 0}),
+    point([2, 4], {cluster: 1}),
+    point([3, 6], {cluster: 1}),
+    point([5, 1], {0: 'foo'}),
+    point([4, 2], {'bar': 'foo'}),
+    point([2, 4], {}),
+    point([4, 3], undefined)
+]);
+
+/**
+ * Benchmark Results
+ *
+ * testing -- createBins x 2,954,562 ops/sec ±1.29% (89 runs sampled)
+ * testing -- propertiesContainsFilter x 10,902,619 ops/sec ±2.11% (85 runs sampled)
+ * testing -- filterProperties x 27,860,084 ops/sec ±1.12% (88 runs sampled)
+ * testing -- applyFilter x 18,971,594 ops/sec ±7.14% (77 runs sampled)
+ * getCluster -- string filter x 5,873,843 ops/sec ±1.30% (87 runs sampled)
+ * getCluster -- object filter x 883,469 ops/sec ±1.28% (93 runs sampled)
+ * getCluster -- aray filter x 3,602,147 ops/sec ±1.30% (89 runs sampled)
+ * clusterEach x 1,133,904 ops/sec ±0.90% (89 runs sampled)
+ * clusterReduce x 1,057,572 ops/sec ±1.13% (89 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-clusters');
+
+// Testing Purposes
+suite
+  .add('testing -- createBins', () => createBins(geojson.features, 'cluster'))
+  .add('testing -- propertiesContainsFilter', () => propertiesContainsFilter({foo: 'bar', cluster: 0}, {cluster: 0}))
+  .add('testing -- filterProperties', () => filterProperties({foo: 'bar', cluster: 0}, ['cluster']))
+  .add('testing -- applyFilter', () => applyFilter({foo: 'bar', cluster: 0}, ['cluster']));
+
+suite
+  .add('getCluster -- string filter', () => getCluster(geojson, 'cluster'))
+  .add('getCluster -- object filter', () => getCluster(geojson, {cluster: 1}))
+  .add('getCluster -- aray filter', () => getCluster(geojson, ['cluster']))
+  .add('clusterEach', () => clusterEach(geojson, 'cluster', cluster => { return cluster; }))
+  .add('clusterReduce', () => clusterReduce(geojson, 'cluster', (previousValue, cluster) => { return cluster; }))
+  .on('cycle', e => console.log(String(e.target)))
+  .on('complete', () => {})
+  .run();

packages/turf-clusters/index.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="geojson" />
+
+type FeatureCollection<T extends GeoJSON.GeometryObject> = GeoJSON.FeatureCollection<T>;
+type Feature<T extends GeoJSON.GeometryObject> = GeoJSON.Feature<T>;
+type GeometryObject = GeoJSON.GeometryObject;
+
+/**
+ * http://turfjs.org/docs/#getcluster
+ */
+export function getCluster<T extends GeometryObject>(
+    geojson: FeatureCollection<T> | Feature<T>[],
+    filter: any
+): FeatureCollection<T>;
+
+/**
+ * http://turfjs.org/docs/#clustereach
+ */
+export function clusterEach<T extends GeometryObject>(
+    geojson: FeatureCollection<T> | Feature<T>[],
+    property: number | string,
+    callback: (cluster: FeatureCollection<T>, clusterValue: any, currentIndex: number) => void
+): void;
+
+/**
+ * http://turfjs.org/docs/#clusterreduce
+ */
+export function clusterReduce<T extends GeometryObject>(
+    geojson: FeatureCollection<T> | Feature<T>[],
+    property: number | string,
+    callback: (previousValue: any, cluster: FeatureCollection<T>, clusterValue: any, currentIndex: number) => void,
+    initialValue: any
+): void;