sharp 0.31.3 → 0.32.1

package/lib/index.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const Sharp = require('./constructor');

package/lib/input.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const color = require('color');
@@ -21,9 +24,9 @@ const align = {
  * @private
  */
 function _inputOptionsFromObject (obj) {
-  const { raw, density, limitInputPixels, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd } = obj;
-  return [raw, density, limitInputPixels, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd].some(is.defined)
-    ? { raw, density, limitInputPixels, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd }
+  const { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd } = obj;
+  return [raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd].some(is.defined)
+    ? { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd }
     : undefined;
 }
 
@@ -35,8 +38,9 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
   const inputDescriptor = {
     failOn: 'warning',
     limitInputPixels: Math.pow(0x3FFF, 2),
+    ignoreIcc: false,
     unlimited: false,
-    sequentialRead: false
+    sequentialRead: true
   };
   if (is.string(input)) {
     // filesystem
@@ -47,6 +51,11 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
       throw Error('Input Buffer is empty');
     }
     inputDescriptor.buffer = input;
+  } else if (is.arrayBuffer(input)) {
+    if (input.byteLength === 0) {
+      throw Error('Input bit Array is empty');
+    }
+    inputDescriptor.buffer = Buffer.from(input, 0, input.byteLength);
   } else if (is.typedArray(input)) {
     if (input.length === 0) {
       throw Error('Input Bit Array is empty');
@@ -92,6 +101,14 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
         throw is.invalidParameterError('density', 'number between 1 and 100000', inputOptions.density);
       }
     }
+    // Ignore embeddded ICC profile
+    if (is.defined(inputOptions.ignoreIcc)) {
+      if (is.bool(inputOptions.ignoreIcc)) {
+        inputDescriptor.ignoreIcc = inputOptions.ignoreIcc;
+      } else {
+        throw is.invalidParameterError('ignoreIcc', 'boolean', inputOptions.ignoreIcc);
+      }
+    }
     // limitInputPixels
     if (is.defined(inputOptions.limitInputPixels)) {
       if (is.bool(inputOptions.limitInputPixels)) {
@@ -327,6 +344,13 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
             throw is.invalidParameterError('text.spacing', 'number', inputOptions.text.spacing);
           }
         }
