Implement Clone module (#824)

* Implement Clone module

* Fix spelling mistake

* Update docs

packages/turf-clone/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-clone/README.md

@@ -0,0 +1,53 @@
+# @turf/clone
+
+# clone
+
+Prevents GeoJSON coordinates from being mutated, similar to JSON.parse(JSON.stringify(geojson)).
+
+Only cloning coordinates can be 3x-20x faster than the `parse + stringify` approach.
+
+**Parameters**
+
+-   `geojson` **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** GeoJSON Object
+-   `cloneAll` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** clones entire GeoJSON (3-20x slower if True) (optional, default `false`)
+
+**Examples**
+
+```javascript
+var line = {
+  "type": "Feature",
+  "properties": {},
+  "geometry": {
+    "type": "LineString",
+    "coordinates": [[-74, 40], [-78, 42], [-82, 35]]
+  }
+}
+var lineCloned = turf.clone(line);
+```
+
+Returns **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** cloned GeoJSON Object
+
+<!-- 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/clone
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-clone/bench.js

@@ -0,0 +1,45 @@
+const Benchmark = require('benchmark');
+const {point, lineString, polygon, featureCollection} = require('@turf/helpers');
+const clone = require('./');
+
+const fixtures = [
+    point([0, 20]),
+    lineString([[10, 40], [0, 20]]),
+    polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]]),
+    featureCollection([
+        point([0, 20]),
+        lineString([[10, 40], [0, 20]]),
+        polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]])
+    ])
+];
+
+/**
+ * Benchmark Results
+ *
+ * Point: 0.149ms
+ * LineString: 0.036ms
+ * Polygon: 0.067ms
+ * FeatureCollection: 0.043ms
+ * Point x 6,972,739 ops/sec ±5.50% (86 runs sampled)
+ * Point -- clones entire object x 357,437 ops/sec ±0.95% (88 runs sampled)
+ * LineString x 1,502,039 ops/sec ±1.01% (86 runs sampled)
+ * LineString -- clones entire object x 291,562 ops/sec ±1.00% (88 runs sampled)
+ * Polygon x 723,111 ops/sec ±1.06% (87 runs sampled)
+ * Polygon -- clones entire object x 227,034 ops/sec ±0.62% (91 runs sampled)
+ * FeatureCollection x 370,012 ops/sec ±1.25% (87 runs sampled)
+ * FeatureCollection -- clones entire object x 91,582 ops/sec ±0.81% (86 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-clone');
+for (const fixture of fixtures) {
+    const name = (fixture.geometry) ? fixture.geometry.type : fixture.type;
+    console.time(name);
+    clone(fixture, true);
+    console.timeEnd(name);
+    suite.add(name, () => clone(fixture));
+    suite.add(name + ' -- clones entire object', () => clone(fixture, true));
+}
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-clone/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+type Types = GeoJSON.FeatureCollection<any> | GeoJSON.Feature<any> | GeoJSON.GeometryObject | GeoJSON.GeometryCollection;
+
+/**
+ * http://turfjs.org/docs/#clone
+ */
+declare function clone<T extends Types>(geojson: T, cloneAll?: boolean): T;
+declare namespace clone { }
+export = clone;

packages/turf-clone/index.js

