refactor: update transformation interface and supported transforms for improved clarity and consistency

Author: manu4543

src/constants/supportedTransforms.ts

@@ -1,7 +1,10 @@
 /**
  * @link https://imagekit.io/docs/transformations
  */
-const supportedTransforms: { [key: string]: string } = {
+export const supportedTransforms: { [key: string]: string } = {
+  // Basic sizing & layout
+  width: "w",
+  height: "h",
   aspectRatio: "ar",
   background: "bg",
   border: "b",
@@ -14,14 +17,11 @@ const supportedTransforms: { [key: string]: string } = {
   xCenter: "xc",
   y: "y",
   yCenter: "yc",
-  height: "h",
-  width: "w",
   format: "f",
   videoCodec: "vc",
   audioCodec: "ac",
   radius: "r",
   rotation: "rt",
-  rotate: "rt",
   blur: "bl",
   named: "n",
   defaultImage: "di",
@@ -31,25 +31,31 @@ const supportedTransforms: { [key: string]: string } = {
   endOffset: "eo",
   duration: "du",
   streamingResolutions: "sr",
-  eGrayscale: "e-grayscale",
-  eRemoveDotBg: "e-removedotbg",
-  eUpscale: "e-upscale",
-  eRetouch: "e-retouch",
-  eGenvar: "e-genvar",
-  eDropshadow: "e-dropshadow",
-  eChangeBg: "e-changebg",
-  eBgRemove: "e-bgremove",
-  eContrast: "e-contrast",
-  eShadow: "e-shadow",
-  eSharpen: "e-sharpen",
-  eUSM: "e-usm",
-  eGradient: "e-gradient",
-  effectContrast: "e-contrast",
-  effectShadow: "e-shadow",
+
+  // Old deprecated mappings
   effectSharpen: "e-sharpen",
   effectUSM: "e-usm",
-  effectGradient: "e-gradient",
+  effectContrast: "e-contrast",
   effectGray: "e-grayscale",
+  effectShadow: "e-shadow",
+  effectGradient: "e-gradient",
+
+  // AI & advanced effects
+  grayscale: "e-grayscale",
+  aiBGRemoveExternal: "e-removedotbg",
+  aiUpscale: "e-upscale",
+  aiRetouch: "e-retouch",
+  aiVariation: "e-genvar",
+  aiDropShadow: "e-dropshadow",
+  aiChangeBackground: "e-changebg",
+  aiRemoveBackground: "e-bgremove",
+  contrastStretch: "e-contrast",
+  shadow: "e-shadow",
+  sharpen: "e-sharpen",
+  unsharpMask: "e-usm",
+  gradient: "e-gradient",
+
+  // Other flags & finishing
   progressive: "pr",
   lossless: "lo",
   colorProfile: "cp",
@@ -58,8 +64,13 @@ const supportedTransforms: { [key: string]: string } = {
   trim: "t",
   zoom: "z",
   page: "pg",
+
+  
+
+  // Raw pass-through
   raw: "raw",
-}
+};
+
 
 
 export default supportedTransforms

src/interfaces/Transformation.ts

@@ -173,45 +173,45 @@ export interface Transformation {
     /**
      * Enable grayscale effect for images.
      */
-    grayScale?: true;
+    grayscale?: true;
 
     /**
      * Use third-party background removal. 
      * See also `removeBackground` for ImageKit's in-house background removal which is 90% cheaper.
      */
-    removeBackgroundThirdParty?: true
+    aiBGRemoveExternal?: true
 
     /**
      * Upscale images beyond their original dimensions with AI.
      */
-    upscale?: true
+    aiUpscale?: true
 
     /**
      * Retouch (AI-based) for improving faces or product shots.
      */
-    retouch?: true
+    aiRetouch?: true
 
     /**
      * Generate variation of an image using AI. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image.
      */
-    generateVariation?: true
+    aiVariation?: true
 
     /**
      * Add an AI-based drop shadow around a foreground object on a transparent or removed background.
      * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`.
      * @link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow
      */
-    AIDropshadow?: string
+    aiDropShadow?: string
 
     /**
      * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`.
      */
-    changeBackground?: string;
+    aiChangeBackground?: string;
 
     /**
      * ImageKit’s in-house background removal.
      */
-    removeBackground?: true
+    aiRemoveBackground?: true
 
     /**
      * Auto-enhance contrast for an image (contrast stretch).
@@ -243,7 +243,7 @@ export interface Transformation {
     /**
      * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image.  This helps you maintain a fast perceived load time.
      */
-    progressiveJPEG?: boolean;
+    progressive?: boolean;
 
     /**
      * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly.
@@ -291,5 +291,42 @@ export interface Transformation {
      * Pass any transformation that is not directly supported by the SDK. This transformation is passed as it is in the URL.
      */
     raw?: string;
+
+    // old as it is but deprecated
+
+    /**
+     * @deprecated Use `rotation` instead.
+     */
+    rotate?: string;
+
+    /**
+     * @deprecated Use `sharpen` instead.
+     */
+    effectSharpen?: string;
+
+    /**
+     * @deprecated Use `unsharpMask` instead.
+     */
+    effectUSM?: string;
+
+    /**
+     * @deprecated Use `contrastStretch` instead.
+     */
+    effectContrast?: string;
+
+    /**
+     * @deprecated Use `grayscale` instead.
+     */
+    effectGray?: string;
+
+    /**
+     * @deprecated Use `shadow` instead.
+     */
+    effectShadow?: string;
+
+    /**
+     * @deprecated Use `gradient` instead.
+     */
+    effectGradient?: string;
 }
 

src/url/builder.ts

@@ -82,19 +82,24 @@ function constructTransformationString(transformation: Transformation[] | undefi
   for (var i = 0, l = transformation.length; i < l; i++) {
     var parsedTransformStep = [];
     for (var key in transformation[i]) {
-      if(transformation[i][key as keyof Transformation] === undefined || transformation[i][key as keyof Transformation] === null )
-      continue;
+      let value = transformation[i][key as keyof Transformation];
+      if (value === undefined || value === null) {
+        continue;
+      }
+
       var transformKey = transformationUtils.getTransformKey(key);
       if (!transformKey) {
         transformKey = key;
       }
 
-      if (transformation[i][key as keyof Transformation] === "-") {
+      if (value === "-") value = true;
+
+      if (["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) && value === true) {
         parsedTransformStep.push(transformKey);
       } else if (key === "raw") {
         parsedTransformStep.push(transformation[i][key]);
       } else {
-        var value = transformation[i][key as keyof Transformation];
+        value = transformation[i][key as keyof Transformation];
         if (transformKey === "di") {
           value = removeTrailingSlash(removeLeadingSlash(value as string || ""));
           value = value.replace(/\//g, "@@");

test/url-generation.js

@@ -317,7 +317,7 @@ describe("URL generation", function () {
             }]
         })
 
-        expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast-true,e-grayscale-true,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`);
+        expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`);
     });
 });