nuxt-ignis 0.5.0 → 0.5.2

package/.output/server/node_modules/sharp/lib/output.js

@@ -1,9 +1,9 @@
-// Copyright 2013 Lovell Fuller and others.
-// SPDX-License-Identifier: Apache-2.0
+/*!
+  Copyright 2013 Lovell Fuller and others.
+  SPDX-License-Identifier: Apache-2.0
+*/
 
-'use strict';
-
-const path = require('path');
+const path = require('node:path');
 const is = require('./is');
 const sharp = require('./sharp');
 
@@ -43,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|withMetadata} for control over this.
+ * See {@link #withmetadata withMetadata} for control over this.
  *
  * The caller is responsible for ensuring directory structures and permissions exist.
  *
@@ -65,6 +65,7 @@ const bitdepthFromColourCount = (colours) => 1 << 31 - Math.clz32(Math.ceil(Math
  * `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.
+ * Animated output will also contain `pageHeight` and `pages`.
  * 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
@@ -86,7 +87,8 @@ function toFile (fileOut, callback) {
     }
   } else {
     this.options.fileOut = fileOut;
-    return this._pipeline(callback);
+    const stack = Error();
+    return this._pipeline(callback, stack);
   }
   return this;
 }
@@ -95,12 +97,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|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 jpeg}, {@link #png 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|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.
@@ -108,6 +110,7 @@ function toFile (fileOut, callback) {
  * - `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`.
+ * Animated output will also contain `pageHeight` and `pages`.
  * May also contain `textAutofitDpi` (dpi the font was rendered at) if image was created from text.
  *
  * A `Promise` is returned when `callback` is not provided.
@@ -157,43 +160,250 @@ function toBuffer (options, callback) {
     this.options.resolveWithObject = false;
   }
   this.options.fileOut = '';
-  return this._pipeline(is.fn(options) ? options : callback);
+  const stack = Error();
+  return this._pipeline(is.fn(options) ? options : callback, stack);
 }
 
 /**
- * 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 if appropriate,
- * unless a custom output profile is provided.
- *
- * The default behaviour, when `withMetadata` is not used, is to convert to the device-independent
- * sRGB colour space and strip all metadata, including the removal of any ICC profile.
+ * Keep all EXIF metadata from the input image in the output image.
  *
  * EXIF metadata is unsupported for TIFF output.
  *
+ * @since 0.33.0
+ *
  * @example
- * sharp('input.jpg')
- *   .withMetadata()
- *   .toFile('output-with-metadata.jpg')
- *   .then(info => { ... });
+ * const outputWithExif = await sharp(inputWithExif)
+ *   .keepExif()
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function keepExif () {
+  this.options.keepMetadata |= 0b00001;
+  return this;
+}
+
+/**
+ * Set EXIF metadata in the output image, ignoring any EXIF in the input image.
+ *
+ * @since 0.33.0
  *
  * @example
- * // Set output EXIF metadata
- * const data = await sharp(input)
- *   .withMetadata({
- *     exif: {
- *       IFD0: {
- *         Copyright: 'The National Gallery'
- *       },
- *       IFD3: {
- *         GPSLatitudeRef: 'N',
- *         GPSLatitude: '51/1 30/1 3230/100',
- *         GPSLongitudeRef: 'W',
- *         GPSLongitude: '0/1 7/1 4366/100'
- *       }
+ * const dataWithExif = await sharp(input)
+ *   .withExif({
+ *     IFD0: {
+ *       Copyright: 'The National Gallery'
+ *     },
+ *     IFD3: {
+ *       GPSLatitudeRef: 'N',
+ *       GPSLatitude: '51/1 30/1 3230/100',
+ *       GPSLongitudeRef: 'W',
+ *       GPSLongitude: '0/1 7/1 4366/100'
+ *     }
+ *   })
+ *   .toBuffer();
+ *
+ * @param {Object<string, Object<string, string>>} exif Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withExif (exif) {
+  if (is.object(exif)) {
+    for (const [ifd, entries] of Object.entries(exif)) {
+      if (is.object(entries)) {
+        for (const [k, v] of Object.entries(entries)) {
+          if (is.string(v)) {
+            this.options.withExif[`exif-${ifd.toLowerCase()}-${k}`] = v;
+          } else {
+            throw is.invalidParameterError(`${ifd}.${k}`, 'string', v);
+          }
+        }
+      } else {
+        throw is.invalidParameterError(ifd, 'object', entries);
+      }
+    }
+  } else {
+    throw is.invalidParameterError('exif', 'object', exif);
+  }
+  this.options.withExifMerge = false;
+  return this.keepExif();
+}
+
+/**
+ * Update EXIF metadata from the input image in the output image.
+ *
+ * @since 0.33.0
+ *
+ * @example
+ * const dataWithMergedExif = await sharp(inputWithExif)
+ *   .withExifMerge({
+ *     IFD0: {
+ *       Copyright: 'The National Gallery'
  *     }
  *   })
  *   .toBuffer();
  *
+ * @param {Object<string, Object<string, string>>} exif Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withExifMerge (exif) {
+  this.withExif(exif);
+  this.options.withExifMerge = true;
+  return this;
+}
+
+/**
+ * Keep ICC profile from the input image in the output image.
+ *
+ * When input and output colour spaces differ, use with {@link /api-colour/#tocolourspace toColourspace} and optionally {@link /api-colour/#pipelinecolourspace pipelineColourspace}.
+ *
+ * @since 0.33.0
+ *
+ * @example
+ * const outputWithIccProfile = await sharp(inputWithIccProfile)
+ *   .keepIccProfile()
+ *   .toBuffer();
+ *
+ * @example
+ * const cmykOutputWithIccProfile = await sharp(cmykInputWithIccProfile)
+ *   .pipelineColourspace('cmyk')
+ *   .toColourspace('cmyk')
+ *   .keepIccProfile()
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function keepIccProfile () {
+  this.options.keepMetadata |= 0b01000;
+  return this;
+}
+
+/**
+ * Transform using an ICC profile and attach to the output image.
+ *
+ * This can either be an absolute filesystem path or
+ * built-in profile name (`srgb`, `p3`, `cmyk`).
+ *
+ * @since 0.33.0
+ *
+ * @example
+ * const outputWithP3 = await sharp(input)
+ *   .withIccProfile('p3')
+ *   .toBuffer();
+ *
+ * @param {string} icc - Absolute filesystem path to output ICC profile or built-in profile name (srgb, p3, cmyk).
+ * @param {Object} [options]
+ * @param {number} [options.attach=true] Should the ICC profile be included in the output image metadata?
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withIccProfile (icc, options) {
+  if (is.string(icc)) {
+    this.options.withIccProfile = icc;
+  } else {
+    throw is.invalidParameterError('icc', 'string', icc);
+  }
+  this.keepIccProfile();
+  if (is.object(options)) {
+    if (is.defined(options.attach)) {
+      if (is.bool(options.attach)) {
+        if (!options.attach) {
+          this.options.keepMetadata &= ~0b01000;
+        }
+      } else {
+        throw is.invalidParameterError('attach', 'boolean', options.attach);
+      }
+    }
+  }
+  return this;
+}
+
+/**
+ * Keep XMP metadata from the input image in the output image.
+ *
+ * @since 0.34.3
+ *
+ * @example
+ * const outputWithXmp = await sharp(inputWithXmp)
+ *   .keepXmp()
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function keepXmp () {
+  this.options.keepMetadata |= 0b00010;
+  return this;
+}
+
+/**
+ * Set XMP metadata in the output image.
+ *
+ * Supported by PNG, JPEG, WebP, and TIFF output.
+ *
+ * @since 0.34.3
+ *
+ * @example
+ * const xmpString = `
+ *   <?xml version="1.0"?>
+ *   <x:xmpmeta xmlns:x="adobe:ns:meta/">
+ *     <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+ *       <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
+ *         <dc:creator><rdf:Seq><rdf:li>John Doe</rdf:li></rdf:Seq></dc:creator>
+ *       </rdf:Description>
+ *     </rdf:RDF>
+ *   </x:xmpmeta>`;
+ *
+ * const data = await sharp(input)
+ *   .withXmp(xmpString)
+ *   .toBuffer();
+ *
+ * @param {string} xmp String containing XMP metadata to be embedded in the output image.
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withXmp (xmp) {
+  if (is.string(xmp) && xmp.length > 0) {
+    this.options.withXmp = xmp;
+    this.options.keepMetadata |= 0b00010;
+  } else {
+    throw is.invalidParameterError('xmp', 'non-empty string', xmp);
+  }
+  return this;
+}
+
+/**
+ * Keep all metadata (EXIF, ICC, XMP, IPTC) from the input image in the output image.
+ *
+ * The default behaviour, when `keepMetadata` is not used, is to convert to the device-independent
+ * sRGB colour space and strip all metadata, including the removal of any ICC profile.
+ *
+ * @since 0.33.0
+ *
+ * @example
+ * const outputWithMetadata = await sharp(inputWithMetadata)
+ *   .keepMetadata()
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function keepMetadata () {
+  this.options.keepMetadata = 0b11111;
+  return this;
+}
+
+/**
+ * Keep most 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 if appropriate.
+ *
+ * Allows orientation and density to be set or updated.
+ *
+ * @example
+ * const outputSrgbWithMetadata = await sharp(inputRgbWithMetadata)
+ *   .withMetadata()
+ *   .toBuffer();
+ *
  * @example
  * // Set output metadata to 96 DPI
  * const data = await sharp(input)
@@ -201,15 +411,14 @@ function toBuffer (options, callback) {
  *   .toBuffer();
  *
  * @param {Object} [options]
- * @param {number} [options.orientation] value between 1 and 8, used to update the EXIF `Orientation` tag.
- * @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.orientation] Used to update the EXIF `Orientation` tag, integer between 1 and 8.
  * @param {number} [options.density] Number of pixels per inch (DPI).
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
 function withMetadata (options) {
-  this.options.withMetadata = is.bool(options) ? options : true;
+  this.keepMetadata();
+  this.withIccProfile('srgb');
   if (is.object(options)) {
     if (is.defined(options.orientation)) {
       if (is.integer(options.orientation) && is.inRange(options.orientation, 1, 8)) {
@@ -226,30 +435,10 @@ function withMetadata (options) {
       }
     }
     if (is.defined(options.icc)) {
-      if (is.string(options.icc)) {
-        this.options.withMetadataIcc = options.icc;
-      } else {
-        throw is.invalidParameterError('icc', 'string filesystem path to ICC profile', options.icc);
-      }
+      this.withIccProfile(options.icc);
     }
     if (is.defined(options.exif)) {
-      if (is.object(options.exif)) {
-        for (const [ifd, entries] of Object.entries(options.exif)) {
-          if (is.object(entries)) {
-            for (const [k, v] of Object.entries(entries)) {
-              if (is.string(v)) {
-                this.options.withMetadataStrs[`exif-${ifd.toLowerCase()}-${k}`] = v;
-              } else {
-                throw is.invalidParameterError(`exif.${ifd}.${k}`, 'string', v);
-              }
-            }
-          } else {
-            throw is.invalidParameterError(`exif.${ifd}`, 'object', entries);
-          }
-        }
-      } else {
-        throw is.invalidParameterError('exif', 'object', options.exif);
-      }
+      this.withExifMerge(options.exif);
     }
   }
   return this;
@@ -377,10 +566,14 @@ function jpeg (options) {
 /**
  * Use these PNG options for output image.
  *
- * By default, PNG output is full colour at 8 or 16 bits per pixel.
+ * By default, PNG output is full colour at 8 bits per pixel.
+ *
  * Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel.
  * Set `palette` to `true` for slower, indexed PNG output.
  *
+ * For 16 bits per pixel output, convert to `rgb16` via
+ * {@link /api-colour/#tocolourspace toColourspace}.
+ *
  * @example
  * // Convert any input to full colour PNG output
  * const data = await sharp(input)
@@ -393,6 +586,13 @@ function jpeg (options) {
  *   .png({ palette: true })
  *   .toBuffer();
  *
+ * @example
+ * // Output 16 bits per pixel RGB(A)
+ * const data = await sharp(input)
+ *  .toColourspace('rgb16')
+ *  .png()
+ *  .toBuffer();
+ *
  * @param {Object} [options]
  * @param {boolean} [options.progressive=false] - use progressive (interlace) scan
  * @param {number} [options.compressionLevel=6] - zlib compression level, 0 (fastest, largest) to 9 (slowest, smallest)
@@ -483,6 +683,7 @@ function png (options) {
  * @param {boolean} [options.lossless=false] - use lossless compression mode
  * @param {boolean} [options.nearLossless=false] - use near_lossless compression mode
  * @param {boolean} [options.smartSubsample=false] - use high quality chroma subsampling
+ * @param {boolean} [options.smartDeblock=false] - auto-adjust the deblocking filter, can improve low contrast edges (slow)
  * @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
@@ -518,6 +719,9 @@ function webp (options) {
     if (is.defined(options.smartSubsample)) {
       this._setBooleanOption('webpSmartSubsample', options.smartSubsample);
     }
+    if (is.defined(options.smartDeblock)) {
+      this._setBooleanOption('webpSmartDeblock', options.smartDeblock);
+    }
     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;
@@ -585,6 +789,7 @@ function webp (options) {
  * @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 {boolean} [options.keepDuplicateFrames=false] - keep duplicate frames in the output instead of combining them
  * @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.force=true] - force GIF output, otherwise attempt to use input format
@@ -635,18 +840,24 @@ function gif (options) {
         throw is.invalidParameterError('interPaletteMaxError', 'number between 0.0 and 256.0', options.interPaletteMaxError);
       }
     }
+    if (is.defined(options.keepDuplicateFrames)) {
+      if (is.bool(options.keepDuplicateFrames)) {
+        this._setBooleanOption('gifKeepDuplicateFrames', options.keepDuplicateFrames);
+      } else {
+        throw is.invalidParameterError('keepDuplicateFrames', 'boolean', options.keepDuplicateFrames);
+      }
+    }
   }
   trySetAnimationOptions(options, this.options);
   return this._updateFormatOut('gif', options);
 }
 
-/* istanbul ignore next */
 /**
  * Use these JP2 options for output image.
  *
  * Requires libvips compiled with support for OpenJPEG.
  * The prebuilt binaries do not include this - see
- * {@link https://sharp.pixelplumbing.com/install#custom-libvips installing a custom libvips}.
+ * {@link /install#custom-libvips installing a custom libvips}.
  *
  * @example
  * // Convert any input to lossless JP2 output
@@ -675,6 +886,7 @@ function gif (options) {
  * @throws {Error} Invalid options
  */
 function jp2 (options) {
+  /* node:coverage ignore next 41 */
   if (!this.constructor.format.jp2k.output.buffer) {
     throw errJp2Save();
   }
@@ -754,7 +966,7 @@ function trySetAnimationOptions (source, target) {
 /**
  * Use these TIFF options for output image.
  *
- * The `density` can be set in pixels/inch via {@link #withmetadata|withMetadata}
+ * The `density` can be set in pixels/inch via {@link #withmetadata withMetadata}
  * instead of providing `xres` and `yres` in pixels/mm.
  *
  * @example
@@ -771,6 +983,7 @@ function trySetAnimationOptions (source, target) {
  * @param {number} [options.quality=80] - quality, integer 1-100
  * @param {boolean} [options.force=true] - force TIFF output, otherwise attempt to use input format
  * @param {string} [options.compression='jpeg'] - compression options: none, jpeg, deflate, packbits, ccittfax4, lzw, webp, zstd, jp2k
+ * @param {boolean} [options.bigtiff=false] - use BigTIFF variant (has no effect when compression is none)
  * @param {string} [options.predictor='horizontal'] - compression predictor options: none, horizontal, float
  * @param {boolean} [options.pyramid=false] - write an image pyramid
  * @param {boolean} [options.tile=false] - write a tiled tiff
@@ -780,6 +993,7 @@ function trySetAnimationOptions (source, target) {
  * @param {number} [options.yres=1.0] - vertical resolution in pixels/mm
  * @param {string} [options.resolutionUnit='inch'] - resolution unit options: inch, cm
  * @param {number} [options.bitdepth=8] - reduce bitdepth to 1, 2 or 4 bit
+ * @param {boolean} [options.miniswhite=false] - write 1-bit images as miniswhite
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
@@ -817,6 +1031,10 @@ function tiff (options) {
         throw is.invalidParameterError('tileHeight', 'integer greater than zero', options.tileHeight);
       }
     }
+    // miniswhite
+    if (is.defined(options.miniswhite)) {
+      this._setBooleanOption('tiffMiniswhite', options.miniswhite);
+    }
     // pyramid
     if (is.defined(options.pyramid)) {
       this._setBooleanOption('tiffPyramid', options.pyramid);
@@ -844,6 +1062,10 @@ function tiff (options) {
         throw is.invalidParameterError('compression', 'one of: none, jpeg, deflate, packbits, ccittfax4, lzw, webp, zstd, jp2k', options.compression);
       }
     }
+    // bigtiff
+    if (is.defined(options.bigtiff)) {
+      this._setBooleanOption('tiffBigtiff', options.bigtiff);
+    }
     // predictor
     if (is.defined(options.predictor)) {
       if (is.string(options.predictor) && is.inArray(options.predictor, ['none', 'horizontal', 'float'])) {
@@ -867,10 +1089,11 @@ function tiff (options) {
 /**
  * Use these AVIF options for output image.
  *
- * Whilst it is possible to create AVIF images smaller than 16x16 pixels,
- * most web browsers do not display these properly.
- *
  * AVIF image sequences are not supported.
+ * Prebuilt binaries support a bitdepth of 8 only.
+ *
+ * This feature is experimental on the Windows ARM64 platform
+ * and requires a CPU with ARM64v8.4 or later.
  *
  * @example
  * const data = await sharp(input)
@@ -889,6 +1112,7 @@ function tiff (options) {
  * @param {boolean} [options.lossless=false] - use lossless compression
  * @param {number} [options.effort=4] - CPU effort, between 0 (fastest) and 9 (slowest)
  * @param {string} [options.chromaSubsampling='4:4:4'] - set to '4:2:0' to use chroma subsampling
+ * @param {number} [options.bitdepth=8] - set bitdepth to 8, 10 or 12 bit
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
@@ -909,17 +1133,23 @@ function avif (options) {
  *
  * @since 0.23.0
  *
- * @param {Object} [options] - output options
+ * @param {Object} options - output options
+ * @param {string} options.compression - compression format: av1, hevc
  * @param {number} [options.quality=50] - quality, integer 1-100
- * @param {string} [options.compression='av1'] - compression format: av1, hevc
  * @param {boolean} [options.lossless=false] - use lossless compression
  * @param {number} [options.effort=4] - CPU effort, between 0 (fastest) and 9 (slowest)
  * @param {string} [options.chromaSubsampling='4:4:4'] - set to '4:2:0' to use chroma subsampling
+ * @param {number} [options.bitdepth=8] - set bitdepth to 8, 10 or 12 bit
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
 function heif (options) {
   if (is.object(options)) {
+    if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
+      this.options.heifCompression = options.compression;
+    } else {
+      throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
+    }
     if (is.defined(options.quality)) {
       if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
         this.options.heifQuality = options.quality;
@@ -934,13 +1164,6 @@ function heif (options) {
         throw is.invalidParameterError('lossless', 'boolean', options.lossless);
       }
     }
-    if (is.defined(options.compression)) {
-      if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
-        this.options.heifCompression = options.compression;
-      } else {
-        throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
-      }
-    }
     if (is.defined(options.effort)) {
       if (is.integer(options.effort) && is.inRange(options.effort, 0, 9)) {
         this.options.heifEffort = options.effort;
@@ -955,6 +1178,18 @@ function heif (options) {
         throw is.invalidParameterError('chromaSubsampling', 'one of: 4:2:0, 4:4:4', options.chromaSubsampling);
       }
     }
+    if (is.defined(options.bitdepth)) {
+      if (is.integer(options.bitdepth) && is.inArray(options.bitdepth, [8, 10, 12])) {
+        if (options.bitdepth !== 8 && this.constructor.versions.heif) {
+          throw is.invalidParameterError('bitdepth when using prebuilt binaries', 8, options.bitdepth);
+        }
+        this.options.heifBitdepth = options.bitdepth;
+      } else {
+        throw is.invalidParameterError('bitdepth', '8, 10 or 12', options.bitdepth);
+      }
+    }
+  } else {
+    throw is.invalidParameterError('options', 'Object', options);
   }
   return this._updateFormatOut('heif', options);
 }
@@ -966,9 +1201,7 @@ function heif (options) {
  *
  * 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.
+ * {@link /install/#custom-libvips installing a custom libvips}.
  *
  * @since 0.31.3
  *
@@ -977,7 +1210,9 @@ function heif (options) {
  * @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)
+ * @param {number} [options.effort=7] - CPU effort, between 1 (fastest) and 9 (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)
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
@@ -1014,13 +1249,14 @@ function jxl (options) {
       }
     }
     if (is.defined(options.effort)) {
-      if (is.integer(options.effort) && is.inRange(options.effort, 3, 9)) {
+      if (is.integer(options.effort) && is.inRange(options.effort, 1, 9)) {
         this.options.jxlEffort = options.effort;
       } else {
-        throw is.invalidParameterError('effort', 'integer between 3 and 9', options.effort);
+        throw is.invalidParameterError('effort', 'integer between 1 and 9', options.effort);
       }
     }
   }
+  trySetAnimationOptions(options, this.options);
   return this._updateFormatOut('jxl', options);
 }
 
@@ -1072,10 +1308,6 @@ 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()
@@ -1104,7 +1336,7 @@ function raw (options) {
  * @param {number} [options.angle=0] tile angle of rotation, must be a multiple of 90.
  * @param {string|Object} [options.background={r: 255, g: 255, b: 255, alpha: 1}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to white without transparency.
  * @param {string} [options.depth] how deep to make the pyramid, possible values are `onepixel`, `onetile` or `one`, default based on layout.
- * @param {number} [options.skipBlanks=-1] threshold to skip tile generation, a value 0 - 255 for 8-bit images or 0 - 65535 for 16-bit images
+ * @param {number} [options.skipBlanks=-1] Threshold to skip tile generation. Range is 0-255 for 8-bit images, 0-65535 for 16-bit images. Default is 5 for `google` layout, -1 (no skip) otherwise.
  * @param {string} [options.container='fs'] tile container, with value `fs` (filesystem) or `zip` (compressed file).
  * @param {string} [options.layout='dz'] filesystem layout, possible values are `dz`, `iiif`, `iiif3`, `zoomify` or `google`.
  * @param {boolean} [options.centre=false] centre image in tile.
@@ -1282,10 +1514,10 @@ function _setBooleanOption (key, val) {
  * @private
  */
 function _read () {
-  /* istanbul ignore else */
   if (!this.options.streamOut) {
     this.options.streamOut = true;
-    this._pipeline();
+    const stack = Error();
+    this._pipeline(undefined, stack);
   }
 }
 
@@ -1294,18 +1526,30 @@ function _read () {
  * Supports callback, stream and promise variants
  * @private
  */
-function _pipeline (callback) {
+function _pipeline (callback, stack) {
   if (typeof callback === 'function') {
     // output=file/buffer
     if (this._isStreamInput()) {
       // output=file/buffer, input=stream
       this.on('finish', () => {
         this._flattenBufferIn();
-        sharp.pipeline(this.options, callback);
+        sharp.pipeline(this.options, (err, data, info) => {
+          if (err) {
+            callback(is.nativeError(err, stack));
+          } else {
+            callback(null, data, info);
+          }
+        });
       });
     } else {
       // output=file/buffer, input=file/buffer
-      sharp.pipeline(this.options, callback);
+      sharp.pipeline(this.options, (err, data, info) => {
+        if (err) {
+          callback(is.nativeError(err, stack));
+        } else {
+          callback(null, data, info);
+        }
+      });
     }
     return this;
   } else if (this.options.streamOut) {
@@ -1316,7 +1560,7 @@ function _pipeline (callback) {
         this._flattenBufferIn();
         sharp.pipeline(this.options, (err, data, info) => {
           if (err) {
-            this.emit('error', err);
+            this.emit('error', is.nativeError(err, stack));
           } else {
             this.emit('info', info);
             this.push(data);
@@ -1332,7 +1576,7 @@ function _pipeline (callback) {
       // output=stream, input=file/buffer
       sharp.pipeline(this.options, (err, data, info) => {
         if (err) {
-          this.emit('error', err);
+          this.emit('error', is.nativeError(err, stack));
         } else {
           this.emit('info', info);
           this.push(data);
@@ -1351,7 +1595,7 @@ function _pipeline (callback) {
           this._flattenBufferIn();
           sharp.pipeline(this.options, (err, data, info) => {
             if (err) {
-              reject(err);
+              reject(is.nativeError(err, stack));
             } else {
               if (this.options.resolveWithObject) {
                 resolve({ data, info });
@@ -1367,10 +1611,10 @@ function _pipeline (callback) {
       return new Promise((resolve, reject) => {
         sharp.pipeline(this.options, (err, data, info) => {
           if (err) {
-            reject(err);
+            reject(is.nativeError(err, stack));
           } else {
             if (this.options.resolveWithObject) {
-              resolve({ data: data, info: info });
+              resolve({ data, info });
             } else {
               resolve(data);
             }
@@ -1383,13 +1627,22 @@ function _pipeline (callback) {
 
 /**
  * Decorate the Sharp prototype with output-related functions.
+ * @module Sharp
  * @private
  */
-module.exports = function (Sharp) {
+module.exports = (Sharp) => {
   Object.assign(Sharp.prototype, {
     // Public
     toFile,
     toBuffer,
+    keepExif,
+    withExif,
+    withExifMerge,
+    keepIccProfile,
+    withIccProfile,
+    keepXmp,
+    withXmp,
+    keepMetadata,
     withMetadata,
     toFormat,
     jpeg,