Merge pull request #96 from Agriculture-Intelligence/master

deps, `options: filename`, multipolygon, `.d.ts`, added compression options to `zip` and `download` interfaces, added deprecation warning for `download`

Author: sheindel

README.md

@@ -18,62 +18,62 @@ Or in a browser
 
 ## Caveats
 
-* Requires a capable fancy modern browser with [Typed Arrays](http://caniuse.com/#feat=typedarrays)
+- Requires a capable fancy modern browser with [Typed Arrays](http://caniuse.com/#feat=typedarrays)
   support
-* Geometries: Point, LineString, Polygon, MultiLineString, MultiPolygon
-* Tabular-style properties export with Shapefile's field name length limit
-* Uses jsZip for ZIP files, but [compression is buggy](https://github.com/Stuk/jszip/issues/53) so it uses STORE instead of DEFLATE.
+- Geometries: Point, LineString, Polygon, MultiLineString, MultiPolygon
+- Tabular-style properties export with Shapefile's field name length limit
+- Uses jsZip for ZIP files, but [compression is buggy](https://github.com/Stuk/jszip/issues/53) so it uses STORE instead of DEFLATE.
 
-## Example
+## Minimal Example
 
 ```js
-var shpwrite = require('shp-write');
+var shpwrite = require("shp-write");
 
-// (optional) set names for feature types and zipped folder
+// (minimal) set names for feature types and zipped folder
 var options = {
-    folder: 'myshapes',
-    types: {
-        point: 'mypoints',
-        polygon: 'mypolygons',
-        line: 'mylines'
-    }
-}
+  folder: "myshapes",
+  filename: "mydownload",
+  outputType: "base64",
+  compression: "DEFLATE",
+  types: {
+    point: "mypoints",
+    polygon: "mypolygons",
+    line: "mylines",
+  },
+};
 // a GeoJSON bridge for features
-shpwrite.download({
-    type: 'FeatureCollection',
+shpwrite.download(
+  {
+    type: "FeatureCollection",
     features: [
-        {
-            type: 'Feature',
-            geometry: {
-                type: 'Point',
-                coordinates: [0, 0]
-            },
-            properties: {
-                name: 'Foo'
-            }
+      {
+        type: "Feature",
+        geometry: {
+          type: "Point",
+          coordinates: [0, 0],
+        },
+        properties: {
+          name: "Foo",
+        },
+      },
+      {
+        type: "Feature",
+        geometry: {
+          type: "Point",
+          coordinates: [0, 10],
+        },
+        properties: {
+          name: "Bar",
         },
-        {
-            type: 'Feature',
-            geometry: {
-                type: 'Point',
-                coordinates: [0, 10]
-            },
-            properties: {
-                name: 'Bar'
-            }
-        }
-    ]
-}, options);
+      },
+    ],
+  },
+  options
+);
 // triggers a download of a zip file with shapefiles contained within.
 ```
 
 ## API
-
-### `download(geojson)`
-
-Given a [GeoJSON](http://geojson.org/) FeatureCollection as an object,
-converts convertible features into Shapefiles and triggers a download.
-
 ### `write(data, geometrytype, geometries, callback)`
 
 Given data, an array of objects for each row of data, geometry, the OGC standard
@@ -88,19 +88,31 @@ arrays, generate a shapfile and call the callback with `err` and an object with
 }
 ```
 
-### `zip(geojson)`
+### `zip(geojson, [options])`
 
 Generate a ArrayBuffer of a zipped shapefile, dbf, and prj, from a GeoJSON
 object.
 
+### DEPRECTEAD! May be removed in a future version
+### `download(geojson, [options])`
+
+Given a [GeoJSON](http://geojson.org/) FeatureCollection as an object,
+converts convertible features into Shapefiles and triggers a download. 
+
+The additional `options` parameter is passed to the underlying `zip` call. 
+
+This is now marked as deprecated because it applies to browsers only and the
+user should instead rely on an external library for this functionality like
+`file-saver` or `downloadjs`
+
 ## Other Implementations
 
-* https://code.google.com/p/pyshp/
+- https://code.google.com/p/pyshp/
 
 ## Reference
 
-* http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf
+- http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf
 
 ## Contributors
 
-* Nick Baugh <[email protected]>
+- Nick Baugh <[email protected]>

dist/index.d.ts

@@ -0,0 +1,84 @@
+declare module "shp-write" {
+  export enum OGCGeometry {
+    NULL,
+    POINT,
+    POLYLINE,
+    POLYGON,
+    MULTIPOINT,
+    POINTZ,
+    POLYLINEZ,
+    POLYGONZ,
+    MULTIPOINTZ,
+    POINTM,
+    POLYLINEM,
+    POLYGONM,
+    MULTIPOINTM,
+    MULTIPATCH,
+  }
+
+  export interface DownloadOptions {
+    folder?: string;
+    filename?: string;
+    types: {
+      point?: string;
+      polygon?: string;
+      line?: string;
+      multipolygon?: string;
+      multiline?: string;
+    };
+  }
+
+  type Compression = 'STORE' | 'DEFLATE';
+  interface OutputByType {
+    base64: string;
+    string: string;
+    text: string;
+    binarystring: string;
+    array: number[];
+    uint8array: Uint8Array;
+    arraybuffer: ArrayBuffer;
+    blob: Blob;
+    nodebuffer: Buffer;
+    stream: ReadableStream;
+  }
+  type OutputType = keyof OutputByType;
+
+  export interface ZipOptions {
+    compression: Compression,
+    outputType: OutputType
+  }
+
+  DEFAULT_ZIP_OPTIONS = {
+    compression: 'STORE',
+    outputType: 'base64',
+    types: {
+      point: "mypoints",
+      polygon: "mypolygons",
+      line: "mylines",
+    },
+  };
+
+  export function download(
+    geojson: GeoJSON.FeatureCollection,
+    options?: DownloadOptions & ZipOptions = DEFAULT_ZIP_OPTIONS
+  ): void;
+
+  export function write(
+    data: Array<object>,
+    geometrytype: OGCGeometry,
+    geometries: Array<object>,
+    callback: (
+      err: any,
+      data: {
+        shp: any;
+        shx: any;
+        dbf: any;
+      }
+    ) => void
+  ): void;
+
+  export function zip<T extends OutputType>(
+    geojson: GeoJSON.FeatureCollection,
+    options: DownloadOptions & ZipOptions = DEFAULT_ZIP_OPTIONS,
+    stream = false): Promise<OutputByType[T]>;
+}

dist/index.js

@@ -0,0 +1,3 @@
+module.exports.download = require("../src/download");
+module.exports.write = require("../src/write");
+module.exports.zip = require("../src/zip");

index.js

@@ -2,7 +2,8 @@
   "name": "shp-write",
   "version": "0.3.2",
   "description": "write shapefiles from pure javascript",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "test": "mocha -R spec",
     "prepublish": "npm run make",
@@ -13,7 +14,8 @@
     "url": "git://github.com/mapbox/shp-write.git"
   },
   "files": [
-    "index.js",
+    "dist/index.js",
+    "dist/index.d.ts",
     "src",
     "shpwrite.js"
   ],
@@ -23,19 +25,14 @@
     "js"
   ],
   "author": "Tom MacWright",
-  "contributors": [
-    {
-      "name": "Nick Baugh",
-      "email": "[email protected]"
-    }
-  ],
   "license": "BSD-2-Clause",
   "bugs": {
     "url": "https://github.com/mapbox/shp-write/issues"
   },
   "dependencies": {
-    "dbf": "0.1.4",
-    "jszip": "2.5.0"
+    "dbf": "0.2.0",
+    "jszip": "3.6.0",
+    "file-saver": "2.0.5"
   },
   "devDependencies": {
     "browserify": "^13.0.0",

package.json

@@ -1,6 +1,28 @@
 var zip = require('./zip');
+var saveAs = require("file-saver").saveAs;
 
-module.exports = function(gj, options) {
-    var content = zip(gj, options);
-    location.href = 'data:application/zip;base64,' + content;
+/**
+ * @deprecated may be removed in a future version, please use an external 
+ * download library
+ */
+module.exports = function (
+    gj, 
+    options = {
+      compression: 'STORE',
+      outputType: 'base64',
+      types: {
+        point: "mypoints",
+        polygon: "mypolygons",
+        line: "mylines",
+      },
+    },
+) {
+  let filename = 'download';
+
+  // since we only need a single filename object, we can use either the folder or
+  // filename, depending on what was passed in
+  if (options && (options.filename || options.folder)) {
+    filename = (options.filename || options.folder);
+  }
+  zip(gj, options).then(function (blob) { saveAs(blob, filename + '.zip'); });
 };

src/download.js

@@ -1,32 +1,35 @@
-module.exports.point = justType('Point', 'POINT');
-module.exports.line = justType('LineString', 'POLYLINE');
-module.exports.polygon = justType('Polygon', 'POLYGON');
+module.exports.point = justType("Point", "POINT");
+module.exports.line = justType("LineString", "POLYLINE");
+module.exports.multiline = justType("MultiLineString", "POLYLINE");
+module.exports.polygon = justType("Polygon", "POLYGON");
+module.exports.multipolygon = justType("MultiPolygon", "POLYGON");
 
 function justType(type, TYPE) {
-    return function(gj) {
-        var oftype = gj.features.filter(isType(type));
-        return {
-            geometries: (TYPE === 'POLYGON' || TYPE === 'POLYLINE') ? [oftype.map(justCoords)] : oftype.map(justCoords),
-            properties: oftype.map(justProps),
-            type: TYPE
-        };
+  return function (gj) {
+    var oftype = gj.features.filter(isType(type));
+    return {
+      geometries: oftype.map(justCoords),
+      properties: oftype.map(justProps),
+      type: TYPE,
     };
+  };
 }
 
 function justCoords(t) {
-    if (t.geometry.coordinates[0] !== undefined &&
-        t.geometry.coordinates[0][0] !== undefined &&
-        t.geometry.coordinates[0][0][0] !== undefined) {
-        return t.geometry.coordinates[0];
-    } else {
-        return t.geometry.coordinates;
-    }
+  return t.geometry.coordinates;
 }
 
 function justProps(t) {
-    return t.properties;
+  return t.properties;
 }
 
 function isType(t) {
-    return function(f) { return f.geometry.type === t; };
+  if (Array.isArray(t))
+    return function (f) {
+      return t.includes(f.geometry.type);
+    };
+  else
+    return function (f) {
+      return f.geometry.type === t;
+    };
 }

src/geojson.js

@@ -11,7 +11,7 @@ module.exports.write = function writePoints(coordinates, extent, shpView, shxVie
         // HEADER
         // 4 record number
         // 4 content length in 16-bit words (20/2)
-        shpView.setInt32(shpI, i);
+        shpView.setInt32(shpI, i + 1);
         shpView.setInt32(shpI + 4, 10);
 
         // record