Calc hashsums (#48)

* Add calc_hashsums option

* Changesets

Author: 11bit

.changeset/fluffy-news-wear.md

@@ -0,0 +1,5 @@
+---
+"@imgproxy/imgproxy-js-core": minor
+---
+
+Add [Calc hashsums](https://docs.imgproxy.net/usage/getting_info#calc-hashsums) info option

src/optionsImageInfo/calcHashsums.ts

@@ -0,0 +1,33 @@
+import type {
+  HashsumType,
+  CalcHashsumsImageInfoOptionsPartial,
+} from "../typesImageInfo/calcHashsums";
+import { guardIsUndef } from "../utils";
+
+const getOpt = (
+  options: CalcHashsumsImageInfoOptionsPartial
+): HashsumType[] | undefined => {
+  if ("calcHashsums" in options) {
+    return options.calcHashsums;
+  } else if ("chs" in options) {
+    return options.chs;
+  }
+
+  return undefined;
+};
+
+const test = (options: CalcHashsumsImageInfoOptionsPartial): boolean =>
+  getOpt(options) !== undefined;
+
+const build = (options: CalcHashsumsImageInfoOptionsPartial): string => {
+  const hashsumTypes = getOpt(options);
+  guardIsUndef(hashsumTypes, "calcHashsums");
+
+  if (!hashsumTypes.length) {
+    return "chs:";
+  }
+
+  return `chs:${hashsumTypes.join(":")}`;
+};
+
+export { test, build };

src/optionsImageInfo/index.ts

@@ -1,6 +1,7 @@
 export * as average from "./average";
 export * as blurhash from "./blurhash";
 export * as cacheBuster from "../optionsShared/cacheBuster";
+export * as calcHashsums from "./calcHashsums";
 export * as crop from "../optionsShared/crop";
 export * as detectObjects from "./detectObjects";
 export * as dimensions from "./dimensions";

src/typesImageInfo/calcHashsums.ts

@@ -0,0 +1,36 @@
+/**
+ * *CalcHashsums option*
+ *
+ * @warning **Slow**. This option requires the image to be fully downloaded and processed.
+ *
+ * When specified, imgproxy will calculate the specified hashsums of the source image.
+ *
+ * Available hashsum types: md5, sha1, sha256, sha512
+ *
+ * Response example:
+ * {
+ * "hashsums": {
+ *   "md5": "cc507f81206a4c7d0a995a07c3d9f43a",
+ *   "sha256": "621f6c6d68de754c6cdf3d286b7837634ce9f273f30f377b3e0df0568a23cee0"
+ * }
+ * }
+ *
+ * @note Hashsum calculation for video files is not supported.
+ *
+ * @see {@link https://docs.imgproxy.net/usage/getting_info#calc-hashsums | CalcHashsums imgproxy docs}
+ */
+type HashsumType = "md5" | "sha1" | "sha256" | "sha512";
+
+/**
+ * *CalcHashsums option*
+ *
+ * To specify hashsum types to calculate, you can use the keyword `calcHashsums` or `chs`.
+ *
+ * @see https://docs.imgproxy.net/usage/getting_info#calc-hashsums
+ */
+interface CalcHashsumsImageInfoOptionsPartial {
+  calcHashsums?: HashsumType[];
+  chs?: HashsumType[];
+}
+
+export { HashsumType, CalcHashsumsImageInfoOptionsPartial };

src/typesImageInfo/index.ts

@@ -1,6 +1,7 @@
 import type { AverageImageInfoOptionsPartial } from "./average";
 import type { BHImageInfoOptionsPartial } from "./blurhash";
 import type { CacheBusterOptionsPartial } from "../typesShared/cacheBuster";
+import type { CalcHashsumsImageInfoOptionsPartial } from "./calcHashsums";
 import type { CropOptionsPartial } from "../typesShared/crop";
 import type { DCImageInfoOptionsPartial } from "./dominantColors";
 import type { DetectObjectsImageInfoOptionsPartial } from "./detectObjects";
@@ -23,6 +24,7 @@ import type { WildOptionsPartial } from "../typesShared/wildOptions";
 export type OptionsImageInfo = AverageImageInfoOptionsPartial &
   BHImageInfoOptionsPartial &
   CacheBusterOptionsPartial &
+  CalcHashsumsImageInfoOptionsPartial &
   CropOptionsPartial &
   DCImageInfoOptionsPartial &
   DetectObjectsImageInfoOptionsPartial &

tests/optionsImageInfo/calcHashsums.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { test, build } from "../../src/optionsImageInfo/calcHashsums";
+
+describe("calcHashsums", () => {
+  describe("test", () => {
+    it("should return true if calcHashsums option is defined", () => {
+      expect(test({ calcHashsums: ["md5", "sha256"] })).toEqual(true);
+    });
+
+    it("should return true if chs option is defined", () => {
+      expect(test({ chs: ["sha1"] })).toEqual(true);
+    });
+
+    it("should return true if calcHashsums is an empty array", () => {
+      expect(test({ calcHashsums: [] })).toEqual(true);
+    });
+
+    it("should return false if calcHashsums option is undefined", () => {
+      expect(test({})).toEqual(false);
+    });
+  });
+
+  describe("build", () => {
+    it("should throw an error if calcHashsums option is undefined", () => {
+      expect(() => build({})).toThrow("calcHashsums option is undefined");
+    });
+
+    it("should return 'chs:' if calcHashsums is an empty array", () => {
+      expect(build({ calcHashsums: [] })).toEqual("chs:");
+    });
+
+    it("should return 'chs:md5' for a single hashsum type", () => {
+      expect(build({ calcHashsums: ["md5"] })).toEqual("chs:md5");
+    });
+
+    it("should return 'chs:md5:sha256' for multiple hashsum types", () => {
+      expect(build({ calcHashsums: ["md5", "sha256"] })).toEqual(
+        "chs:md5:sha256"
+      );
+    });
+
+    it("should work with the chs alias", () => {
+      expect(build({ chs: ["sha1", "sha512"] })).toEqual("chs:sha1:sha512");
+    });
+  });
+});