pejay-ui 1.0.3 → 1.1.0

package/templates/scaffolds/tanstack-query/api-queries.ts

@@ -0,0 +1,274 @@
+import { ModuleQueries } from "./module";
+
+export const apiQueries = {
+  module: ModuleQueries,
+};
+
+export * from "./module";
+
+/* 
+# NOTE : here you export all the queries from the module folder so it will be easy to import in components
+
+  const { data: name } = useQuery(ModuleQueries.fetch_query_name_example());
+  const { data: name } = useSuspenseQuery(ModuleQueries.fetch_query_name_example());
+
+  // Example with parameters & request cancellation:
+  // const { data } = useQuery(ModuleQueries.fetch_query_with_params_example({ search: 'query', filter: 'active' }));
+
+  ---------------------------------------------------------------------------------------------------
+
+  | Feature             | `useQuery`                                     | `useSuspenseQuery`                                  |
+| ------------------- | ---------------------------------------------- | --------------------------------------------------- |
+| Loading state       | Returns `isLoading`, `isPending`, `isFetching` | Does **not** return loading state                   |
+| Data type           | `data` can be `undefined`                      | `data` is guaranteed to exist when rendered         |
+| Error handling      | Use `error` from hook                          | Error is caught by React Error Boundary             |
+| Loading UI          | Handle manually (`if (isLoading)`)             | Handled by React `<Suspense>` fallback              |
+| Component rendering | Renders immediately, then fetches              | Suspends rendering until data is ready              |
+| Setup complexity    | Simpler                                        | Requires `<Suspense>` and usually an Error Boundary |
+| Best for            | Most applications                              | Apps fully using React Suspense                     |
+
+----------------------------------------------------------------------------------------------------
+
+# NOTE : Example for useQuery
+const ModuleComponent = () => {
+
+const { data, isLoading, error } = useQuery(
+  ModuleQueries.fetch_query_name_example()
+);
+
+if (isLoading) return <FallBackComponent />;
+if (error) return <ErrorComponent />;
+
+return <ModuleComponent data={data} />;
+
+}
+
+-----------------------------------------------------------------------------------------------------
+
+# NOTE : Example for useSuspenseQuery
+
+const ModuleComponent = () => {
+
+const { data } = useSuspenseQuery(
+  ModuleQueries.fetch_query_name_example()
+);
+
+return <ModuleComponent data={data} />;
+
+}
+
+# NOTE : Wrapping
+<Suspense fallback={<FallBackComponent />}>
+  <ModuleComponent />
+</Suspense>
+
+---------------------------------------------------------------------------------------------------
+
+Use useQuery when you want to manage loading and errors inside the component.
+Use useSuspenseQuery when your app already uses React Suspense and you want cleaner components with guaranteed data.
+
+---------------------------------------------------------------------------------------------------
+
+# NOTE : Example for useInfiniteQuery (Infinite Scrolling)
+
+1. In queries.ts, define the option:
+   export const ModuleQueries = {
+     fetch_infinite_query_example: () =>
+       infiniteQueryOptions({
+         queryKey: [...ModuleKeys.module(), "infinite"] as const,
+         queryFn: async ({ pageParam = 1 }) => {
+           const raw = await ModuleService.get_infinite_query_example(pageParam as number);
+           return raw as { data: any[]; meta: { current_page: number; last_page: number } };
+         },
+          getNextPageParam: (raw) => {
+            // E.g., if page-based (extracting from 'meta' object):
+            const { current_page, last_page } = raw?.meta || {};
+            return current_page < last_page ? current_page + 1 : undefined;
+          },
+          initialPageParam: 1,
+          select: (raw) => ({
+            pages: raw.pages.map((pageData: any) => ({
+              ...pageData,
+              data: ModuleMappers.fetch_infinite_query_example(pageData.data),
+            })),
+            pageParams: raw.pageParams,
+          }),
+        })
+    }
+
+2. In your Component:
+   import { useInfiniteQuery } from "@tanstack/react-query";
+   import { useEffect } from "react";
+   import { useInView } from "react-intersection-observer"; // optional, or use standard scroll listener
+   import { ModuleQueries } from "./queries";
+
+   const InfiniteListComponent = () => {
+     const {
+       data,
+       fetchNextPage,
+       hasNextPage,
+       isFetchingNextPage,
+       isLoading,
+       error
+     } = useInfiniteQuery(ModuleQueries.fetch_infinite_query_example());
+
+     // Optional hook to detect if target element is visible in the viewport
+     const { ref, inView } = useInView();
+
+     useEffect(() => {
+       if (inView && hasNextPage && !isFetchingNextPage) {
+         fetchNextPage();
+       }
+     }, [inView, hasNextPage, isFetchingNextPage, fetchNextPage]);
+
+     if (isLoading) return <Loading />;
+     if (error) return <Error />;
+
+     // Flatten the paginated data pages into a single flat array
+     const items = data ? data.pages.flatMap((page) => page.data) : [];
+
+     return (
+       <div>
+         <ul>
+           {items.map((item) => (
+             <li key={item.id}>{item.name}</li>
+           ))}
+         </ul>
+
+         // This invisible boundary element triggers loading the next page when scrolled into view 
+         <div ref={ref} style={{ height: "10px" }}>
+           {isFetchingNextPage ? "Loading more..." : ""}
+         </div>
+       </div>
+     );
+   };
+
+ ---------------------------------------------------------------------------------------------------
+
+# HOW INFINITE SCROLLING WORKS:
+1. **Initial Load:** `useInfiniteQuery` calls `queryFn` using `initialPageParam` (usually page `1`). The response is saved in `data.pages[0]`.
+2. **Next Page Calculation:** `getNextPageParam` is called with the last fetched page data. It checks if there is more data (e.g., if `current_page < last_page`). If returned, `hasNextPage` becomes `true`.
+3. **Scroll Trigger:** When the user scrolls down, an observer (like `react-intersection-observer` on the bottom `div` element) fires an `inView` event.
+4. **Fetch Call:** If `inView`, `hasNextPage`, and not currently loading, we call `fetchNextPage()`.
+5. **Caching & Appending:** TanStack Query triggers `queryFn` passing the next page number (e.g., `2`) as the new `pageParam`. The new data is fetched and appended as a new array element inside `data.pages` (e.g., `data.pages[1]`). The UI re-renders with the flattened items list.
+
+---------------------------------------------------------------------------------------------------
+
+# NOTE : Example for Query Parameters (Filters & Cancellation)
+
+This example shows a component using query parameters (including an array of brands) with automatic request cancellation:
+
+```typescript
+import { useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { ModuleQueries } from "./queries";
+import { useDebounce } from "@/hooks/use-debounce"; // custom debounce hook
+
+const FilteredProductList = () => {
+  const [search, setSearch] = useState("");
+  const [selectedBrands, setSelectedBrands] = useState<string[]>([]); // e.g., ["samsung", "apple"]
+  const [sortBy, setSortBy] = useState("price_asc"); // Single key-value parameter example
+
+  // 1. Debounce fast inputs (like keystrokes) to prevent hammering the server
+  const debouncedSearch = useDebounce(search, 300);
+
+  // 2. Combine your states. Any change to these properties will update the queryKey
+  const filters = {
+    search: debouncedSearch,
+    brands: selectedBrands, // Array will be serialized as "brands=samsung&brands=apple" by the service
+    sort: sortBy,           // Single key-value parameter (e.g., "price_asc")
+  };
+
+  // 3. Pass the filter object directly to the query option builder
+  const { data, isLoading, isFetching, error } = useQuery(
+    ModuleQueries.fetch_query_with_params_example(filters)
+  );
+
+  const toggleBrand = (brand: string) => {
+    setSelectedBrands(prev => 
+      prev.includes(brand) ? prev.filter(b => b !== brand) : [...prev, brand]
+    );
+  };
+
+  return (
+    <div>
+      <input 
+        type="text" 
+        value={search} 
+        onChange={(e) => setSearch(e.target.value)} 
+        placeholder="Search mobiles..." 
+      />
+
+      <select value={sortBy} onChange={(e) => setSortBy(e.target.value)}>
+        <option value="price_asc">Price: Low to High</option>
+        <option value="price_desc">Price: High to Low</option>
+      </select>
+
+      <div>
+        <label>
+          <input 
+            type="checkbox" 
+            checked={selectedBrands.includes("samsung")} 
+            onChange={() => toggleBrand("samsung")} 
+          /> Samsung
+        </label>
+        <label>
+          <input 
+            type="checkbox" 
+            checked={selectedBrands.includes("apple")} 
+            onChange={() => toggleBrand("apple")} 
+          /> Apple
+        </label>
+      </div>
+
+      {isFetching && <span>Updating results (Old requests cancelled automatically)...</span>}
+
+      {isLoading ? (
+        <p>Loading...</p>
+      ) : error ? (
+        <p>Error loading items</p>
+      ) : (
+        <ul>
+          {data?.map((item: any) => (
+            <li key={item.id}>{item.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};
+```
+
+---------------------------------------------------------------------------------------------------
+
+# NOTE: WHY WE DO NOT GET DUPLICATE KEY ERRORS IN FRONTEND STATE
+Even though the final URL repeats the same key (e.g., `?brands=samsung&brands=apple`), 
+your frontend React state or router object only has one clean unique key mapping to an array:
+`const filters = { brands: ["samsung", "apple"] };`
+
+The service layer safely iterates over the array and appends the items individually to the query parameters (`queryParams.append`). 
+This keeps your frontend state easy to manage without causing duplicate key errors.
+
+
+
+
+
+
+useEffect(() => {
+  // 1. Get query string from URL (or SessionStorage if URL is empty)
+  const searchParams = new URLSearchParams(window.location.search);
+  // 2. Parse the single values
+  const searchVal = searchParams.get("search") || "";
+  const sortVal = searchParams.get("sort") || "price_asc";
+  // 3. Parse the repeated values as an array
+  const brandsVal = searchParams.getAll("brands"); // returns ["samsung", "apple"]
+  // 4. Populate your component state
+  setSearch(searchVal);
+  setSortBy(sortVal);
+  setSelectedBrands(brandsVal);
+}, []);
+
+*/
+
+
+

