feat(image-loader): integrate query-string for streamlined URL generation

Replaced manual URL parameter handling with `query-string` for improved readability, maintainability, and reduced boilerplate in image loaders. Updated `jest.config.ts` to ensure proper transformation of the `query-string` library, added it as a dependency, and adjusted `pnpm-lock.yaml` accordingly.

Author: thevuong

.changeset/cruel-cups-lead.md

@@ -0,0 +1,13 @@
+---
+"@codefast/image-loader": patch
+"@codefast-ui/checkbox-group": patch
+"@codefast/eslint-config": patch
+"@codefast/hooks": patch
+"@codefast-ui/input": patch
+"@codefast-ui/input-number": patch
+"@codefast-ui/progress-circle": patch
+"@codefast/typescript-config": patch
+"@codefast/ui": patch
+---
+
+feat(image-loader): integrate `query-string` for streamlined URL generation

packages/image-loader/jest.config.ts

@@ -34,8 +34,9 @@ const config: Config = {
   /**
    * Specifies which files should be ignored during transformation
    * Prevents Jest from transforming files in the node_modules directory
+   * Exception: query-string needs to be transformed as it uses ES modules
    */
-  transformIgnorePatterns: ["/node_modules/"],
+  transformIgnorePatterns: ["/node_modules/(?!query-string)"],
 
   verbose: true,
 

packages/image-loader/package.json

@@ -57,6 +57,9 @@
     "test:watch": "jest --watch",
     "type-check": "tsc --noEmit"
   },
