Add support for SEO-friendly filenames in generated URL (#78)

* Add support for SEO-friendly filenames

* Add changesets

---------

Co-authored-by: Ivan Buryak <ivan.buryak@gmail.com>

Author: YoannMa

.changeset/gentle-hounds-relate.md

@@ -0,0 +1,5 @@
+---
+"@imgproxy/imgproxy-js-core": minor
+---
+
+Add support for SEO-friendly filenames in generated URLs. The `URL` object passed to `generateUrl()` and `generateImageInfoUrl()` now accepts an optional `filename` field, which is appended to `base64` and `encrypted` URLs (see [`IMGPROXY_BASE64_URL_INCLUDES_FILENAME`](https://docs.imgproxy.net/configuration/options#source-image-urls)). Thanks @YoannMa!

README.md

@@ -86,6 +86,7 @@ The `imgproxy-js-core` library exposes a method called `generateUrl`, which take
     - `plain`: A plain URL.
     - `base64`: A base64 encoded URL.
     - `encoded`: An AES-CBC encrypted URL.
+  - `filename` (optional): A SEO-friendly filename that will be appended to `base64` or `encrypted` URLs (requires [`IMGPROXY_BASE64_URL_INCLUDES_FILENAME`](https://docs.imgproxy.net/configuration/options#source-image-urls) to be enabled on the imgproxy server). Not allowed for `plain` URLs.
 - `options` (optional): An object that contains [imgproxy options](https://docs.imgproxy.net/generating_the_url?id=processing-options).
 
 For a detailed description of the available options, please refer to the [imgproxy documentation](https://docs.imgproxy.net/generating_the_url?id=processing-options), as well as the option types files in the `imgproxy-js-core` library.
@@ -106,6 +107,7 @@ The `imgproxy-js-core` library exposes a method called `generateImageInfoUrl`, w
     - `plain`: A plain URL.
     - `base64`: A base64 encoded URL.
     - `encoded`: An AES-CBC encrypted URL.
+  - `filename` (optional): A SEO-friendly filename that will be appended to `base64` or `encrypted` URLs (requires [`IMGPROXY_BASE64_URL_INCLUDES_FILENAME`](https://docs.imgproxy.net/configuration/options#source-image-urls) to be enabled on the imgproxy server). Not allowed for `plain` URLs.
 - `options` (optional): An object that contains [imgproxy options](https://docs.imgproxy.net/getting_the_image_info?id=info-options).
 
 For a detailed description of the available options, please refer to the [imgproxy documentation](https://docs.imgproxy.net/getting_the_image_info?id=info-options), as well as the option types files in the `imgproxy-js-core` library.

src/methods/generateImageInfoUrl.test.ts

@@ -115,4 +115,37 @@ describe("generateImageInfoUrl", () => {
       )
     ).toEqual("/test:test2/plain/https://example.com/host/pic.png");
   });
+
+  it("should return base64 url with SEO friendly filename", () => {
+    expect(
+      generateUrl({
+        value: "aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS9waWMucG5n",
+        filename: "pic.png",
+        type: "base64",
+      })
+    ).toEqual("/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS9waWMucG5n/pic.png");
+  });
+
+  it("should return encrypted url with SEO friendly filename", () => {
+    expect(
+      generateUrl({
+        value:
+          "hLhDnxN9acjq3LDooARQ3t6OU1UwAG1IeXsM2b7qxOyMP4DF+GsbBdnG1K9B0+bz",
+        filename: "pic.png",
+        type: "encrypted",
+      })
+    ).toEqual(
+      "/enc/hLhDnxN9acjq3LDooARQ3t6OU1UwAG1IeXsM2b7qxOyMP4DF+GsbBdnG1K9B0+bz/pic.png"
+    );
+  });
+
+  it("should throw an error if url.filename is set on a plain url", () => {
+    expect(() =>
+      generateUrl({
+        value: "https://example.com/host/pic.png",
+        type: "plain",
+        filename: "pic.png",
+      })
+    ).toThrow("url.filename is only valid for base64 or encrypted url");
+  });
 });

src/methods/generateImageInfoUrl.ts

@@ -12,6 +12,7 @@ const correctUrlTypes = {
 export type URLImageInfo = {
   value: string;
   type: "plain" | "base64" | "encrypted";
+  filename?: string;
 };
 
 const allModules = Object.values(optionModules);
@@ -30,6 +31,10 @@ const generateImageInfoUrl = (
   );
   guardIsValidVal(correctUrlTypes, url.type, "url.type");
 
+  if (url.filename && url.type === "plain") {
+    throw new Error("url.filename is only valid for base64 or encrypted url");
+  }
+
   let optsPart = "";
   if (options) {
     const modules = settings?.onlyPresets ? presetOnlyModule : allModules;
@@ -52,6 +57,10 @@ const generateImageInfoUrl = (
     urlPart = `/enc/${url.value}`;
   }
 
+  if (url.filename) {
+    urlPart += `/${url.filename}`;
+  }
+
   return `${optsPart}${urlPart}`;
 };
 

src/methods/generateUrl.test.ts

@@ -93,4 +93,37 @@ describe("generateUrl", () => {
       )
     ).toEqual("/preset1:preset2/plain/https://example.com/host/pic.png");
   });
+
+  it("should return base64 url with SEO friendly filename", () => {
+    expect(
+      generateUrl({
+        value: "aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS9waWMucG5n",
+        filename: "pic.png",
+        type: "base64",
+      })
+    ).toEqual("/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS9waWMucG5n/pic.png");
+  });
+
+  it("should return encrypted url with SEO friendly filename", () => {
+    expect(
+      generateUrl({
+        value:
+          "hLhDnxN9acjq3LDooARQ3t6OU1UwAG1IeXsM2b7qxOyMP4DF+GsbBdnG1K9B0+bz",
+        filename: "pic.png",
+        type: "encrypted",
+      })
+    ).toEqual(
+      "/enc/hLhDnxN9acjq3LDooARQ3t6OU1UwAG1IeXsM2b7qxOyMP4DF+GsbBdnG1K9B0+bz/pic.png"
+    );
+  });
+
+  it("should throw an error if url.filename is set on a plain url", () => {
+    expect(() =>
+      generateUrl({
+        value: "https://example.com/host/pic.png",
+        type: "plain",
+        filename: "pic.png",
+      })
+    ).toThrow("url.filename is only valid for base64 or encrypted url");
+  });
 });

src/methods/generateUrl.ts

@@ -26,6 +26,10 @@ const generateUrl = (
   );
   guardIsValidVal(correctUrlTypes, url.type, "url.type");
 
+  if (url.filename && url.type === "plain") {
+    throw new Error("url.filename is only valid for base64 or encrypted url");
+  }
+
   let optsPart = "";
   if (options) {
     const modules = settings?.onlyPresets ? presetOnlyModule : allModules;
@@ -48,6 +52,10 @@ const generateUrl = (
     urlPart = `/enc/${url.value}`;
   }
 
+  if (url.filename) {
+    urlPart += `/${url.filename}`;
+  }
+
   return `${optsPart}${urlPart}`;
 };