package/templates/scaffolds/tanstack-query/client.ts

@@ -0,0 +1,63 @@
+import { API_CONFIG } from "./api-base";
+
+//NOTE: apiRequest:  This is the core function that all other methods use.
+export async function apiRequest<T>(
+  endpoint: string,
+  options: RequestInit = {},
+) {
+  // # NOTE: Retrieve your authentication token dynamically (e.g., from localStorage or cookies)
+  // const token = typeof window !== "undefined" ? localStorage.getItem("token") : null;
+  const token = null;
+
+  const response = await fetch(`${API_CONFIG.baseUrl}${endpoint}`, {
+    ...options,
+    headers: {
+      ...API_CONFIG.headers,
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) throw new Error(`Error Code ${response.status}`);
+  return (await response.json()) as T;
+}
+
+function withJsonBody(method: string, body: any, options?: RequestInit) {
+  return {
+    ...options,
+    method,
+    body: body === undefined ? undefined : JSON.stringify(body),
+    /* 
+    # NOTE : fetch expects JSON bodies as strings
+    line this 
+    body: '{"name":"John"}'
+    and not 
+    body: data
+    in case of undefined - does a Undefined Body Check
+    body: "undefined"
+     */
+  } satisfies RequestInit;
+}
+
+/* 
+
+Contains all api type calls
+Usage: 
+const data = await apiClient.get<User>("/users/1");
+const data = await apiClient.post<User>("/users", { name: "John" });
+const data = await apiClient.put<User>("/users/1", { name: "John" });
+const data = await apiClient.patch<User>("/users/1", { name: "John" });
+const data = await apiClient.delete<User>("/users/1");
+
+ */
+export const apiClient = {
+  get: apiRequest,
+  post: <T>(endpoint: string, body?: any, options?: RequestInit) =>
+    apiRequest<T>(endpoint, withJsonBody("POST", body, options)),
+  put: <T>(endpoint: string, body?: any, options?: RequestInit) =>
+    apiRequest<T>(endpoint, withJsonBody("PUT", body, options)),
+  patch: <T>(endpoint: string, body?: any, options?: RequestInit) =>
+    apiRequest<T>(endpoint, withJsonBody("PATCH", body, options)),
+  delete: <T>(endpoint: string, options?: RequestInit) =>
+    apiRequest<T>(endpoint, { ...options, method: "DELETE" }),
+} as const;

package/templates/scaffolds/tanstack-query/module/index.ts

@@ -0,0 +1,12 @@
+export { ModuleKeys } from "./keys";
+export { ModuleMappers } from "./mappers";
+export { ModuleService } from "./services";
+export { ModuleQueries } from "./queries";
+export { ModuleMutations } from "./mutations";
+
+/* 
+# NOTE: here we can export types.ts as well if we defining types seperately in a file 
+export type * from "./types";
+# NOTE : we can also export a mocks.ts file if we using mocks which contains dummy / fall back data
+export { ModuleMocks } from "./mocks";
+ */

package/templates/scaffolds/tanstack-query/module/keys.ts

@@ -0,0 +1,17 @@
+export const ModuleKeys = {
+  module: () => ["moduleName"] as const,
+  fetch_query_name_example: () => [...ModuleKeys.module(), "fetch"] as const,
+  create_query_name_example: () => [...ModuleKeys.module(), "create"] as const,
+  update_query_name_example: () => [...ModuleKeys.module(), "update"] as const,
+  delete_query_name_example: () => [...ModuleKeys.module(), "delete"] as const,
+  fetch_infinite_query_name_example: () => [...ModuleKeys.module(), "fetch-infinite"] as const,
+  fetch_query_with_params_example: (params: any) => [...ModuleKeys.module(), "fetch-with-params", params] as const,
+  fetch_query_by_id_example: (id: string) => [...ModuleKeys.module(), "fetch-by-id", id] as const,
+  fetch_query_combo_example: (id: string, params: any) => [...ModuleKeys.module(), "fetch-combo", id, params] as const,
+};
+
+/* 
+# NOTE: as const is used at end so that keys are immutable
+# NOTE : ans insted of standard object keys usd as function so its easy and clean to use and maintain in larger scale
+# NOTE : you can change *_name_example to your own query name
+ */

package/templates/scaffolds/tanstack-query/module/mappers.ts

@@ -0,0 +1,15 @@
+/* 
+# NOTE : you can change *_name_example to your own query name 
+# NOTE : you can change raw to your own data after manipulation 
+*/
+
+export const ModuleMappers = {
+  fetch_query_name_example(raw: any) {
+    const data = raw || "manipulate your data here and then return it";
+    return data;
+  },
+  fetch_infinite_query_example(raw: any) {
+    const data = raw || [];
+    return data;
+  },
+};

package/templates/scaffolds/tanstack-query/module/mutations.ts

@@ -0,0 +1,55 @@
+import { mutationOptions, type QueryClient } from "@tanstack/react-query";
+import { ModuleKeys } from "./keys";
+import { ModuleService } from "./services";
+
+export const ModuleMutations = {
+  create_query_name_example: (queryClient: QueryClient) =>
+    mutationOptions({
+      mutationFn: (newItem: any) =>
+        ModuleService.post_query_name_example(newItem),
+      onMutate: async (newItem: any) => {
+        /* 
+        # OPTIMISTIC UPDATE TECHNIQUE:
+        1. Cancel outgoing refetches so they don't overwrite our optimistic update.
+        2. Snapshot the current cache value.
+        3. Optimistically insert the new item into the cache.
+        4. Return context containing the previous value for error rollbacks.
+        */
+        await queryClient.cancelQueries({ queryKey: ModuleKeys.fetch_query_name_example() });
+
+        const previousItems = queryClient.getQueryData(ModuleKeys.fetch_query_name_example());
+
+        queryClient.setQueryData(ModuleKeys.fetch_query_name_example(), (old: any) => {
+          return old ? [...old, newItem] : [newItem];
+        });
+
+        return { previousItems };
+      },
+      onSuccess: async () => {
+        /* 
+        # NOTE: In case of mutations, invalidate query keys to refresh with fresh server data.
+        */
+        await queryClient.invalidateQueries({
+          queryKey: ModuleKeys.fetch_query_name_example(),
+        });
+      },
+      onError: (error, newItem, context: any) => {
+        /* 
+        # ROLLBACK ON FAILURE:
+        If the mutation fails, rollback the cache to our snapshotted state.
+        */
+        if (context?.previousItems) {
+          queryClient.setQueryData(
+            ModuleKeys.fetch_query_name_example(),
+            context.previousItems
+          );
+        }
+      },
+      onSettled: async () => {
+        // Always refetch after error or success to keep server in sync
+        await queryClient.invalidateQueries({
+          queryKey: ModuleKeys.fetch_query_name_example(),
+        });
+      },
+    }),
+};

package/templates/scaffolds/tanstack-query/module/queries.ts

@@ -0,0 +1,133 @@
+import { queryOptions, infiniteQueryOptions, keepPreviousData } from "@tanstack/react-query";
+
+import { ModuleKeys } from "./keys";
+import { ModuleMappers } from "./mappers";
+import { ModuleService } from "./services";
+
+export const ModuleQueries = {
+  fetch_query_name_example: () =>
+    queryOptions({
+      queryKey: ModuleKeys.fetch_query_name_example(),
+      queryFn: () => {
+        /* 
+        # NOTE:  ModuleService.get_query_name_example() -> hits the api of query fetch or GET
+        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
+        */
+        return ModuleService.get_query_name_example();
+      },
+      select: (raw) => {
+        /* 
+        # NOTE: ModuleMappers.fetch_query_name_example() -> manipulates the data from api into desird format before returning to ui or page
+        Using the 'select' property memoizes this transformation (only runs when cached data changes).
+        */
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      /* 
+      # NOTE: keeps the last successfully fetched data visible on screen 
+      while fetching new data or if a subsequent fetch fails (preventing layout flickers/empty states).
+      */
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_infinite_query_example: () =>
+    infiniteQueryOptions({
+      queryKey: ModuleKeys.fetch_infinite_query_name_example(),
+      queryFn: ({ pageParam = 1 }) => {
+        /* 
+        # NOTE:  ModuleService.get_infinite_query_example(pageParam) -> hits the api of query fetch or GET
+        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
+        */
+        return ModuleService.get_infinite_query_example(pageParam as number);
+      },
+      getNextPageParam: (raw: any) => {
+        // --- Option A: Cursor-based Pagination ---
+        // return raw.nextCursor ?? undefined;
+
+        // --- Option B: Page-number Metadata Pagination (last_page, current_page) ---
+        // Access metadata from the 'meta' object returned in your API response
+        const { current_page, last_page } = raw?.meta || {};
+        const hasMore = current_page < last_page;
+        return hasMore ? current_page + 1 : undefined;
+      },
+      initialPageParam: 1,
+      select: (raw) => {
+        /* 
+        # NOTE: ModuleMappers.fetch_infinite_query_example() -> manipulates the data from api into desird format before returning to ui or page
+        Using the 'select' property memoizes this transformation (only runs when cached data changes).
+        */
+        return {
+          pages: raw.pages.map((pageData: any) => ({
+            ...pageData,
+            data: ModuleMappers.fetch_infinite_query_example(pageData.data),
+          })),
+          pageParams: raw.pageParams,
+        };
+      },
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_query_with_params_example: (params: Record<string, any>) =>
+    queryOptions({
+      queryKey: ModuleKeys.fetch_query_with_params_example(params),
+      queryFn: ({ signal }) => {
+        /* 
+        # NOTE: Pass the native 'signal' from the TanStack queryFn context down to the service call.
+        This enables automatic cancellation if query parameters change or the component unmounts.
+        */
+        return ModuleService.get_query_with_params_example(params, signal);
+      },
+      select: (raw) => {
+        // Reusing the same mapper example for consistency
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_query_by_id_example: (id?: string | null) =>
+    queryOptions({
+      queryKey: ModuleKeys.fetch_query_by_id_example(id || ""),
+      queryFn: ({ signal }) => {
+        return ModuleService.get_query_by_id_example(id!, signal);
+      },
+      select: (raw) => {
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+      /* 
+      # NOTE: Conditional/Dependent Queries
+      Setting 'enabled: !!id' stops the query from executing automatically if the ID is missing (undefined, null, or empty).
+      */
+      enabled: !!id,
+    }),
+
+  fetch_query_combo_example: (id: string | null | undefined, params: Record<string, any>) =>
+    queryOptions({
+      queryKey: ModuleKeys.fetch_query_combo_example(id || "", params),
+      queryFn: ({ signal }) => {
+        return ModuleService.get_query_combo_example(id!, params, signal);
+      },
+      select: (raw) => {
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+      enabled: !!id, // Automatically stops API call if ID is null/undefined
+    }),
+};
+
+/*
+# NOTE: RAW DATA VS. MAPPED DATA & MEMOIZATION
+
+1. **Where Raw Data Lives:**
+   - The raw response returned by the API (`queryFn`) is stored unmodified inside the **TanStack Query Cache**. 
+   - This represents the exact payload from your backend database/server.
+
+2. **Where Mapped Data Lives:**
+   - The mapped data is delivered directly to the **UI / React Component** consuming the hook.
+   - It is calculated on-the-fly by executing the `select` function on the cached raw data.
+
+3. **How Memoization Works (Performance Optimization):**
+   - The `select` function is **automatically memoized** by TanStack Query.
+   - It will ONLY re-run when the cached raw data changes. 
+   - If the component re-renders for other reasons (e.g., local UI states, parent re-renders, or window focus checks), TanStack Query skips the mapper execution completely and returns the already memoized mapped data instantly.
+*/
+

package/templates/scaffolds/tanstack-query/module/services.ts

@@ -0,0 +1,66 @@
+import { apiClient } from "../client";
+
+export const ModuleService = {
+  get_query_name_example: () => apiClient.get("/api_name/get"),
+  get_infinite_query_example: (page: number) =>
+    apiClient.get(`/api_name/list?page=${page}`),
+  get_query_with_params_example: (params: Record<string, any>, signal?: AbortSignal) => {
+    const queryParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((val) => {
+          if (val !== undefined && val !== null && val !== "") {
+            queryParams.append(key, String(val));
+          }
+        });
+      } else if (value !== undefined && value !== null && value !== "") {
+        queryParams.set(key, String(value));
+      }
+    });
+    return apiClient.get(`/api_name/get-with-params?${queryParams.toString()}`, { signal });
+  },
+  get_query_by_id_example: (id: string, signal?: AbortSignal) =>
+    apiClient.get(`/api_name/get-by-id/${id}`, { signal }),
+  get_query_combo_example: (id: string, params: Record<string, any>, signal?: AbortSignal) => {
+    const queryParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((val) => {
+          if (val !== undefined && val !== null && val !== "") {
+            queryParams.append(key, String(val));
+          }
+        });
+      } else if (value !== undefined && value !== null && value !== "") {
+        queryParams.set(key, String(value));
+      }
+    });
+    return apiClient.get(`/api_name/get-combo/${id}?${queryParams.toString()}`, { signal });
+  },
+  post_query_name_example: (input: any) =>
+    apiClient.post("/api_name/post", input),
+  patch_query_name_example: (input: any) =>
+    apiClient.patch("/api_name/patch", input),
+  delete_query_name_example: (id: string) =>
+    apiClient.delete(`/api_name/${id}`),
+};
+
+/* 
+# NOTE: you can change *_name_example to your own query name
+# NOTE: you can change /api_name to your own api name
+# NOTE: you can change input to your own data type
+# NOTE: you can change id to your own data type
+
+-------------------------------------------------------------------------
+
+# NOTE: WHY WE USE URLSearchParams & THE ROLE OF THE SERVICE LAYER
+
+1. **Why we use `URLSearchParams`:**
+   - **Automatic URL-Encoding:** It automatically sanitizes special characters (like spaces, commas, or quotes) into browser-safe formats (e.g., space becomes `%20`), preventing broken URLs.
+   - **Dynamic Query String Building:** It generates the final string from a raw object dynamically (calling `.toString()` results in `key1=val1&key2=val2`).
+
+2. **Role of this Service Layer (`get_query_with_params_example`):**
+   - **Decoupled Contracts:** It keeps components "dumb" about network specifics. The component only needs to pass a clean JavaScript object containing the filters.
+   - **Centralization:** If endpoints change or parameter serialization logic needs to adjust in the future, it is managed in this single file rather than modifying multiple UI files.
+*/
+
+