sharp 0.17.2 → 0.18.2

package/lib/output.js

@@ -1,6 +1,5 @@
 'use strict';
 
-const util = require('util');
 const is = require('./is');
 const sharp = require('../build/Release/sharp.node');
 
@@ -15,11 +14,12 @@ 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`.
+ * `info` contains the output image `format`, `size` (bytes), `width`, `height`,
+ * `channels` and `premultiplied` (indicating if premultiplication was used).
  * @returns {Promise<Object>} - when no callback is provided
  * @throws {Error} Invalid parameters
  */
-const toFile = function toFile (fileOut, callback) {
+function toFile (fileOut, callback) {
   if (!fileOut || fileOut.length === 0) {
     const errOutputInvalid = new Error('Invalid output');
     if (is.fn(callback)) {
@@ -41,25 +41,33 @@ const toFile = function toFile (fileOut, callback) {
     }
   }
   return this;
-};
+}
 
 /**
  * Write output to a Buffer.
- * JPEG, PNG, WebP, and RAW output are supported.
+ * JPEG, PNG, WebP, TIFF and RAW output are supported.
  * By default, the format will match the input image, except GIF and SVG input which become PNG output.
  *
- * `callback`, if present, gets three arguments `(err, buffer, info)` where:
- * - `err` is an error message, if any.
- * - `buffer` is the output image data.
- * - `info` contains the output image `format`, `size` (bytes), `width`, `height` and `channels`.
- * A Promises/A+ promise is returned when `callback` is not provided.
+ * `callback`, if present, gets three arguments `(err, data, info)` where:
+ * - `err` is an error, if any.
+ * - `data` is the output image data.
+ * - `info` contains the output image `format`, `size` (bytes), `width`, `height`,
+ * `channels` and `premultiplied` (indicating if premultiplication was used).
+ * A Promise is returned when `callback` is not provided.
  *
+ * @param {Object} [options]
+ * @param {Boolean} [options.resolveWithObject] Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`.
  * @param {Function} [callback]
  * @returns {Promise<Buffer>} - when no callback is provided
  */
