Pro: Add pages_number option to generateImageInfoUrl() (#63)

* feat: add `pages_number` option to `generateImageInfoUrl()`

* chore: lint

* chore: changeset

* Fix readme

* Update changesets

---------

Co-authored-by: Gamalta <[email protected]>
Co-authored-by: Ivan Buryak <[email protected]>

Author: 3 people

.changeset/sad-dryers-flow.md

@@ -0,0 +1,5 @@
+---
+"@imgproxy/imgproxy-js-core": minor
+---
+
+Add `page_number` option to generateImageInfoUrl(). Thanks @Elio-Swello 

package-lock.json

@@ -76,14 +76,15 @@ describe("generateImageInfoUrl", () => {
           detect_objects: true,
           dominant_colors: { dominant_colors: 1, build_missed: 1 },
           iptc: "t",
+          pages_number: "t",
           palette: 6,
           expires: 1729409825,
           size: 1,
           preset: ["test", "test2"],
         }
       )
     ).toEqual(
-      "/avg:t:f/do:t/dc:t:t/exp:1729409825/iptc:t/p:6/pr:test:test2/s:t/plain/https://example.com/host/pic.png"
+      "/avg:t:f/do:t/dc:t:t/exp:1729409825/iptc:t/pn:t/p:6/pr:test:test2/s:t/plain/https://example.com/host/pic.png"
     );
   });
 

src/methods/generateImageInfoUrl.test.ts

@@ -13,6 +13,7 @@ export * as iptc from "./iptc";
 export * as maxSrcFileSize from "../optionsShared/maxSrcFileSize";
 export * as maxSrcResolution from "../optionsShared/maxSrcResolution";
 export * as page from "../optionsShared/page";
+export * as pagesNumber from "../optionsImageInfo/pagesNumber";
 export * as palette from "./palette";
 export * as preset from "../optionsShared/preset";
 export * as size from "./size";

src/optionsImageInfo/index.ts

@@ -0,0 +1,28 @@
+import type {
+  NeedPagesNumber,
+  PagesNumberInfoOptionsPartial,
+} from "../typesImageInfo/pagesNumber";
+import { guardIsUndef, normalizeBoolean } from "../utils";
+
+const getOpt = (
+  options: PagesNumberInfoOptionsPartial
+): NeedPagesNumber | undefined => {
+  if ("pages_number" in options) {
+    return options.pages_number;
+  } else if ("pn" in options) {
+    return options.pn;
+  }
+
+  return undefined;
+};
+
+const test = (options: PagesNumberInfoOptionsPartial): boolean =>
+  getOpt(options) !== undefined;
+
+const build = (options: PagesNumberInfoOptionsPartial): string => {
+  const pagesNumberOpts = getOpt(options);
+  guardIsUndef(pagesNumberOpts, "pages_number");
+  return `pn:${normalizeBoolean(pagesNumberOpts)}`;
+};
+
+export { test, build };

src/optionsImageInfo/pagesNumber.ts

@@ -13,6 +13,7 @@ import type { IptcImageInfoOptionsPartial } from "./iptc";
 import type { MaxSrcFileSizeOptionsPartial } from "../typesShared/maxSrcFileSize";
 import type { MaxSrcResolutionOptionsPartial } from "../typesShared/maxSrcResolution";
 import type { PageOptionsPartial } from "../typesShared/page";
+import type { PagesNumberInfoOptionsPartial } from "./pagesNumber";
 import type { PaletteImageInfoOptionsPartial } from "./palette";
 import type { PresetOptionsPartial } from "../typesShared/preset";
 import type { SizeImageInfoOptionsPartial } from "./size";
@@ -36,6 +37,7 @@ export type OptionsImageInfo = AverageImageInfoOptionsPartial &
   MaxSrcFileSizeOptionsPartial &
   MaxSrcResolutionOptionsPartial &
   PageOptionsPartial &
+  PagesNumberInfoOptionsPartial &
   PaletteImageInfoOptionsPartial &
   PresetOptionsPartial &
   SizeImageInfoOptionsPartial &

src/typesImageInfo/index.ts

@@ -0,0 +1,34 @@
+/**
+ * *Pages number option*
+ *
+ * When set to `1`, `"t"` or `true`, imgproxy will return the number of pages the image contains.
+ * For animated images, it'll return the number of animation frames.
+ *
+ *
+ * @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
+ *
+ * Response example:
+ * {
+ *   "pages_number": 10
+ * }
+ *
+ * @default false
+ *
+ *
+ * @see {@link https://docs.imgproxy.net/usage/getting_info?#pages-number | Pages number imgproxy docs}
+ */
+type NeedPagesNumber = 1 | "t" | true | false | string;
+
+/**
+ * *Pages number option*
+ *
+ * To describe the Pages number option, you can use the keyword `pages_number` or `pn`.
+ *
+ * @see https://docs.imgproxy.net/usage/getting_info?#pages-number
+ */
+interface PagesNumberInfoOptionsPartial {
+  pages_number?: NeedPagesNumber;
+  pn?: NeedPagesNumber;
+}
+
+export { NeedPagesNumber, PagesNumberInfoOptionsPartial };

src/typesImageInfo/pagesNumber.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { test, build } from "../../src/optionsImageInfo/pagesNumber";
+
+describe("pages_number", () => {
+  describe("test", () => {
+    it("should return true if pages_number option is defined", () => {
+      expect(test({ pages_number: 1 })).toEqual(true);
+    });
+
+    it("should return true if pages_number option is false", () => {
+      expect(test({ pn: false })).toEqual(true);
+    });
+
+    it("should return false if pages_number option is undefined", () => {
+      expect(test({})).toEqual(false);
+    });
+
+    it("should return true if pn option is defined", () => {
+      expect(test({ pn: "t" })).toEqual(true);
+    });
+  });
+
+  describe("build", () => {
+    it("should throw an error if pages_number option is undefined", () => {
+      expect(() => build({})).toThrow("pages_number option is undefined");
+    });
+
+    it("should return 't' if pages_number option is 1", () => {
+      expect(build({ pages_number: 1 })).toEqual("pn:t");
+    });
+
+    it("should return 't' if s option is 't'", () => {
+      expect(build({ pn: "t" })).toEqual("pn:t");
+    });
+
+    it("should return 't' if pages_number option is true", () => {
+      expect(build({ pages_number: true })).toEqual("pn:t");
+    });
+
+    it("should return 'f' if pages_number option is false", () => {
+      expect(build({ pages_number: false })).toEqual("pn:f");
+    });
+
+    it("should return 'f' if pages_number option is 0", () => {
+      // @ts-expect-error: Let's ignore an error.
+      expect(build({ pages_number: 0 })).toEqual("pn:f");
+    });
+
+    it("should return 'f' if pages_number option is string (except 't')", () => {
+      expect(build({ pages_number: "true" })).toEqual("pn:f");
+    });
+  });
+});