sharp - npm Package Compare versions

Comparing version 0.30.7 to 0.32.6

install/can-compile.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -2,0 +5,0 @@

install/dll-copy.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -2,0 +5,0 @@

install/libvips.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -11,2 +14,3 @@
 const detectLibc = require('detect-libc');
+const semverCoerce = require('semver/functions/coerce');
 const semverLessThan = require('semver/functions/lt');
@@ -78,3 +82,7 @@ const semverSatisfies = require('semver/functions/satisfies');
       if (expected !== digest) {
-        libvips.removeVendoredLibvips();
+        try {
+          libvips.removeVendoredLibvips();
+        } catch (err) {
+          libvips.log(err.message);
+        }
         libvips.log(`Integrity expected: ${expected}`);
@@ -133,5 +141,2 @@ libvips.log(`Integrity received: ${digest}`);
     }
-    if (platformAndArch === 'darwin-arm64') {
-      throw new Error("Please run 'brew install vips' to install libvips on Apple M1 (ARM64) systems");
-    }
     if (platformAndArch === 'freebsd-x64' || platformAndArch === 'openbsd-x64' || platformAndArch === 'sunos-x64') {
@@ -141,12 +146,15 @@ throw new Error(`BSD/SunOS systems require manual installation of libvips >= ${minimumLibvipsVersion}`);
     // Linux libc version check
-    const libcFamily = detectLibc.familySync();
-    const libcVersion = detectLibc.versionSync();
-    if (libcFamily === detectLibc.GLIBC && libcVersion && minimumGlibcVersionByArch[arch]) {
-      if (semverLessThan(`${libcVersion}.0`, `${minimumGlibcVersionByArch[arch]}.0`)) {
-        handleError(new Error(`Use with glibc ${libcVersion} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
+    const libcVersionRaw = detectLibc.versionSync();
+    if (libcVersionRaw) {
+      const libcFamily = detectLibc.familySync();
+      const libcVersion = semverCoerce(libcVersionRaw).version;
+      if (libcFamily === detectLibc.GLIBC && minimumGlibcVersionByArch[arch]) {
+        if (semverLessThan(libcVersion, semverCoerce(minimumGlibcVersionByArch[arch]).version)) {
+          handleError(new Error(`Use with glibc ${libcVersionRaw} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
+        }
       }
-    }
-    if (libcFamily === detectLibc.MUSL && libcVersion) {
-      if (semverLessThan(libcVersion, '1.1.24')) {
-        handleError(new Error(`Use with musl ${libcVersion} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
+      if (libcFamily === detectLibc.MUSL) {
+        if (semverLessThan(libcVersion, '1.1.24')) {
+          handleError(new Error(`Use with musl ${libcVersionRaw} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
+        }
       }
@@ -159,3 +167,2 @@ }
     }
-
     // Download to per-process temporary file
@@ -175,3 +182,3 @@ const tarFilename = ['libvips', minimumLibvipsVersionLabelled, platformAndArch].join('-') + '.tar.br';
       libvips.log(`Downloading ${url}`);
-      simpleGet({ url: url, agent: agent() }, function (err, response) {
+      simpleGet({ url: url, agent: agent(libvips.log) }, function (err, response) {
         if (err) {
@@ -178,0 +185,0 @@ fail(err);

lib/agent.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -21,3 +24,3 @@
 
-module.exports = function () {
+module.exports = function (log) {
   try {
@@ -31,2 +34,3 @@ const proxy = new url.URL(proxies.map(env).find(is.string));
       : null;
+    log(`Via proxy ${proxy.protocol}//${proxy.hostname}:${proxy.port} ${proxyAuth ? 'with' : 'no'} credentials`);
     return tunnel({
@@ -33,0 +37,0 @@ proxy: {

lib/channel.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -101,3 +104,3 @@
   }
-  return this.toColourspace('b-w');
+  return this;
 }
@@ -104,0 +107,0 @@

lib/colour.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -70,3 +73,4 @@
  * The input image will be converted to the provided colourspace at the start of the pipeline.
- * All operations will use this colourspace before converting to the output colourspace, as defined by {@link toColourspace}.
+ * All operations will use this colourspace before converting to the output colourspace,
+ * as defined by {@link #tocolourspace|toColourspace}.
  *
@@ -73,0 +77,0 @@ * This feature is experimental and has not yet been fully-tested with all operations.

lib/composite.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -46,2 +49,5 @@
  *
+ * Any resize, rotate or extract operations in the same processing pipeline
+ * will always be applied to the input image before composition.
+ *
  * The `blend` option can be one of `clear`, `source`, `over`, `in`, `out`, `atop`,
@@ -97,2 +103,13 @@ * `dest`, `dest-over`, `dest-in`, `dest-out`, `dest-atop`,
  * @param {String|Object} [images[].input.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+ * @param {Object} [images[].input.text] - describes a new text image to be created.
+ * @param {string} [images[].input.text.text] - text to render as a UTF-8 string. It can contain Pango markup, for example `<i>Le</i>Monde`.
+ * @param {string} [images[].input.text.font] - font name to render with.
+ * @param {string} [images[].input.text.fontfile] - absolute filesystem path to a font file that can be used by `font`.
+ * @param {number} [images[].input.text.width=0] - integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries.
+ * @param {number} [images[].input.text.height=0] - integral number of pixels high. When defined, `dpi` will be ignored and the text will automatically fit the pixel resolution defined by `width` and `height`. Will be ignored if `width` is not specified or set to 0.
+ * @param {string} [images[].input.text.align='left'] - text alignment (`'left'`, `'centre'`, `'center'`, `'right'`).
+ * @param {boolean} [images[].input.text.justify=false] - set this to true to apply justification to the text.
+ * @param {number} [images[].input.text.dpi=72] - the resolution (size) at which to render the text. Does not take effect if `height` is specified.
+ * @param {boolean} [images[].input.text.rgba=false] - set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for Pango markup features like `<span foreground="red">Red!</span>`.
+ * @param {number} [images[].input.text.spacing=0] - text line height in points. Will use the font line height if none is specified.
  * @param {String} [images[].blend='over'] - how to blend this image with the image below.
@@ -103,3 +120,3 @@ * @param {String} [images[].gravity='centre'] - gravity at which to place the overlay.
  * @param {Boolean} [images[].tile=false] - set to true to repeat the overlay image across the entire image with the given `gravity`.
- * @param {Boolean} [images[].premultiplied=false] - set to true to avoid premultipling the image below. Equivalent to the `--premultiplied` vips option.
+ * @param {Boolean} [images[].premultiplied=false] - set to true to avoid premultiplying the image below. Equivalent to the `--premultiplied` vips option.
  * @param {Number} [images[].density=72] - number representing the DPI for vector overlay image.
@@ -106,0 +123,0 @@ * @param {Object} [images[].raw] - describes overlay when using raw pixel data.

lib/constructor.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -49,3 +52,3 @@
  * @example
- * // Create a blank 300x200 PNG image of semi-transluent red pixels
+ * // Create a blank 300x200 PNG image of semi-translucent red pixels
  * sharp({
@@ -96,4 +99,25 @@ *   create: {
  *
- * @param {(Buffer|Uint8Array|Uint8ClampedArray|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array|Float32Array|Float64Array|string)} [input] - if present, can be
- *  a Buffer / Uint8Array / Uint8ClampedArray containing JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image data, or
+ * @example
+ * // Generate an image from text
+ * await sharp({
+ *   text: {
+ *     text: 'Hello, world!',
+ *     width: 400, // max width
+ *     height: 300 // max height
+ *   }
+ * }).toFile('text_bw.png');
+ *
+ * @example
+ * // Generate an rgba image from text using pango markup and font
+ * await sharp({
+ *   text: {
+ *     text: '<span foreground="red">Red!</span><span background="cyan">blue</span>',
+ *     font: 'sans',
+ *     rgba: true,
+ *     dpi: 300
+ *   }
+ * }).toFile('text_rgba.png');
+ *
+ * @param {(Buffer|ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array|Float32Array|Float64Array|string)} [input] - if present, can be
+ *  a Buffer / ArrayBuffer / Uint8Array / Uint8ClampedArray containing JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image data, or
  *  a TypedArray containing raw pixel image data, or
@@ -103,15 +127,15 @@ *  a String containing the filesystem path to an JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image file.
  * @param {Object} [options] - if present, is an Object with optional attributes.
- * @param {string} [options.failOn='warning'] - level of sensitivity to invalid images, one of (in order of sensitivity): 'none' (least), 'truncated', 'error' or 'warning' (most), highers level imply lower levels.
+ * @param {string} [options.failOn='warning'] - when to abort processing of invalid pixel data, one of (in order of sensitivity): 'none' (least), 'truncated', 'error' or 'warning' (most), higher levels imply lower levels, invalid metadata will always abort.
  * @param {number|boolean} [options.limitInputPixels=268402689] - Do not process input images where the number of pixels
  *  (width x height) exceeds this limit. Assumes image dimensions contained in the input metadata can be trusted.
  *  An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF).
- * @param {boolean} [options.unlimited=false] - Set this to `true` to remove safety features that help prevent memory exhaustion (SVG, PNG).
- * @param {boolean} [options.sequentialRead=false] - Set this to `true` to use sequential rather than random access where possible.
- *  This can reduce memory usage and might improve performance on some systems.
+ * @param {boolean} [options.unlimited=false] - Set this to `true` to remove safety features that help prevent memory exhaustion (JPEG, PNG, SVG, HEIF).
+ * @param {boolean} [options.sequentialRead=true] - Set this to `false` to use random access rather than sequential read. Some operations will do this automatically.
  * @param {number} [options.density=72] - number representing the DPI for vector images in the range 1 to 100000.
- * @param {number} [options.pages=1] - number of pages to extract for multi-page input (GIF, WebP, AVIF, TIFF, PDF), use -1 for all pages.
- * @param {number} [options.page=0] - page number to start extracting from for multi-page input (GIF, WebP, AVIF, TIFF, PDF), zero based.
+ * @param {number} [options.ignoreIcc=false] - should the embedded ICC profile, if any, be ignored.
+ * @param {number} [options.pages=1] - Number of pages to extract for multi-page input (GIF, WebP, TIFF), use -1 for all pages.
+ * @param {number} [options.page=0] - Page number to start extracting from for multi-page input (GIF, WebP, TIFF), zero based.
  * @param {number} [options.subifd=-1] - subIFD (Sub Image File Directory) to extract for OME-TIFF, defaults to main image.
  * @param {number} [options.level=0] - level to extract from a multi-level input (OpenSlide), zero based.
- * @param {boolean} [options.animated=false] - Set to `true` to read all frames/pages of an animated image (equivalent of setting `pages` to `-1`).
+ * @param {boolean} [options.animated=false] - Set to `true` to read all frames/pages of an animated image (GIF, WebP, TIFF), equivalent of setting `pages` to `-1`.
  * @param {Object} [options.raw] - describes raw pixel input image data. See `raw()` for pixel ordering.
@@ -132,2 +156,14 @@ * @param {number} [options.raw.width] - integral number of pixels wide.
  * @param {number} [options.create.noise.sigma] - standard deviation of pixels in generated noise.
+ * @param {Object} [options.text] - describes a new text image to be created.
+ * @param {string} [options.text.text] - text to render as a UTF-8 string. It can contain Pango markup, for example `<i>Le</i>Monde`.
+ * @param {string} [options.text.font] - font name to render with.
+ * @param {string} [options.text.fontfile] - absolute filesystem path to a font file that can be used by `font`.
+ * @param {number} [options.text.width=0] - Integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries.
+ * @param {number} [options.text.height=0] - Maximum integral number of pixels high. When defined, `dpi` will be ignored and the text will automatically fit the pixel resolution defined by `width` and `height`. Will be ignored if `width` is not specified or set to 0.
+ * @param {string} [options.text.align='left'] - Alignment style for multi-line text (`'left'`, `'centre'`, `'center'`, `'right'`).
+ * @param {boolean} [options.text.justify=false] - set this to true to apply justification to the text.
+ * @param {number} [options.text.dpi=72] - the resolution (size) at which to render the text. Does not take effect if `height` is specified.
+ * @param {boolean} [options.text.rgba=false] - set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`.
+ * @param {number} [options.text.spacing=0] - text line height in points. Will use the font line height if none is specified.
+ * @param {string} [options.text.wrap='word'] - word wrapping style when width is provided, one of: 'word', 'char', 'charWord' (prefer char, fallback to word) or 'none'.
  * @returns {Sharp}
@@ -171,2 +207,3 @@ * @throws {Error} Invalid parameters
     extendBackground: [0, 0, 0, 255],
+    extendWith: 'background',
     withoutEnlargement: false,
@@ -188,2 +225,3 @@ withoutReduction: false,
     flattenBackground: [0, 0, 0],
+    unflatten: false,
     negate: false,
@@ -201,2 +239,3 @@ negateAlpha: true,
     thresholdGrayscale: true,
+    trimBackground: [],
     trimThreshold: 0,
@@ -207,2 +246,4 @@ gamma: 0,
     normalise: false,
+    normaliseLower: 1,
+    normaliseUpper: 99,
     claheWidth: 0,
@@ -261,6 +302,13 @@ claheHeight: 0,
     webpSmartSubsample: false,
+    webpPreset: 'default',
     webpEffort: 4,
+    webpMinSize: false,
+    webpMixed: false,
     gifBitdepth: 8,
     gifEffort: 7,
     gifDither: 1,
+    gifInterFrameMaxError: 0,
+    gifInterPaletteMaxError: 3,
+    gifReuse: true,
+    gifProgressive: false,
     tiffQuality: 80,
@@ -282,2 +330,6 @@ tiffCompression: 'jpeg',
     heifChromaSubsampling: '4:4:4',
+    jxlDistance: 1,
+    jxlDecodingTier: 0,
+    jxlEffort: 7,
+    jxlLossless: false,
     rawDepth: 'uchar',
@@ -295,5 +347,6 @@ tileSize: 256,
     tileId: 'https://example.com/iiif',
+    tileBasename: '',
     timeoutSeconds: 0,
-    linearA: 1,
-    linearB: 0,
+    linearA: [],
+    linearB: [],
     // Function to notify of libvips warnings
@@ -360,3 +413,3 @@ debuglog: warning => {
  *
- * // https://github.com/sindresorhus/got#gotstreamurl-options
+ * // https://github.com/sindresorhus/got/blob/main/documentation/3-streams.md
  * got.stream("https://www.example.com/some-file.jpg").pipe(sharpStream);
@@ -363,0 +416,0 @@ *

lib/index.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -2,0 +5,0 @@

lib/input.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -8,2 +11,14 @@
 /**
+ * Justication alignment
+ * @member
+ * @private
+ */
+const align = {
+  left: 'low',
+  center: 'centre',
+  centre: 'centre',
+  right: 'high'
+};
+
+/**
  * Extract input options, if any, from an object.
@@ -13,5 +28,5 @@ * @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;
@@ -28,4 +43,5 @@ }
     limitInputPixels: Math.pow(0x3FFF, 2),
+    ignoreIcc: false,
     unlimited: false,
-    sequentialRead: false
+    sequentialRead: true
   };
@@ -41,2 +57,7 @@ if (is.string(input)) {
     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)) {
@@ -87,2 +108,10 @@ if (input.length === 0) {
     }
+    // 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
@@ -253,2 +282,84 @@ if (is.defined(inputOptions.limitInputPixels)) {
     }
+    // Create a new image with text
+    if (is.defined(inputOptions.text)) {
+      if (is.object(inputOptions.text) && is.string(inputOptions.text.text)) {
+        inputDescriptor.textValue = inputOptions.text.text;
+        if (is.defined(inputOptions.text.height) && is.defined(inputOptions.text.dpi)) {
+          throw new Error('Expected only one of dpi or height');
+        }
+        if (is.defined(inputOptions.text.font)) {
+          if (is.string(inputOptions.text.font)) {
+            inputDescriptor.textFont = inputOptions.text.font;
+          } else {
+            throw is.invalidParameterError('text.font', 'string', inputOptions.text.font);
+          }
+        }
+        if (is.defined(inputOptions.text.fontfile)) {
+          if (is.string(inputOptions.text.fontfile)) {
+            inputDescriptor.textFontfile = inputOptions.text.fontfile;
+          } else {
+            throw is.invalidParameterError('text.fontfile', 'string', inputOptions.text.fontfile);
+          }
+        }
+        if (is.defined(inputOptions.text.width)) {
+          if (is.number(inputOptions.text.width)) {
+            inputDescriptor.textWidth = inputOptions.text.width;
+          } else {
+            throw is.invalidParameterError('text.textWidth', 'number', inputOptions.text.width);
+          }
+        }
+        if (is.defined(inputOptions.text.height)) {
+          if (is.number(inputOptions.text.height)) {
+            inputDescriptor.textHeight = inputOptions.text.height;
+          } else {
+            throw is.invalidParameterError('text.height', 'number', inputOptions.text.height);
+          }
+        }
+        if (is.defined(inputOptions.text.align)) {
+          if (is.string(inputOptions.text.align) && is.string(this.constructor.align[inputOptions.text.align])) {
+            inputDescriptor.textAlign = this.constructor.align[inputOptions.text.align];
+          } else {
+            throw is.invalidParameterError('text.align', 'valid alignment', inputOptions.text.align);
+          }
+        }
+        if (is.defined(inputOptions.text.justify)) {
+          if (is.bool(inputOptions.text.justify)) {
+            inputDescriptor.textJustify = inputOptions.text.justify;
+          } else {
+            throw is.invalidParameterError('text.justify', 'boolean', inputOptions.text.justify);
+          }
+        }
+        if (is.defined(inputOptions.text.dpi)) {
+          if (is.number(inputOptions.text.dpi) && is.inRange(inputOptions.text.dpi, 1, 100000)) {
+            inputDescriptor.textDpi = inputOptions.text.dpi;
+          } else {
+            throw is.invalidParameterError('text.dpi', 'number between 1 and 100000', inputOptions.text.dpi);
+          }
+        }
+        if (is.defined(inputOptions.text.rgba)) {
+          if (is.bool(inputOptions.text.rgba)) {
+            inputDescriptor.textRgba = inputOptions.text.rgba;
+          } else {
+            throw is.invalidParameterError('text.rgba', 'bool', inputOptions.text.rgba);
+          }
+        }
+        if (is.defined(inputOptions.text.spacing)) {
+          if (is.number(inputOptions.text.spacing)) {
+            inputDescriptor.textSpacing = inputOptions.text.spacing;
+          } else {
+            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.');
+      }
+    }
   } else if (is.defined(inputOptions)) {
@@ -309,5 +420,9 @@ throw new Error('Invalid input options ' + inputOptions);
  *
- * 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}.
+ *
  * A `Promise` is returned when `callback` is not provided.
@@ -327,2 +442,3 @@ *
  * - `pageHeight`: Number of pixels high each page in a multi-page image will be.
+ * - `paletteBitDepth`: Bit depth of palette-based image (GIF, PNG).
  * - `loop`: Number of times to loop an animated image, zero refers to a continuous loop.
@@ -344,2 +460,3 @@ * - `delay`: Delay in ms between each page in an animated image, provided as an array of integers.
  * - `tifftagPhotoshop`: Buffer containing raw TIFFTAG_PHOTOSHOP data, if present
+ * - `formatMagick`: String containing format for images loaded via *magick
  *
@@ -391,3 +508,3 @@ * @example
       return new Promise((resolve, reject) => {
-        this.on('finish', () => {
+        const finished = () => {
           this._flattenBufferIn();
@@ -401,3 +518,8 @@ sharp.metadata(this.options, (err, metadata) => {
           });
-        });
+        };
+        if (this.writableFinished) {
+          finished();
+        } else {
+          this.once('finish', finished);
+        }
       });
@@ -518,2 +640,4 @@ } else {
   });
+  // Class attributes
+  Sharp.align = align;
 };

lib/is.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -75,2 +78,10 @@
 /**
+ * Is this value an ArrayBuffer object?
+ * @private
+ */
+const arrayBuffer = function (val) {
+  return val instanceof ArrayBuffer;
+};
+
+/**
  * Is this value a non-empty string?
@@ -138,2 +149,3 @@ * @private
   typedArray: typedArray,
+  arrayBuffer: arrayBuffer,
   string: string,
@@ -140,0 +152,0 @@ number: number,

lib/libvips.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -88,6 +91,6 @@
 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 */
 const pkgConfigPath = function () {
@@ -118,2 +121,3 @@ if (process.platform !== 'win32') {
   if (isRosetta()) {
+    log('Detected Rosetta, skipping search for globally-installed libvips');
     return false;
@@ -120,0 +124,0 @@ }

lib/operation.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -11,3 +14,3 @@
  * If an angle is provided, it is converted to a valid positive degree rotation.
- * For example, `-450` will produce a 270deg rotation.
+ * For example, `-450` will produce a 270 degree rotation.
  *
@@ -20,7 +23,10 @@ * When rotating by an angle other than a multiple of 90,
  *
- * The use of `rotate` implies the removal of the EXIF `Orientation` tag, if any.
+ * The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
  *
- * Method order is important when both rotating and extracting regions,
- * for example `rotate(x).extract(y)` will produce a different result to `extract(y).rotate(x)`.
+ * Only one rotation can occur per pipeline.
+ * Previous calls to `rotate` in the same pipeline will be ignored.
  *
+ * Method order is important when rotating, resizing and/or extracting regions,
+ * for example `.rotate(x).extract(y)` will produce a different result to `.extract(y).rotate(x)`.
+ *
  * @example
@@ -37,2 +43,12 @@ * const pipeline = sharp()
  *
+ * @example
+ * const rotateThenResize = await sharp(input)
+ *   .rotate(90)
+ *   .resize({ width: 16, height: 8, fit: 'fill' })
+ *   .toBuffer();
+ * const resizeThenRotate = await sharp(input)
+ *   .resize({ width: 16, height: 8, fit: 'fill' })
+ *   .rotate(90)
+ *   .toBuffer();
+ *
  * @param {number} [angle=auto] angle of rotation.
@@ -45,2 +61,5 @@ * @param {Object} [options] - if present, is an Object with optional attributes.
 function rotate (angle, options) {
+  if (this.options.useExifOrientation || this.options.angle || this.options.rotationAngle) {
+    this.options.debuglog('ignoring previous rotate options');
+  }
   if (!is.defined(angle)) {
@@ -68,5 +87,7 @@ this.options.useExifOrientation = true;
 /**
- * Flip the image about the vertical Y axis. This always occurs after rotation, if any.
- * The use of `flip` implies the removal of the EXIF `Orientation` tag, if any.
+ * Mirror the image vertically (up-down) about the x-axis.
+ * This always occurs before rotation, if any.
  *
+ * This operation does not work correctly with multi-page images.
+ *
  * @example
@@ -84,4 +105,4 @@ * const output = await sharp(input).flip().toBuffer();
 /**
- * Flop the image about the horizontal X axis. This always occurs after rotation, if any.
- * The use of `flop` implies the removal of the EXIF `Orientation` tag, if any.
+ * Mirror the image horizontally (left-right) about the y-axis.
+ * This always occurs before rotation, if any.
  *
@@ -104,3 +125,3 @@ * @example
  * 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`.
  *
@@ -122,3 +143,3 @@ * In the case of a 2x2 matrix, the transform is:
  *      background: 'white',
- *      interpolate: sharp.interpolators.nohalo
+ *      interpolator: sharp.interpolators.nohalo
  *   })
@@ -200,5 +221,7 @@ *   .toBuffer((err, outputBuffer, info) => {
  * Sharpen the image.
+ *
  * When used without parameters, performs a fast, mild sharpen of the output image.
+ *
  * When a `sigma` is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
- * Separate control over the level of sharpening in "flat" and "jagged" areas is available.
+ * Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.
  *
@@ -217,3 +240,3 @@ * See {@link https://www.libvips.org/API/current/libvips-convolution.html#vips-sharpen|libvips sharpen} operation.
  *     sigma: 2,
- *     m1: 0
+ *     m1: 0,
  *     m2: 3,
@@ -226,9 +249,9 @@ *     x1: 3,
  *
- * @param {Object|number} [options] - if present, is an Object with attributes or (deprecated) a number for `options.sigma`.
- * @param {number} [options.sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
- * @param {number} [options.m1=1.0] - the level of sharpening to apply to "flat" areas.
- * @param {number} [options.m2=2.0] - the level of sharpening to apply to "jagged" areas.
- * @param {number} [options.x1=2.0] - threshold between "flat" and "jagged"
- * @param {number} [options.y2=10.0] - maximum amount of brightening.
- * @param {number} [options.y3=20.0] - maximum amount of darkening.
+ * @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 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
+ * @param {number} [options.y2=10.0] - maximum amount of brightening, between 0 and 1000000
+ * @param {number} [options.y3=20.0] - maximum amount of darkening, between 0 and 1000000
  * @param {number} [flat] - (deprecated) see `options.m1`.
@@ -266,40 +289,40 @@ * @param {number} [jagged] - (deprecated) see `options.m2`.
   } else if (is.plainObject(options)) {
-    if (is.number(options.sigma) && is.inRange(options.sigma, 0.01, 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.01 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, 10000)) {
+      if (is.number(options.m1) && is.inRange(options.m1, 0, 1000000)) {
         this.options.sharpenM1 = options.m1;
       } else {
-        throw is.invalidParameterError('options.m1', 'number between 0 and 10000', options.m1);
+        throw is.invalidParameterError('options.m1', 'number between 0 and 1000000', options.m1);
       }
     }
     if (is.defined(options.m2)) {
-      if (is.number(options.m2) && is.inRange(options.m2, 0, 10000)) {
+      if (is.number(options.m2) && is.inRange(options.m2, 0, 1000000)) {
         this.options.sharpenM2 = options.m2;
       } else {
-        throw is.invalidParameterError('options.m2', 'number between 0 and 10000', options.m2);
+        throw is.invalidParameterError('options.m2', 'number between 0 and 1000000', options.m2);
       }
     }
     if (is.defined(options.x1)) {
-      if (is.number(options.x1) && is.inRange(options.x1, 0, 10000)) {
+      if (is.number(options.x1) && is.inRange(options.x1, 0, 1000000)) {
         this.options.sharpenX1 = options.x1;
       } else {
-        throw is.invalidParameterError('options.x1', 'number between 0 and 10000', options.x1);
+        throw is.invalidParameterError('options.x1', 'number between 0 and 1000000', options.x1);
       }
     }
     if (is.defined(options.y2)) {
-      if (is.number(options.y2) && is.inRange(options.y2, 0, 10000)) {
+      if (is.number(options.y2) && is.inRange(options.y2, 0, 1000000)) {
         this.options.sharpenY2 = options.y2;
       } else {
-        throw is.invalidParameterError('options.y2', 'number between 0 and 10000', options.y2);
+        throw is.invalidParameterError('options.y2', 'number between 0 and 1000000', options.y2);
       }
     }
     if (is.defined(options.y3)) {
-      if (is.number(options.y3) && is.inRange(options.y3, 0, 10000)) {
+      if (is.number(options.y3) && is.inRange(options.y3, 0, 1000000)) {
         this.options.sharpenY3 = options.y3;
       } else {
-        throw is.invalidParameterError('options.y3', 'number between 0 and 10000', options.y3);
+        throw is.invalidParameterError('options.y3', 'number between 0 and 1000000', options.y3);
       }
@@ -400,2 +423,28 @@ }
 /**
+ * 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`
@@ -464,12 +513,46 @@ * then increasing the encoding (brighten) post-resize at a factor of `gamma`.
 /**
- * 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();
  *
- * @param {Boolean} [normalise=true]
+ * @example
+ * const output = await sharp(input)
+ *   .normalise({ lower: 0, upper: 100 })
+ *   .toBuffer();
+ *
+ * @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;
@@ -482,9 +565,13 @@ }
  * @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,7 +596,5 @@
  * @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}
@@ -519,22 +604,23 @@ * @throws {Error} Invalid parameters
 function clahe (options) {
-  if (!is.plainObject(options)) {
+  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 {
     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);
-  } else {
-    this.options.claheMaxSlope = options.maxSlope;
-  }
   return this;
@@ -648,5 +734,22 @@ }
 /**
- * Apply the linear formula a * input + b to the image (levels adjustment)
- * @param {number} [a=1.0] multiplier
- * @param {number} [b=0.0] offset
+ * Apply the linear formula `a` * input + `b` to the image to adjust image levels.
+ *
+ * When a single number is provided, it will be used for all image channels.
+ * When an array of numbers is provided, the array length must match the number of channels.
+ *
+ * @example
+ * await sharp(input)
+ *   .linear(0.5, 2)
+ *   .toBuffer();
+ *
+ * @example
+ * await sharp(rgbInput)
+ *   .linear(
+ *     [0.25, 0.5, 0.75],
+ *     [150, 100, 50]
+ *   )
+ *   .toBuffer();
+ *
+ * @param {(number|number[])} [a=[]] multiplier
+ * @param {(number|number[])} [b=[]] offset
  * @returns {Sharp}
@@ -656,16 +759,28 @@ * @throws {Error} Invalid parameters
 function linear (a, b) {
+  if (!is.defined(a) && is.number(b)) {
+    a = 1.0;
+  } else if (is.number(a) && !is.defined(b)) {
+    b = 0.0;
+  }
   if (!is.defined(a)) {
-    this.options.linearA = 1.0;
+    this.options.linearA = [];
   } else if (is.number(a)) {
+    this.options.linearA = [a];
+  } else if (Array.isArray(a) && a.length && a.every(is.number)) {
     this.options.linearA = a;
   } else {
-    throw is.invalidParameterError('a', 'numeric', a);
+    throw is.invalidParameterError('a', 'number or array of numbers', a);
   }
   if (!is.defined(b)) {
-    this.options.linearB = 0.0;
+    this.options.linearB = [];
   } else if (is.number(b)) {
+    this.options.linearB = [b];
+  } else if (Array.isArray(b) && b.length && b.every(is.number)) {
     this.options.linearB = b;
   } else {
-    throw is.invalidParameterError('b', 'numeric', b);
+    throw is.invalidParameterError('b', 'number or array of numbers', b);
   }
+  if (this.options.linearA.length !== this.options.linearB.length) {
+    throw new Error('Expected a and b to be arrays of the same length');
+  }
   return this;
@@ -675,3 +790,3 @@ }
 /**
- * Recomb the image with the specified matrix.
+ * Recombine the image with the specified matrix.
  *
@@ -689,3 +804,3 @@ * @since 0.21.1
  *   .toBuffer(function(err, data, info) {
- *     // data contains the raw pixel data after applying the recomb
+ *     // data contains the raw pixel data after applying the matrix
  *     // With this example input, a sepia filter has been applied
@@ -747,3 +862,3 @@ *   });
  * @example
- * // decreate brightness and saturation while also hue-rotating by 90 degrees
+ * // decrease brightness and saturation while also hue-rotating by 90 degrees
  * const output = await sharp(input)
@@ -813,2 +928,3 @@ *   .modulate({
     flatten,
+    unflatten,
     gamma,
@@ -815,0 +931,0 @@ negate,

lib/output.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -13,2 +16,5 @@
   ['jpg', 'jpeg'],
+  ['jpe', 'jpeg'],
+  ['tile', 'tile'],
+  ['dz', 'tile'],
   ['png', 'png'],
@@ -23,7 +29,10 @@ ['raw', 'raw'],
   ['j2k', 'jp2'],
-  ['j2c', 'jp2']
+  ['j2c', 'jp2'],
+  ['jxl', 'jxl']
 ]);
 
-const errJp2Save = new Error('JP2 output requires libvips with support for OpenJPEG');
+const jp2Regex = /\.(jp[2x]|j2[kc])$/i;
 
+const errJp2Save = () => new Error('JP2 output requires libvips with support for OpenJPEG');
+
 const bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math.log2(colours)));
@@ -39,3 +48,3 @@
  * 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.
  *
@@ -61,2 +70,4 @@ * The caller is responsible for ensuring directory structures and permissions exist.
  * 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
@@ -71,2 +82,4 @@ * @throws {Error} Invalid parameters
     err = new Error('Cannot use same file for input and output');
+  } else if (jp2Regex.test(path.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
+    err = errJp2Save();
   }
@@ -90,3 +103,3 @@ if (err) {
  *
- * 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.
  *
@@ -96,3 +109,3 @@ * 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.
  *
@@ -105,2 +118,3 @@ * `callback`, if present, gets three arguments `(err, data, info)` where:
  * When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`.
+ * May also contain `textAutofitDpi` (dpi the font was rendered at) if image was created from text.
  *
@@ -159,4 +173,4 @@ * A `Promise` is returned when `callback` is not provided.
  * Include all metadata (EXIF, XMP, IPTC) from the input image in the output image.
- * This will also convert to and add a web-friendly sRGB ICC profile unless a custom
- * output profile is provided.
+ * This will also convert to and add a web-friendly sRGB ICC profile if appropriate,
+ * unless a custom output profile is provided.
  *
@@ -175,3 +189,3 @@ * The default behaviour, when `withMetadata` is not used, is to convert to the device-independent
  * @example
- * // Set "IFD0-Copyright" in output EXIF metadata
+ * // Set output EXIF metadata
  * const data = await sharp(input)
@@ -181,3 +195,9 @@ *   .withMetadata({
  *       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'
  *       }
@@ -196,3 +216,3 @@ *     }
  * @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.
@@ -417,2 +437,10 @@ * @param {number} [options.density] Number of pixels per inch (DPI).
     }
+    const colours = options.colours || options.colors;
+    if (is.defined(colours)) {
+      if (is.integer(colours) && is.inRange(colours, 2, 256)) {
+        this.options.pngBitdepth = bitdepthFromColourCount(colours);
+      } else {
+        throw is.invalidParameterError('colours', 'integer between 2 and 256', colours);
+      }
+    }
     if (is.defined(options.palette)) {
@@ -438,10 +466,2 @@ this._setBooleanOption('pngPalette', options.palette);
       }
-      const colours = options.colours || options.colors;
-      if (is.defined(colours)) {
-        if (is.integer(colours) && is.inRange(colours, 2, 256)) {
-          this.options.pngBitdepth = bitdepthFromColourCount(colours);
-        } else {
-          throw is.invalidParameterError('colours', 'integer between 2 and 256', colours);
-        }
-      }
       if (is.defined(options.dither)) {
@@ -480,5 +500,8 @@ if (is.number(options.dither) && is.inRange(options.dither, 0, 1)) {
  * @param {boolean} [options.smartSubsample=false] - use high quality chroma subsampling
+ * @param {string} [options.preset='default'] - named preset for preprocessing/filtering, one of: default, photo, picture, drawing, icon, text
  * @param {number} [options.effort=4] - CPU effort, between 0 (fastest) and 6 (slowest)
  * @param {number} [options.loop=0] - number of animation iterations, use 0 for infinite animation
  * @param {number|number[]} [options.delay] - delay(s) between animation frames (in milliseconds)
+ * @param {boolean} [options.minSize=false] - prevent use of animation key frames to minimise file size (slow)
+ * @param {boolean} [options.mixed=false] - allow mixture of lossy and lossless animation frames (slow)
  * @param {boolean} [options.force=true] - force WebP output, otherwise attempt to use input format
@@ -513,10 +536,22 @@ * @returns {Sharp}
     }
-    const effort = is.defined(options.effort) ? options.effort : options.reductionEffort;
-    if (is.defined(effort)) {
-      if (is.integer(effort) && is.inRange(effort, 0, 6)) {
-        this.options.webpEffort = effort;
+    if (is.defined(options.preset)) {
+      if (is.string(options.preset) && is.inArray(options.preset, ['default', 'photo', 'picture', 'drawing', 'icon', 'text'])) {
+        this.options.webpPreset = options.preset;
       } else {
-        throw is.invalidParameterError('effort', 'integer between 0 and 6', effort);
+        throw is.invalidParameterError('preset', 'one of: default, photo, picture, drawing, icon, text', options.preset);
       }
     }
+    if (is.defined(options.effort)) {
+      if (is.integer(options.effort) && is.inRange(options.effort, 0, 6)) {
+        this.options.webpEffort = options.effort;
+      } else {
+        throw is.invalidParameterError('effort', 'integer between 0 and 6', options.effort);
+      }
+    }
+    if (is.defined(options.minSize)) {
+      this._setBooleanOption('webpMinSize', options.minSize);
+    }
+    if (is.defined(options.mixed)) {
+      this._setBooleanOption('webpMixed', options.mixed);
+    }
   }
@@ -532,2 +567,4 @@ trySetAnimationOptions(options, this.options);
  *
+ * The palette of the input image will be re-used if possible.
+ *
  * @since 0.30.0
@@ -553,3 +590,11 @@ *
  *
+ * @example
+ * // Lossy file size reduction of animated GIF
+ * await sharp('in.gif', { animated: true })
+ *   .gif({ interFrameMaxError: 8 })
+ *   .toFile('optim.gif');
+ *
  * @param {Object} [options] - output options
+ * @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
@@ -559,2 +604,4 @@ * @param {number} [options.colors=256] - alternative spelling of `options.colours`
  * @param {number} [options.dither=1.0] - level of Floyd-Steinberg error diffusion, between 0 (least) and 1 (most)
+ * @param {number} [options.interFrameMaxError=0] - maximum inter-frame error for transparency, between 0 (lossless) and 32
+ * @param {number} [options.interPaletteMaxError=3] - maximum inter-palette error for palette reuse, between 0 and 256
  * @param {number} [options.loop=0] - number of animation iterations, use 0 for infinite animation
@@ -568,2 +615,8 @@ * @param {number|number[]} [options.delay] - delay(s) between animation frames (in milliseconds)
   if (is.object(options)) {
+    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;
@@ -591,2 +644,16 @@ if (is.defined(colours)) {
     }
+    if (is.defined(options.interFrameMaxError)) {
+      if (is.number(options.interFrameMaxError) && is.inRange(options.interFrameMaxError, 0, 32)) {
+        this.options.gifInterFrameMaxError = options.interFrameMaxError;
+      } else {
+        throw is.invalidParameterError('interFrameMaxError', 'number between 0.0 and 32.0', options.interFrameMaxError);
+      }
+    }
+    if (is.defined(options.interPaletteMaxError)) {
+      if (is.number(options.interPaletteMaxError) && is.inRange(options.interPaletteMaxError, 0, 256)) {
+        this.options.gifInterPaletteMaxError = options.interPaletteMaxError;
+      } else {
+        throw is.invalidParameterError('interPaletteMaxError', 'number between 0.0 and 256.0', options.interPaletteMaxError);
+      }
+    }
   }
@@ -597,2 +664,3 @@ trySetAnimationOptions(options, this.options);
 
+/* istanbul ignore next */
 /**
@@ -631,6 +699,5 @@ * Use these JP2 options for output image.
  */
-/* istanbul ignore next */
 function jp2 (options) {
   if (!this.constructor.format.jp2k.output.buffer) {
-    throw errJp2Save;
+    throw errJp2Save();
   }
@@ -668,3 +735,3 @@ if (is.object(options)) {
       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 {
@@ -714,3 +781,4 @@ throw is.invalidParameterError('chromaSubsampling', 'one of: 4:2:0, 4:4:4', options.chromaSubsampling);
  *
- * 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.
  *
@@ -730,3 +798,3 @@ * @example
  * @param {boolean} [options.force=true] - force TIFF output, otherwise attempt to use input format
- * @param {string} [options.compression='jpeg'] - compression options: lzw, deflate, jpeg, ccittfax4
+ * @param {string} [options.compression='jpeg'] - compression options: none, jpeg, deflate, packbits, ccittfax4, lzw, webp, zstd, jp2k
  * @param {string} [options.predictor='horizontal'] - compression predictor options: none, horizontal, float
@@ -799,6 +867,6 @@ * @param {boolean} [options.pyramid=false] - write an image pyramid
     if (is.defined(options.compression)) {
-      if (is.string(options.compression) && is.inArray(options.compression, ['lzw', 'deflate', 'jpeg', 'ccittfax4', 'none'])) {
+      if (is.string(options.compression) && is.inArray(options.compression, ['none', 'jpeg', 'deflate', 'packbits', 'ccittfax4', 'lzw', 'webp', 'zstd', 'jp2k'])) {
         this.options.tiffCompression = options.compression;
       } else {
-        throw is.invalidParameterError('compression', 'one of: lzw, deflate, jpeg, ccittfax4, none', options.compression);
+        throw is.invalidParameterError('compression', 'one of: none, jpeg, deflate, packbits, ccittfax4, lzw, webp, zstd, jp2k', options.compression);
       }
@@ -834,2 +902,12 @@ }
  *
+ * @example
+ * const data = await sharp(input)
+ *   .avif({ effort: 2 })
+ *   .toBuffer();
+ *
+ * @example
+ * const data = await sharp(input)
+ *   .avif({ lossless: true })
+ *   .toBuffer();
+ *
  * @since 0.27.0
@@ -852,5 +930,10 @@ *
  *
- * Support for patent-encumbered HEIC images requires the use of a
+ * Support for patent-encumbered HEIC images using `hevc` compression requires the use of a
  * globally-installed libvips compiled with support for libheif, libde265 and x265.
  *
+ * @example
+ * const data = await sharp(input)
+ *   .heif({ compression: 'hevc' })
+ *   .toBuffer();
+ *
  * @since 0.23.0
@@ -896,8 +979,2 @@ *
       }
-    } else if (is.defined(options.speed)) {
-      if (is.integer(options.speed) && is.inRange(options.speed, 0, 9)) {
-        this.options.heifEffort = 9 - options.speed;
-      } else {
-        throw is.invalidParameterError('speed', 'integer between 0 and 9', options.speed);
-      }
     }
@@ -916,2 +993,67 @@ if (is.defined(options.chromaSubsampling)) {
 /**
+ * Use these JPEG-XL (JXL) options for output image.
+ *
+ * This feature is experimental, please do not use in production systems.
+ *
+ * Requires libvips compiled with support for libjxl.
+ * The prebuilt binaries do not include this - see
+ * {@link https://sharp.pixelplumbing.com/install#custom-libvips installing a custom libvips}.
+ *
+ * Image metadata (EXIF, XMP) is unsupported.
+ *
+ * @since 0.31.3
+ *
+ * @param {Object} [options] - output options
+ * @param {number} [options.distance=1.0] - maximum encoding error, between 0 (highest quality) and 15 (lowest quality)
+ * @param {number} [options.quality] - calculate `distance` based on JPEG-like quality, between 1 and 100, overrides distance if specified
+ * @param {number} [options.decodingTier=0] - target decode speed tier, between 0 (highest quality) and 4 (lowest quality)
+ * @param {boolean} [options.lossless=false] - use lossless compression
+ * @param {number} [options.effort=7] - CPU effort, between 3 (fastest) and 9 (slowest)
+ * @returns {Sharp}
+ * @throws {Error} Invalid options
+ */
+function jxl (options) {
+  if (is.object(options)) {
+    if (is.defined(options.quality)) {
+      if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
+        // https://github.com/libjxl/libjxl/blob/0aeea7f180bafd6893c1db8072dcb67d2aa5b03d/tools/cjxl_main.cc#L640-L644
+        this.options.jxlDistance = options.quality >= 30
+          ? 0.1 + (100 - options.quality) * 0.09
+          : 53 / 3000 * options.quality * options.quality - 23 / 20 * options.quality + 25;
+      } else {
+        throw is.invalidParameterError('quality', 'integer between 1 and 100', options.quality);
+      }
+    } else if (is.defined(options.distance)) {
+      if (is.number(options.distance) && is.inRange(options.distance, 0, 15)) {
+        this.options.jxlDistance = options.distance;
+      } else {
+        throw is.invalidParameterError('distance', 'number between 0.0 and 15.0', options.distance);
+      }
+    }
+    if (is.defined(options.decodingTier)) {
+      if (is.integer(options.decodingTier) && is.inRange(options.decodingTier, 0, 4)) {
+        this.options.jxlDecodingTier = options.decodingTier;
+      } else {
+        throw is.invalidParameterError('decodingTier', 'integer between 0 and 4', options.decodingTier);
+      }
+    }
+    if (is.defined(options.lossless)) {
+      if (is.bool(options.lossless)) {
+        this.options.jxlLossless = options.lossless;
+      } else {
+        throw is.invalidParameterError('lossless', 'boolean', options.lossless);
+      }
+    }
+    if (is.defined(options.effort)) {
+      if (is.integer(options.effort) && is.inRange(options.effort, 3, 9)) {
+        this.options.jxlEffort = options.effort;
+      } else {
+        throw is.invalidParameterError('effort', 'integer between 3 and 9', options.effort);
+      }
+    }
+  }
+  return this._updateFormatOut('jxl', options);
+}
+
+/**
  * Force output to be raw, uncompressed pixel data.
@@ -938,2 +1080,3 @@ * Pixel ordering is left-to-right, top-to-bottom, without padding.
  * @param {string} [options.depth='uchar'] - bit depth, one of: char, uchar (default), short, ushort, int, uint, float, complex, double, dpcomplex
+ * @returns {Sharp}
  * @throws {Error} Invalid options
@@ -958,5 +1101,12 @@ */
  * Use tile-based deep zoom (image pyramid) output.
+ *
  * Set the format and options for tile images via the `toFormat`, `jpeg`, `png` or `webp` functions.
  * Use a `.zip` or `.szi` file extension with `toFile` to write to a compressed archive file format.
  *
+ * 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
@@ -973,2 +1123,13 @@ *  sharp('input.tiff')
  *
+ * @example
+ * const zipFileWithTiles = await sharp(input)
+ *   .tile({ basename: "tiles" })
+ *   .toBuffer();
+ *
+ * @example
+ * const iiififier = sharp().tile({ layout: "iiif" });
+ * readableStream
+ *   .pipe(iiififier)
+ *   .pipe(writeableStream);
+ *
  * @param {Object} [options]
@@ -986,2 +1147,3 @@ * @param {number} [options.size=256] tile size in pixels, a value between 1 and 8192.
  * @param {string} [options.id='https://example.com/iiif'] when `layout` is `iiif`/`iiif3`, sets the `@id`/`id` attribute of `info.json`
+ * @param {string} [options.basename] the name of the directory within the zip file when container is `zip`.
  * @returns {Sharp}
@@ -1068,2 +1230,10 @@ * @throws {Error} Invalid parameters
     }
+    // Basename for zip container
+    if (is.defined(options.basename)) {
+      if (is.string(options.basename)) {
+        this.options.tileBasename = options.basename;
+      } else {
+        throw is.invalidParameterError('basename', 'string', options.basename);
+      }
+    }
   }
@@ -1086,2 +1256,13 @@ // Format
  *
+ * @example
+ * // Ensure processing takes no longer than 3 seconds
+ * try {
+ *   const data = await sharp(input)
+ *     .blur(1000)
+ *     .timeout({ seconds: 3 })
+ *     .toBuffer();
+ * } catch (err) {
+ *   if (err.message.includes('timeout')) { ... }
+ * }
+ *
  * @since 0.29.2
@@ -1181,3 +1362,3 @@ *
           this.push(null);
-          this.emit('close');
+          this.on('end', () => this.emit('close'));
         });
@@ -1198,3 +1379,3 @@ });
         this.push(null);
-        this.emit('close');
+        this.on('end', () => this.emit('close'));
       });
@@ -1260,2 +1441,3 @@ }
     heif,
+    jxl,
     gif,
@@ -1262,0 +1444,0 @@ raw,

lib/platform.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -2,0 +5,0 @@

lib/resize.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -40,2 +43,14 @@
 /**
+ * How to extend the image.
+ * @member
+ * @private
+ */
+const extendWith = {
+  background: 'background',
+  copy: 'copy',
+  repeat: 'repeat',
+  mirror: 'mirror'
+};
+
+/**
  * Strategies for automagic cover behaviour.
@@ -97,6 +112,13 @@ * @member
 /**
+ * @private
+ */
+function isResizeExpected (options) {
+  return options.width !== -1 || options.height !== -1;
+}
+
+/**
  * 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.
@@ -109,3 +131,5 @@ * - `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
  *
- * When using a `fit` of `cover` or `contain`, the default **position** is `centre`. Other options are:
+ * <img alt="Examples of various values for the fit property when resizing" width="100%" style="aspect-ratio: 998/243" src="https://cdn.jsdelivr.net/gh/lovell/sharp@main/docs/image/api-resize-fit.svg">
+ *
+ * When using a **fit** of `cover` or `contain`, the default **position** is `centre`. Other options are:
  * - `sharp.position`: `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`.
@@ -129,2 +153,5 @@ * - `sharp.gravity`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` or `centre`.
  *
+ * Only one resize can occur per pipeline.
+ * Previous calls to `resize` in the same pipeline will be ignored.
+ *
  * @example
@@ -211,25 +238,28 @@ * sharp(input)
  *
- * @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 take priority.
- * @param {String} [options.height] - alternative means of specifying `height`. If both are present this take 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) {
-  if (is.defined(width)) {
-    if (is.object(width) && !is.defined(options)) {
-      options = width;
-    } else if (is.integer(width) && width > 0) {
-      this.options.width = width;
+function resize (widthOrOptions, height, options) {
+  if (isResizeExpected(this.options)) {
+    this.options.debuglog('ignoring previous resize options');
+  }
+  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);
     }
@@ -308,2 +338,5 @@ } else {
   }
+  if (isRotationExpected(this.options) && isResizeExpected(this.options)) {
+    this.options.rotateBeforePreExtract = true;
+  }
   return this;
@@ -313,3 +346,4 @@ }
 /**
- * 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.
@@ -340,2 +374,11 @@ *
  *
+ * @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
@@ -346,2 +389,3 @@ * @param {number} [extend.top=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.
@@ -387,2 +431,9 @@ * @returns {Sharp}
     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 {
@@ -425,3 +476,6 @@ throw is.invalidParameterError('extend', 'integer or object', extend);
 function extract (options) {
-  const suffix = this.options.width === -1 && this.options.height === -1 ? 'Pre' : 'Post';
+  const suffix = isResizeExpected(this.options) || this.options.widthPre !== -1 ? 'Post' : 'Pre';
+  if (this.options[`width${suffix}`] !== -1) {
+    this.options.debuglog('ignoring previous extract options');
+  }
   ['left', 'top', 'width', 'height'].forEach(function (name) {
@@ -436,4 +490,6 @@ const value = options[name];
   // Ensure existing rotation occurs before pre-resize extraction
-  if (suffix === 'Pre' && isRotationExpected(this.options)) {
-    this.options.rotateBeforePreExtract = true;
+  if (isRotationExpected(this.options) && !isResizeExpected(this.options)) {
+    if (this.options.widthPre === -1 || this.options.widthPost === -1) {
+      this.options.rotateBeforePreExtract = true;
+    }
   }
@@ -444,21 +500,74 @@ return this;
 /**
- * Trim "boring" pixels from all edges that contain values similar to the top-left pixel.
- * Images consisting entirely of a single colour will calculate "boring" using the alpha channel, if any.
+ * Trim pixels from all edges that contain values similar to the given background colour, which defaults to that of the top-left pixel.
  *
+ * Images with an alpha channel will use the combined bounding box of alpha and non-alpha channels.
+ *
+ * If the result of this operation would trim an image to nothing then no change is made.
+ *
  * The `info` response Object, obtained from callback of `.toFile()` or `.toBuffer()`,
  * will contain `trimOffsetLeft` and `trimOffsetTop` properties.
  *
- * @param {number} [threshold=10] the allowed difference from the top-left pixel, a number greater than zero.
+ * @example
+ * // Trim pixels with a colour similar to that of the top-left pixel.
+ * sharp(input)
+ *   .trim()
+ *   .toFile(output, function(err, info) {
+ *     ...
+ *   });
+ * @example
+ * // Trim pixels with the exact same colour as that of the top-left pixel.
+ * sharp(input)
+ *   .trim(0)
+ *   .toFile(output, function(err, info) {
+ *     ...
+ *   });
+ * @example
+ * // Trim only pixels with a similar colour to red.
+ * sharp(input)
+ *   .trim("#FF0000")
+ *   .toFile(output, function(err, info) {
+ *     ...
+ *   });
+ * @example
+ * // Trim all "yellow-ish" pixels, being more lenient with the higher threshold.
+ * sharp(input)
+ *   .trim({
+ *     background: "yellow",
+ *     threshold: 42,
+ *   })
+ *   .toFile(output, function(err, info) {
+ *     ...
+ *   });
+ *
+ * @param {string|number|Object} trim - the specific background colour to trim, the threshold for doing so or an Object with both.
+ * @param {string|Object} [trim.background='top-left pixel'] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to that of the top-left pixel.
+ * @param {number} [trim.threshold=10] - the allowed difference from the above colour, a positive number.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-function trim (threshold) {
-  if (!is.defined(threshold)) {
+function trim (trim) {
+  if (!is.defined(trim)) {
     this.options.trimThreshold = 10;
-  } else if (is.number(threshold) && threshold > 0) {
-    this.options.trimThreshold = threshold;
+  } else if (is.string(trim)) {
+    this._setBackgroundColourOption('trimBackground', trim);
+    this.options.trimThreshold = 10;
+  } else if (is.number(trim)) {
+    if (trim >= 0) {
+      this.options.trimThreshold = trim;
+    } else {
+      throw is.invalidParameterError('threshold', 'positive number', trim);
+    }
+  } else if (is.object(trim)) {
+    this._setBackgroundColourOption('trimBackground', trim.background);
+    if (!is.defined(trim.threshold)) {
+      this.options.trimThreshold = 10;
+    } else if (is.number(trim.threshold) && trim.threshold >= 0) {
+      this.options.trimThreshold = trim.threshold;
+    } else {
+      throw is.invalidParameterError('threshold', 'positive number', trim);
+    }
   } else {
-    throw is.invalidParameterError('threshold', 'number greater than zero', threshold);
+    throw is.invalidParameterError('trim', 'string, number or object', trim);
   }
-  if (this.options.trimThreshold && isRotationExpected(this.options)) {
+  if (isRotationExpected(this.options)) {
     this.options.rotateBeforePreExtract = true;
@@ -465,0 +574,0 @@ }

lib/sharp.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -2,0 +5,0 @@

lib/utility.js

@@ -0,1 +1,4 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
@@ -20,2 +23,6 @@
 const format = sharp.format();
+format.heif.output.alias = ['avif', 'heic'];
+format.jpeg.output.alias = ['jpe', 'jpg'];
+format.tiff.output.alias = ['tif'];
+format.jp2k.output.alias = ['j2c', 'j2k', 'jp2', 'jpx'];
 
@@ -43,3 +50,3 @@ /**
 /**
- * An Object containing the version numbers of libvips and its dependencies.
+ * An Object containing the version numbers of sharp, libvips and its dependencies.
  * @member
@@ -55,2 +62,3 @@ * @example
 } catch (_err) { /* ignore */ }
+versions.sharp = require('../package.json').version;
 
@@ -201,2 +209,68 @@ /**
 /**
+ * Block libvips operations at runtime.
+ *
+ * This is in addition to the `VIPS_BLOCK_UNTRUSTED` environment variable,
+ * which when set will block all "untrusted" operations.
+ *
+ * @since 0.32.4
+ *
+ * @example <caption>Block all TIFF input.</caption>
+ * sharp.block({
+ *   operation: ['VipsForeignLoadTiff']
+ * });
+ *
+ * @param {Object} options
+ * @param {Array<string>} options.operation - List of libvips low-level operation names to block.
+ */
+function block (options) {
+  if (is.object(options)) {
+    if (Array.isArray(options.operation) && options.operation.every(is.string)) {
+      sharp.block(options.operation, true);
+    } else {
+      throw is.invalidParameterError('operation', 'Array<string>', options.operation);
+    }
+  } else {
+    throw is.invalidParameterError('options', 'object', options);
+  }
+}
+
+/**
+ * Unblock libvips operations at runtime.
+ *
+ * This is useful for defining a list of allowed operations.
+ *
+ * @since 0.32.4
+ *
+ * @example <caption>Block all input except WebP from the filesystem.</caption>
+ * sharp.block({
+ *   operation: ['VipsForeignLoad']
+ * });
+ * sharp.unblock({
+ *   operation: ['VipsForeignLoadWebpFile']
+ * });
+ *
+ * @example <caption>Block all input except JPEG and PNG from a Buffer or Stream.</caption>
+ * sharp.block({
+ *   operation: ['VipsForeignLoad']
+ * });
+ * sharp.unblock({
+ *   operation: ['VipsForeignLoadJpegBuffer', 'VipsForeignLoadPngBuffer']
+ * });
+ *
+ * @param {Object} options
+ * @param {Array<string>} options.operation - List of libvips low-level operation names to unblock.
+ */
+function unblock (options) {
+  if (is.object(options)) {
+    if (Array.isArray(options.operation) && options.operation.every(is.string)) {
+      sharp.block(options.operation, false);
+    } else {
+      throw is.invalidParameterError('operation', 'Array<string>', options.operation);
+    }
+  } else {
+    throw is.invalidParameterError('options', 'object', options);
+  }
+}
+
+/**
  * Decorate the Sharp class with utility-related functions.
@@ -215,2 +289,4 @@ * @private
   Sharp.queue = queue;
+  Sharp.block = block;
+  Sharp.unblock = unblock;
 };

package.json

 {
   "name": "sharp",
   "description": "High performance Node.js image processing, the fastest module to resize JPEG, PNG, WebP, GIF, AVIF and TIFF images",
-  "version": "0.30.7",
+  "version": "0.32.6",
   "author": "Lovell Fuller <[e-mail]>",
@@ -86,3 +86,6 @@ "homepage": "https://github.com/lovell/sharp",
     "Brodan <[e-mail]",
-    "Ankur Parihar <[e-mail]>"
+    "Ankur Parihar <[e-mail]>",
+    "Brahim Ait elhaj <[e-mail]>",
+    "Mart Jansink <[e-mail]>",
+    "Lachlan Newman <[e-mail]>"
   ],
@@ -92,9 +95,9 @@ "scripts": {
     "clean": "rm -rf node_modules/ build/ vendor/ .nyc_output/ coverage/ test/fixtures/output.*",
-    "test": "npm run test-lint && npm run test-unit && npm run test-licensing",
+    "test": "npm run test-lint && npm run test-unit && npm run test-licensing && npm run test-types",
     "test-lint": "semistandard && cpplint",
-    "test-unit": "nyc --reporter=lcov --branches=99 mocha --slow=1000 --timeout=60000 ./test/unit/*.js",
+    "test-unit": "nyc --reporter=lcov --reporter=text --check-coverage --branches=100 mocha",
     "test-licensing": "license-checker --production --summary --onlyAllow=\"Apache-2.0;BSD;ISC;MIT\"",
-    "test-coverage": "./test/coverage/report.sh",
     "test-leak": "./test/leak/leak.sh",
-    "docs-build": "documentation lint lib && node docs/build && node docs/search-index/build",
+    "test-types": "tsd",
+    "docs-build": "node docs/build && node docs/search-index/build",
     "docs-serve": "cd docs && npx serve",
@@ -104,2 +107,3 @@ "docs-publish": "cd docs && npx firebase-tools deploy --project pixelplumbing --only hosting:pixelplumbing-sharp"
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
@@ -135,46 +139,47 @@ "binding.gyp",
     "color": "^4.2.3",
-    "detect-libc": "^2.0.1",
-    "node-addon-api": "^5.0.0",
+    "detect-libc": "^2.0.2",
+    "node-addon-api": "^6.1.0",
     "prebuild-install": "^7.1.1",
-    "semver": "^7.3.7",
+    "semver": "^7.5.4",
     "simple-get": "^4.0.1",
-    "tar-fs": "^2.1.1",
+    "tar-fs": "^3.0.4",
     "tunnel-agent": "^0.6.0"
   },
   "devDependencies": {
+    "@types/node": "*",
     "async": "^3.2.4",
     "cc": "^3.0.1",
-    "decompress-zip": "^0.3.3",
-    "documentation": "^13.2.5",
-    "exif-reader": "^1.0.3",
-    "icc": "^2.0.0",
+    "exif-reader": "^1.2.0",
+    "extract-zip": "^2.0.1",
+    "icc": "^3.0.0",
+    "jsdoc-to-markdown": "^8.0.0",
     "license-checker": "^25.0.1",
-    "mocha": "^10.0.0",
-    "mock-fs": "^5.1.2",
+    "mocha": "^10.2.0",
+    "mock-fs": "^5.2.0",
     "nyc": "^15.1.0",
-    "prebuild": "^11.0.3",
-    "rimraf": "^3.0.2",
-    "semistandard": "^16.0.1"
+    "prebuild": "^12.0.0",
+    "semistandard": "^16.0.1",
+    "tsd": "^0.29.0"
   },
   "license": "Apache-2.0",
   "config": {
-    "libvips": "8.12.2",
+    "libvips": "8.14.5",
     "integrity": {
-      "darwin-arm64v8": "sha512-p46s/bbJAjkOXzPISZt9HUpG9GWjwQkYnLLRLKzsBJHLtB3X6C6Y/zXI5Hd0DOojcFkks9a0kTN+uDQ/XJY19g==",
-      "darwin-x64": "sha512-6vOHVZnvXwe6EXRsy29jdkUzBE6ElNpXUwd+m8vV7qy32AnXu7B9YemHsZ44vWviIwPZeXF6Nhd9EFLM0wWohw==",
-      "linux-arm64v8": "sha512-XwZdS63yhqLtbFtx/0eoLF/Agf5qtTrI11FMnMRpuBJWd4jHB60RAH+uzYUgoChCmKIS+AeXYMLm4d8Ns2QX8w==",
-      "linux-armv6": "sha512-Rh0Q0kqwPG2MjXWOkPCuPEyiUKFgKJYWLgS835D4MrXgdKr8Tft/eVrc2iGIxt2re30VpDiZ1h0Rby1aCZt2zw==",
-      "linux-armv7": "sha512-heTS/MsmRvu4JljINxP+vDiS9ZZfuGhr3IStb5F7Gc0/QLRhllYAg4rcO8L1eTK9sIIzG5ARvI19+YUZe7WbzA==",
-      "linux-x64": "sha512-SSWAwBFi0hx8V/h/v82tTFGKWTFv9FiCK3Timz5OExuI+sX1Ngrd0PVQaWXOThGNdel/fcD3Bz9YjSt4feBR1g==",
-      "linuxmusl-arm64v8": "sha512-Rhks+5C7p7aO6AucLT1uvzo8ohlqcqCUPgZmN+LZjsPWob/Iix3MfiDYtv/+gTvdeEfXxbCU6/YuPBwHQ7/crA==",
-      "linuxmusl-x64": "sha512-IOyjSQqpWVntqOUpCHVWuQwACwmmjdi15H8Pc+Ma1JkhPogTfVsFQWyL7DuOTD3Yr23EuYGzovUX00duOtfy/g==",
-      "win32-arm64v8": "sha512-A+Qe8Ipewtvw9ldvF6nWed2J8kphzrUE04nFeKCtNx6pfGQ/MAlCKMjt/U8VgUKNjB01zJDUW9XE0+FhGZ/UpQ==",
-      "win32-ia32": "sha512-cMrAvwFdDeAVnLJt0IPMPRKaIFhyXYGTprsM0DND9VUHE8F7dJMR44tS5YkXsGh1QNDtjKT6YuxAVUglmiXtpA==",
-      "win32-x64": "sha512-vLFIfw6aW2zABa8jpgzWDhljnE6glktrddErVyazAIoHl6BFFe/Da+LK1DbXvIYHz7fyOoKhSfCJHCiJG1Vg6w=="
+      "darwin-arm64v8": "sha512-1QZzICfCJd4wAO0P6qmYI5e5VFMt9iCE4QgefI8VMMbdSzjIXA9L/ARN6pkMQPZ3h20Y9RtJ2W1skgCsvCIccw==",
+      "darwin-x64": "sha512-sMIKMYXsdU9FlIfztj6Kt/SfHlhlDpP0Ups7ftVFqwjaszmYmpI9y/d/q3mLb4jrzuSiSUEislSWCwBnW7MPTw==",
+      "linux-arm64v8": "sha512-CD8owELzkDumaom+O3jJ8fKamILAQdj+//KK/VNcHK3sngUcFpdjx36C8okwbux9sml/T7GTB/gzpvReDrAejQ==",
+      "linux-armv6": "sha512-wk6IPHatDFVWKJy7lI1TJezHGHPQut1wF2bwx256KlZwXUQU3fcVcMpV1zxXjgLFewHq2+uhyMkoSGBPahWzlA==",
+      "linux-armv7": "sha512-HEZC9KYtkmBK5rUR2MqBhrVarnQVZ/TwLUeLkKq0XuoM2pc/eXI6N0Fh5NGEFwdXI2XE8g1ySf+OYS6DDi+xCQ==",
+      "linux-x64": "sha512-SlFWrITSW5XVUkaFPQOySAaSGXnhkGJCj8X2wGYYta9hk5piZldQyMp4zwy0z6UeRu1qKTKtZvmq28W3Gnh9xA==",
+      "linuxmusl-arm64v8": "sha512-ga9iX7WUva3sG/VsKkOD318InLlCfPIztvzCZKZ2/+izQXRbQi8VoXWMHgEN4KHACv45FTl7mJ/8CRqUzhS8wQ==",
+      "linuxmusl-x64": "sha512-yeaHnpfee1hrZLok2l4eFceHzlfq8gN3QOu0R4Mh8iMK5O5vAUu97bdtxeZZeJJvHw8tfh2/msGi0qysxKN8bw==",
+      "win32-arm64v8": "sha512-kR91hy9w1+GEXK56hLh51+hBCBo7T+ijM4Slkmvb/2PsYZySq5H7s61n99iDYl6kTJP2y9sW5Xcvm3uuXDaDgg==",
+      "win32-ia32": "sha512-HrnofEbzHNpHJ0vVnjsTj5yfgVdcqdWshXuwFO2zc8xlEjA83BvXZ0lVj9MxPxkxJ2ta+/UlLr+CFzc5bOceMw==",
+      "win32-x64": "sha512-BwKckinJZ0Fu/EcunqiLPwOLEBWp4xf8GV7nvmVuKKz5f6B+GxoA2k9aa2wueqv4r4RJVgV/aWXZWFKOIjre/Q=="
     },
     "runtime": "napi",
-    "target": 5
+    "target": 7
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14.15.0"
   },
@@ -186,3 +191,3 @@ "funding": {
     "napi_versions": [
-      5
+      7
     ]
@@ -200,3 +205,6 @@ },
     ]
+  },
+  "tsd": {
+    "directory": "test/types/"
   }
 }

README.md

@@ -19,3 +19,3 @@ # sharp
 
-Most modern macOS, Windows and Linux systems running Node.js >= 12.13.0
+Most modern macOS, Windows and Linux systems running Node.js >= 14.15.0
 do not require any additional install or runtime dependencies.
@@ -102,8 +102,5 @@
 
-[![Test Coverage](https://coveralls.io/repos/lovell/sharp/badge.svg?branch=main)](https://coveralls.io/r/lovell/sharp?branch=main)
-[![Node-API v5](https://img.shields.io/badge/Node--API-v5-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix)
-
 ## Licensing
 
-Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Lovell Fuller and contributors.
+Copyright 2013 Lovell Fuller and others.
 
@@ -110,0 +107,0 @@ Licensed under the Apache License, Version 2.0 (the "License");

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

609870

increased by23.6%

Number of package files

42

increased by5%

Lines of code

6830

increased by47.45%

Worsened metrics

Dev dependency count

14

increased by7.69%

Number of lines in readme file

115

decreased by-2.54%

Published versions last year

14

decreased by-6.67%