+        if (is.defined(inputOptions.text.wrap)) {
+          if (is.string(inputOptions.text.wrap) && is.inArray(inputOptions.text.wrap, ['word', 'char', 'wordChar', 'none'])) {
+            inputDescriptor.textWrap = inputOptions.text.wrap;
+          } else {
+            throw is.invalidParameterError('text.wrap', 'one of: word, char, wordChar, none', inputOptions.text.wrap);
+          }
+        }
         delete inputDescriptor.buffer;
       } else {
         throw new Error('Expected a valid string to create an image with text.');
@@ -387,8 +411,9 @@ function _isStreamInput () {
 /**
  * Fast access to (uncached) image metadata without decoding any compressed pixel data.
  *
- * This is taken from the header of the input image.
- * It does not include operations, such as resize, to be applied to the output image.
+ * This is read from the header of the input image.
+ * It does not take into consideration any operations to be applied to the output image,
+ * such as resize or rotate.
  *
  * Dimensions in the response will respect the `page` and `pages` properties of the
  * {@link /api-constructor#parameters|constructor parameters}.
@@ -423,6 +448,7 @@ function _isStreamInput () {
  * - `iptc`: Buffer containing raw IPTC data, if present
  * - `xmp`: Buffer containing raw XMP data, if present
  * - `tifftagPhotoshop`: Buffer containing raw TIFFTAG_PHOTOSHOP data, if present
+ * - `formatMagick`: String containing format for images loaded via *magick
  *
  * @example
  * const metadata = await sharp(input).metadata();

package/lib/is.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 /**
@@ -71,6 +74,14 @@ const typedArray = function (val) {
   return false;
 };
 
+/**
+ * Is this value an ArrayBuffer object?
+ * @private
+ */
+const arrayBuffer = function (val) {
+  return val instanceof ArrayBuffer;
+};
+
 /**
  * Is this value a non-empty string?
  * @private
@@ -134,6 +145,7 @@ module.exports = {
   bool: bool,
   buffer: buffer,
   typedArray: typedArray,
+  arrayBuffer: arrayBuffer,
   string: string,
   number: number,
   integer: integer,

package/lib/libvips.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const fs = require('fs');
@@ -85,8 +88,7 @@ const hasVendoredLibvips = function () {
 
 /* istanbul ignore next */
 const removeVendoredLibvips = function () {
-  const rm = fs.rmSync ? fs.rmSync : fs.rmdirSync;
-  rm(vendorPath, { recursive: true, maxRetries: 3, force: true });
+  fs.rmSync(vendorPath, { recursive: true, maxRetries: 3, force: true });
 };
 
 /* istanbul ignore next */
@@ -115,6 +117,7 @@ const useGlobalLibvips = function () {
   }
   /* istanbul ignore next */
   if (isRosetta()) {
+    log('Detected Rosetta, skipping search for globally-installed libvips');
     return false;
   }
   const globalVipsVersion = globalLibvipsVersion();

package/lib/operation.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const color = require('color');
@@ -111,7 +114,7 @@ function flop (flop) {
  *
  * You must provide an array of length 4 or a 2x2 affine transformation matrix.
  * By default, new pixels are filled with a black background. You can provide a background color with the `background` option.
- * A particular interpolator may also be specified. Set the `interpolator` option to an attribute of the `sharp.interpolator` Object e.g. `sharp.interpolator.nohalo`.
+ * A particular interpolator may also be specified. Set the `interpolator` option to an attribute of the `sharp.interpolators` Object e.g. `sharp.interpolators.nohalo`.
  *
  * In the case of a 2x2 matrix, the transform is:
  * - X = `matrix[0, 0]` \* (x + `idx`) + `matrix[0, 1]` \* (y + `idy`) + `odx`
@@ -128,7 +131,7 @@ function flop (flop) {
  * const pipeline = sharp()
  *   .affine([[1, 0.3], [0.1, 0.7]], {
  *      background: 'white',
- *      interpolate: sharp.interpolators.nohalo
+ *      interpolator: sharp.interpolators.nohalo
  *   })
  *   .toBuffer((err, outputBuffer, info) => {
  *      // outputBuffer contains the transformed image
@@ -232,7 +235,7 @@ function affine (matrix, options) {
  *   .toBuffer();
  *
  * @param {Object|number} [options] - if present, is an Object with attributes
- * @param {number} [options.sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`, between 0.000001 and 10000
+ * @param {number} [options.sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`, between 0.000001 and 10
  * @param {number} [options.m1=1.0] - the level of sharpening to apply to "flat" areas, between 0 and 1000000
  * @param {number} [options.m2=2.0] - the level of sharpening to apply to "jagged" areas, between 0 and 1000000
  * @param {number} [options.x1=2.0] - threshold between "flat" and "jagged", between 0 and 1000000
@@ -270,10 +273,10 @@ function sharpen (options, flat, jagged) {
       }
     }
   } else if (is.plainObject(options)) {
-    if (is.number(options.sigma) && is.inRange(options.sigma, 0.000001, 10000)) {
+    if (is.number(options.sigma) && is.inRange(options.sigma, 0.000001, 10)) {
       this.options.sharpenSigma = options.sigma;
     } else {
-      throw is.invalidParameterError('options.sigma', 'number between 0.000001 and 10000', options.sigma);
+      throw is.invalidParameterError('options.sigma', 'number between 0.000001 and 10', options.sigma);
     }
     if (is.defined(options.m1)) {
       if (is.number(options.m1) && is.inRange(options.m1, 0, 1000000)) {
@@ -402,6 +405,32 @@ function flatten (options) {
   return this;
 }
 
+/**
+ * Ensure the image has an alpha channel
+ * with all white pixel values made fully transparent.
+ *
+ * Existing alpha channel values for non-white pixels remain unchanged.
+ *
+ * This feature is experimental and the API may change.
+ *
+ * @since 0.32.1
+ *
+ * @example
+ * await sharp(rgbInput)
+ *   .unflatten()
+ *   .toBuffer();
+ *
+ * @example
+ * await sharp(rgbInput)
+ *   .threshold(128, { grayscale: false }) // converter bright pixels to white
+ *   .unflatten()
+ *   .toBuffer();
+ */
+function unflatten () {
+  this.options.unflatten = true;
+  return this;
+}
+
 /**
  * Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of `1/gamma`
  * then increasing the encoding (brighten) post-resize at a factor of `gamma`.
@@ -466,16 +495,50 @@ function negate (options) {
 }
 
 /**
- * Enhance output image contrast by stretching its luminance to cover the full dynamic range.
+ * Enhance output image contrast by stretching its luminance to cover a full dynamic range.
+ *
+ * Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.
+ *
+ * Luminance values below the `lower` percentile will be underexposed by clipping to zero.
+ * Luminance values above the `upper` percentile will be overexposed by clipping to the max pixel value.
  *
  * @example
- * const output = await sharp(input).normalise().toBuffer();
+ * const output = await sharp(input)
+ *   .normalise()
+ *   .toBuffer();
+ *
+ * @example
+ * const output = await sharp(input)
+ *   .normalise({ lower: 0, upper: 100 })
+ *   .toBuffer();
  *
- * @param {Boolean} [normalise=true]
+ * @param {Object} [options]
+ * @param {number} [options.lower=1] - Percentile below which luminance values will be underexposed.
+ * @param {number} [options.upper=99] - Percentile above which luminance values will be overexposed.
  * @returns {Sharp}
  */
-function normalise (normalise) {
-  this.options.normalise = is.bool(normalise) ? normalise : true;
+function normalise (options) {
+  if (is.plainObject(options)) {
+    if (is.defined(options.lower)) {
+      if (is.number(options.lower) && is.inRange(options.lower, 0, 99)) {
+        this.options.normaliseLower = options.lower;
+      } else {
+        throw is.invalidParameterError('lower', 'number between 0 and 99', options.lower);
+      }
+    }
+    if (is.defined(options.upper)) {
+      if (is.number(options.upper) && is.inRange(options.upper, 1, 100)) {
+        this.options.normaliseUpper = options.upper;
+      } else {
+        throw is.invalidParameterError('upper', 'number between 1 and 100', options.upper);
+      }
+    }
+  }
+  if (this.options.normaliseLower >= this.options.normaliseUpper) {
+    throw is.invalidParameterError('range', 'lower to be less than upper',
+      `${this.options.normaliseLower} >= ${this.options.normaliseUpper}`);
+  }
+  this.options.normalise = true;
   return this;
 }
 
@@ -483,13 +546,17 @@ function normalise (normalise) {
  * Alternative spelling of normalise.
  *
  * @example
- * const output = await sharp(input).normalize().toBuffer();
+ * const output = await sharp(input)
+ *   .normalize()
+ *   .toBuffer();
  *
- * @param {Boolean} [normalize=true]
+ * @param {Object} [options]
+ * @param {number} [options.lower=1] - Percentile below which luminance values will be underexposed.
+ * @param {number} [options.upper=99] - Percentile above which luminance values will be overexposed.
  * @returns {Sharp}
  */
-function normalize (normalize) {
-  return this.normalise(normalize);
+function normalize (options) {
+  return this.normalise(options);
 }
 
 /**
@@ -509,34 +576,33 @@ function normalize (normalize) {
  *   .toBuffer();
  *
  * @param {Object} options
- * @param {number} options.width - integer width of the region in pixels.
- * @param {number} options.height - integer height of the region in pixels.
- * @param {number} [options.maxSlope=3] - maximum value for the slope of the
- *  cumulative histogram. A value of 0 disables contrast limiting. Valid values
- *  are integers in the range 0-100 (inclusive)
+ * @param {number} options.width - Integral width of the search window, in pixels.
+ * @param {number} options.height - Integral height of the search window, in pixels.
+ * @param {number} [options.maxSlope=3] - Integral level of brightening, between 0 and 100, where 0 disables contrast limiting.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
 function clahe (options) {
-  if (!is.plainObject(options)) {
-    throw is.invalidParameterError('options', 'plain object', options);
-  }
-  if (!('width' in options) || !is.integer(options.width) || options.width <= 0) {
-    throw is.invalidParameterError('width', 'integer above zero', options.width);
-  } else {
-    this.options.claheWidth = options.width;
-  }
-  if (!('height' in options) || !is.integer(options.height) || options.height <= 0) {
-    throw is.invalidParameterError('height', 'integer above zero', options.height);
-  } else {
-    this.options.claheHeight = options.height;
-  }
-  if (!is.defined(options.maxSlope)) {
-    this.options.claheMaxSlope = 3;
-  } else if (!is.integer(options.maxSlope) || options.maxSlope < 0 || options.maxSlope > 100) {
-    throw is.invalidParameterError('maxSlope', 'integer 0-100', options.maxSlope);
+  if (is.plainObject(options)) {
+    if (is.integer(options.width) && options.width > 0) {
+      this.options.claheWidth = options.width;
+    } else {
+      throw is.invalidParameterError('width', 'integer greater than zero', options.width);
+    }
+    if (is.integer(options.height) && options.height > 0) {
+      this.options.claheHeight = options.height;
+    } else {
+      throw is.invalidParameterError('height', 'integer greater than zero', options.height);
+    }
+    if (is.defined(options.maxSlope)) {
+      if (is.integer(options.maxSlope) && is.inRange(options.maxSlope, 0, 100)) {
+        this.options.claheMaxSlope = options.maxSlope;
+      } else {
+        throw is.invalidParameterError('maxSlope', 'integer between 0 and 100', options.maxSlope);
+      }
+    }
   } else {
-    this.options.claheMaxSlope = options.maxSlope;
+    throw is.invalidParameterError('options', 'plain object', options);
   }
   return this;
 }
@@ -835,6 +901,7 @@ module.exports = function (Sharp) {
     median,
     blur,
     flatten,
+    unflatten,
     gamma,
     negate,
     normalise,

package/lib/output.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const path = require('path');
@@ -40,7 +43,7 @@ const bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math
  * Note that raw pixel data is only supported for buffer output.
  *
  * By default all metadata will be removed, which includes EXIF-based orientation.
- * See {@link withMetadata} for control over this.
+ * See {@link #withmetadata|withMetadata} for control over this.
  *
  * The caller is responsible for ensuring directory structures and permissions exist.
  *
@@ -61,6 +64,7 @@ const bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math
  * `info` contains the output image `format`, `size` (bytes), `width`, `height`,
  * `channels` and `premultiplied` (indicating if premultiplication was used).
  * When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`.
+ * When using the attention crop strategy also contains `attentionX` and `attentionY`, the focal point of the cropped region.
  * May also contain `textAutofitDpi` (dpi the font was rendered at) if image was created from text.
  * @returns {Promise<Object>} - when no callback is provided
  * @throws {Error} Invalid parameters
@@ -91,12 +95,12 @@ function toFile (fileOut, callback) {
  * Write output to a Buffer.
  * JPEG, PNG, WebP, AVIF, TIFF, GIF and raw pixel data output are supported.
  *
- * Use {@link toFormat} or one of the format-specific functions such as {@link jpeg}, {@link png} etc. to set the output format.
+ * Use {@link #toformat|toFormat} or one of the format-specific functions such as {@link jpeg}, {@link png} etc. to set the output format.
  *
  * If no explicit format is set, the output format will match the input image, except SVG input which becomes PNG output.
  *
  * By default all metadata will be removed, which includes EXIF-based orientation.
- * See {@link withMetadata} for control over this.
+ * See {@link #withmetadata|withMetadata} for control over this.
  *
  * `callback`, if present, gets three arguments `(err, data, info)` where:
  * - `err` is an error, if any.
@@ -173,12 +177,18 @@ function toBuffer (options, callback) {
  *   .then(info => { ... });
  *
  * @example
- * // Set "IFD0-Copyright" in output EXIF metadata
+ * // Set output EXIF metadata
  * const data = await sharp(input)
  *   .withMetadata({
  *     exif: {
  *       IFD0: {
- *         Copyright: 'Wernham Hogg'
+ *         Copyright: 'The National Gallery'
+ *       },
+ *       IFD3: {
+ *         GPSLatitudeRef: 'N',
+ *         GPSLatitude: '51/1 30/1 3230/100',
+ *         GPSLongitudeRef: 'W',
+ *         GPSLongitude: '0/1 7/1 4366/100'
  *       }
  *     }
  *   })
@@ -192,7 +202,7 @@ function toBuffer (options, callback) {
  *
  * @param {Object} [options]
  * @param {number} [options.orientation] value between 1 and 8, used to update the EXIF `Orientation` tag.
- * @param {string} [options.icc] filesystem path to output ICC profile, defaults to sRGB.
+ * @param {string} [options.icc='srgb'] Filesystem path to output ICC profile, relative to `process.cwd()`, defaults to built-in sRGB.
  * @param {Object<Object>} [options.exif={}] Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
  * @param {number} [options.density] Number of pixels per inch (DPI).
  * @returns {Sharp}
@@ -559,8 +569,8 @@ function webp (options) {
  *   .toFile('optim.gif');
  *
  * @param {Object} [options] - output options
- * @param {boolean} [options.reoptimise=false] - always generate new palettes (slow), re-use existing by default
- * @param {boolean} [options.reoptimize=false] - alternative spelling of `options.reoptimise`
+ * @param {boolean} [options.reuse=true] - re-use existing palette, otherwise generate new (slow)
+ * @param {boolean} [options.progressive=false] - use progressive (interlace) scan
  * @param {number} [options.colours=256] - maximum number of palette entries, including transparency, between 2 and 256
  * @param {number} [options.colors=256] - alternative spelling of `options.colours`
  * @param {number} [options.effort=7] - CPU effort, between 1 (fastest) and 10 (slowest)
@@ -575,10 +585,11 @@ function webp (options) {
  */
 function gif (options) {
   if (is.object(options)) {
-    if (is.defined(options.reoptimise)) {
-      this._setBooleanOption('gifReoptimise', options.reoptimise);
-    } else if (is.defined(options.reoptimize)) {
-      this._setBooleanOption('gifReoptimise', options.reoptimize);
+    if (is.defined(options.reuse)) {
+      this._setBooleanOption('gifReuse', options.reuse);
+    }
+    if (is.defined(options.progressive)) {
+      this._setBooleanOption('gifProgressive', options.progressive);
     }
     const colours = options.colours || options.colors;
     if (is.defined(colours)) {
@@ -621,6 +632,7 @@ function gif (options) {
   return this._updateFormatOut('gif', options);
 }
 
+/* istanbul ignore next */
 /**
  * Use these JP2 options for output image.
  *
@@ -654,7 +666,6 @@ function gif (options) {
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
-/* istanbul ignore next */
 function jp2 (options) {
   if (!this.constructor.format.jp2k.output.buffer) {
     throw errJp2Save();
@@ -690,7 +701,7 @@ function jp2 (options) {
     }
     if (is.defined(options.chromaSubsampling)) {
       if (is.string(options.chromaSubsampling) && is.inArray(options.chromaSubsampling, ['4:2:0', '4:4:4'])) {
-        this.options.heifChromaSubsampling = options.chromaSubsampling;
+        this.options.jp2ChromaSubsampling = options.chromaSubsampling;
       } else {
         throw is.invalidParameterError('chromaSubsampling', 'one of: 4:2:0, 4:4:4', options.chromaSubsampling);
       }
@@ -735,7 +746,8 @@ function trySetAnimationOptions (source, target) {
 /**
  * Use these TIFF options for output image.
  *
- * The `density` can be set in pixels/inch via {@link withMetadata} instead of providing `xres` and `yres` in pixels/mm.
+ * The `density` can be set in pixels/inch via {@link #withmetadata|withMetadata}
+ * instead of providing `xres` and `yres` in pixels/mm.
  *
  * @example
  * // Convert SVG input to LZW-compressed, 1 bit per pixel TIFF output
@@ -1051,6 +1063,10 @@ function raw (options) {
  *
  * The container will be set to `zip` when the output is a Buffer or Stream, otherwise it will default to `fs`.
  *
+ * Requires libvips compiled with support for libgsf.
+ * The prebuilt binaries do not include this - see
+ * {@link https://sharp.pixelplumbing.com/install#custom-libvips installing a custom libvips}.
+ *
  * @example
  *  sharp('input.tiff')
  *   .png()

package/lib/platform.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const detectLibc = require('detect-libc');

package/lib/resize.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const is = require('./is');
@@ -36,6 +39,18 @@ const position = {
   'left top': 8
 };
 
+/**
+ * How to extend the image.
+ * @member
+ * @private
+ */
+const extendWith = {
+  background: 'background',
+  copy: 'copy',
+  repeat: 'repeat',
+  mirror: 'mirror'
+};
+
 /**
  * Strategies for automagic cover behaviour.
  * @member
@@ -103,7 +118,7 @@ function isResizeExpected (options) {
  * Resize image to `width`, `height` or `width x height`.
  *
  * When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
- * - `cover`: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit.
+ * - `cover`: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
  * - `contain`: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
  * - `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
  * - `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
@@ -216,32 +231,32 @@ function isResizeExpected (options) {
  *     .toBuffer()
  *   );
  *
- * @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 {number} [width] - How many pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
+ * @param {number} [height] - How many 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.width] - alternative means of specifying `width`. If both are present this takes priority.
- * @param {String} [options.height] - alternative means of specifying `height`. If both are present this takes priority.
- * @param {String} [options.fit='cover'] - how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`.
- * @param {String} [options.position='centre'] - position, gravity or strategy to use when `fit` is `cover` or `contain`.
+ * @param {number} [options.width] - An alternative means of specifying `width`. If both are present this takes priority.
+ * @param {number} [options.height] - An alternative means of specifying `height`. If both are present this takes priority.
+ * @param {String} [options.fit='cover'] - How the image should be resized/cropped to fit the target dimension(s), one of `cover`, `contain`, `fill`, `inside` or `outside`.
+ * @param {String} [options.position='centre'] - A position, gravity or strategy to use when `fit` is `cover` or `contain`.
  * @param {String|Object} [options.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour when `fit` is `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency.
- * @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction.
- * @param {Boolean} [options.withoutEnlargement=false] - do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option.
- * @param {Boolean} [options.withoutReduction=false] - do not reduce if the width *or* height are already greater than the specified dimensions, equivalent to GraphicsMagick's `<` geometry option.
- * @param {Boolean} [options.fastShrinkOnLoad=true] - take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images.
+ * @param {String} [options.kernel='lanczos3'] - The kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load.
+ * @param {Boolean} [options.withoutEnlargement=false] - Do not scale up if the width *or* height are already less than the target dimensions, equivalent to GraphicsMagick's `>` geometry option. This may result in output dimensions smaller than the target dimensions.
+ * @param {Boolean} [options.withoutReduction=false] - Do not scale down if the width *or* height are already greater than the target dimensions, equivalent to GraphicsMagick's `<` geometry option. This may still result in a crop to reach the target dimensions.
+ * @param {Boolean} [options.fastShrinkOnLoad=true] - Take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-function resize (width, height, options) {
+function resize (widthOrOptions, height, options) {
   if (isResizeExpected(this.options)) {
     this.options.debuglog('ignoring previous resize options');
   }
-  if (is.defined(width)) {
-    if (is.object(width) && !is.defined(options)) {
-      options = width;
-    } else if (is.integer(width) && width > 0) {
-      this.options.width = width;
+  if (is.defined(widthOrOptions)) {
+    if (is.object(widthOrOptions) && !is.defined(options)) {
+      options = widthOrOptions;
+    } else if (is.integer(widthOrOptions) && widthOrOptions > 0) {
+      this.options.width = widthOrOptions;
     } else {
-      throw is.invalidParameterError('width', 'positive integer', width);
+      throw is.invalidParameterError('width', 'positive integer', widthOrOptions);
     }
   } else {
     this.options.width = -1;
@@ -322,7 +337,8 @@ function resize (width, height, options) {
 }
 
 /**
- * Extends/pads the edges of the image with the provided background colour.
+ * Extend / pad / extrude one or more edges of the image with either
+ * the provided background colour or pixels derived from the image.
  * This operation will always occur after resizing and extraction, if any.
  *
  * @example
@@ -348,11 +364,21 @@ function resize (width, height, options) {
  *   })
  *   ...
  *
+ * @example
+ * // Extrude image by 8 pixels to the right, mirroring existing right hand edge
+ * sharp(input)
+ *   .extend({
+ *     right: 8,
+ *     background: 'mirror'
+ *   })
+ *   ...
+ *
  * @param {(number|Object)} extend - single pixel count to add to all edges or an Object with per-edge counts
  * @param {number} [extend.top=0]
  * @param {number} [extend.left=0]
  * @param {number} [extend.bottom=0]
  * @param {number} [extend.right=0]
+ * @param {String} [extend.extendWith='background'] - populate new pixels using this method, one of: background, copy, repeat, mirror.
  * @param {String|Object} [extend.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
@@ -393,6 +419,13 @@ function extend (extend) {
       }
     }
     this._setBackgroundColourOption('extendBackground', extend.background);
+    if (is.defined(extend.extendWith)) {
+      if (is.string(extendWith[extend.extendWith])) {
+        this.options.extendWith = extendWith[extend.extendWith];
+      } else {
+        throw is.invalidParameterError('extendWith', 'one of: background, copy, repeat, mirror', extend.extendWith);
+      }
+    }
   } else {
     throw is.invalidParameterError('extend', 'integer or object', extend);
   }

package/lib/sharp.js

@@ -1,3 +1,6 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const platformAndArch = require('./platform')();