@@ -0,0 +1,121 @@
+/**
+ * Prevents GeoJSON coordinates from being mutated, similar to JSON.parse(JSON.stringify(geojson)).
+ *
+ * Only cloning coordinates can be 3x-20x faster than the `parse + stringify` approach.
+ *
+ * @name clone
+ * @param {GeoJSON} geojson GeoJSON Object
+ * @param {Boolean} [cloneAll=false] clones entire GeoJSON (3-20x slower if True)
+ * @returns {GeoJSON} cloned GeoJSON Object
+ * @example
+ * var line = {
+ *   "type": "Feature",
+ *   "properties": {},
+ *   "geometry": {
+ *     "type": "LineString",
+ *     "coordinates": [[-74, 40], [-78, 42], [-82, 35]]
+ *   }
+ * }
+ * var lineCloned = turf.clone(line);
+ */
+module.exports = function (geojson, cloneAll) {
+    if (!geojson) throw new Error('geojson is required');
+    if (cloneAll && typeof cloneAll !== 'boolean') throw new Error('cloneAll must be a Boolean');
+
+    // Clone entire GeoJSON object (3-20x slower)
+    if (cloneAll) return JSON.parse(JSON.stringify(geojson));
+
+    // Clones only coordinates
+    return clone(geojson);
+};
+
+/**
+ * Clone
+ *
+ * @private
+ * @param {GeoJSON} geojson GeoJSON Feature or Geometry
+ * @returns {GeoJSON} cloned Feature
+ */
+function clone(geojson) {
+    // Geometry Object
+    if (geojson.coordinates) return cloneGeometry(geojson);
+
+    // Feature
+    if (geojson.type === 'Feature') return cloneFeature(geojson);
+
+    // Feature Collection
+    if (geojson.type === 'FeatureCollection') return cloneFeatureCollection(geojson);
+
+    // Geometry Collection
+    if (geojson.type === 'GeometryCollection') return cloneGeometry(geojson);
+}
+
+/**
+ * Clone Feature
+ *
+ * @private
+ * @param {Feature<any>} feature GeoJSON Feature
+ * @returns {Feature<any>} cloned Feature
+ */
+function cloneFeature(feature) {
+    var cloned = {
+        type: 'Feature',
+        properties: feature.properties || {},
+        geometry: cloneGeometry(feature.geometry)
+    };
+    if (feature.id) cloned.id = feature.id;
+    if (feature.bbox) cloned.bbox = feature.bbox;
+    return cloned;
+}
+
+/**
+ * Clone Feature Collection
+ *
+ * @private
+ * @param {FeatureCollection<any>} geojson GeoJSON Feature Collection
+ * @returns {FeatureCollection<any>} cloned Feature Collection
+ */
+function cloneFeatureCollection(geojson) {
+    return {
+        type: 'FeatureCollection',
+        features: geojson.features.map(function (feature) {
+            return cloneFeature(feature);
+        })
+    };
+}
+
+/**
+ * Clone Geometry
+ *
+ * @private
+ * @param {Geometry<any>} geometry GeoJSON Geometry
+ * @returns {Geometry<any>} cloned Geometry
+ */
+function cloneGeometry(geometry) {
+    if (geometry.type === 'GeometryCollection') {
+        return {
+            type: 'GeometryCollection',
+            geometries: geometry.geometries.map(function (geom) {
+                return cloneGeometry(geom);
+            })
+        };
+    }
+    return {
+        type: geometry.type,
+        coordinates: deepSlice(geometry.coordinates)
+    };
+}
+
+/**
+ * Deep Slice coordinates
+ *
+ * @private
+ * @param {Coordinates} coords Coordinates
+ * @returns {Coordinates} all coordinates sliced
+ */
+function deepSlice(coords) {
+    if (typeof coords[0] !== 'object') { return coords.slice(); }
+    return coords.map(function (coord) {
+        return deepSlice(coord);
+    });
+}

packages/turf-clone/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@turf/clone",
+  "version": "4.0.0",
+  "description": "turf clone module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "bench": "node bench.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/Turfjs/turf.git"
+  },
+  "keywords": [
+    "turf",
+    "clone"
+  ],
+  "author": "Turf Authors",
+  "contributors": [
+    "Denis Carriere <@DenisCarriere>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "@turf/helpers": "^4.4.0",
+    "@turf/meta": "^4.4.0",
+    "benchmark": "^2.1.4",
+    "tape": "^4.6.3"
+  },
+  "dependencies": {}
+}

packages/turf-clone/test.js

