Add support for crop_aspect_ratio option (#53)

Author: 11bit

src/options/cropAspectRatio.ts

@@ -0,0 +1,34 @@
+import type {
+  CropAspectRatio,
+  CropAspectRatioOptionsPartial,
+} from "../types/cropAspectRatio";
+import { guardIsUndef, guardIsNotNum, normalizeBoolean } from "../utils";
+
+const getOpt = (
+  options: CropAspectRatioOptionsPartial
+): CropAspectRatio | undefined =>
+  options.crop_aspect_ratio || options.crop_ar || options.car;
+
+const test = (options: CropAspectRatioOptionsPartial): boolean =>
+  Boolean(getOpt(options));
+
+const build = (options: CropAspectRatioOptionsPartial): string => {
+  const cropArOpts = getOpt(options);
+
+  guardIsUndef(cropArOpts, "crop_aspect_ratio");
+  const { aspect_ratio, enlarge } = cropArOpts;
+  guardIsUndef(aspect_ratio, "crop_aspect_ratio.aspect_ratio");
+  guardIsNotNum(aspect_ratio, "crop_aspect_ratio.aspect_ratio", {
+    addParam: { min: 0 },
+  });
+
+  let result = `crop_ar:${aspect_ratio}`;
+
+  if (enlarge !== undefined) {
+    result += `:${normalizeBoolean(enlarge)}`;
+  }
+
+  return result;
+};
+
+export { test, build };

src/options/index.ts

@@ -10,6 +10,7 @@ export * as cacheBuster from "../optionsShared/cacheBuster";
 export * as colorize from "./colorize";
 export * as contrast from "./contrast";
 export * as crop from "../optionsShared/crop";
+export * as cropAspectRatio from "./cropAspectRatio";
 export * as disableAnimation from "./disableAnimation";
 export * as duotone from "./duotone";
 export * as dpi from "./dpi";

src/types/cropAspectRatio.ts

@@ -0,0 +1,36 @@
+/**
+ * *Crop aspect ratio option*. **PRO feature**
+ *
+ * **Description to the generateUrl method**
+ *
+ * Defines the aspect ratio to match the crop area. This is a Pro feature.
+ *
+ * @param {number} `aspect_ratio` defines the desired aspect ratio for the crop area:
+ * - When set to `0`, no aspect ratio correction is applied.
+ * - Any positive number defines the aspect ratio (width/height).
+ *
+ * @param `enlarge` {1 | "t" | true} - (optional) controls crop area sizing:
+ * - When set to `true`, `1`, or `"t"`, imgproxy will enlarge the crop area if needed.
+ * - If the enlarged crop area exceeds the image size, imgproxy will reduce the area to fit while maintaining the requested aspect ratio.
+ *
+ * @see {@link https://docs.imgproxy.net/latest/usage/processing#crop-aspect-ratio | crop aspect ratio imgproxy docs}
+ */
+interface CropAspectRatio {
+  aspect_ratio: number;
+  enlarge?: boolean | 1 | 0 | "t" | "f";
+}
+
+/**
+ * *Crop aspect ratio option*
+ *
+ * To describe the crop aspect ratio option, you can use the keyword `crop_aspect_ratio`, `crop_ar`, or `car`.
+ *
+ * @see https://docs.imgproxy.net/latest/usage/processing#crop-aspect-ratio
+ */
+interface CropAspectRatioOptionsPartial {
+  crop_aspect_ratio?: CropAspectRatio;
+  crop_ar?: CropAspectRatio;
+  car?: CropAspectRatio;
+}
+
+export { CropAspectRatio, CropAspectRatioOptionsPartial };

src/types/index.ts

@@ -10,6 +10,7 @@ import type { CacheBusterOptionsPartial } from "../typesShared/cacheBuster";
 import type { ColorizeOptionsPartial } from "./colorize";
 import type { ContrastOptionsPartial } from "./contrast";
 import type { CropOptionsPartial } from "../typesShared/crop";
+import type { CropAspectRatioOptionsPartial } from "./cropAspectRatio";
 import type { DisableAnimationOptionsPartial } from "./disableAnimation";
 import type { DuotoneOptionsPartial } from "./duotone";
 import type { DPIOptionsPartial } from "./dpi";
@@ -86,6 +87,7 @@ export type Options = AdjustOptionsPartial &
   ColorizeOptionsPartial &
   ContrastOptionsPartial &
   CropOptionsPartial &
+  CropAspectRatioOptionsPartial &
   DisableAnimationOptionsPartial &
   DuotoneOptionsPartial &
   DPIOptionsPartial &

src/utils.ts

@@ -1,4 +1,4 @@
-export const normalizeBoolean = (value: 1 | string | boolean): string => {
+export const normalizeBoolean = (value: 1 | 0 | string | boolean): string => {
   if (value === true || value === "t" || value === 1) {
     return "t";
   }

tests/optionsBasic/cropAspectRatio.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { test, build } from "../../src/options/cropAspectRatio";
+
+describe("cropAspectRatio", () => {
+  describe("test", () => {
+    it("should return true if crop_aspect_ratio option is defined", () => {
+      expect(test({ crop_aspect_ratio: { aspect_ratio: 1.5 } })).toEqual(true);
+    });
+
+    it("should return true if crop_ar option is defined", () => {
+      expect(test({ crop_ar: { aspect_ratio: 1.1 } })).toEqual(true);
+    });
+
+    it("should return true if car option is defined", () => {
+      expect(test({ car: { aspect_ratio: 1.1 } })).toEqual(true);
+    });
+
+    it("should return false if crop_aspect_ratio option is undefined", () => {
+      expect(test({})).toEqual(false);
+    });
+  });
+
+  describe("build", () => {
+    it("should throw an error if crop_aspect_ratio option is undefined", () => {
+      expect(() => build({})).toThrow("crop_aspect_ratio option is undefined");
+    });
+
+    it("should throw an error if aspect_ratio option is undefined", () => {
+      // @ts-expect-error: Let's ignore an error (check for users with vanilla js).
+      expect(() => build({ crop_aspect_ratio: {} })).toThrow(
+        "crop_aspect_ratio.aspect_ratio is undefined"
+      );
+    });
+
+    it("should throw an error if aspect_ratio is not a number", () => {
+      expect(() =>
+        // @ts-expect-error: Let's ignore an error (check for users with vanilla js).
+        build({ crop_aspect_ratio: { aspect_ratio: "1.5" } })
+      ).toThrow("crop_aspect_ratio.aspect_ratio is not a number");
+    });
+
+    it("should throw an error if aspect_ratio is less than 0", () => {
+      expect(() =>
+        build({ crop_aspect_ratio: { aspect_ratio: -1 } })
+      ).toThrowError(
+        "crop_aspect_ratio.aspect_ratio value can't be less then 0"
+      );
+    });
+
+    it("should return crop_ar:1.5 if crop_aspect_ratio aspect_ratio is 1.5", () => {
+      expect(build({ crop_aspect_ratio: { aspect_ratio: 1.5 } })).toEqual(
+        "crop_ar:1.5"
+      );
+    });
+
+    it("should return crop_ar:1.1 if crop_ar aspect_ratio is 1.1", () => {
+      expect(build({ crop_ar: { aspect_ratio: 1.1 } })).toEqual("crop_ar:1.1");
+    });
+
+    it("should return crop_ar:0 if aspect_ratio is 0", () => {
+      expect(build({ crop_aspect_ratio: { aspect_ratio: 0 } })).toEqual(
+        "crop_ar:0"
+      );
+    });
+
+    it("should return crop_ar:1.5:t if crop_aspect_ratio aspect_ratio is 1.5 and enlarge is true", () => {
+      expect(
+        build({ crop_aspect_ratio: { aspect_ratio: 1.5, enlarge: true } })
+      ).toEqual("crop_ar:1.5:t");
+    });
+
+    it("should return crop_ar:1.1:t if crop_ar aspect_ratio is 1.1 and enlarge is 1", () => {
+      expect(build({ crop_ar: { aspect_ratio: 1.1, enlarge: 1 } })).toEqual(
+        "crop_ar:1.1:t"
+      );
+    });
+
+    it("should return crop_ar:2:t if aspect_ratio is 2.0 and enlarge is 't'", () => {
+      expect(
+        build({ crop_aspect_ratio: { aspect_ratio: 2.0, enlarge: "t" } })
+      ).toEqual("crop_ar:2:t");
+    });
+
+    it("should return crop_ar:1.5:f if aspect_ratio is 1.5 and enlarge is false", () => {
+      expect(
+        build({ crop_aspect_ratio: { aspect_ratio: 1.5, enlarge: false } })
+      ).toEqual("crop_ar:1.5:f");
+    });
+
+    it("should return crop_ar:1.1:f if aspect_ratio is 1.1 and enlarge is 'f'", () => {
+      expect(build({ crop_ar: { aspect_ratio: 1.1, enlarge: "f" } })).toEqual(
+        "crop_ar:1.1:f"
+      );
+    });
+  });
+});