sharp 0.33.5 → 0.35.0

package/{lib/output.js → dist/output.cjs}

@@ -1,11 +1,11 @@
-// Copyright 2013 Lovell Fuller and others.
-// SPDX-License-Identifier: Apache-2.0
-
-'use strict';
+/*!
+  Copyright 2013 Lovell Fuller and others.
+  SPDX-License-Identifier: Apache-2.0
+*/
 
 const path = require('node:path');
-const is = require('./is');
-const sharp = require('./sharp');
+const is = require('./is.cjs');
+const sharp = require('./sharp.cjs');
 
 const formats = new Map([
   ['heic', 'heif'],
@@ -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.
  *
@@ -76,7 +76,7 @@ function toFile (fileOut, callback) {
     err = new Error('Missing output file path');
   } else if (is.string(this.options.input.file) && path.resolve(this.options.input.file) === path.resolve(fileOut)) {
     err = new Error('Cannot use same file for input and output');
-  } else if (jp2Regex.test(path.extname(fileOut)) && !this.constructor.format.jp2k.output.file) {
+  } else if (jp2Regex.test(path.extname(fileOut)) && !this.constructor.format.jp2.output.file) {
     err = errJp2Save();
   }
   if (err) {
@@ -97,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.
@@ -164,6 +164,64 @@ function toBuffer (options, callback) {
   return this._pipeline(is.fn(options) ? options : callback, stack);
 }
 
+/**
+ * Write output to a `Uint8Array` backed by a transferable `ArrayBuffer`.
+ * 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 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 #keepexif keepExif} and similar methods for control over this.
+ *
+ * Resolves with an `Object` containing:
+ * - `data` is the output image as a `Uint8Array` backed by a transferable `ArrayBuffer`.
+ * - `info` contains properties relating to the output image such as `width` and `height`.
+ *
+ * @since v0.35.0
+ *
+ * @example
+ * const { data, info } = await sharp(input).toUint8Array();
+ *
+ * @example
+ * const { data } = await sharp(input)
+ *   .avif()
+ *   .toUint8Array();
+ * const base64String = data.toBase64();
+ *
+ * @returns {Promise<{ data: Uint8Array, info: Object }>}
+ */
+function toUint8Array () {
+  this.options.resolveWithObject = true;
+  this.options.typedArrayOut = true;
+  const stack = Error();
+  return this._pipeline(null, stack);
+}
+
+/**
+ * Set output density (DPI) in EXIF metadata.
+ *
+ * @since 0.35.0
+ *
+ * @example
+ * const data = await sharp(input)
+ *   .withDensity(96)
+ *   .toBuffer();
+ *
+ * @param {number} density Number of pixels per inch (DPI).
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withDensity (density) {
+  if (is.number(density) && density > 0) {
+    this.options.withMetadataDensity = density;
+  } else {
+    throw is.invalidParameterError('density', 'positive number', density);
+  }
+  return this.keepExif();
+}
+
 /**
  * Keep all EXIF metadata from the input image in the output image.
  *
@@ -256,7 +314,7 @@ function withExifMerge (exif) {
 /**
  * Keep ICC profile from the input image in the output image.
  *
- * Where necessary, will attempt to convert the output colour space to match the profile.
+ * 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
  *
@@ -265,6 +323,13 @@ function withExifMerge (exif) {
  *   .keepIccProfile()
  *   .toBuffer();
  *
+ * @example
+ * const cmykOutputWithIccProfile = await sharp(cmykInputWithIccProfile)
+ *   .pipelineColourspace('cmyk')
+ *   .toColourspace('cmyk')
+ *   .keepIccProfile()
+ *   .toBuffer();
+ *
  * @returns {Sharp}
  */
 function keepIccProfile () {
@@ -312,6 +377,113 @@ function withIccProfile (icc, options) {
   return this;
 }
 
+/**
+ * If the input contains gain map metadata, attempt to process the image and gain map separately,
+ * recombining them into a single output image.
+ *
+ * This approach is faster and should produce better results than {@link #withgainmap withGainMap},
+ * however not all operations are supported.
+ *
+ * Only JPEG input and output are supported.
+ * JPEG output options other than `quality` are ignored.
+ *
+ * This feature is experimental and the API may change.
+ *
+ * @since 0.35.0
+ *
+ * @example
+ * const outputWithResizedGainMap = await sharp(inputWithGainMap)
+ *   .keepGainMap()
+ *   .resize({ width: 64 })
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function keepGainMap() {
+  this.options.keepGainMap = true;
+  this.options.withGainMap = false;
+  this.options.keepMetadata |= 0b100000;
+  return this;
+}
+
+/**
+ * If the input contains gain map metadata, use it to convert the main image to HDR (High Dynamic Range) before further processing.
+ * The input gain map is discarded.
+ *
+ * If the output is JPEG, generate and attach a new ISO 21496-1 gain map.
+ * JPEG output options other than `quality` are ignored.
+ *
+ * This feature is experimental and the API may change.
+ *
+ * @since 0.35.0
+ *
+ * @example
+ * const outputWithRegeneratedGainMap = await sharp(inputWithGainMap)
+ *   .withGainMap()
+ *   .toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function withGainMap() {
+  this.options.withGainMap = true;
+  this.options.keepGainMap = false;
+  this.options.colourspace = 'scrgb';
+  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.
  *
@@ -328,7 +500,7 @@ function withIccProfile (icc, options) {
  * @returns {Sharp}
  */
 function keepMetadata () {
-  this.options.keepMetadata = 0b11111;
+  this.options.keepMetadata |= 0b11111;
   return this;
 }
 
@@ -512,7 +684,7 @@ function jpeg (options) {
  * Set `palette` to `true` for slower, indexed PNG output.
  *
  * For 16 bits per pixel output, convert to `rgb16` via
- * {@link /api-colour#tocolourspace|toColourspace}.
+ * {@link /api-colour/#tocolourspace toColourspace}.
  *
  * @example
  * // Convert any input to full colour PNG output
@@ -623,12 +795,14 @@ 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
  * @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.exact=false] - preserve the colour data in transparent pixels
  * @param {boolean} [options.force=true] - force WebP output, otherwise attempt to use input format
  * @returns {Sharp}
  * @throws {Error} Invalid options
@@ -658,6 +832,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;
@@ -678,6 +855,9 @@ function webp (options) {
     if (is.defined(options.mixed)) {
       this._setBooleanOption('webpMixed', options.mixed);
     }
+    if (is.defined(options.exact)) {
+      this._setBooleanOption('webpExact', options.exact);
+    }
   }
   trySetAnimationOptions(options, this.options);
   return this._updateFormatOut('webp', options);
@@ -725,6 +905,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
@@ -775,18 +956,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
@@ -815,7 +1002,8 @@ function gif (options) {
  * @throws {Error} Invalid options
  */
 function jp2 (options) {
-  if (!this.constructor.format.jp2k.output.buffer) {
+  /* node:coverage ignore next 41 */
+  if (!this.constructor.format.jp2.output.buffer) {
     throw errJp2Save();
   }
   if (is.object(options)) {
@@ -894,7 +1082,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
@@ -911,6 +1099,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
@@ -919,7 +1108,7 @@ function trySetAnimationOptions (source, target) {
  * @param {number} [options.xres=1.0] - horizontal resolution in pixels/mm
  * @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 {number} [options.bitdepth=0] - 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
@@ -934,10 +1123,10 @@ function tiff (options) {
       }
     }
     if (is.defined(options.bitdepth)) {
-      if (is.integer(options.bitdepth) && is.inArray(options.bitdepth, [1, 2, 4, 8])) {
+      if (is.integer(options.bitdepth) && is.inArray(options.bitdepth, [1, 2, 4])) {
         this.options.tiffBitdepth = options.bitdepth;
       } else {
-        throw is.invalidParameterError('bitdepth', '1, 2, 4 or 8', options.bitdepth);
+        throw is.invalidParameterError('bitdepth', '1, 2 or 4', options.bitdepth);
       }
     }
     // tiling
@@ -989,6 +1178,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'])) {
@@ -1013,7 +1206,8 @@ function tiff (options) {
  * Use these AVIF options for output image.
  *
  * AVIF image sequences are not supported.
- * Prebuilt binaries support a bitdepth of 8 only.
+ *
+ * When using Windows ARM64, this feature requires a CPU with ARM64v8.4 or later.
  *
  * @example
  * const data = await sharp(input)
@@ -1033,6 +1227,7 @@ function tiff (options) {
  * @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
+ * @param {string} [options.tune='auto'] - tune output for a quality metric, one of 'auto' (default), 'iq', 'psnr' or 'ssim'
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
@@ -1060,6 +1255,7 @@ function avif (options) {
  * @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
+ * @param {string} [options.tune='auto'] - tune output for a quality metric, one of 'auto' (default), 'iq', 'psnr' or 'ssim'
  * @returns {Sharp}
  * @throws {Error} Invalid options
  */
@@ -1100,14 +1296,22 @@ function heif (options) {
     }
     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);
       }
     }
+    if (is.defined(options.tune)) {
+      if (is.string(options.tune) && is.inArray(options.tune, ['auto', 'iq', 'psnr', 'ssim'])) {
+        if (this.options.heifLossless && options.tune === 'iq') {
+          this.options.heifTune = 'ssim';
+        } else {
+          this.options.heifTune = options.tune;
+        }
+      } else {
+        throw is.invalidParameterError('tune', 'one of: auto, iq, psnr, ssim', options.tune);
+      }
+    }
   } else {
     throw is.invalidParameterError('options', 'Object', options);
   }
@@ -1121,9 +1325,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
  *
@@ -1132,7 +1334,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
  */
@@ -1169,13 +1373,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);
 }
 
@@ -1227,10 +1432,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()
@@ -1437,7 +1638,6 @@ function _setBooleanOption (key, val) {
  * @private
  */
 function _read () {
-  /* istanbul ignore else */
   if (!this.options.streamOut) {
     this.options.streamOut = true;
     const stack = Error();
@@ -1551,18 +1751,25 @@ function _pipeline (callback, stack) {
 
 /**
  * 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,
+    toUint8Array,
+    withDensity,
     keepExif,
     withExif,
     withExifMerge,
     keepIccProfile,
     withIccProfile,
+    keepGainMap,
+    withGainMap,
+    keepXmp,
+    withXmp,
     keepMetadata,
     withMetadata,
     toFormat,