@depup/sharp 0.34.5-depup.0 → 0.35.4-depup.0

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

@@ -4,8 +4,8 @@
 */
 
 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'],
@@ -33,7 +33,7 @@ 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)));
+const bitdepthFromColourCount = (colours) => 1 << 32 - Math.clz32(Math.ceil(Math.log2(colours)) - 1);
 
 /**
  * Write output image data to a file.
@@ -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) {
@@ -113,24 +113,20 @@ function toFile (fileOut, callback) {
  * 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.
+ * The underlying `ArrayBuffer` may be marked as non-transferable by some JavaScript runtimes.
+ * Use {@link #touint8array toUint8Array} for a guaranteed transferable `ArrayBuffer`.
  *
- * @example
- * sharp(input)
- *   .toBuffer((err, data, info) => { ... });
+ * A `Promise` is returned when `callback` is not provided.
  *
  * @example
- * sharp(input)
- *   .toBuffer()
- *   .then(data => { ... })
- *   .catch(err => { ... });
+ * const data = await sharp(input)
+ *   .png()
+ *   .toBuffer();
  *
  * @example
- * sharp(input)
+ * const { data, info } = await sharp(input)
  *   .png()
- *   .toBuffer({ resolveWithObject: true })
- *   .then(({ data, info }) => { ... })
- *   .catch(err => { ... });
+ *   .toBuffer({ resolveWithObject: true });
  *
  * @example
  * const { data, info } = await sharp('my-image.jpg')
@@ -164,6 +160,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.
  *
@@ -319,6 +373,60 @@ 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.
  *
@@ -388,7 +496,7 @@ function withXmp (xmp) {
  * @returns {Sharp}
  */
 function keepMetadata () {
-  this.options.keepMetadata = 0b11111;
+  this.options.keepMetadata |= 0b11111;
   return this;
 }
 
