sharp 0.28.1 → 0.29.1

package/README.md

@@ -16,7 +16,7 @@ Lanczos resampling ensures quality is not sacrificed for speed.
 As well as image resizing, operations such as
 rotation, extraction, compositing and gamma correction are available.
 
-Most modern macOS, Windows and Linux systems running Node.js v10+
+Most modern macOS, Windows and Linux systems running Node.js >= 12.13.0
 do not require any additional install or runtime dependencies.
 
 ## Documentation
@@ -99,7 +99,7 @@ A [guide for contributors](https://github.com/lovell/sharp/blob/master/.github/C
 covers reporting bugs, requesting features and submitting code changes.
 
 [![Test Coverage](https://coveralls.io/repos/lovell/sharp/badge.svg?branch=master)](https://coveralls.io/r/lovell/sharp?branch=master)
-[![N-API v3](https://img.shields.io/badge/N--API-v3-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix)
+[![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
 

package/binding.gyp

@@ -1,7 +1,8 @@
 {
   'variables': {
     'vips_version': '<!(node -p "require(\'./lib/libvips\').minimumLibvipsVersion")',
-    'sharp_vendor_dir': '<(module_root_dir)/vendor/<(vips_version)'
+    'platform_and_arch': '<!(node -p "require(\'./lib/platform\')()")',
+    'sharp_vendor_dir': './vendor/<(vips_version)/<(platform_and_arch)'
   },
   'targets': [{
     'target_name': 'libvips-cpp',
@@ -37,6 +38,7 @@
             'msvs_settings': {
               'VCCLCompilerTool': {
                 'ExceptionHandling': 1,
+                'Optimization': 1,
                 'WholeProgramOptimization': 'true'
               },
               'VCLibrarianTool': {
@@ -65,9 +67,9 @@
       }]
     ]
   }, {
-    'target_name': 'sharp',
+    'target_name': 'sharp-<(platform_and_arch)',
     'defines': [
-      'NAPI_VERSION=3'
+      'NAPI_VERSION=5'
     ],
     'dependencies': [
       '<!(node -p "require(\'node-addon-api\').gyp")',
@@ -138,7 +140,7 @@
           }],
           ['OS == "mac"', {
             'link_settings': {
-              'library_dirs': ['<(sharp_vendor_dir)/lib'],
+              'library_dirs': ['../<(sharp_vendor_dir)/lib'],
               'libraries': [
                 'libvips-cpp.42.dylib'
               ]
@@ -146,7 +148,7 @@
             'xcode_settings': {
               'OTHER_LDFLAGS': [
                 # Ensure runtime linking is relative to sharp.node
-                '-Wl,-rpath,\'@loader_path/../../vendor/<(vips_version)/lib\''
+                '-Wl,-rpath,\'@loader_path/../../<(sharp_vendor_dir)/lib\''
               ]
             }
           }],
@@ -155,13 +157,13 @@
               '_GLIBCXX_USE_CXX11_ABI=1'
             ],
             'link_settings': {
-              'library_dirs': ['<(sharp_vendor_dir)/lib'],
+              'library_dirs': ['../<(sharp_vendor_dir)/lib'],
               'libraries': [
                 '-l:libvips-cpp.so.42'
               ],
               'ldflags': [
                 # Ensure runtime linking is relative to sharp.node
-                '-Wl,-s -Wl,--disable-new-dtags -Wl,-rpath=\'$$ORIGIN/../../vendor/<(vips_version)/lib\''
+                '-Wl,-s -Wl,--disable-new-dtags -Wl,-rpath=\'$$ORIGIN/../../<(sharp_vendor_dir)/lib\''
               ]
             }
           }]
@@ -172,7 +174,7 @@
       '-std=c++0x',
       '-fexceptions',
       '-Wall',
-      '-O3'
+      '-Os'
     ],
     'xcode_settings': {
       'CLANG_CXX_LANGUAGE_STANDARD': 'c++11',
@@ -182,7 +184,7 @@
       'OTHER_CPLUSPLUSFLAGS': [
         '-fexceptions',
         '-Wall',
-        '-O3'
+        '-Oz'
       ]
     },
     'configurations': {
@@ -202,6 +204,7 @@
             'msvs_settings': {
               'VCCLCompilerTool': {
                 'ExceptionHandling': 1,
+                'Optimization': 1,
                 'WholeProgramOptimization': 'true'
               },
               'VCLibrarianTool': {

package/install/can-compile.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const libvips = require('../lib/libvips');
+
+try {
+  if (!(libvips.useGlobalLibvips() || libvips.hasVendoredLibvips())) {
+    process.exitCode = 1;
+  }
+} catch (err) {
+  process.exitCode = 1;
+}

package/install/dll-copy.js

@@ -4,19 +4,19 @@ const fs = require('fs');
 const path = require('path');
 
 const libvips = require('../lib/libvips');
+const platform = require('../lib/platform');
 
 const minimumLibvipsVersion = libvips.minimumLibvipsVersion;
 
-const platform = process.env.npm_config_platform || process.platform;
-if (platform === 'win32') {
-  const buildDir = path.join(__dirname, '..', 'build');
-  const buildReleaseDir = path.join(buildDir, 'Release');
+const platformAndArch = platform();
+
+if (platformAndArch.startsWith('win32')) {
+  const buildReleaseDir = path.join(__dirname, '..', 'build', 'Release');
   libvips.log(`Creating ${buildReleaseDir}`);
   try {
-    libvips.mkdirSync(buildDir);
     libvips.mkdirSync(buildReleaseDir);
   } catch (err) {}
-  const vendorLibDir = path.join(__dirname, '..', 'vendor', minimumLibvipsVersion, 'lib');
+  const vendorLibDir = path.join(__dirname, '..', 'vendor', minimumLibvipsVersion, platformAndArch, 'lib');
   libvips.log(`Copying DLLs from ${vendorLibDir} to ${buildReleaseDir}`);
   try {
     fs

package/install/libvips.js

@@ -7,7 +7,8 @@ const stream = require('stream');
 const zlib = require('zlib');
 
 const detectLibc = require('detect-libc');
-const semver = require('semver');
+const semverLessThan = require('semver/functions/lt');
+const semverSatisfies = require('semver/functions/satisfies');
 const simpleGet = require('simple-get');
 const tarFs = require('tar-fs');
 
@@ -23,6 +24,7 @@ const minimumGlibcVersionByArch = {
 
 const hasSharpPrebuild = [
   'darwin-x64',
+  'darwin-arm64',
   'linux-arm64',
   'linux-x64',
   'linuxmusl-x64',
@@ -34,22 +36,27 @@ const hasSharpPrebuild = [
 const { minimumLibvipsVersion, minimumLibvipsVersionLabelled } = libvips;
 const distHost = process.env.npm_config_sharp_libvips_binary_host || 'https://github.com/lovell/sharp-libvips/releases/download';
 const distBaseUrl = process.env.npm_config_sharp_dist_base_url || process.env.SHARP_DIST_BASE_URL || `${distHost}/v${minimumLibvipsVersionLabelled}/`;
-const supportsBrotli = ('BrotliDecompress' in zlib);
+const installationForced = !!(process.env.npm_config_sharp_install_force || process.env.SHARP_INSTALL_FORCE);
 
 const fail = function (err) {
   libvips.log(err);
   if (err.code === 'EACCES') {
     libvips.log('Are you trying to install as a root or sudo user? Try again with the --unsafe-perm flag');
   }
-  libvips.log('Attempting to build from source via node-gyp but this may fail due to the above error');
   libvips.log('Please see https://sharp.pixelplumbing.com/install for required dependencies');
   process.exit(1);
 };
 
+const handleError = function (err) {
+  if (installationForced) {
+    libvips.log(`Installation warning: ${err.message}`);
+  } else {
+    throw err;
+  }
+};
+
 const extractTarball = function (tarPath, platformAndArch) {
-  const vendorPath = path.join(__dirname, '..', 'vendor');
-  libvips.mkdirSync(vendorPath);
-  const versionedVendorPath = path.join(vendorPath, minimumLibvipsVersion);
+  const versionedVendorPath = path.join(__dirname, '..', 'vendor', minimumLibvipsVersion, platformAndArch);
   libvips.mkdirSync(versionedVendorPath);
 
   const ignoreVendorInclude = hasSharpPrebuild.includes(platformAndArch) && !process.env.npm_config_build_from_source;
@@ -59,7 +66,7 @@ const extractTarball = function (tarPath, platformAndArch) {
 
   stream.pipeline(
     fs.createReadStream(tarPath),
-    supportsBrotli ? new zlib.BrotliDecompress() : new zlib.Gunzip(),
+    new zlib.BrotliDecompress(),
     tarFs.extract(versionedVendorPath, { ignore }),
     function (err) {
       if (err) {
@@ -95,26 +102,25 @@ try {
     if (platformAndArch === 'freebsd-x64' || platformAndArch === 'openbsd-x64' || platformAndArch === 'sunos-x64') {
       throw new Error(`BSD/SunOS systems require manual installation of libvips >= ${minimumLibvipsVersion}`);
     }
-    if (detectLibc.family === detectLibc.GLIBC && detectLibc.version) {
-      if (semver.lt(`${detectLibc.version}.0`, `${minimumGlibcVersionByArch[arch]}.0`)) {
-        throw new Error(`Use with glibc ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`);
+    // Linux libc version check
+    if (detectLibc.family === detectLibc.GLIBC && detectLibc.version && minimumGlibcVersionByArch[arch]) {
+      if (semverLessThan(`${detectLibc.version}.0`, `${minimumGlibcVersionByArch[arch]}.0`)) {
+        handleError(new Error(`Use with glibc ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
       }
     }
     if (detectLibc.family === detectLibc.MUSL && detectLibc.version) {
-      if (semver.lt(detectLibc.version, '1.1.24')) {
-        throw new Error(`Use with musl ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`);
+      if (semverLessThan(detectLibc.version, '1.1.24')) {
+        handleError(new Error(`Use with musl ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
       }
     }
-
+    // Node.js minimum version check
     const supportedNodeVersion = process.env.npm_package_engines_node || require('../package.json').engines.node;
-    if (!semver.satisfies(process.versions.node, supportedNodeVersion)) {
-      throw new Error(`Expected Node.js version ${supportedNodeVersion} but found ${process.versions.node}`);
+    if (!semverSatisfies(process.versions.node, supportedNodeVersion)) {
+      handleError(new Error(`Expected Node.js version ${supportedNodeVersion} but found ${process.versions.node}`));
     }
 
-    const extension = supportsBrotli ? 'br' : 'gz';
-
     // Download to per-process temporary file
-    const tarFilename = ['libvips', minimumLibvipsVersion, platformAndArch].join('-') + '.tar.' + extension;
+    const tarFilename = ['libvips', minimumLibvipsVersion, platformAndArch].join('-') + '.tar.br';
     const tarPathCache = path.join(libvips.cachePath(), tarFilename);
     if (fs.existsSync(tarPathCache)) {
       libvips.log(`Using cached ${tarPathCache}`);

package/lib/agent.js

@@ -25,7 +25,7 @@ module.exports = function () {
       ? tunnelAgent.httpsOverHttps
       : tunnelAgent.httpsOverHttp;
     const proxyAuth = proxy.username && proxy.password
-      ? `${proxy.username}:${proxy.password}`
+      ? `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`
       : null;
     return tunnel({
       proxy: {

package/lib/channel.js

@@ -15,6 +15,8 @@ const bool = {
 /**
  * Remove alpha channel, if any. This is a no-op if the image does not have an alpha channel.
  *
+ * See also {@link /api-operation#flatten|flatten}.
+ *
  * @example
  * sharp('rgba.png')
  *   .removeAlpha()
@@ -70,13 +72,17 @@ function ensureAlpha (alpha) {
  * Extract a single channel from a multi-channel image.
  *
  * @example
- * sharp(input)
+ * // green.jpg is a greyscale image containing the green channel of the input
+ * await sharp(input)
  *   .extractChannel('green')
- *   .toColourspace('b-w')
- *   .toFile('green.jpg', function(err, info) {
- *     // info.channels === 1
- *     // green.jpg is a greyscale image containing the green channel of the input
- *    });
+ *   .toFile('green.jpg');
+ *
+ * @example
+ * // red1 is the red value of the first pixel, red2 the second pixel etc.
+ * const [red1, red2, ...] = await sharp(input)
+ *   .extractChannel(0)
+ *   .raw()
+ *   .toBuffer();
  *
  * @param {number|string} channel - zero-indexed channel/band number to extract, or `red`, `green`, `blue` or `alpha`.
  * @returns {Sharp}
@@ -92,7 +98,7 @@ function extractChannel (channel) {
   } else {
     throw is.invalidParameterError('channel', 'integer or one of: red, green, blue, alpha', channel);
   }
-  return this;
+  return this.toColourspace('b-w');
 }
 
 /**

package/lib/colour.js

@@ -54,6 +54,45 @@ function grayscale (grayscale) {
   return this.greyscale(grayscale);
 }
 
+/**
+ * Set the pipeline colourspace.
+ *
+ * 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}.
+ *
+ * This feature is experimental and has not yet been fully-tested with all operations.
+ *
+ * @since 0.29.0
+ *
+ * @example
+ * // Run pipeline in 16 bits per channel RGB while converting final result to 8 bits per channel sRGB.
+ * await sharp(input)
+ *  .pipelineColourspace('rgb16')
+ *  .toColourspace('srgb')
+ *  .toFile('16bpc-pipeline-to-8bpc-output.png')
+ *
+ * @param {string} [colourspace] - pipeline colourspace e.g. `rgb16`, `scrgb`, `lab`, `grey16` [...](https://github.com/libvips/libvips/blob/41cff4e9d0838498487a00623462204eb10ee5b8/libvips/iofuncs/enumtypes.c#L774)
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function pipelineColourspace (colourspace) {
+  if (!is.string(colourspace)) {
+    throw is.invalidParameterError('colourspace', 'string', colourspace);
+  }
+  this.options.colourspaceInput = colourspace;
+  return this;
+}
+
+/**
+ * Alternative spelling of `pipelineColourspace`.
+ * @param {string} [colorspace] - pipeline colorspace.
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function pipelineColorspace (colorspace) {
+  return this.pipelineColourspace(colorspace);
+}
+
 /**
  * Set the output colourspace.
  * By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
@@ -64,7 +103,7 @@ function grayscale (grayscale) {
  *  .toColourspace('rgb16')
  *  .toFile('16-bpp.png')
  *
- * @param {string} [colourspace] - output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/libvips/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568)
+ * @param {string} [colourspace] - output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/libvips/libvips/blob/3c0bfdf74ce1dc37a6429bed47fa76f16e2cd70a/libvips/iofuncs/enumtypes.c#L777-L794)
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -119,6 +158,8 @@ module.exports = function (Sharp) {
     tint,
     greyscale,
     grayscale,
+    pipelineColourspace,
+    pipelineColorspace,
     toColourspace,
     toColorspace,
     // Private

package/lib/composite.js

@@ -89,6 +89,8 @@ const blend = {
  * @param {Number} [images[].raw.width]
  * @param {Number} [images[].raw.height]
  * @param {Number} [images[].raw.channels]
+ * @param {boolean} [images[].failOnError=true] - @see {@link /api-constructor#parameters|constructor parameters}
+ * @param {number|boolean} [images[].limitInputPixels=268402689] - @see {@link /api-constructor#parameters|constructor parameters}
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */

package/lib/constructor.js

@@ -5,32 +5,7 @@ const stream = require('stream');
 const is = require('./is');
 
 require('./libvips').hasVendoredLibvips();
-
-/* istanbul ignore next */
-try {
-  require('../build/Release/sharp.node');
-} catch (err) {
-  // Bail early if bindings aren't available
-  const help = ['', 'Something went wrong installing the "sharp" module', '', err.message, ''];
-  if (/NODE_MODULE_VERSION/.test(err.message)) {
-    help.push('- Ensure the version of Node.js used at install time matches that used at runtime');
-  } else if (/invalid ELF header/.test(err.message)) {
-    help.push(`- Ensure "${process.platform}" is used at install time as well as runtime`);
-  } else if (/dylib/.test(err.message) && /Incompatible library version/.test(err.message)) {
-    help.push('- Run "brew update && brew upgrade vips"');
-  } else {
-    help.push(
-      '- Remove the "node_modules/sharp" directory then run',
-      '  "npm install --ignore-scripts=false --verbose sharp" and look for errors'
-    );
-  }
-  help.push(
-    '- Consult the installation documentation at https://sharp.pixelplumbing.com/install',
-    '- Search for this error at https://github.com/lovell/sharp/issues', ''
-  );
-  const error = help.join('\n');
-  throw new Error(error);
-}
+require('./sharp');
 
 // Use NODE_DEBUG=sharp to enable libvips warnings
 const debuglog = util.debuglog('sharp');
@@ -117,8 +92,9 @@ const debuglog = util.debuglog('sharp');
  *  }
  * }).toFile('noise.png');
  *
- * @param {(Buffer|Uint8Array|Uint8ClampedArray|string)} [input] - if present, can be
- *  a Buffer / Uint8Array / Uint8ClampedArray containing JPEG, PNG, WebP, AVIF, GIF, SVG, TIFF or raw pixel image data, or
+ * @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
+ *  a TypedArray containing raw pixel image data, or
  *  a String containing the filesystem path to an JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image file.
  *  JPEG, PNG, WebP, AVIF, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when not present.
  * @param {Object} [options] - if present, is an Object with optional attributes.
@@ -139,6 +115,8 @@ const debuglog = util.debuglog('sharp');
  * @param {number} [options.raw.width] - integral number of pixels wide.
  * @param {number} [options.raw.height] - integral number of pixels high.
  * @param {number} [options.raw.channels] - integral number of channels, between 1 and 4.
+ * @param {boolean} [options.raw.premultiplied] - specifies that the raw input has already been premultiplied, set to `true`
+ *  to avoid sharp premultiplying the image. (optional, default `false`)
  * @param {Object} [options.create] - describes a new image to be created.
  * @param {number} [options.create.width] - integral number of pixels wide.
  * @param {number} [options.create.height] - integral number of pixels high.
@@ -202,6 +180,7 @@ const Sharp = function (input, options) {
     flatten: false,
     flattenBackground: [0, 0, 0],
     negate: false,
+    negateAlpha: true,
     medianSize: 0,
     blurSigma: 0,
     sharpenSigma: 0,
@@ -214,9 +193,13 @@ const Sharp = function (input, options) {
     gammaOut: 0,
     greyscale: false,
     normalise: false,
+    claheWidth: 0,
+    claheHeight: 0,
+    claheMaxSlope: 3,
     brightness: 1,
     saturation: 1,
     hue: 0,
+    lightness: 0,
     booleanBufferIn: null,
     booleanFileIn: '',
     joinChannelIn: [],
@@ -224,6 +207,7 @@ const Sharp = function (input, options) {
     removeAlpha: false,
     ensureAlpha: -1,
     colourspace: 'srgb',
+    colourspaceInput: 'last',
     composite: [],
     // output
     fileOut: '',
@@ -231,6 +215,7 @@ const Sharp = function (input, options) {
     streamOut: false,
     withMetadata: false,
     withMetadataOrientation: -1,
+    withMetadataDensity: 0,
     withMetadataIcc: '',
     withMetadataStrs: {},
     resolveWithObject: false,
@@ -248,8 +233,13 @@ const Sharp = function (input, options) {
     pngAdaptiveFiltering: false,
     pngPalette: false,
     pngQuality: 100,
-    pngColours: 256,
+    pngBitdepth: 8,
     pngDither: 1,
+    jp2Quality: 80,
+    jp2TileHeight: 512,
+    jp2TileWidth: 512,
+    jp2Lossless: false,
+    jp2ChromaSubsampling: '4:4:4',
     webpQuality: 80,
     webpAlphaQuality: 100,
     webpLossless: false,
@@ -270,7 +260,8 @@ const Sharp = function (input, options) {
     heifLossless: false,
     heifCompression: 'av1',
     heifSpeed: 5,
-    heifChromaSubsampling: '4:2:0',
+    heifChromaSubsampling: '4:4:4',
+    rawDepth: 'uchar',
     tileSize: 256,
     tileOverlap: 0,
     tileContainer: 'fs',

package/lib/input.js

@@ -2,7 +2,7 @@
 
 const color = require('color');
 const is = require('./is');
-const sharp = require('../build/Release/sharp.node');
+const sharp = require('./sharp');
 
 /**
  * Extract input options, if any, from an object.
@@ -30,9 +30,14 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
     inputDescriptor.file = input;
   } else if (is.buffer(input)) {
     // Buffer
+    if (input.length === 0) {
+      throw Error('Input Buffer is empty');
+    }
     inputDescriptor.buffer = input;
-  } else if (is.uint8Array(input)) {
-    // Uint8Array or Uint8ClampedArray
+  } else if (is.typedArray(input)) {
+    if (input.length === 0) {
+      throw Error('Input Bit Array is empty');
+    }
     inputDescriptor.buffer = Buffer.from(input.buffer);
   } else if (is.plainObject(input) && !is.defined(inputOptions)) {
     // Plain Object descriptor, e.g. create
@@ -97,6 +102,38 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
         inputDescriptor.rawWidth = inputOptions.raw.width;
         inputDescriptor.rawHeight = inputOptions.raw.height;
         inputDescriptor.rawChannels = inputOptions.raw.channels;
+        inputDescriptor.rawPremultiplied = !!inputOptions.raw.premultiplied;
+
+        switch (input.constructor) {
+          case Uint8Array:
+          case Uint8ClampedArray:
+            inputDescriptor.rawDepth = 'uchar';
+            break;
+          case Int8Array:
+            inputDescriptor.rawDepth = 'char';
+            break;
+          case Uint16Array:
+            inputDescriptor.rawDepth = 'ushort';
+            break;
+          case Int16Array:
+            inputDescriptor.rawDepth = 'short';
+            break;
+          case Uint32Array:
+            inputDescriptor.rawDepth = 'uint';
+            break;
+          case Int32Array:
+            inputDescriptor.rawDepth = 'int';
+            break;
+          case Float32Array:
+            inputDescriptor.rawDepth = 'float';
+            break;
+          case Float64Array:
+            inputDescriptor.rawDepth = 'double';
+            break;
+          default:
+            inputDescriptor.rawDepth = 'uchar';
+            break;
+        }
       } else {
         throw new Error('Expected width, height and channels for raw pixel input');
       }
@@ -264,6 +301,8 @@ function _isStreamInput () {
  * - `pagePrimary`: Number of the primary page in a HEIF image
  * - `levels`: Details of each level in a multi-level image provided as an array of objects, requires libvips compiled with support for OpenSlide
  * - `subifds`: Number of Sub Image File Directories in an OME-TIFF image
+ * - `background`: Default background colour, if present, for PNG (bKGD) and GIF images, either an RGB Object or a single greyscale value
+ * - `compression`: The encoder used to compress an HEIF file, `av1` (AVIF) or `hevc` (HEIC)
  * - `hasProfile`: Boolean indicating the presence of an embedded ICC profile
  * - `hasAlpha`: Boolean indicating the presence of an alpha transparency channel
  * - `orientation`: Number value of the EXIF Orientation header, if present
@@ -349,6 +388,9 @@ function metadata (callback) {
  * - `sharpness`: Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any (experimental)
  * - `dominant`: Object containing most dominant sRGB colour based on a 4096-bin 3D histogram (experimental)
  *
+ * **Note**: Statistics are derived from the original input image. Any operations performed on the image must first be
+ * written to a buffer in order to run `stats` on the result (see third example).
+ *
  * @example
  * const image = sharp(inputJpg);
  * image
@@ -361,6 +403,13 @@ function metadata (callback) {
  * const { entropy, sharpness, dominant } = await sharp(input).stats();
  * const { r, g, b } = dominant;
  *
+ * @example
+ * const image = sharp(input);
+ * // store intermediate result
+ * const part = await image.extract(region).toBuffer();
+ * // create new instance to obtain statistics of extracted region
+ * const stats = await sharp(part).stats();
+ *
  * @param {Function} [callback] - called with the arguments `(err, stats)`
  * @returns {Promise<Object>}
  */

package/lib/is.js

@@ -49,12 +49,26 @@ const buffer = function (val) {
 };
 
 /**
- * Is this value a Uint8Array or Uint8ClampedArray object?
+ * Is this value a typed array object?. E.g. Uint8Array or Uint8ClampedArray?
  * @private
  */
-const uint8Array = function (val) {
-  // allow both since Uint8ClampedArray simply clamps the values between 0-255
-  return val instanceof Uint8Array || val instanceof Uint8ClampedArray;
+const typedArray = function (val) {
+  if (defined(val)) {
+    switch (val.constructor) {
+      case Uint8Array:
+      case Uint8ClampedArray:
+      case Int8Array:
+      case Uint16Array:
+      case Int16Array:
+      case Uint32Array:
+      case Int32Array:
+      case Float32Array:
+      case Float64Array:
+        return true;
+    }
+  }
+
+  return false;
 };
 
 /**
@@ -119,7 +133,7 @@ module.exports = {
   fn: fn,
   bool: bool,
   buffer: buffer,
-  uint8Array: uint8Array,
+  typedArray: typedArray,
   string: string,
   number: number,
   integer: integer,