+  "dependencies": {
+    "query-string": "^7.1.3"
+  },
   "devDependencies": {
     "@codefast/eslint-config": "workspace:*",
     "@codefast/typescript-config": "workspace:*",

packages/image-loader/src/base-loader.ts

@@ -1,4 +1,5 @@
 import type { ImageLoaderProps } from "next/image";
+import queryString from "query-string";
 
 import type { ImageLoader } from "@/types";
 
@@ -91,20 +92,12 @@ export abstract class BaseImageLoader implements ImageLoader {
   }
 
   /**
-   * Utility method to build query parameters
+   * Utility method to build query parameters using query-string library
    * Helper method for URL construction
    */
   protected buildQueryParams(params: Record<string, number | string | undefined>): string {
-    const searchParams = new URLSearchParams();
-
-    for (const [key, value] of Object.entries(params)) {
-      if (value !== undefined) {
-        searchParams.append(key, String(value));
-      }
-    }
-
-    const queryString = searchParams.toString();
-    return queryString ? `?${queryString}` : "";
+    const queryString_ = queryString.stringify(params);
+    return queryString_ ? `?${queryString_}` : "";
   }
 
   /**

packages/image-loader/src/loaders/aws-cloudfront-loader.ts

@@ -1,4 +1,6 @@
 import type { ImageLoaderProps } from "next/image";
+import type { StringifiableRecord } from "query-string";
+import queryString from "query-string";
 
 import { BaseImageLoader } from "@/base-loader";
 
@@ -23,30 +25,24 @@ export class AWSCloudFrontLoader extends BaseImageLoader {
     const { quality, src, width } = config;
 
     try {
-      const url = new URL(src);
-
       // AWS CloudFront with Lambda@Edge or CloudFront Functions
       // Common query parameters for image optimization:
       // w = width
       // q = quality
       // f = format
       // fit = fit mode
 
-      // Set width parameter
-      url.searchParams.set("w", String(width));
-
-      // Set quality parameter
-      if (quality !== undefined) {
-        url.searchParams.set("q", String(quality));
-      }
-
-      // Request auto format (if supported by the Lambda function)
-      url.searchParams.set("f", "auto");
-
-      // Use cover fit mode for consistent sizing
-      url.searchParams.set("fit", "cover");
-
-      return url.toString();
+      const params: StringifiableRecord = {
+        f: "auto",
+        fit: "cover",
+        q: quality,
+        w: width,
+      };
+
+      return queryString.stringifyUrl({
+        query: params,
+        url: src,
+      });
     } catch (error) {
       console.warn(`Failed to transform AWS CloudFront URL: ${src}`, error);
       return src;

packages/image-loader/src/loaders/imgix-loader.ts

@@ -1,4 +1,5 @@
 import type { ImageLoaderProps } from "next/image";
+import queryString, { type StringifiableRecord } from "query-string";
 
 import { BaseImageLoader } from "@/base-loader";
 
@@ -23,33 +24,25 @@ export class ImgixLoader extends BaseImageLoader {
     const { quality, src, width } = config;
 
     try {
-      const url = new URL(src);
-
       // Imgix URL parameters:
       // w = width
       // q = quality (1-100)
       // auto = auto format and compress
       // fit = fit mode (crop, scale, etc.)
       // crop = crop mode (faces, entropy, etc.)
 
-      // Set width parameter
-      url.searchParams.set("w", String(width));
-
-      // Set quality parameter
-      if (quality !== undefined) {
-        url.searchParams.set("q", String(quality));
-      }
-
-      // Enable auto format and compression
-      url.searchParams.set("auto", "format,compress");
-
-      // Use crop fit mode for consistent sizing
-      url.searchParams.set("fit", "crop");
-
-      // Use faces crop mode for better cropping of images with people
-      url.searchParams.set("crop", "faces,entropy");
-
-      return url.toString();
+      const params: StringifiableRecord = {
+        auto: "format,compress",
+        crop: "faces,entropy",
+        fit: "crop",
+        q: quality,
+        w: width,
+      };
+
+      return queryString.stringifyUrl({
+        query: params,
+        url: src,
+      });
     } catch (error) {
       console.warn(`Failed to transform Imgix URL: ${src}`, error);
       return src;

packages/image-loader/src/loaders/supabase-loader.ts

@@ -1,4 +1,5 @@
 import type { ImageLoaderProps } from "next/image";
+import queryString, { type StringifiableRecord } from "query-string";
 
 import { BaseImageLoader } from "@/base-loader";
 
@@ -23,29 +24,23 @@ export class SupabaseLoader extends BaseImageLoader {
     const { quality, src, width } = config;
 
     try {
-      const url = new URL(src);
-
       // Supabase Storage image transformation parameters:
       // width = width
       // quality = quality (1-100)
       // format = format (auto, webp, jpg, png)
       // resize = resize mode (cover, contain, fill)
 
-      // Set width parameter
-      url.searchParams.set("width", String(width));
-
-      // Set quality parameter
-      if (quality !== undefined) {
-        url.searchParams.set("quality", String(quality));
-      }
-
-      // Request auto format for best optimization
-      url.searchParams.set("format", "auto");
-
-      // Use cover resize mode for consistent sizing
-      url.searchParams.set("resize", "cover");
-
-      return url.toString();
+      const params: StringifiableRecord = {
+        format: "auto",
+        quality: quality,
+        resize: "cover",
+        width: width,
+      };
+
+      return queryString.stringifyUrl({
+        query: params,
+        url: src,
+      });
     } catch (error) {
       console.warn(`Failed to transform Supabase URL: ${src}`, error);
       return src;

packages/image-loader/src/loaders/unsplash-loader.ts

@@ -1,4 +1,5 @@
 import type { ImageLoaderProps } from "next/image";
+import queryString, { type StringifiableRecord } from "query-string";
 
 import { BaseImageLoader } from "@/base-loader";
 
@@ -23,29 +24,23 @@ export class UnsplashLoader extends BaseImageLoader {
     const { quality, src, width } = config;
 
     try {
-      const url = new URL(src);
-
       // Unsplash URL parameters:
       // w = width
       // q = quality (1-100)
       // fm = format (auto, jpg, png, webp)
       // fit = fit mode (crop, scale, etc.)
 
-      // Set width parameter
-      url.searchParams.set("w", String(width));
-
-      // Set quality parameter
-      if (quality !== undefined) {
-        url.searchParams.set("q", String(quality));
-      }
-
-      // Set format to auto for the best optimization
-      url.searchParams.set("fm", "auto");
-
-      // Use crop fit mode for consistent sizing
-      url.searchParams.set("fit", "crop");
-
-      return url.toString();
+      const params: StringifiableRecord = {
+        fit: "crop",
+        fm: "auto",
+        q: quality,
+        w: width,
+      };
+
+      return queryString.stringifyUrl({
+        query: params,
+        url: src,
+      });
     } catch (error) {
       console.warn(`Failed to transform Unsplash URL: ${src}`, error);
       return src;