From effa77afeeba0cea90ca66881083dc6db8503f92 Mon Sep 17 00:00:00 2001 From: Lovell Fuller Date: Thu, 17 Nov 2016 19:50:19 +0000 Subject: [PATCH] Docs/types: add Promise and Array #472 Changelog updates and version bump of devDeps --- docs/api-channel.md | 2 +- docs/api-constructor.md | 48 +++++++++++------------ docs/api-input.md | 2 +- docs/api-operation.md | 2 +- docs/api-output.md | 4 +- docs/changelog.md | 4 ++ lib/channel.js | 2 +- lib/constructor.js | 2 +- lib/input.js | 2 +- lib/operation.js | 2 +- lib/output.js | 4 +- lib/types.d.ts | 87 +++++++++++++++++++++++++++++++++-------- package.json | 6 +-- 13 files changed, 113 insertions(+), 54 deletions(-) diff --git a/docs/api-channel.md b/docs/api-channel.md index ae19f025..079245af 100644 --- 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)<([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 index 42f25e72..6c959c2f 100644 --- a/docs/api-constructor.md +++ b/docs/api-constructor.md @@ -1,6 +1,6 @@ -# +# 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); -``` diff --git a/docs/api-input.md b/docs/api-input.md index 9f065dbf..28207842 100644 --- 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)<[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 index aff9f37a..4c5dbfc0 100644 --- 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)<[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 index 6a0973b4..353e2dc1 100644 --- 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)<[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 diff --git a/docs/changelog.md b/docs/changelog.md index bc4b436c..9b1d7004 100644 --- 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 index 21c11b71..88ffd5a4 100644 --- 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} 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 index b9066d38..b530f195 100644 --- 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 index 01a947c0..6f85ef7e 100644 --- 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|Sharp} */ const metadata = function metadata (callback) { const that = this; diff --git a/lib/operation.js b/lib/operation.js index e516691f..b57011fe 100644 --- 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} 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 index c8a91ede..ee498d3b 100644 --- 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} - 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} - 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 index c4a5cf9f..9920ce7b 100644 --- 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 +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|Sharp} */ -declare function metadata(callback?: (() => any)): (Promise|Sharp); +declare function metadata(callback?: (() => any)): (Promise.|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} 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} 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} - 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.; /** * 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} - when no callback is provided */ -declare function toBuffer(callback?: (() => any)): Promise; +declare function toBuffer(callback?: (() => any)): Promise.; /** * Include all metadata (EXIF, XMP, IPTC) from the input image in the output image. diff --git a/package.json b/package.json index 7f7b3451..cf9b943e 100644 --- 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",