-const toBuffer = function toBuffer (callback) {
-  return this._pipeline(callback);
-};
+function toBuffer (options, callback) {
+  if (is.object(options)) {
+    if (is.bool(options.resolveWithObject)) {
+      this.options.resolveWithObject = options.resolveWithObject;
+    }
+  }
+  return this._pipeline(is.fn(options) ? options : callback);
+}
 
 /**
  * Include all metadata (EXIF, XMP, IPTC) from the input image in the output image.
@@ -70,7 +78,7 @@ const toBuffer = function toBuffer (callback) {
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-const withMetadata = function withMetadata (withMetadata) {
+function withMetadata (withMetadata) {
   this.options.withMetadata = is.bool(withMetadata) ? withMetadata : true;
   if (is.object(withMetadata)) {
     if (is.defined(withMetadata.orientation)) {
@@ -82,7 +90,7 @@ const withMetadata = function withMetadata (withMetadata) {
     }
   }
   return this;
-};
+}
 
 /**
  * Use these JPEG options for output image.
@@ -98,7 +106,7 @@ const withMetadata = function withMetadata (withMetadata) {
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
-const jpeg = function jpeg (options) {
+function jpeg (options) {
   if (is.object(options)) {
     if (is.defined(options.quality)) {
       if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
@@ -133,7 +141,7 @@ const jpeg = function jpeg (options) {
     }
   }
   return this._updateFormatOut('jpeg', options);
-};
+}
 
 /**
  * Use these PNG options for output image.
@@ -145,7 +153,7 @@ const jpeg = function jpeg (options) {
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
-const png = function png (options) {
+function png (options) {
   if (is.object(options)) {
     if (is.defined(options.progressive)) {
       this._setBooleanOption('pngProgressive', options.progressive);
@@ -162,7 +170,7 @@ const png = function png (options) {
     }
   }
   return this._updateFormatOut('png', options);
-};
+}
 
 /**
  * Use these WebP options for output image.
@@ -175,7 +183,7 @@ const png = function png (options) {
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
-const webp = function webp (options) {
+function webp (options) {
   if (is.object(options) && is.defined(options.quality)) {
     if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
       this.options.webpQuality = options.quality;
@@ -197,17 +205,22 @@ const webp = function webp (options) {
     this._setBooleanOption('webpNearLossless', options.nearLossless);
   }
   return this._updateFormatOut('webp', options);
-};
+}
 
 /**
  * Use these TIFF options for output image.
  * @param {Object} [options] - output options
  * @param {Number} [options.quality=80] - quality, integer 1-100
  * @param {Boolean} [options.force=true] - force TIFF output, otherwise attempt to use input format
+ * @param {Boolean} [options.compression='jpeg'] - compression options: lzw, deflate, jpeg
+ * @param {Boolean} [options.predictor='none'] - compression predictor options: none, horizontal, float
+ * @param {Number} [options.xres=1.0] - horizontal resolution in pixels/mm
+ * @param {Number} [options.yres=1.0] - vertical resolution in pixels/mm
+ * @param {Boolean} [options.squash=false] - squash 8-bit images down to 1 bit
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
-const tiff = function tiff (options) {
+function tiff (options) {
   if (is.object(options) && is.defined(options.quality)) {
     if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
       this.options.tiffQuality = options.quality;
@@ -215,16 +228,56 @@ const tiff = function tiff (options) {
       throw new Error('Invalid quality (integer, 1-100) ' + options.quality);
     }
   }
+  if (is.object(options) && is.defined(options.squash)) {
+    if (is.bool(options.squash)) {
+      this.options.tiffSquash = options.squash;
+    } else {
+      throw new Error('Invalid Value for squash ' + options.squash + ' Only Boolean Values allowed for options.squash.');
+    }
+  }
+  // resolution
+  if (is.object(options) && is.defined(options.xres)) {
+    if (is.number(options.xres)) {
+      this.options.tiffXres = options.xres;
+    } else {
+      throw new Error('Invalid Value for xres ' + options.xres + ' Only numeric values allowed for options.xres');
+    }
+  }
+  if (is.object(options) && is.defined(options.yres)) {
+    if (is.number(options.yres)) {
+      this.options.tiffYres = options.yres;
+    } else {
+      throw new Error('Invalid Value for yres ' + options.yres + ' Only numeric values allowed for options.yres');
+    }
+  }
+  // compression
+  if (is.defined(options) && is.defined(options.compression)) {
+    if (is.string(options.compression) && is.inArray(options.compression, ['lzw', 'deflate', 'jpeg', 'none'])) {
+      this.options.tiffCompression = options.compression;
+    } else {
+      const message = `Invalid compression option "${options.compression}". Should be one of: lzw, deflate, jpeg, none`;
+      throw new Error(message);
+    }
+  }
+  // predictor
+  if (is.defined(options) && is.defined(options.predictor)) {
+    if (is.string(options.predictor) && is.inArray(options.predictor, ['none', 'horizontal', 'float'])) {
+      this.options.tiffPredictor = options.predictor;
+    } else {
+      const message = `Invalid predictor option "${options.predictor}". Should be one of: none, horizontal, float`;
+      throw new Error(message);
+    }
+  }
   return this._updateFormatOut('tiff', options);
-};
+}
 
 /**
  * Force output to be raw, uncompressed uint8 pixel data.
  * @returns {Sharp}
  */
-const raw = function raw () {
+function raw () {
   return this._updateFormatOut('raw');
-};
+}
 
 /**
  * Force output to a given format.
@@ -233,15 +286,16 @@ const raw = function raw () {
  * @returns {Sharp}
  * @throws {Error} unsupported format or options
  */
-const toFormat = function toFormat (format, options) {
+function toFormat (format, options) {
   if (is.object(format) && is.string(format.id)) {
     format = format.id;
   }
+  if (format === 'jpg') format = 'jpeg';
   if (!is.inArray(format, ['jpeg', 'png', 'webp', 'tiff', 'raw'])) {
     throw new Error('Unsupported output format ' + format);
   }
   return this[format](options);
-};
+}
 
 /**
  * Use tile-based deep zoom (image pyramid) output.
@@ -267,7 +321,7 @@ const toFormat = function toFormat (format, options) {
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-const tile = function tile (tile) {
+function tile (tile) {
   if (is.object(tile)) {
     // Size of square tiles, in pixels
     if (is.defined(tile.size)) {
@@ -312,7 +366,7 @@ const tile = function tile (tile) {
     throw new Error('Invalid tile format ' + this.options.formatOut);
   }
   return this._updateFormatOut('dz');
-};
+}
 
 /**
  * Update the output format unless options.force is false,
@@ -323,10 +377,10 @@ const tile = function tile (tile) {
  * @param {Boolean} [options.force=true] - force output format, otherwise attempt to use input format
  * @returns {Sharp}
  */
