Add support for numeric direction option (#45)

* Add support for numeric direction (angle) for  option

* Add changesets

Author: 11bit

.changeset/many-horses-vanish.md

@@ -0,0 +1,5 @@
+---
+"@imgproxy/imgproxy-js-core": minor
+---
+
+Add support for numeric direction value in [gradient](https://docs.imgproxy.net/usage/processing#gradient) option

src/options/gradient.ts

@@ -32,8 +32,12 @@ const build = (options: GradientOptionsPartial): string => {
 
   if (color) guardIsNotStr(color, "gradient.color", true);
   if (direction) {
-    guardIsNotStr(direction, "gradient.direction");
-    guardIsValidVal(currentDirection, direction, "gradient.direction");
+    if (typeof direction === "number") {
+      guardIsNotNum(direction, "gradient.direction");
+    } else {
+      guardIsNotStr(direction, "gradient.direction");
+      guardIsValidVal(currentDirection, direction, "gradient.direction");
+    }
   }
   if (start)
     guardIsNotNum(start, "gradient.start", { addParam: { min: 0, max: 1 } });

src/types/gradient.ts

@@ -5,13 +5,14 @@
  *
  * @param {number} opacity - specifies gradient opacity. When set to 0, gradient is not applied. Value range: `0` - `1`.
  * @param {string} [color="000"] - (optional) specifies gradient color. If omitted, the gradient is black. Default `"000"`.
- * @param {"down" | "up" | "right" | "left"} [direction="down"] - (optional) specifies gradient direction. Default `"down"`.
+ * @param {"down" | "up" | "right" | "left" | number} [direction="down"] - (optional) specifies gradient direction. Default `"down"`.
  *
  * Available values:
  * - `down` - the top side of the gradient is transparrent, the bottom side is opaque
  * - `up` - the bottom side of the gradient is transparrent, the top side is opaque
  * - `right` -  the left side of the gradient is transparrent, the right side is opaque
  * - `left` - the right side of the gradient is transparrent, the left side is opaque
+ * - `number` - angle in degrees (clockwise). `0` creates a gradient from top to bottom; `90` creates a gradient from right to left.
  * @param {number} [start=0.0] - (optional) specifies the start point of the gradient. Value range: `0.0` - `1.0`. Default `0.0`.
  * @param {number} [stop=1.0] - (optional) specifies the end point of the gradient. Value range: `0.0` - `1.0`. Default `1.0`.
  *
@@ -25,12 +26,15 @@
  * // Apply a gray gradient with 0.3 opacity from the left to the right of the image with the start point at 0.2 and the end point at 0.8
  * {gradient: {opacity: 0.3, direction: "right", color: "808080", start: 0.2, stop: 0.8}}
  *
+ * // Apply a gray gradient with 0.3 opacity at a 45 degree angle
+ * {gradient: {opacity: 0.3, direction: 45, color: "808080"}}
+ *
  * @see https://docs.imgproxy.net/generating_the_url?id=gradient
  */
 interface Gradient {
   opacity: number;
   color?: string;
-  direction?: "down" | "up" | "right" | "left";
+  direction?: "down" | "up" | "right" | "left" | number;
   start?: number;
   stop?: number;
 }

tests/optionsBasic/gradient.test.ts

@@ -68,14 +68,14 @@ describe("gradient", () => {
       );
     });
 
-    it("should throw an error if direction is not a string", () => {
+    it("should throw an error if direction is not a string or number", () => {
       expect(() =>
         // @ts-expect-error: Let's ignore an error (check for users with vanilla js).
-        build({ gradient: { opacity: 0.5, direction: 250 } })
+        build({ gradient: { opacity: 0.5, direction: true } })
       ).toThrow("gradient.direction is not a string");
     });
 
-    it("should throw an error if direction is not one of: down, up, right, left", () => {
+    it("should throw an error if direction is a string not among: down, up, right, left", () => {
       expect(() =>
         // @ts-expect-error: Let's ignore an error (check for users with vanilla js).
         build({ gradient: { opacity: 0.5, direction: "top" } })
@@ -84,6 +84,17 @@ describe("gradient", () => {
       );
     });
 
+    it("should accept numeric angle for direction", () => {
+      expect(
+        build({
+          gradient: {
+            opacity: 0.5,
+            direction: 45,
+          },
+        })
+      ).toEqual("gr:0.5::45");
+    });
+
     it("should throw an error if start is not a number", () => {
       expect(() =>
         // @ts-expect-error: Let's ignore an error (check for users with vanilla js).