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

lovell · lovell · commit effa77afeeba · 2016-11-17T21:29:41.000Z
Changelog updates and version bump of devDeps
diff --git a/docs/api-channel.md b/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)&lt;([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.
 
 
diff --git a/docs/api-constructor.md b/docs/api-constructor.md
@@ -1,6 +1,6 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-# 
+# Sharp
 
 **Parameters**
 
@@ -41,41 +41,41 @@ 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)** 
 
-# queue
-
-An EventEmitter that emits a `change` event when a task is either:
+## format
 
--   queued, waiting for _libuv_ to provide a worker thread
--   complete
+An Object containing nested boolean values representing the available input and output formats/methods.
 
 **Examples**
 
 ```javascript
-sharp.queue.on('change', function(queueLength) {
-  console.log('Queue contains ' + queueLength + ' task(s)');
-});
+console.log(sharp.format());
 ```
 
-# format
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
 
-An Object containing nested boolean values representing the available input and output formats/methods.
+## versions
+
+An Object containing the version numbers of libvips and its dependencies.
 
 **Examples**
 
 ```javascript
-console.log(sharp.format());
+console.log(sharp.versions);
 ```
 
-Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+# queue
 
-# versions
+An EventEmitter that emits a `change` event when a task is either:
 
-An Object containing the version numbers of libvips and its dependencies.
+-   queued, waiting for _libuv_ to provide a worker thread
+-   complete
 
 **Examples**
 
 ```javascript
-console.log(sharp.versions);
+sharp.queue.on('change', function(queueLength) {
+  console.log('Queue contains ' + queueLength + ' task(s)');
+});
 ```
diff --git a/docs/api-input.md b/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)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)> | Sharp)** 
 
 # limitInputPixels
 
diff --git a/docs/api-operation.md b/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)&lt;[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`)
 
diff --git a/docs/api-output.md b/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)&lt;[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)&lt;[Buffer](https://nodejs.org/api/buffer.html)>** when no callback is provided
 
 # withMetadata
 
diff --git a/docs/changelog.md b/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
diff --git a/lib/channel.js b/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
diff --git a/lib/constructor.js b/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.
  *
diff --git a/lib/input.js b/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;
diff --git a/lib/operation.js b/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}
diff --git a/lib/output.js b/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);
diff --git a/lib/types.d.ts b/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
-
-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.: any;
+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 });
+
+   /**
+    * An Object containing nested boolean values representing the available input and output formats/methods.
+    * @example
+    * console.log(sharp.format());
+    * @returns {Object}
+    */
+   static format: any;
+
+   /**
+    * An Object containing the version numbers of libvips and its dependencies.
+    * @member
+    * @example
+    * console.log(sharp.versions);
+    */
+   static versions: 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.
diff --git a/package.json b/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",

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ const extractChannel = function extractChannel (channel) {`
`54`	`54`	`* Buffers may be any of the image formats supported by sharp: JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data.`
`55`	`55`	* 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.
`56`	`56`	`*`
`57`		`- * @param {Array\|String\|Buffer} images - one or more images (file paths, Buffers).`
	`57`	`+ * @param {Array<String\|Buffer>\|String\|Buffer} images - one or more images (file paths, Buffers).`
`58`	`58`	* @param {Object} options - image options, see `sharp()` constructor.
`59`	`59`	`* @returns {Sharp}`
`60`	`60`	`* @throws {Error} Invalid parameters`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ let versions = {`
`25`	`25`	`})();`
`26`	`26`
`27`	`27`	`/**`
`28`		`- * @name sharp`
	`28`	`+ * @class Sharp`
`29`	`29`	`*`
`30`	`30`	* Constructor factory to create an instance of `sharp`, to which further methods are chained.
`31`	`31`	`*`
Original file line number	Diff line number	Diff line change
`@@ -154,7 +154,7 @@ const clone = function clone () {`
`154`	`154`	`* });`
`155`	`155`	`*`
`156`	`156`	* @param {Function} [callback] - called with the arguments `(err, metadata)`
`157`		`- * @returns {Promise\|Sharp}`
	`157`	`+ * @returns {Promise<Object>\|Sharp}`
`158`	`158`	`*/`
`159`	`159`	`const metadata = function metadata (callback) {`
`160`	`160`	`const that = this;`