-const _updateFormatOut = function _updateFormatOut (formatOut, options) {
+function _updateFormatOut (formatOut, options) {
   this.options.formatOut = (is.object(options) && options.force === false) ? 'input' : formatOut;
   return this;
-};
+}
 
 /**
  * Update a Boolean attribute of the this.options Object.
@@ -335,31 +389,31 @@ const _updateFormatOut = function _updateFormatOut (formatOut, options) {
  * @param {Boolean} val
  * @throws {Error} Invalid key
  */
-const _setBooleanOption = function _setBooleanOption (key, val) {
+function _setBooleanOption (key, val) {
   if (is.bool(val)) {
     this.options[key] = val;
   } else {
     throw new Error('Invalid ' + key + ' (boolean) ' + val);
   }
-};
+}
 
 /**
  * Called by a WriteableStream to notify us it is ready for data.
  * @private
  */
-const _read = function _read () {
+function _read () {
   if (!this.options.streamOut) {
     this.options.streamOut = true;
     this._pipeline();
   }
-};
+}
 
 /**
  * Invoke the C++ image processing pipeline
  * Supports callback, stream and promise variants
  * @private
  */
-const _pipeline = function _pipeline (callback) {
+function _pipeline (callback) {
   const that = this;
   if (typeof callback === 'function') {
     // output=file/buffer
@@ -423,11 +477,15 @@ const _pipeline = function _pipeline (callback) {
       return new Promise(function (resolve, reject) {
         that.on('finish', function () {
           that._flattenBufferIn();
-          sharp.pipeline(that.options, function (err, data) {
+          sharp.pipeline(that.options, function (err, data, info) {
             if (err) {
               reject(err);
             } else {
-              resolve(data);
+              if (that.options.resolveWithObject) {
+                resolve({ data: data, info: info });
+              } else {
+                resolve(data);
+              }
             }
           });
         });
@@ -435,77 +493,21 @@ const _pipeline = function _pipeline (callback) {
     } else {
       // output=promise, input=file/buffer
       return new Promise(function (resolve, reject) {
-        sharp.pipeline(that.options, function (err, data) {
+        sharp.pipeline(that.options, function (err, data, info) {
           if (err) {
             reject(err);
           } else {
-            resolve(data);
+            if (that.options.resolveWithObject) {
+              resolve({ data: data, info: info });
+            } else {
+              resolve(data);
+            }
           }
         });
       });
     }
   }
-};
-
-// Deprecated output options
-/* istanbul ignore next */
-const quality = util.deprecate(function (quality) {
-  const formatOut = this.options.formatOut;
-  const options = { quality: quality };
-  this.jpeg(options).webp(options).tiff(options);
-  this.options.formatOut = formatOut;
-  return this;
-}, 'quality: use jpeg({ quality: ... }), webp({ quality: ... }) and/or tiff({ quality: ... }) instead');
-/* istanbul ignore next */
-const progressive = util.deprecate(function (progressive) {
-  const formatOut = this.options.formatOut;
-  const options = { progressive: (progressive !== false) };
-  this.jpeg(options).png(options);
-  this.options.formatOut = formatOut;
-  return this;
-}, 'progressive: use jpeg({ progressive: ... }) and/or png({ progressive: ... }) instead');
-/* istanbul ignore next */
-const compressionLevel = util.deprecate(function (compressionLevel) {
-  const formatOut = this.options.formatOut;
-  this.png({ compressionLevel: compressionLevel });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'compressionLevel: use png({ compressionLevel: ... }) instead');
-/* istanbul ignore next */
-const withoutAdaptiveFiltering = util.deprecate(function (withoutAdaptiveFiltering) {
-  const formatOut = this.options.formatOut;
-  this.png({ adaptiveFiltering: (withoutAdaptiveFiltering === false) });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'withoutAdaptiveFiltering: use png({ adaptiveFiltering: ... }) instead');
-/* istanbul ignore next */
-const withoutChromaSubsampling = util.deprecate(function (withoutChromaSubsampling) {
-  const formatOut = this.options.formatOut;
-  this.jpeg({ chromaSubsampling: (withoutChromaSubsampling === false) ? '4:2:0' : '4:4:4' });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'withoutChromaSubsampling: use jpeg({ chromaSubsampling: "4:4:4" }) instead');
-/* istanbul ignore next */
-const trellisQuantisation = util.deprecate(function (trellisQuantisation) {
-  const formatOut = this.options.formatOut;
-  this.jpeg({ trellisQuantisation: (trellisQuantisation !== false) });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'trellisQuantisation: use jpeg({ trellisQuantisation: ... }) instead');
-/* istanbul ignore next */
-const overshootDeringing = util.deprecate(function (overshootDeringing) {
-  const formatOut = this.options.formatOut;
-  this.jpeg({ overshootDeringing: (overshootDeringing !== false) });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'overshootDeringing: use jpeg({ overshootDeringing: ... }) instead');
-/* istanbul ignore next */
-const optimiseScans = util.deprecate(function (optimiseScans) {
-  const formatOut = this.options.formatOut;
-  this.jpeg({ optimiseScans: (optimiseScans !== false) });
-  this.options.formatOut = formatOut;
-  return this;
-}, 'optimiseScans: use jpeg({ optimiseScans: ... }) instead');
+}
 
 /**
  * Decorate the Sharp prototype with output-related functions.
@@ -532,15 +534,4 @@ module.exports = function (Sharp) {
   ].forEach(function (f) {
     Sharp.prototype[f.name] = f;
   });
-  // Deprecated
-  Sharp.prototype.quality = quality;
-  Sharp.prototype.progressive = progressive;
-  Sharp.prototype.compressionLevel = compressionLevel;
-  Sharp.prototype.withoutAdaptiveFiltering = withoutAdaptiveFiltering;
-  Sharp.prototype.withoutChromaSubsampling = withoutChromaSubsampling;
-  Sharp.prototype.trellisQuantisation = trellisQuantisation;
-  Sharp.prototype.trellisQuantization = trellisQuantisation;
-  Sharp.prototype.overshootDeringing = overshootDeringing;
-  Sharp.prototype.optimiseScans = optimiseScans;
-  Sharp.prototype.optimizeScans = optimiseScans;
 };

package/lib/resize.js

@@ -36,6 +36,7 @@ const strategy = {
  * @private
  */
 const kernel = {
+  nearest: 'nearest',
   cubic: 'cubic',
   lanczos2: 'lanczos2',
   lanczos3: 'lanczos3'
@@ -62,6 +63,7 @@ const interpolator = {
  * By default, the resized image is centre cropped to the exact size specified.
  *
  * Possible reduction kernels are:
+ * - `nearest`: Use [nearest neighbour interpolation](http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation).
  * - `cubic`: Use a [Catmull-Rom spline](https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline).
  * - `lanczos2`: Use a [Lanczos kernel](https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel) with `a=2`.
  * - `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
@@ -89,8 +91,8 @@ const interpolator = {
  *     // of the image data in inputBuffer
  *   });
  *
- * @param {Number} [width] - pixels wide the resultant image should be, between 1 and 16383 (0x3FFF). Use `null` or `undefined` to auto-scale the width to match the height.
- * @param {Number} [height] - pixels high the resultant image should be, between 1 and 16383. Use `null` or `undefined` to auto-scale the height to match the width.
+ * @param {Number} [width] - pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
+ * @param {Number} [height] - pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
  * @param {Object} [options]
  * @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction.
  * @param {String} [options.interpolator='bicubic'] - the interpolator to use for image enlargement.
@@ -99,21 +101,21 @@ const interpolator = {
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-const resize = function resize (width, height, options) {
+function resize (width, height, options) {
   if (is.defined(width)) {
-    if (is.integer(width) && is.inRange(width, 1, this.constructor.maximum.width)) {
+    if (is.integer(width) && width > 0) {
       this.options.width = width;
     } else {
-      throw is.invalidParameterError('width', `integer between 1 and ${this.constructor.maximum.width}`, width);
+      throw is.invalidParameterError('width', 'positive integer', width);
     }
   } else {
     this.options.width = -1;
   }
   if (is.defined(height)) {
-    if (is.integer(height) && is.inRange(height, 1, this.constructor.maximum.height)) {
+    if (is.integer(height) && height > 0) {
       this.options.height = height;
     } else {
-      throw is.invalidParameterError('height', `integer between 1 and ${this.constructor.maximum.height}`, height);
+      throw is.invalidParameterError('height', 'positive integer', height);
     }
   } else {
     this.options.height = -1;
@@ -142,7 +144,7 @@ const resize = function resize (width, height, options) {
     }
   }
   return this;
-};
+}
 
 /**
  * Crop the resized image to the exact size specified, the default behaviour.
@@ -170,7 +172,7 @@ const resize = function resize (width, height, options) {
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-const crop = function crop (crop) {
+function crop (crop) {
   this.options.canvas = 'crop';
   if (!is.defined(crop)) {
     // Default
@@ -184,11 +186,14 @@ const crop = function crop (crop) {
   } else if (is.integer(crop) && crop >= strategy.entropy) {
     // Strategy
     this.options.crop = crop;
+  } else if (is.string(crop) && is.integer(strategy[crop])) {
+    // Strategy (string)
+    this.options.crop = strategy[crop];
   } else {
     throw is.invalidParameterError('crop', 'valid crop id/name/strategy', crop);
   }
   return this;
-};
+}
 
 /**
  * Preserving aspect ratio, resize the image to the maximum `width` or `height` specified
@@ -213,10 +218,10 @@ const crop = function crop (crop) {
  *
  * @returns {Sharp}
  */
-const embed = function embed () {
+function embed () {
   this.options.canvas = 'embed';
   return this;
-};
+}
 
 /**
  * Preserving aspect ratio, resize the image to be as large as possible
@@ -237,10 +242,10 @@ const embed = function embed () {
  *
  * @returns {Sharp}
  */
-const max = function max () {
+function max () {
   this.options.canvas = 'max';
   return this;
-};
+}
 
 /**
  * Preserving aspect ratio, resize the image to be as small as possible
@@ -250,20 +255,20 @@ const max = function max () {
  *
  * @returns {Sharp}
  */
-const min = function min () {
+function min () {
   this.options.canvas = 'min';
   return this;
-};
+}
 
 /**
  * Ignoring the aspect ratio of the input, stretch the image to
  * the exact `width` and/or `height` provided via `resize`.
  * @returns {Sharp}
  */
-const ignoreAspectRatio = function ignoreAspectRatio () {
+function ignoreAspectRatio () {
   this.options.canvas = 'ignore_aspect';
   return this;
-};
+}
 
 /**
  * Do not enlarge the output image if the input image width *or* height are already less than the required dimensions.
@@ -272,10 +277,10 @@ const ignoreAspectRatio = function ignoreAspectRatio () {
  * @param {Boolean} [withoutEnlargement=true]
  * @returns {Sharp}
 */
-const withoutEnlargement = function withoutEnlargement (withoutEnlargement) {
+function withoutEnlargement (withoutEnlargement) {
   this.options.withoutEnlargement = is.bool(withoutEnlargement) ? withoutEnlargement : true;
   return this;
-};
+}
 
 /**
  * Decorate the Sharp prototype with resize-related functions.

package/lib/utility.js

@@ -22,7 +22,7 @@ const sharp = require('../build/Release/sharp.node');
  * @param {Number} [options.items=100] - is the maximum number of operations to cache
  * @returns {Object}
  */
-const cache = function cache (options) {
+function cache (options) {
   if (is.bool(options)) {
     if (options) {
       // Default cache settings of 50MB, 20 files, 100 items
@@ -35,7 +35,7 @@ const cache = function cache (options) {
   } else {
     return sharp.cache();
   }
-};
+}
 cache(true);
 
 /**
@@ -57,9 +57,9 @@ cache(true);
  * @param {Number} [concurrency]
  * @returns {Number} concurrency
  */
-const concurrency = function concurrency (concurrency) {
+function concurrency (concurrency) {
   return sharp.concurrency(is.integer(concurrency) ? concurrency : null);
-};
+}
 
 /**
  * Provides access to internal task counters.
@@ -71,9 +71,9 @@ const concurrency = function concurrency (concurrency) {
  *
  * @returns {Object}
  */
-const counters = function counters () {
+function counters () {
   return sharp.counters();
-};
+}
 
 /**
  * Get and set use of SIMD vector unit instructions.
@@ -95,9 +95,9 @@ const counters = function counters () {
  * @param {Boolean} [simd=false]
  * @returns {Boolean}
  */
-const simd = function simd (simd) {
+function simd (simd) {
   return sharp.simd(is.bool(simd) ? simd : null);
-};
+}
 simd(false);
 
 /**