Mathis/sharp
1
0
Fork 0
mirror of https://github.com/lovell/sharp.git synced 2025-07-09 18:40:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Changelog updates and version bump of devDeps
This commit is contained in:
Lovell Fuller 2016-11-17 19:50:19 +00:00
parent 6ccccf8c39
commit effa77afee
13 changed files with 113 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/api-channel.md
View File

@ -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.

48
docs/api-constructor.md
View File

@ -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);
```

2
docs/api-input.md
View File

@ -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

2
docs/api-operation.md
View File

@ -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`)

4
docs/api-output.md
View File

@ -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

4
docs/changelog.md
View File

@ -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

2
lib/channel.js
View File

@ -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

2
lib/constructor.js
View File

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

2
lib/input.js
View File

@ -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;

2
lib/operation.js
View File

@ -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}

4
lib/output.js
View File

@ -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);

87
lib/types.d.ts vendored
View File

@ -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.

6
package.json
View File

@ -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",