feat: add Format constants for convert media types, including JXL

CHANGES.md

@@ -1,3 +1,6 @@
+## 1.9.0
+* Added `tinify.Format` constants for the media types `convert` accepts. `SupportedImageTypes` is now derived from them.
+
 ## 1.8.3
 * add JXL to supported image formats
 * add node 26 as test target

README.md

@@ -5,11 +5,11 @@
 
 # Tinify API client for Node.js
 
-A lightweight Node.js client for the Tinify API, used for [tinypng API](https://tinypng.com) and [TinyJPG](https://tinyjpg.com). This library lets you intelligently **compress**, **resize**, **convert**, and **store** images (AVIF, WebP, JPEG, PNG) with minimal effort. Read more at [http://tinify.com](http://tinify.com).
+A lightweight Node.js client for the Tinify API, used for [tinypng API](https://tinypng.com) and [TinyJPG](https://tinyjpg.com). This library lets you intelligently **compress**, **resize**, **convert**, and **store** images (AVIF, JXL, WebP, JPEG, PNG) with minimal effort. Read more at [http://tinify.com](http://tinify.com).
 
 ## 🚀 Features
 
-- Compress and optimize images in AVIF, WebP, JPEG, and PNG formats
+- Compress and optimize images in AVIF, JXL, WebP, JPEG, and PNG formats
 - Resize with intelligent cropping
 - Convert between formats
 - Preserve metadata (copyright, GPS, creation time)
@@ -65,6 +65,17 @@ extension.then(ext => {
   converted.toFile("panda-sticker." + ext);
 })
 
+// Convert format using the Format constants
+// (tinify.Format.WEBP, PNG, JPEG, JPG, AVIF, JXL and ANY)
+tinify.fromFile("panda-sticker.jpg")
+  .convert({type: tinify.Format.JXL})
+  .toFile("panda-sticker.jxl");
+
+// Pass several and the API returns the smallest result
+tinify.fromFile("panda-sticker.jpg")
+  .convert({type: [tinify.Format.JXL, tinify.Format.WEBP]})
+  .toFile("panda-sticker.min");
+
 // Preserve metadata
 tinify.fromFile("original.jpg")
   .preserve("copyright", "location", "creation")

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinify",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "Node.js client for the Tinify API. Tinify compresses your images intelligently. Read more at https://tinify.com.",
   "keywords": [
     "tinify",

src/index.ts

@@ -1,6 +1,7 @@
 import tinify from "./tinify"
 
 import Client from "./tinify/Client"
+import Format from "./tinify/Format"
 import Result from "./tinify/Result"
 import ResultMeta from "./tinify/ResultMeta"
 import Source from "./tinify/Source"
@@ -14,6 +15,7 @@ import {
 } from "./tinify/Error"
 
 tinify.Client = Client
+tinify.Format = Format
 tinify.ResultMeta = ResultMeta
 tinify.Result = Result
 tinify.Source = Source

src/tinify.ts

@@ -1,6 +1,7 @@
 import {nodeify, Callback} from "./tinify/compat"
 
 import Client from "./tinify/Client"
+import Format from "./tinify/Format"
 import Result from "./tinify/Result"
 import ResultMeta from "./tinify/ResultMeta"
 import Source from "./tinify/Source"
@@ -19,6 +20,7 @@ class Tinify {
   compressionCount?: number
 
   Client!: typeof Client
+  Format!: typeof Format
   Source!: typeof Source
   Result!: typeof Result
   ResultMeta!: typeof ResultMeta

src/tinify/Format.ts

@@ -0,0 +1,47 @@
+/**
+ * Media types that images can be converted to.
+ *
+ * ```js
+ * const tinify = require("tinify")
+ *
+ * tinify.fromFile("input.png")
+ *   .convert({type: tinify.Format.JXL})
+ *   .toFile("output.jxl")
+ * ```
+ *
+ * Multiple types may be supplied, in which case the API returns the smallest
+ * result:
+ *
+ * ```js
+ * .convert({type: [tinify.Format.JXL, tinify.Format.WEBP]})
+ * ```
+ */
+const Format = {
+  /** WebP. */
+  WEBP: "image/webp",
+
+  /** PNG. */
+  PNG: "image/png",
+
+  /** JPEG. */
+  JPEG: "image/jpeg",
+
+  /**
+   * JPEG, under the alternative `image/jpg` media type the API also accepts.
+   * The API normalises this to `image/jpeg`, so the result is identical to
+   * `JPEG`. The two constants hold different strings but select the same
+   * format.
+   */
+  JPG: "image/jpg",
+
+  /** AVIF. */
+  AVIF: "image/avif",
+
+  /** JPEG XL. */
+  JXL: "image/jxl",
+
+  /** Wildcard, returns the smallest of the supported types. */
+  ANY: "*/*",
+} as const
+
+export default Format

src/tinify/Source.ts

@@ -2,18 +2,17 @@ import tinify from "../tinify"
 import {readFile, Callback} from "./compat"
 
 import Client from "./Client"
+import Format from "./Format"
 import Result from "./Result"
 import ResultMeta from "./ResultMeta"
 
-export type SupportedImageTypes = "image/webp"
-  | "image/png"
-  | "image/jpg"
-  | "image/jpeg"
-  | "image/jxl"
-  | "image/avif";
+type FormatValues = (typeof Format)[keyof typeof Format];
 
+export type SupportedImageTypes = Exclude<FormatValues, typeof Format.ANY>;
+
+// The wildcard "*/*" returns the smallest of Tinify's supported image types.
 export type WildcardOrSupportedImageTypes = SupportedImageTypes
-  | "*/*"; // The wildcard "*/*" returns the smallest of Tinify's supported image types, currently JPEG, PNG and WebP.
+  | typeof Format.ANY;
 
 export type ConvertOptions = {
   type: WildcardOrSupportedImageTypes | SupportedImageTypes[];

test/tinify-typing-test.ts

@@ -15,8 +15,24 @@ async function run() {
     await tinify.fromFile("/foo/bar").convert({ type: "image/webp" })
     await tinify.fromFile("/foo/bar").convert({ type: "image/png" })
     await tinify.fromFile("/foo/bar").convert({ type: "image/jpg" })
+    await tinify.fromFile("/foo/bar").convert({ type: "image/jxl" })
+    await tinify.fromFile("/foo/bar").convert({ type: "image/avif" })
     await tinify.fromFile("/foo/bar").convert({ type: "*/*" })
 
+    // The Format constants are accepted everywhere a literal is.
+    await tinify.fromFile("/foo/bar").convert({ type: tinify.Format.JXL })
+    await tinify.fromFile("/foo/bar").convert({ type: tinify.Format.ANY })
+    await tinify.fromFile("/foo/bar").convert({
+      type: [tinify.Format.JXL, tinify.Format.WEBP],
+    })
+
+    // SupportedImageTypes is derived from Format; these assert the derived
+    // union is no wider than the literal list it replaced.
+    // @ts-expect-error an unknown media type is not assignable
+    await tinify.fromFile("/foo/bar").convert({ type: "image/bogus" })
+    // @ts-expect-error the "*/*" wildcard is not valid inside the array form
+    await tinify.fromFile("/foo/bar").convert({ type: ["*/*"] })
+
     await tinify.fromBuffer("foo")
       .resize({method: "fit", width: 150, height: 100})
       .preserve("copyright", "creation")