@@ -690,6 +798,7 @@ function png (options) {
  * @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
@@ -742,6 +851,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);
@@ -813,7 +925,7 @@ function gif (options) {
       }
     }
     if (is.defined(options.effort)) {
-      if (is.number(options.effort) && is.inRange(options.effort, 1, 10)) {
+      if (is.integer(options.effort) && is.inRange(options.effort, 1, 10)) {
         this.options.gifEffort = options.effort;
       } else {
         throw is.invalidParameterError('effort', 'integer between 1 and 10', options.effort);
@@ -887,7 +999,7 @@ function gif (options) {
  */
 function jp2 (options) {
   /* node:coverage ignore next 41 */
-  if (!this.constructor.format.jp2k.output.buffer) {
+  if (!this.constructor.format.jp2.output.buffer) {
     throw errJp2Save();
   }
   if (is.object(options)) {
@@ -987,12 +1099,12 @@ function trySetAnimationOptions (source, target) {
  * @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
- * @param {number} [options.tileWidth=256] - horizontal tile size
- * @param {number} [options.tileHeight=256] - vertical tile size
- * @param {number} [options.xres=1.0] - horizontal resolution in pixels/mm
- * @param {number} [options.yres=1.0] - vertical resolution in pixels/mm
+ * @param {number} [options.tileWidth=256] - horizontal tile size, valid values are integers in the range 1-32768
+ * @param {number} [options.tileHeight=256] - vertical tile size, valid values are integers in the range 1-32768
+ * @param {number} [options.xres=1.0] - horizontal resolution in pixels/mm, valid values are numbers in the range 0.001-1000000
+ * @param {number} [options.yres=1.0] - vertical resolution in pixels/mm, valid values are numbers in the range 0.001-1000000
  * @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
@@ -1007,10 +1119,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
@@ -1018,17 +1130,17 @@ function tiff (options) {
       this._setBooleanOption('tiffTile', options.tile);
     }
     if (is.defined(options.tileWidth)) {
-      if (is.integer(options.tileWidth) && options.tileWidth > 0) {
+      if (is.integer(options.tileWidth) && is.inRange(options.tileWidth, 1, 32768)) {
         this.options.tiffTileWidth = options.tileWidth;
       } else {
-        throw is.invalidParameterError('tileWidth', 'integer greater than zero', options.tileWidth);
+        throw is.invalidParameterError('tileWidth', 'integer between 1 and 32768', options.tileWidth);
       }
     }
     if (is.defined(options.tileHeight)) {
-      if (is.integer(options.tileHeight) && options.tileHeight > 0) {
+      if (is.integer(options.tileHeight) && is.inRange(options.tileHeight, 1, 32768)) {
         this.options.tiffTileHeight = options.tileHeight;
       } else {
-        throw is.invalidParameterError('tileHeight', 'integer greater than zero', options.tileHeight);
+        throw is.invalidParameterError('tileHeight', 'integer between 1 and 32768', options.tileHeight);
       }
     }
     // miniswhite
@@ -1041,17 +1153,17 @@ function tiff (options) {
     }
     // resolution
     if (is.defined(options.xres)) {
-      if (is.number(options.xres) && options.xres > 0) {
+      if (is.number(options.xres) && is.inRange(options.xres, 0.001, 1000000)) {
         this.options.tiffXres = options.xres;
       } else {
-        throw is.invalidParameterError('xres', 'number greater than zero', options.xres);
+        throw is.invalidParameterError('xres', 'number between 0.001 and 1000000', options.xres);
       }
     }
     if (is.defined(options.yres)) {
-      if (is.number(options.yres) && options.yres > 0) {
+      if (is.number(options.yres) && is.inRange(options.yres, 0.001, 1000000)) {
         this.options.tiffYres = options.yres;
       } else {
-        throw is.invalidParameterError('yres', 'number greater than zero', options.yres);
+        throw is.invalidParameterError('yres', 'number between 0.001 and 1000000', options.yres);
       }
     }
     // compression
@@ -1090,10 +1202,6 @@ function tiff (options) {
  * Use these AVIF options for output image.
  *
  * 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)
@@ -1113,6 +1221,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
  */
@@ -1140,6 +1249,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
  */
@@ -1180,14 +1290,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);
   }
@@ -1531,7 +1649,7 @@ function _pipeline (callback, stack) {
     // output=file/buffer
     if (this._isStreamInput()) {
       // output=file/buffer, input=stream
-      this.on('finish', () => {
+      this._whenStreamInFinished(() => {
         this._flattenBufferIn();
         sharp.pipeline(this.options, (err, data, info) => {
           if (err) {
@@ -1556,7 +1674,7 @@ function _pipeline (callback, stack) {
     // output=stream
     if (this._isStreamInput()) {
       // output=stream, input=stream
-      this.once('finish', () => {
+      this._whenStreamInFinished(() => {
         this._flattenBufferIn();
         sharp.pipeline(this.options, (err, data, info) => {
           if (err) {
@@ -1569,9 +1687,6 @@ function _pipeline (callback, stack) {
           this.on('end', () => this.emit('close'));
         });
       });
-      if (this.streamInFinished) {
-        this.emit('finish');
-      }
     } else {
       // output=stream, input=file/buffer
       sharp.pipeline(this.options, (err, data, info) => {
@@ -1591,7 +1706,7 @@ function _pipeline (callback, stack) {
     if (this._isStreamInput()) {
       // output=promise, input=stream
       return new Promise((resolve, reject) => {
-        this.once('finish', () => {
+        this._whenStreamInFinished(() => {
           this._flattenBufferIn();
           sharp.pipeline(this.options, (err, data, info) => {
             if (err) {
@@ -1635,11 +1750,15 @@ module.exports = (Sharp) => {
     // Public
     toFile,
     toBuffer,
+    toUint8Array,
+    withDensity,
     keepExif,
     withExif,
     withExifMerge,
     keepIccProfile,
     withIccProfile,
+    keepGainMap,
+    withGainMap,
     keepXmp,
     withXmp,
     keepMetadata,