test cases and logic for overlay handling

Author: manu4543

src/constants/supportedTransforms.ts

@@ -66,6 +66,20 @@ export const supportedTransforms: { [key: string]: string } = {
   zoom: "z",
   page: "pg",
 
+  // Text overlay transformations which are not defined yet
+  fontSize: "fs",
+  fontFamily: "ff",
+  fontColor: "co",
+  innerAlignment: "ia",
+  padding: "pa",
+  alpha: "al",
+  typography: "tg",
+  lineHeight: "lh",
+
+  // Subtitles transformations which are not defined
+  fontOutline: "fol",
+  fontShadow: "fsh",
+
   // Raw pass-through
   raw: "raw",
 };

src/interfaces/Transformation.ts

@@ -526,7 +526,7 @@ export interface TextOverlay extends BaseOverlay {
     /**
      * Control styling of the text overlay.
      */
-    transformations?: TextOverlayTransformation[];
+    transformation?: TextOverlayTransformation[];
 }
 
 export interface ImageOverlay extends BaseOverlay {
@@ -538,11 +538,11 @@ export interface ImageOverlay extends BaseOverlay {
     input: string;
 
     /**
-     * List of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset.
+     * Array of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset.
      * 
      * {@link https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay|Video}
      */
-    transformations?: Transformation[];
+    transformation?: Transformation[];
 }
 
 export interface VideoOverlay extends BaseOverlay {
@@ -553,11 +553,11 @@ export interface VideoOverlay extends BaseOverlay {
     input: string;
 
     /**
-     * List of transformations to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported.
+     * Array of transformation to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported.
      * 
      * {@link https://imagekit.io/docs/video-transformation|Video Transformations}
      */
-    transformations?: Transformation[];
+    transformation?: Transformation[];
 }
 
 export interface SubtitleOverlay extends BaseOverlay {
@@ -572,7 +572,7 @@ export interface SubtitleOverlay extends BaseOverlay {
      * 
      * {@link https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer|Styling subtitles}
      */
-    transformations?: SubtitleOverlayTransformation[];
+    transformation?: SubtitleOverlayTransformation[];
 }
 
 export interface SolidColorOverlay extends BaseOverlay {
@@ -588,7 +588,7 @@ export interface SolidColorOverlay extends BaseOverlay {
      * 
      * {@link https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay|Video}
      */
-    transformations?: SolidColorOverlayTransformation[];
+    transformation?: SolidColorOverlayTransformation[];
 }
 
 export type TextOverlayTransformation = {

src/url/builder.ts

@@ -1,6 +1,7 @@
 import { ImageKitOptions, UrlOptions } from "../interfaces";
 import { Transformation } from "../interfaces/Transformation";
 import transformationUtils from "../utils/transformation";
+import { safeBtoa } from "../utils/transformation";
 const TRANSFORMATION_PARAMETER = "tr";
 
 function removeTrailingSlash(str: string) {
@@ -73,20 +74,106 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => {
   return urlObj.href;
 };
 
+
+function processOverlay(overlay: Transformation["overlay"]): string | undefined {
+  const entries = [];
+  if (!overlay) {
+    return;
+  }
+  const { type, position = {}, timing = {}, transformation = [] } = overlay;
+
+  if (!type) {
+    throw new Error("Overlay type is required");
+  }
+
+  switch (type) {
+    case "text":
+      entries.push("l-text");
+      if (overlay.text) {
+        entries.push(`ie-${encodeURIComponent(safeBtoa(overlay.text))}`);
+      }
+      break;
+    case "image":
+      entries.push("l-image");
+      if (overlay.input) {
+        entries.push(`i-${overlay.input}`);
+      }
+      break;
+    case "video":
+      entries.push("l-video");
+      if (overlay.input) {
+        entries.push(`i-${overlay.input}`);
+      }
+      break;
+    case "subtitle":
+      entries.push("l-subtitle");
+      if (overlay.input) {
+        entries.push(`i-${overlay.input}`);
+      }
+      break;
+    case "solidColor":
+      entries.push("l-image");
+      entries.push(`i-ik_canvas`);
+      if (overlay.color) {
+        entries.push(`bg-${overlay.color}`);
+      }
+      break;
+  }
+
+  const { x, y, focus } = position;
+  if (x) {
+    entries.push(`lxo-${x}`);
+  }
+  if (y) {
+    entries.push(`lyo-${y}`);
+  }
+  if (focus) {
+    entries.push(`lfo-${focus}`);
+  }
+
+  const { start, end, duration } = timing;
+
+  if (start) {
+    entries.push(`lso-${start}`);
+  }
+  if (end) {
+    entries.push(`leo-${end}`);
+  }
+  if (duration) {
+    entries.push(`ldu-${duration}`);
+  }
+
+  const transformationString = constructTransformationString(transformation);
+
+  if (transformationString && transformationString.trim() !== "") entries.push(transformationString);
+
+  entries.push("l-end");
+
+  return entries.join(transformationUtils.getTransformDelimiter());
+}
+
 function constructTransformationString(transformation: Transformation[] | undefined) {
   if (!Array.isArray(transformation)) {
     return "";
   }
 
-  var parsedTransforms = [];
+  var parsedTransforms: string[] = [];
   for (var i = 0, l = transformation.length; i < l; i++) {
-    var parsedTransformStep = [];
+    var parsedTransformStep: string[] = [];
     for (var key in transformation[i]) {
       let value = transformation[i][key as keyof Transformation];
       if (value === undefined || value === null) {
         continue;
       }
 
+      if (key === "overlay" && typeof value === "object") {
+        var rawString = processOverlay(value as Transformation["overlay"]);
+        if (rawString) {
+          parsedTransformStep.push(rawString);
+          continue;
+        }
+      }
+
       var transformKey = transformationUtils.getTransformKey(key);
       if (!transformKey) {
         transformKey = key;
@@ -111,7 +198,7 @@ function constructTransformationString(transformation: Transformation[] | undefi
       ) {
         parsedTransformStep.push(transformKey);
       } else if (key === "raw") {
-        parsedTransformStep.push(transformation[i][key]);
+        parsedTransformStep.push(transformation[i][key] as string);
       } else {
         if (transformKey === "di") {
           value = removeTrailingSlash(removeLeadingSlash(value as string || ""));

src/utils/transformation.ts

@@ -1,12 +1,12 @@
 import supportedTransforms from "../constants/supportedTransforms";
 import { ImageKitOptions, TransformationPosition } from "../interfaces";
 
-const DEFAULT_TRANSFORMATION_POSITION : TransformationPosition = "path";
-const QUERY_TRANSFORMATION_POSITION : TransformationPosition = "query";
+const DEFAULT_TRANSFORMATION_POSITION: TransformationPosition = "path";
+const QUERY_TRANSFORMATION_POSITION: TransformationPosition = "query";
 const VALID_TRANSFORMATION_POSITIONS = [DEFAULT_TRANSFORMATION_POSITION, QUERY_TRANSFORMATION_POSITION];
-const CHAIN_TRANSFORM_DELIMITER : string = ":";
-const TRANSFORM_DELIMITER : string = ",";
-const TRANSFORM_KEY_VALUE_DELIMITER : string = "-";
+const CHAIN_TRANSFORM_DELIMITER: string = ":";
+const TRANSFORM_DELIMITER: string = ",";
+const TRANSFORM_KEY_VALUE_DELIMITER: string = "-";
 
 export default {
     getDefault: (): TransformationPosition => {
@@ -15,8 +15,8 @@ export default {
     addAsQueryParameter: (options: ImageKitOptions) => {
         return options.transformationPosition === QUERY_TRANSFORMATION_POSITION;
     },
-    validParameters: (options: ImageKitOptions) =>  {
-		if(typeof options.transformationPosition == "undefined") return false;
+    validParameters: (options: ImageKitOptions) => {
+        if (typeof options.transformationPosition == "undefined") return false;
         return VALID_TRANSFORMATION_POSITIONS.indexOf(options.transformationPosition) != -1;
     },
     getTransformKey: function (transform: string) {
@@ -33,4 +33,13 @@ export default {
     getTransformKeyValueDelimiter: function () {
         return TRANSFORM_KEY_VALUE_DELIMITER;
     }
+}
+
+export const safeBtoa = function (str: string): string {
+    if (typeof btoa !== "undefined") {
+        return btoa(str);
+    } else {
+        // Node fallback
+        return Buffer.from(str, "utf8").toString("base64");
+    }
 }