Add colorize option (#44)

* Add  option

* Add changests

Author: 11bit

.changeset/fruity-beds-train.md

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

src/options/colorize.ts

@@ -0,0 +1,42 @@
+import type { Colorize, ColorizeOptionsPartial } from "../types/colorize";
+import { guardIsNotNum, guardIsUndef } from "../utils";
+
+const getOpt = (options: ColorizeOptionsPartial): Colorize | undefined =>
+  options.colorize ?? options.col;
+
+const test = (options: ColorizeOptionsPartial): boolean => {
+  return Boolean(getOpt(options));
+};
+
+const build = (options: ColorizeOptionsPartial): string => {
+  const colorizeOpt = getOpt(options);
+
+  guardIsUndef(colorizeOpt, "colorize");
+
+  const { opacity, color, keepAlpha } = colorizeOpt;
+
+  guardIsNotNum(opacity, "colorize.opacity", {
+    addParam: {
+      min: 0,
+      max: 1,
+    },
+  });
+
+  let result = `col:${opacity}`;
+
+  if (color) {
+    result += `:${color}`;
+  }
+
+  if (keepAlpha !== undefined) {
+    // Add color parameter if it wasn't provided but keepAlpha is set
+    if (!color) {
+      result += ":";
+    }
+    result += `:${keepAlpha ? 1 : 0}`;
+  }
+
+  return result;
+};
+
+export { test, build };

src/options/index.ts

@@ -7,6 +7,7 @@ export * as blur from "./blur";
 export * as blurDetections from "./blurDetections";
 export * as brightness from "./brightness";
 export * as cacheBuster from "../optionsShared/cacheBuster";
+export * as colorize from "./colorize";
 export * as contrast from "./contrast";
 export * as crop from "../optionsShared/crop";
 export * as disableAnimation from "./disableAnimation";

src/types/colorize.ts

@@ -0,0 +1,20 @@
+/**
+ * *Colorize option*. **PRO feature**
+ *
+ * Places a color overlay on the processed image.
+ * @see
+ * - `colorize` https://docs.imgproxy.net/generating_the_url?id=colorize
+ */
+export interface Colorize {
+  /** Opacity of the color overlay (0-1). When set to 0, overlay is not applied */
+  opacity: number;
+  /** Optional hex-coded color value (default is black: 000) */
+  color?: string;
+  /** Optional flag to preserve the original image's alpha channel (default is false) */
+  keepAlpha?: boolean;
+}
+
+export interface ColorizeOptionsPartial {
+  colorize?: Colorize;
+  col?: Colorize;
+}

src/types/index.ts

@@ -7,6 +7,7 @@ import type { BlurDetectionsOptionsPartial } from "./blurDetections";
 import type { BlurOptionsPartial } from "./blur";
 import type { BrightnessOptionsPartial } from "./brightness";
 import type { CacheBusterOptionsPartial } from "../typesShared/cacheBuster";
+import type { ColorizeOptionsPartial } from "./colorize";
 import type { ContrastOptionsPartial } from "./contrast";
 import type { CropOptionsPartial } from "../typesShared/crop";
 import type { DisableAnimationOptionsPartial } from "./disableAnimation";
@@ -81,6 +82,7 @@ export type Options = AdjustOptionsPartial &
   BlurOptionsPartial &
   BrightnessOptionsPartial &
   CacheBusterOptionsPartial &
+  ColorizeOptionsPartial &
   ContrastOptionsPartial &
   CropOptionsPartial &
   DisableAnimationOptionsPartial &

tests/optionsBasic/colorize.test.ts

@@ -0,0 +1,73 @@
+import { it, expect, describe, assertType } from "vitest";
+import { test, build } from "../../src/options/colorize";
+import { Options } from "../../src/types";
+
+describe("colorize", () => {
+  describe("test", () => {
+    it("should test true if colorize is set", () => {
+      expect(test({ colorize: { opacity: 0.5 } })).toBe(true);
+    });
+
+    it("should test true if col is set", () => {
+      expect(test({ col: { opacity: 0.5 } })).toBe(true);
+    });
+
+    it("should test false if colorize is not set", () => {
+      expect(test({})).toBe(false);
+    });
+  });
+
+  describe("build", () => {
+    it("should work with opacity only", () => {
+      expect(build({ colorize: { opacity: 0 } })).toBe("col:0");
+      expect(build({ colorize: { opacity: 1 } })).toBe("col:1");
+      expect(build({ colorize: { opacity: 0.4 } })).toBe("col:0.4");
+    });
+
+    it("should work with opacity and color", () => {
+      expect(build({ colorize: { opacity: 0.5, color: "ff0000" } })).toBe(
+        "col:0.5:ff0000"
+      );
+    });
+
+    it("should work with opacity, color, and keepAlpha", () => {
+      expect(
+        build({ colorize: { opacity: 0.5, color: "ff0000", keepAlpha: true } })
+      ).toBe("col:0.5:ff0000:1");
+      expect(
+        build({ colorize: { opacity: 0.5, color: "ff0000", keepAlpha: false } })
+      ).toBe("col:0.5:ff0000:0");
+    });
+
+    it("should work with opacity and keepAlpha without color", () => {
+      expect(build({ colorize: { opacity: 0.5, keepAlpha: true } })).toBe(
+        "col:0.5::1"
+      );
+      expect(build({ colorize: { opacity: 0.5, keepAlpha: false } })).toBe(
+        "col:0.5::0"
+      );
+    });
+
+    it("should validate opacity", () => {
+      expect(() => build({ colorize: { opacity: -1 } })).toThrow();
+      expect(() => build({ colorize: { opacity: 2 } })).toThrow();
+    });
+  });
+
+  describe("Check types", () => {
+    it("check TS type declaration", () => {
+      assertType<Options>({
+        colorize: {
+          opacity: 0.5,
+          color: "ff0000",
+          keepAlpha: true,
+        },
+        col: {
+          opacity: 0.5,
+          color: "ff0000",
+          keepAlpha: false,
+        },
+      });
+    });
+  });
+});