TypeScript: take advantage of color dependency types

Author: lovell

lib/index.d.ts

@@ -28,6 +28,7 @@
 /// <reference types="node" />
 
 import type { Duplex } from 'node:stream';
+import { ColorLike } from '@img/colour';
 
 //#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.
@@ -1014,7 +1015,7 @@ declare namespace sharp {
         /** @deprecated Use {@link SharpOptions.tiff} instead */
         subifd?: number | undefined;
         /** @deprecated Use {@link SharpOptions.pdf} instead */
-        pdfBackground?: Colour | Color | undefined;
+        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) */
@@ -1073,7 +1074,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. */
@@ -1120,7 +1121,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. */
@@ -1141,7 +1142,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 {
@@ -1510,7 +1511,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';
@@ -1526,7 +1527,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 {
@@ -1551,7 +1552,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) */
@@ -1594,14 +1595,14 @@ declare namespace sharp {
         /** single pixel count to right edge (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) */
@@ -1617,15 +1618,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. */
@@ -1691,7 +1685,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 */

package.json

@@ -140,7 +140,7 @@
     "vips"
   ],
   "dependencies": {
-    "@img/colour": "^1.0.0",
+    "@img/colour": "^1.1.0",
     "detect-libc": "^2.1.2",
     "semver": "^7.7.4"
   },

test/types/sharp.test-d.ts

@@ -1,7 +1,7 @@
 // biome-ignore-all lint/correctness/noUnusedFunctionParameters: types only test file
 // biome-ignore-all lint/correctness/noUnusedVariables: types only test file
 
-import sharp = require('../../');
+import sharp from '../../';
 
 import { createReadStream, createWriteStream } from 'node:fs';
 
@@ -726,7 +726,7 @@ sharp(input).composite([
 
 // Support format-specific input options
 const colour: sharp.Colour = '#fff';
-const color: sharp.Color = '#fff';
+const color: sharp.Color = { l: 1, a: 2, b: 3 };
 sharp({ pdf: { background: colour } });
 sharp({ pdf: { background: color } });
 sharp({ pdfBackground: colour }); // Deprecated