Docs/types: add Promise<T> and Array<T> #472

Changelog updates and version bump of devDeps

docs/api-channel.md

@@ -38,7 +38,7 @@ For raw pixel input, the `options` object should contain a `raw` attribute, whic
 
 **Parameters**
 
--   `images` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Buffer](https://nodejs.org/api/buffer.html))** one or more images (file paths, Buffers).
+-   `images` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Buffer](https://nodejs.org/api/buffer.html))> | [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Buffer](https://nodejs.org/api/buffer.html))** one or more images (file paths, Buffers).
 -   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** image options, see `sharp()` constructor.
 
 

docs/api-constructor.md

@@ -1,6 +1,6 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-# 
+# Sharp
 
 **Parameters**
 
@@ -41,7 +41,29 @@ readableStream.pipe(transformer).pipe(writableStream);
 
 -   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
 
-Returns **Sharp** 
+Returns **[Sharp](#sharp)** 
+
+## format
+
+An Object containing nested boolean values representing the available input and output formats/methods.
+
+**Examples**
+
+```javascript
+console.log(sharp.format());
+```
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+
+## versions
+
+An Object containing the version numbers of libvips and its dependencies.
+
+**Examples**
+
+```javascript
+console.log(sharp.versions);
+```
 
 # queue
 
@@ -57,25 +79,3 @@ sharp.queue.on('change', function(queueLength) {
   console.log('Queue contains ' + queueLength + ' task(s)');
 });
 ```
-
-# format
-
-An Object containing nested boolean values representing the available input and output formats/methods.
-
-**Examples**
-
-```javascript
-console.log(sharp.format());
-```
-
-Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
-
-# versions
-
-An Object containing the version numbers of libvips and its dependencies.
-
-**Examples**
-
-```javascript
-console.log(sharp.versions);
-```

docs/api-input.md

@@ -57,7 +57,7 @@ image
   });
 ```
 
-Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | Sharp)** 
+Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)> | Sharp)** 
 
 # limitInputPixels
 

docs/api-operation.md

@@ -238,7 +238,7 @@ Convolve the image with the specified kernel.
 -   `kernel` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
     -   `kernel.width` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width of the kernel in pixels.
     -   `kernel.height` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width of the kernel in pixels.
-    -   `kernel.kernel` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of length `width*height` containing the kernel values.
+    -   `kernel.kernel` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>** Array of length `width*height` containing the kernel values.
     -   `kernel.scale` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** the scale of the kernel in pixels. (optional, default `sum`)
     -   `kernel.offset` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** the offset of the kernel in pixels. (optional, default `0`)
 

docs/api-output.md

@@ -19,7 +19,7 @@ A Promises/A+ promise is returned when `callback` is not provided.
 
 -   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
 
-Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** when no callback is provided
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** when no callback is provided
 
 # toBuffer
 