@@ -0,0 +1,91 @@
+const test = require('tape');
+const {point, lineString, polygon, featureCollection, geometryCollection} = require('@turf/helpers');
+const {coordEach} = require('@turf/meta');
+const clone = require('./');
+
+
+test('turf-clone', t => {
+    // Define Features
+    const pt = point([0, 20]);
+    const line = lineString([[10, 40], [0, 20]]);
+    const poly = polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]]);
+    const fc = featureCollection([
+        point([0, 20]),
+        lineString([[10, 40], [0, 20]]),
+        polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]])
+    ]);
+    const gc = geometryCollection([
+        point([0, 20]).geometry,
+        lineString([[10, 40], [0, 20]]).geometry,
+        polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]]).geometry
+    ]).geometry;
+
+    // Clone Features
+    const ptCloned = clone(pt);
+    const lineCloned = clone(line);
+    const polyCloned = clone(poly, true);
+    const fcCloned = clone(fc);
+    const gcCloned = clone(gc);
+
+    // Apply Mutation
+    ptCloned.geometry.coordinates.reverse();
+    lineCloned.geometry.coordinates.reverse();
+    polyCloned.geometry.coordinates.reverse();
+    coordEach(fcCloned, coord => coord.reverse());
+    coordEach(gcCloned, coord => coord.reverse());
+
+    // Original Geometries should not be mutated
+    t.deepEqual(pt.geometry.coordinates, [0, 20], 'point');
+    t.deepEqual(line.geometry.coordinates, [[10, 40], [0, 20]], 'lineString');
+    t.deepEqual(poly.geometry.coordinates, [[[10, 40], [0, 20], [20, 0], [10, 40]]], 'polygon');
+
+    // Feature Collection
+    t.deepEqual(fc.features[0].geometry.coordinates, [0, 20], 'fc - point');
+    t.deepEqual(fc.features[1].geometry.coordinates, [[10, 40], [0, 20]], 'fc - lineString');
+    t.deepEqual(fc.features[2].geometry.coordinates, [[[10, 40], [0, 20], [20, 0], [10, 40]]], 'fc - polygon');
+
+    // Geometry Collection
+    t.deepEqual(gc.geometries[0].coordinates, [0, 20], 'gc - point');
+    t.deepEqual(gc.geometries[1].coordinates, [[10, 40], [0, 20]], 'gc - lineString');
+    t.deepEqual(gc.geometries[2].coordinates, [[[10, 40], [0, 20], [20, 0], [10, 40]]], 'gc - polygon');
+    t.end();
+});
+
+test('turf-clone -- throws', t => {
+    const pt = point([0, 20]);
+
+    t.throws(() => clone(), /geojson is required/);
+    t.throws(() => clone(pt, 'foo'), /cloneAll must be a Boolean/);
+    t.end();
+});
+
+test('turf-clone -- optional properties', t => {
+    const pt = point([0, 20]);
+    pt.properties = undefined;
+    pt.id = 300;
+    pt.bbox = [0, 20, 0, 20];
+
+    const ptCloned = clone(pt);
+    t.deepEqual(ptCloned.bbox, [0, 20, 0, 20]);
+    t.equal(ptCloned.id, 300);
+    t.end();
+});
+
+test('turf-clone -- Geometry Objects', t => {
+    const pt = point([0, 20]).geometry;
+    const line = lineString([[10, 40], [0, 20]]).geometry;
+    const poly = polygon([[[10, 40], [0, 20], [20, 0], [10, 40]]]).geometry;
+
+    const ptCloned = clone(pt);
+    const lineCloned = clone(line);
+    const polyCloned = clone(poly);
+
+    ptCloned.coordinates.reverse();
+    lineCloned.coordinates.reverse();
+    polyCloned.coordinates.reverse();
+
+    t.deepEqual(pt.coordinates, [0, 20], 'geometry point');
+    t.deepEqual(line.coordinates, [[10, 40], [0, 20]], 'geometry line');
+    t.deepEqual(poly.coordinates, [[[10, 40], [0, 20], [20, 0], [10, 40]]], 'geometry polygon');
+    t.end();
+});

packages/turf-clone/types.ts

@@ -0,0 +1,6 @@
+import {point} from '@turf/helpers'
+import * as clone from './'
+
+const pt = point([0, 20])
+const ptCloned = clone(pt)
+const ptClonedAll = clone(pt, true)