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

package/lib/index.d.ts

@@ -27,7 +27,8 @@
 
 /// <reference types="node" />
 
-import type { Duplex } from 'node:stream';
+declare type Duplex = import('node:stream').Duplex;
+declare type ColorLike = import('@img/colour').ColorLike;
 
 //#region Constructor functions
 
@@ -234,7 +235,7 @@ declare namespace sharp {
          * @param tint Parsed by the color module.
          * @returns A sharp instance that can be used to chain operations
          */
-        tint(tint: Colour | Color): Sharp;
+        tint(tint: ColorLike): Sharp;
 
         /**
          * Convert to 8-bit greyscale; 256 shades of grey.
@@ -259,7 +260,6 @@ declare namespace sharp {
          * 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 toColourspace.
-         * This feature is experimental and has not yet been fully-tested with all operations.
          *
          * @param colourspace pipeline colourspace e.g. rgb16, scrgb, lab, grey16 ...
          * @throws {Error} Invalid parameters
@@ -470,21 +470,6 @@ declare namespace sharp {
          */
         sharpen(options?: SharpenOptions): Sharp;
 
-        /**
-         * Sharpen the image.
-         * When used without parameters, performs a fast, mild sharpen of the output image.
-         * When a sigma is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
-         * Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.
-         * @param sigma the sigma of the Gaussian mask, where sigma = 1 + radius / 2.
-         * @param flat the level of sharpening to apply to "flat" areas. (optional, default 1.0)
-         * @param jagged the level of sharpening to apply to "jagged" areas. (optional, default 2.0)
-         * @throws {Error} Invalid parameters
-         * @returns A sharp instance that can be used to chain operations
-         *
-         * @deprecated Use the object parameter `sharpen({sigma, m1, m2, x1, y2, y3})` instead
-         */
-        sharpen(sigma?: number, flat?: number, jagged?: number): Sharp;
-
         /**
          * Apply median filter. When used without parameters the default window is 3x3.
          * @param size square mask size: size x size (optional, default 3)
@@ -673,25 +658,42 @@ declare namespace sharp {
          * @param callback Callback function called on completion with three arguments (err, buffer, info).
          * @returns A sharp instance that can be used to chain operations
          */
-        toBuffer(callback: (err: Error, buffer: Buffer, info: OutputInfo) => void): Sharp;
+        toBuffer(callback: (err: Error, buffer: Buffer<ArrayBuffer>, info: OutputInfo) => void): Sharp;
 
         /**
          * Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported.
          * By default, the format will match the input image, except SVG input which becomes PNG output.
+         * The underlying `ArrayBuffer` may be marked as non-transferable by some JavaScript runtimes.
          * @param options resolve options
          * @param options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
          * @returns A promise that resolves with the Buffer data.
          */
-        toBuffer(options?: { resolveWithObject: false }): Promise<Buffer>;
+        toBuffer(options?: { resolveWithObject: false }): Promise<Buffer<ArrayBuffer>>;
 
         /**
          * Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported.
          * By default, the format will match the input image, except SVG input which becomes PNG output.
+         * The underlying `ArrayBuffer` may be marked as non-transferable by some JavaScript runtimes.
          * @param options resolve options
          * @param options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
          * @returns A promise that resolves with an object containing the Buffer data and an info object containing the output image format, size (bytes), width, height and channels
          */
-        toBuffer(options: { resolveWithObject: true }): Promise<{ data: Buffer; info: OutputInfo }>;
+        toBuffer(options: { resolveWithObject: true }): Promise<{ data: Buffer<ArrayBuffer>; info: OutputInfo }>;
+
+        /**
+         * Write output to a Uint8Array backed by a transferable ArrayBuffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported.
+         * By default, the format will match the input image, except SVG input which becomes PNG output.
+         * @returns A promise that resolves with an object containing the Uint8Array data and an info object containing the output image format, size (bytes), width, height and channels
+         */
+        toUint8Array(): Promise<{ data: Uint8Array; info: OutputInfo }>;
+
+        /**
+         * Set output density (DPI) in EXIF metadata.
+         * @param density Density in dots per inch (DPI).
+         * @returns A sharp instance that can be used to chain operations
+         * @throws {Error} Invalid parameters
+         */
+        withDensity(density: number): Sharp;
 
         /**
          * Keep all EXIF metadata from the input image in the output image.
@@ -849,7 +851,7 @@ declare namespace sharp {
          * @returns A sharp instance that can be used to chain operations
          */
         toFormat(
-            format: keyof FormatEnum | AvailableFormatInfo,
+            format: keyof FormatEnum | AvailableFormatInfo | "avif",
             options?:
                 | OutputOptions
                 | JpegOptions
@@ -903,7 +905,7 @@ declare namespace sharp {
          *  - sharp.gravity: north, northeast, east, southeast, south, southwest, west, northwest, center or centre.
          *  - sharp.strategy: cover only, dynamically crop using either the entropy or attention strategy. Some of these values are based on the object-position CSS property.
          *
-         * The experimental strategy-based approach resizes so one dimension is at its target length then repeatedly ranks edge regions,
+         * The strategy-based approach resizes so one dimension is at its target length then repeatedly ranks edge regions,
          * discarding the edge with the lowest score based on the selected strategy.
          *  - entropy: focus on the region with the highest Shannon entropy.
          *  - attention: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
@@ -989,28 +991,27 @@ declare namespace sharp {
         autoOrient?: boolean | undefined;
         /**
          *  When to abort processing of invalid pixel data, one of (in order of sensitivity):
-         *  'none' (least), 'truncated', 'error' or 'warning' (most), highers level imply lower levels, invalid metadata will always abort. (optional, default 'warning')
+         *  'none' (least), 'truncated', 'error' or 'warning' (most), highers level imply lower levels, invalid metadata will always abort.
+         *  Use the default 'warning' level with untrusted input. (optional, default 'warning')
          */
         failOn?: FailOnOptions | undefined;
-        /**
-         * By default halt processing and raise an error when loading invalid images.
-         * Set this flag to false if you'd rather apply a "best effort" to decode images,
-         * even if the data is corrupt or invalid. (optional, default true)
-         *
-         * @deprecated Use `failOn` instead
-         */
-        failOnError?: boolean | undefined;
         /**
          * Do not process input images where the number of pixels (width x height) exceeds this limit.
          * Assumes image dimensions contained in the input metadata can be trusted.
          * An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF). (optional, default 268402689)
          */
         limitInputPixels?: number | boolean | undefined;
+        /**
+         * Do not process input images where the number of channels exceeds this limit.
+         * Assumes image metadata can be trusted.
+         * An integral Number of channels, zero or false to remove limit, true to use default limit of 5. (optional, default 5)
+         */
+        limitInputChannels?: number | boolean | undefined;
         /** Set this to true to remove safety features that help prevent memory exhaustion (SVG, PNG). (optional, default false) */
         unlimited?: boolean | undefined;
         /** Set this to false to use random access rather than sequential read. Some operations will do this automatically. */
         sequentialRead?: boolean | undefined;
-        /** Number representing the DPI for vector images in the range 1 to 100000. (optional, default 72) */
+        /** The DPI at which to render SVG and PDF images, in the range 1 to 100000. (optional, default 72) */
         density?: number | undefined;
         /** Should the embedded ICC profile, if any, be ignored. */
         ignoreIcc?: boolean | undefined;
@@ -1028,11 +1029,11 @@ declare namespace sharp {
         openSlide?: OpenSlideInputOptions | undefined;
         /** JPEG 2000 specific input options */
         jp2?: Jp2InputOptions | undefined;
-        /** Deprecated: use tiff.subifd instead */
+        /** @deprecated Use {@link SharpOptions.tiff} instead */
         subifd?: number | undefined;
-        /** Deprecated: use pdf.background instead */
-        pdfBackground?: Colour | Color | undefined;
-        /** Deprecated: use openSlide.level instead */
+        /** @deprecated Use {@link SharpOptions.pdf} instead */
+        pdfBackground?: ColorLike | undefined;
+        /** @deprecated Use {@link SharpOptions.openSlide} instead */
         level?: number | undefined;
         /** Set to `true` to read all frames/pages of an animated image (equivalent of setting `pages` to `-1`). (optional, default false) */
         animated?: boolean | undefined;
@@ -1090,7 +1091,7 @@ declare namespace sharp {
         /** Number of bands, 3 for RGB, 4 for RGBA */
         channels: CreateChannels;
         /** Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. */
-        background: Colour | Color;
+        background: ColorLike;
         /** Describes a noise to be created. */
         noise?: Noise | undefined;
         /** The height of each page/frame for animated images, must be an integral factor of the overall image height. */
@@ -1137,7 +1138,7 @@ declare namespace sharp {
         /** Space between images, in pixels. */
         shim?: number | undefined;
         /** Background colour. */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
         /** Horizontal alignment. */
         halign?: HorizontalAlignment | undefined;
         /** Vertical alignment. */
@@ -1158,7 +1159,7 @@ declare namespace sharp {
 
     interface PdfInputOptions {
         /** Background colour to use when PDF is partially transparent. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick. */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
     }
 
     interface OpenSlideInputOptions {
@@ -1184,8 +1185,27 @@ declare namespace sharp {
 
     type HeifCompression = 'av1' | 'hevc';
 
+    type HeifTune = 'auto' | 'iq' | 'psnr' | 'ssim';
+
     type Unit = 'inch' | 'cm';
 
+    type MediaType =
+        'application/pdf' |
+        'image/avif' |
+        'image/fits' |
+        'image/gif' |
+        'image/heic' |
+        'image/jp2' |
+        'image/jpeg' |
+        'image/jxl' |
+        'image/png' |
+        'image/svg+xml' |
+        'image/tiff' |
+        'image/vnd.radiance' |
+        'image/webp' |
+        'image/x-exr' |
+        'image/x-portable-pixmap';
+
     interface WriteableMetadata {
         /** Number of pixels per inch (DPI) */
         density?: number | undefined;
@@ -1277,6 +1297,10 @@ declare namespace sharp {
         formatMagick?: string | undefined;
         /** Array of keyword/text pairs representing PNG text blocks, if present. */
         comments?: CommentsMetadata[] | undefined;
+        /** HDR gain map, if present */
+        gainMap?: GainMapMetadata | undefined;
+        /** Media Type (MIME Type) */
+        mediaType?: MediaType | undefined;
     }
 
     interface LevelMetadata {
@@ -1289,16 +1313,21 @@ declare namespace sharp {
         text: string;
     }
 
+    interface GainMapMetadata {
+        /** JPEG image */
+        image: Buffer;
+    }
+
     interface Stats {
         /** Array of channel statistics for each channel in the image. */
         channels: ChannelStats[];
         /** Value to identify if the image is opaque or transparent, based on the presence and use of alpha channel */
         isOpaque: boolean;
-        /** Histogram-based estimation of greyscale entropy, discarding alpha channel if any (experimental) */
+        /** Histogram-based estimation of greyscale entropy, discarding alpha channel if any */
         entropy: number;
-        /** Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any (experimental) */
+        /** Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any */
         sharpness: number;
-        /** Object containing most dominant sRGB colour based on a 4096-bin 3D histogram (experimental) */
+        /** Object containing most dominant sRGB colour based on a 4096-bin 3D histogram */
         dominant: { r: number; g: number; b: number };
     }
 
@@ -1404,11 +1433,13 @@ declare namespace sharp {
         /** Level of CPU effort to reduce file size, integer 0-6 (optional, default 4) */
         effort?: number | undefined;
         /** Prevent use of animation key frames to minimise file size (slow) (optional, default false) */
-        minSize?: boolean;
+        minSize?: boolean | undefined;
         /** Allow mixture of lossy and lossless animation frames (slow) (optional, default false) */
-        mixed?: boolean;
+        mixed?: boolean | undefined;
         /** Preset options: one of default, photo, picture, drawing, icon, text (optional, default 'default') */
         preset?: keyof PresetEnum | undefined;
+        /** Preserve the colour data in transparent pixels (optional, default false) */
+        exact?: boolean | undefined;
     }
 
     interface AvifOptions extends OutputOptions {
@@ -1422,6 +1453,8 @@ declare namespace sharp {
         chromaSubsampling?: string | undefined;
         /** Set bitdepth to 8, 10 or 12 bit (optional, default 8) */
         bitdepth?: 8 | 10 | 12 | undefined;
+        /** Tune output for a quality metric, one of 'auto', 'iq', 'psnr' or 'ssim' (optional, default 'auto') */
+        tune?: HeifTune | undefined;
     }
 
     interface HeifOptions extends OutputOptions {
@@ -1437,6 +1470,8 @@ declare namespace sharp {
         chromaSubsampling?: string | undefined;
         /** Set bitdepth to 8, 10 or 12 bit (optional, default 8) */
         bitdepth?: 8 | 10 | 12 | undefined;
+        /** Tune output for a quality metric, one of 'auto', 'iq', 'psnr' or 'ssim' (optional, default 'auto') */
+        tune?: HeifTune | undefined;
     }
 
     interface GifOptions extends OutputOptions, AnimationOptions {
@@ -1475,14 +1510,14 @@ declare namespace sharp {
         tile?: boolean | undefined;
         /** Horizontal tile size (optional, default 256) */
         tileWidth?: number | undefined;
-        /** Vertical tile size (optional, default 256) */
+        /** Vertical tile size, valid values are integers in the range 1-32768 (optional, default 256) */
         tileHeight?: number | undefined;
-        /** Horizontal resolution in pixels/mm (optional, default 1.0) */
+        /** Horizontal resolution in pixels/mm, valid values are numbers in the range 0.001-1000000 (optional, default 1.0) */
         xres?: number | undefined;
-        /** Vertical resolution in pixels/mm (optional, default 1.0) */
+        /** Vertical resolution in pixels/mm, valid values are numbers in the range 0.001-1000000 (optional, default 1.0) */
         yres?: number | undefined;
-        /** Reduce bitdepth to 1, 2 or 4 bit (optional, default 8) */
-        bitdepth?: 1 | 2 | 4 | 8 | undefined;
+        /** Reduce bitdepth to 1, 2 or 4 bit (optional) */
+        bitdepth?: 1 | 2 | 4 | undefined;
         /** Write 1-bit images as miniswhite (optional, default false) */
         miniswhite?: boolean | undefined;
         /** Resolution unit options: inch, cm (optional, default 'inch') */
@@ -1512,7 +1547,7 @@ declare namespace sharp {
 
     interface RotateOptions {
         /** parsed by the color module to extract values for red, green, blue and alpha. (optional, default "#000000") */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
     }
 
     type Precision = 'integer' | 'float' | 'approximate';
@@ -1528,7 +1563,7 @@ declare namespace sharp {
 
     interface FlattenOptions {
         /** background colour, parsed by the color module, defaults to black. (optional, default {r:0,g:0,b:0}) */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
     }
 
     interface NegateOptions {
@@ -1553,7 +1588,7 @@ declare namespace sharp {
         /** Position, gravity or strategy to use when fit is cover or contain. (optional, default 'centre') */
         position?: number | string | undefined;
         /** Background colour when using a fit of contain, parsed by the color module, defaults to black without transparency. (optional, default {r:0,g:0,b:0,alpha:1}) */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
         /** The kernel to use for image reduction. (optional, default 'lanczos3') */
         kernel?: keyof KernelEnum | undefined;
         /** Do not enlarge if the width or height are already less than the specified dimensions, equivalent to GraphicsMagick's > geometry option. (optional, default false) */
@@ -1565,13 +1600,13 @@ declare namespace sharp {
     }
 
     interface Region {
-        /** zero-indexed offset from left edge */
+        /** zero-indexed offset from left edge, an integer between 0 and 100000000 */
         left: number;
-        /** zero-indexed offset from top edge */
+        /** zero-indexed offset from top edge, an integer between 0 and 100000000 */
         top: number;
-        /** dimension of extracted image */
+        /** dimension of extracted image, an integer between 0 and 100000000 */
         width: number;
-        /** dimension of extracted image */
+        /** dimension of extracted image, an integer between 0 and 100000000 */
         height: number;
     }
 
@@ -1587,27 +1622,29 @@ declare namespace sharp {
     type ExtendWith = 'background' | 'copy' | 'repeat' | 'mirror';
 
     interface ExtendOptions {
-        /** single pixel count to top edge (optional, default 0) */
+        /** single pixel count to top edge, valid values are integers in the range 0-10000 (optional, default 0) */
         top?: number | undefined;
-        /** single pixel count to left edge (optional, default 0) */
+        /** single pixel count to left edge, valid values are integers in the range 0-10000 (optional, default 0) */
         left?: number | undefined;
-        /** single pixel count to bottom edge (optional, default 0) */
+        /** single pixel count to bottom edge, valid values are integers in the range 0-10000 (optional, default 0) */
         bottom?: number | undefined;
-        /** single pixel count to right edge (optional, default 0) */
+        /** single pixel count to right edge, valid values are integers in the range 0-10000 (optional, default 0) */
         right?: number | undefined;
         /** background colour, parsed by the color module, defaults to black without transparency. (optional, default {r:0,g:0,b:0,alpha:1}) */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
         /** how the extension is done, one of: "background", "copy", "repeat", "mirror" (optional, default `'background'`) */
         extendWith?: ExtendWith | undefined;
     }
 
     interface TrimOptions {
         /** Background colour, parsed by the color module, defaults to that of the top-left pixel. (optional) */
-        background?: Colour | Color | undefined;
+        background?: ColorLike | undefined;
         /** Allowed difference from the above colour, a positive number. (optional, default 10) */
         threshold?: number | undefined;
         /** Does the input more closely resemble line art (e.g. vector) rather than being photographic? (optional, default false) */
         lineArt?: boolean | undefined;
+        /** Leave a margin around trimmed content, integral number of pixels between 0 and 10000000. (optional, default 0) */
+        margin?: number | undefined;
     }
 
     interface RawOptions {
@@ -1617,15 +1654,8 @@ declare namespace sharp {
     /** 1 for grayscale, 2 for grayscale + alpha, 3 for sRGB, 4 for CMYK or RGBA */
     type Channels = 1 | 2 | 3 | 4;
 
-    interface RGBA {
-        r?: number | undefined;
-        g?: number | undefined;
-        b?: number | undefined;
-        alpha?: number | undefined;
-    }
-
-    type Colour = string | RGBA;
-    type Color = Colour;
+    type Colour = ColorLike;
+    type Color = ColorLike;
 
     interface Kernel {
         /** width of the kernel in pixels. */
@@ -1641,11 +1671,11 @@ declare namespace sharp {
     }
 
     interface ClaheOptions {
-        /** width of the region */
+        /** width of the region. Valid values are integers in the range 1-65536. */
         width: number;
-        /** height of the region */
+        /** height of the region. Valid values are integers in the range 1-65536. */
         height: number;
-        /** max slope of the cumulative contrast. A value of 0 disables contrast limiting. Valid values are integers in the range 0-100 (inclusive) (optional, default 3) */
+        /** max slope of the cumulative contrast. A value of 0 disables contrast limiting. Valid values are integers in the range 0-100. (optional, default 3) */
         maxSlope?: number | undefined;
     }
 
@@ -1663,9 +1693,9 @@ declare namespace sharp {
         blend?: Blend | undefined;
         /** gravity at which to place the overlay. (optional, default 'centre') */
         gravity?: Gravity | undefined;
-        /** the pixel offset from the top edge. */
+        /** the pixel offset from the top edge, an integer between -100000000 and 100000000. */
         top?: number | undefined;
-        /** the pixel offset from the left edge. */
+        /** the pixel offset from the left edge, an integer between -100000000 and 100000000. */
         left?: number | undefined;
         /** set to true to repeat the overlay image across the entire image with the given  gravity. (optional, default false) */
         tile?: boolean | undefined;
@@ -1691,7 +1721,7 @@ declare namespace sharp {
         /** Tile angle of rotation, must be a multiple of 90. (optional, default 0) */
         angle?: number | undefined;
         /** background colour, parsed by the color module, defaults to white without transparency. (optional, default {r:255,g:255,b:255,alpha:1}) */
-        background?: string | RGBA | undefined;
+        background?: ColorLike | undefined;
         /** How deep to make the pyramid, possible values are "onepixel", "onetile" or "one" (default based on layout) */
         depth?: string | undefined;
         /** Threshold to skip tile generation, a value 0 - 255 for 8-bit images or 0 - 65535 for 16-bit images */
@@ -1755,6 +1785,8 @@ declare namespace sharp {
         channels: Channels;
         /** indicating if premultiplication was used */
         premultiplied: boolean;
+        /** Indicates if the output image has an alpha channel */
+        hasAlpha: boolean;
         /** Only defined when using a crop strategy */
         cropOffsetLeft?: number | undefined;
         /** Only defined when using a crop strategy */
@@ -1913,16 +1945,13 @@ declare namespace sharp {
     }
 
     interface FormatEnum {
-        avif: AvailableFormatInfo;
         dcraw: AvailableFormatInfo;
         dz: AvailableFormatInfo;
         exr: AvailableFormatInfo;
         fits: AvailableFormatInfo;
         gif: AvailableFormatInfo;
         heif: AvailableFormatInfo;
-        input: AvailableFormatInfo;
         jpeg: AvailableFormatInfo;
-        jpg: AvailableFormatInfo;
         jp2: AvailableFormatInfo;
         jxl: AvailableFormatInfo;
         magick: AvailableFormatInfo;
@@ -1934,8 +1963,7 @@ declare namespace sharp {
         raw: AvailableFormatInfo;
         svg: AvailableFormatInfo;
         tiff: AvailableFormatInfo;
-        tif: AvailableFormatInfo;
-        v: AvailableFormatInfo;
+        vips: AvailableFormatInfo;
         webp: AvailableFormatInfo;
     }