@@ -36,7 +36,7 @@ By default, the format will match the input image. JPEG, PNG, WebP, and RAW are
 
 -   `callback` **\[[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** 
 
-Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** when no callback is provided
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Buffer](https://nodejs.org/api/buffer.html)>** when no callback is provided
 
 # withMetadata
 

docs/changelog.md

@@ -30,6 +30,10 @@ Requires libvips v8.4.2.
   [#622](https://github.com/lovell/sharp/pull/622)
   [@ppaskaris](https://github.com/ppaskaris)
 
+* Allow use of extend with greyscale input.
+  [#623](https://github.com/lovell/sharp/pull/623)
+  [@ppaskaris](https://github.com/ppaskaris)
+
 ### v0.16 - "*pencil*"
 
 Requires libvips v8.3.3

lib/channel.js

@@ -54,7 +54,7 @@ const extractChannel = function extractChannel (channel) {
  * Buffers may be any of the image formats supported by sharp: JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data.
  * For raw pixel input, the `options` object should contain a `raw` attribute, which follows the format of the attribute of the same name in the `sharp()` constructor.
  *
- * @param {Array|String|Buffer} images - one or more images (file paths, Buffers).
+ * @param {Array<String|Buffer>|String|Buffer} images - one or more images (file paths, Buffers).
  * @param {Object} options - image options, see `sharp()` constructor.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters

lib/constructor.js

@@ -25,7 +25,7 @@ let versions = {
 })();
 
 /**
- * @name sharp
+ * @class Sharp
  *
  * Constructor factory to create an instance of `sharp`, to which further methods are chained.
  *

lib/input.js

@@ -154,7 +154,7 @@ const clone = function clone () {
  *   });
  *
  * @param {Function} [callback] - called with the arguments `(err, metadata)`
- * @returns {Promise|Sharp}
+ * @returns {Promise<Object>|Sharp}
  */
 const metadata = function metadata (callback) {
   const that = this;

lib/operation.js

@@ -318,7 +318,7 @@ const normalize = function normalize (normalize) {
  * @param {Object} kernel
  * @param {Number} kernel.width - width of the kernel in pixels.
  * @param {Number} kernel.height - width of the kernel in pixels.
- * @param {Array} kernel.kernel - Array of length `width*height` containing the kernel values.
+ * @param {Array<Number>} kernel.kernel - Array of length `width*height` containing the kernel values.
  * @param {Number} [kernel.scale=sum] - the scale of the kernel in pixels.
  * @param {Number} [kernel.offset=0] - the offset of the kernel in pixels.
  * @returns {Sharp}

lib/output.js

@@ -16,7 +16,7 @@ const sharp = require('../build/Release/sharp.node');
  * @param {String} fileOut - the path to write the image data to.
  * @param {Function} [callback] - called on completion with two arguments `(err, info)`.
  * `info` contains the output image `format`, `size` (bytes), `width`, `height` and `channels`.
- * @returns {Promise} - when no callback is provided
+ * @returns {Promise<Object>} - when no callback is provided
  * @throws {Error} Invalid parameters
  */
 const toFile = function toFile (fileOut, callback) {
@@ -53,7 +53,7 @@ const toFile = function toFile (fileOut, callback) {
  * A Promises/A+ promise is returned when `callback` is not provided.
  *
  * @param {Function} [callback]
- * @returns {Promise} - when no callback is provided
+ * @returns {Promise<Buffer>} - when no callback is provided
  */
 const toBuffer = function toBuffer (callback) {
   return this._pipeline(callback);

lib/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * @name sharp
+ * @class Sharp
  *
  * Constructor factory to create an instance of `sharp`, to which further methods are chained.
  *
@@ -41,14 +41,69 @@
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-declare var sharp
+declare class Sharp {
+   /**
+    * @class Sharp
+    *
+    * Constructor factory to create an instance of `sharp`, to which further methods are chained.
+    *
+    * JPEG, PNG or WebP format image data can be streamed out from this object.
+    * When using Stream based output, derived attributes are available from the `info` event.
+    *
+    * Implements the [stream.Duplex](http://nodejs.org/api/stream.html#stream_class_stream_duplex) class.
+    *
+    * @example
+    * sharp('input.jpg')
+    *   .resize(300, 200)
+    *   .toFile('output.jpg', function(err) {
+    *     // output.jpg is a 300 pixels wide and 200 pixels high image
+    *     // containing a scaled and cropped version of input.jpg
+    *   });
+    *
+    * @example
+    * // Read image data from readableStream,
+    * // resize to 300 pixels wide,
+    * // emit an 'info' event with calculated dimensions
+    * // and finally write image data to writableStream
+    * var transformer = sharp()
+    *   .resize(300)
+    *   .on('info', function(info) {
+    *     console.log('Image height is ' + info.height);
+    *   });
+    * readableStream.pipe(transformer).pipe(writableStream);
+    *
+    * @param {(Buffer|String)} [input] - if present, can be
+    *  a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or
+    *  a String containing the path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file.
+    *  JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when null or undefined.
+    * @param {Object} [options] - if present, is an Object with optional attributes.
+    * @param {Number} [options.density=72] - integral number representing the DPI for vector images.
+    * @param {Object} [options.raw] - describes raw pixel image data. See `raw()` for pixel ordering.
+    * @param {Number} [options.raw.width]
+    * @param {Number} [options.raw.height]
+    * @param {Number} [options.raw.channels]
+    * @returns {Sharp}
+    * @throws {Error} Invalid parameters
+    */
+   constructor(input?: (Buffer|String), options?: { density: Number, raw: Object });
 
-Constructor factory to create an instance of `sharp`, to which further methods are chained.
+   /**
+    * An Object containing nested boolean values representing the available input and output formats/methods.
+    * @example
+    * console.log(sharp.format());
+    * @returns {Object}
+    */
+   static format: any;
 
-JPEG, PNG or WebP format image data can be streamed out from this object.
+   /**
-When using Stream based output, derived attributes are available from the `info` event.
+    * An Object containing the version numbers of libvips and its dependencies.
+    * @member
+    * @example
+    * console.log(sharp.versions);
+    */
+   static versions: any;
 
-Implements the [stream.Duplex](http://nodejs.org/api/stream.html#stream_class_stream_duplex) class.: any;
+}
 
 /**
  * Pixel limits.
@@ -145,9 +200,9 @@ declare function clone(): Sharp;
  *   });
  *
  * @param {Function} [callback] - called with the arguments `(err, metadata)`
- * @returns {Promise|Sharp}
+ * @returns {Promise<Object>|Sharp}
  */
-declare function metadata(callback?: (() => any)): (Promise|Sharp);
+declare function metadata(callback?: (() => any)): (Promise.<Object>|Sharp);
 
 /**
  * Do not process input images where the number of pixels (width * height) exceeds this limit.
@@ -570,13 +625,13 @@ declare function normalize(normalize?: Boolean): Sharp;
  * @param {Object} kernel
  * @param {Number} kernel.width - width of the kernel in pixels.
  * @param {Number} kernel.height - width of the kernel in pixels.
- * @param {Array} kernel.kernel - Array of length `width*height` containing the kernel values.
+ * @param {Array<Number>} kernel.kernel - Array of length `width*height` containing the kernel values.
  * @param {Number} [kernel.scale=sum] - the scale of the kernel in pixels.
  * @param {Number} [kernel.offset=0] - the offset of the kernel in pixels.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-declare function convolve(kernel: { width: Number, height: Number, kernel: Array, scale: Number, offset: Number }): Sharp;
+declare function convolve(kernel: { width: Number, height: Number, kernel: Number[], scale: Number, offset: Number }): Sharp;
 
 /**
  * Any pixel value greather than or equal to the threshold value will be set to 255, otherwise it will be set to 0.
@@ -697,12 +752,12 @@ declare function extractChannel(channel: (Number|String)): Sharp;
  * Buffers may be any of the image formats supported by sharp: JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data.
  * For raw pixel input, the `options` object should contain a `raw` attribute, which follows the format of the attribute of the same name in the `sharp()` constructor.
  *
- * @param {Array|String|Buffer} images - one or more images (file paths, Buffers).
+ * @param {Array<String|Buffer>|String|Buffer} images - one or more images (file paths, Buffers).
  * @param {Object} options - image options, see `sharp()` constructor.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-declare function joinChannel(images: (Array|String|Buffer), options: Object): Sharp;
+declare function joinChannel(images: ((String|Buffer)[]|String|Buffer), options: Object): Sharp;
 
 /**
  * Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image.
@@ -734,10 +789,10 @@ declare function bandbool(boolOp: String): Sharp;
  * @param {String} fileOut - the path to write the image data to.
  * @param {Function} [callback] - called on completion with two arguments `(err, info)`.
  * `info` contains the output image `format`, `size` (bytes), `width`, `height` and `channels`.
- * @returns {Promise} - when no callback is provided
+ * @returns {Promise<Object>} - when no callback is provided
  * @throws {Error} Invalid parameters
  */
-declare function toFile(fileOut: String, callback?: (() => any)): Promise;
+declare function toFile(fileOut: String, callback?: (() => any)): Promise.<Object>;
 
 /**
  * Write output to a Buffer.
@@ -749,9 +804,9 @@ declare function toFile(fileOut: String, callback?: (() => any)): Promise;
  * A Promises/A+ promise is returned when `callback` is not provided.
  *
  * @param {Function} [callback]
- * @returns {Promise} - when no callback is provided
+ * @returns {Promise<Buffer>} - when no callback is provided
  */
-declare function toBuffer(callback?: (() => any)): Promise;
+declare function toBuffer(callback?: (() => any)): Promise.<Buffer>;
 
 /**
  * Include all metadata (EXIF, XMP, IPTC) from the input image in the output image.

package.json

@@ -72,13 +72,13 @@
     "async": "^2.1.2",
     "bufferutil": "^1.2.1",
     "cross-env": "^3.1.3",
-    "documentation": "^4.0.0-beta12",
+    "documentation": "^4.0.0-beta13",
     "exif-reader": "^1.0.1",
     "icc": "^0.0.2",
-    "jsdoc": "^3.4.2",
+    "jsdoc": "^3.4.3",
     "mocha": "^3.1.2",
     "node-cpplint": "^0.4.0",
-    "nyc": "^8.4.0",
+    "nyc": "^9.0.1",
     "rimraf": "^2.5.4",
     "semistandard": "^9.1.0",
     "tsd-jsdoc": "^1.0.1",