pjdev2d-cli 1.1.1 → 1.1.3

package/README.md

@@ -1,5 +1,11 @@
-# To add components 
+# To add components
 
 ```bash
 npx pjdev2d-cli add <name>
-```
+```
+
+# To add Tanstack Query Template
+
+```bash
+npx pjdev2d-cli add tanstack-query-template
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pjdev2d-cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "description": "CLI to install reusable React components like shadcn/ui",
   "main": "bin/cli.js",

package/templates/tanstack-query/api-base.ts

@@ -0,0 +1,68 @@
+/* 
+#ANCHOR : TYPE:1 VITE PROJECT
+const BASE_URL = import.meta.env.VITE_API_URL; 
+
+Environment variables must start with VITE_ to be exposed to client-side code in Vite.
+
+---------------------------------------------------------
+
+#ANCHOR : TYPE:2 NEXT.JS / NON-VITE PROJECTS
+const BASE_URL = process.env.NEXT_PUBLIC_API_URL;
+
+Environment variables must start with NEXT_PUBLIC_ to be available in Next.js browser code.
+
+---------------------------------------------------------
+#ANCHOR 
+Vite doesn't automatically provide Node's process.env in browser code.
+
+| Framework       | Access Method       | Public Prefix    |
+| --------------- | ------------------- | ---------------- |
+| Next.js         | `process.env.X`     | `NEXT_PUBLIC_`   |
+| Vite            | `import.meta.env.X` | `VITE_`          |
+| Node.js Backend | `process.env.X`     | No prefix needed |
+
+*/
+
+export const API_CONFIG = {
+  // NOTE: Change this BASE_URL to match your actual API endpoint
+  baseUrl: "http://localhost:5000/api",
+  timeout: 10000,
+  headers: {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+  },
+} as const;
+
+export const QUERY_CLIENT_CONFIG = {
+  defaultOptions: {
+    queries: {
+      // # NOTE: Global TanStack Query configurations
+      retry: 3,                    // Automatically retries failed requests 3 times on failure
+      refetchOnWindowFocus: false,  // Refetches stale active queries when the browser tab gets focused
+      staleTime: 1000 * 60 * 5,    // Data is considered fresh for 5 minutes (prevents duplicate requests)
+    },
+  },
+} as const;
+
+/*
+# NOTE: HOW AND WHERE TO USE QUERY_CLIENT_CONFIG
+
+This configuration is imported and passed when initializing the QueryClient at the root of your application (e.g., in App.tsx, main.tsx, or layout.tsx):
+
+```typescript
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QUERY_CLIENT_CONFIG } from "./api-base";
+
+const queryClient = new QueryClient(QUERY_CLIENT_CONFIG);
+
+export default function Providers({ children }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+```
+*/
+
+

package/templates/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/tanstack-query/{services/client.ts → client.ts}

@@ -1,41 +1,19 @@
-/* 
-#ANCHOR : TYPE:1 VITE PROJECT
-const BASE_URL = process.env.NEXT_PUBLIC_API_URL;
-
-Uses import.meta.env
-Environment variables must start with VITE_ to be exposed to client-side code.
-
----------------------------------------------------------
-
-#ANCHOR : TYPE:2 NON-VITE PROJECTS
-const BASE_URL = import.meta.env.VITE_API_URL; 
-
-Uses process.env
-Environment variables must start with NEXT_PUBLIC_ to be available in the browser.
-
----------------------------------------------------------
-#ANCHOR 
-Vite doesn't automatically provide Node's process.env in browser code.
-
-| Framework       | Access Method       | Public Prefix    |
-| --------------- | ------------------- | ---------------- |
-| Next.js         | `process.env.X`     | `NEXT_PUBLIC_`   |
-| Vite            | `import.meta.env.X` | `VITE_`          |
-| Node.js Backend | `process.env.X`     | No prefix needed |
-
-*/
-// NOTE BASE_URL to change with actual api
-const BASE_URL = "http://localhost:5000/api";
+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 = {},
 ) {
-  const response = await fetch(`${BASE_URL}${endpoint}`, {
+  // # 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: {
-      "Content-Type": "application/json",
+      ...API_CONFIG.headers,
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
       ...options.headers,
     },
   });

package/templates/tanstack-query/{services/module → module}/index.ts

@@ -1,12 +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";
- */
+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/tanstack-query/{services/module → module}/keys.ts

@@ -1,13 +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,
-};
-
-/* 
-# 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
- */
+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/tanstack-query/{services/module → module}/mappers.ts

@@ -1,11 +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;
-  },
-};
+/* 
+# 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/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/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/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.
+*/
+
+

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

@@ -1,25 +0,0 @@
-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: (input_name: any) =>
-        ModuleService.post_query_name_example(input_name),
-      onMutate: () => {
-        /* Write optimistic update logic here */
-      },
-      onSuccess: async () => {
-        /* 
-        # NOTE: In case of POST/PATCH/DELETE operations, it is very important to invalidate the queries that depend on the data that was mutated.
-        */
-        await queryClient.invalidateQueries({
-          queryKey: ModuleKeys.fetch_query_name_example(),
-        });
-      },
-      onError: (error) => {
-        /* Write error logic here */
-      },
-    }),
-};

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

@@ -1,27 +0,0 @@
-import { queryOptions } 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: async () => {
-        try {
-          /* 
-          # NOTE:  ModuleService.get_query_name_example() -> hts the api of query fetch or GET
-          # NOTE: ModuleMappers.fetch_query_name_example() -> manipulates the data from api into desird format before returning to ui or page
-          */
-          const raw = await ModuleService.get_query_name_example();
-          return ModuleMappers.fetch_query_name_example(raw as any);
-        } catch {
-          /* 
-          # NOTE: you can change null to empty array [] or fallback data that you will get from mocks.ts file or you can handel some other logic here
-          */
-          return ModuleMappers.fetch_query_name_example(null);
-        }
-      },
-    }),
-};

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

@@ -1,18 +0,0 @@
-import { apiClient } from "../client";
-
-export const ModuleService = {
-  get_query_name_example: () => apiClient.get("/api_name/get"),
-  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
-*/

package/templates/tanstack-query/services/queries.ts

@@ -1,67 +0,0 @@
-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());
-
-  ---------------------------------------------------------------------------------------------------
-
-  | 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.
-
- */