pejay-ui 1.0.4 → 1.1.0

package/README.md

@@ -129,3 +129,10 @@ Below is the list of components you can add. Each has a copyable command block w
   ```bash
   npx pejay-ui add dropdown/multiselect-input
   ```
+
+### Scaffolds & Templates
+
+* **`tanstack-query-client`**: Bare-bone TanStack Query client and context provider setup, copied directly into your project's `src/tanstack-query/`.
+  ```bash
+  npx pejay-ui add tanstack-query-client
+  ```

package/bin/cli.js

@@ -21,6 +21,23 @@ const prompt = async (questions) => {
   return inquirer.default.prompt(questions);
 };
 
+// Helper to get all files recursively from a directory
+const getFilesRecursively = async (dir) => {
+  let results = [];
+  const list = await fs.readdir(dir);
+  for (const file of list) {
+    const filePath = path.join(dir, file);
+    const stat = await fs.stat(filePath);
+    if (stat && stat.isDirectory()) {
+      const subFiles = await getFilesRecursively(filePath);
+      results = results.concat(subFiles);
+    } else {
+      results.push(filePath);
+    }
+  }
+  return results;
+};
+
 program
   .name("pejay-ui")
   .description("CLI to initialize, add, and remove React UI components")
@@ -178,7 +195,12 @@ program
         }
 
         // 3. Process & Copy Component Files
-        const targetDir = path.join(cwd, config.baseDir, "components", componentData.category);
+        let targetDir;
+        if (componentData.category === "tanstack-query") {
+          targetDir = path.join(cwd, "src", "tanstack-query");
+        } else {
+          targetDir = path.join(cwd, config.baseDir, "components", componentData.category);
+        }
         const outputExt = isTsProject ? "tsx" : "jsx";
 
         // Determine list of files to copy
@@ -192,29 +214,70 @@ program
             process.exit(1);
           }
 
-          const filename = path.basename(srcFilePath).replace(/\.(tsx|ts)$/, (match) => {
-            return match === ".tsx" ? `.${outputExt}` : `.${isTsProject ? "ts" : "js"}`;
-          });
-          const targetFile = path.join(targetDir, filename);
-
-          let componentCode = await fs.readFile(templateSrc, "utf-8");
+          const isDir = (await fs.stat(templateSrc)).isDirectory();
+          if (isDir) {
+            const allFiles = await getFilesRecursively(templateSrc);
+            for (const file of allFiles) {
+              const relativePath = path.relative(templateSrc, file);
+              const filename = relativePath.replace(/\.(tsx|ts)$/, (match) => {
+                return match === ".tsx" ? `.${outputExt}` : `.${isTsProject ? "ts" : "js"}`;
+              });
+              const targetFile = path.join(targetDir, filename);
+
+              let componentCode = await fs.readFile(file, "utf-8");
+
+              const fileDir = path.dirname(targetFile);
+              const relativeToUtils = path.relative(fileDir, targetUtilsDir).replace(/\\/g, "/");
+              const cnImportPath = isTsProject 
+                ? `${relativeToUtils}/cn` 
+                : `${relativeToUtils}/cn.js`;
+              componentCode = componentCode.replace(/@\/utils\/cn/g, cnImportPath);
 
-          // Replace `@/utils/cn` with relative path to the local utils/cn folder
-          const cnImportPath = isTsProject ? "../../utils/cn" : "../../utils/cn.js";
-          componentCode = componentCode.replace(/@\/utils\/cn/g, cnImportPath);
+              if (!isTsProject) {
+                const transformed = babel.transformSync(componentCode, {
+                  presets: ["@babel/preset-typescript"],
+                  filename: path.basename(file),
+                });
+                componentCode = transformed?.code || componentCode;
+              }
 
-          if (!isTsProject) {
-            const transformed = babel.transformSync(componentCode, {
-              presets: ["@babel/preset-typescript"],
-              filename: path.basename(srcFilePath),
+              await fs.ensureDir(path.dirname(targetFile));
+              await fs.writeFile(targetFile, componentCode, "utf-8");
+              
+              const relativeTargetFile = path.relative(cwd, targetFile).replace(/\\/g, "/");
+              console.log(`✅ Created ${relativeTargetFile}`);
+              installedFiles.push(path.relative(path.join(cwd, config.baseDir), targetFile).replace(/\\/g, "/"));
+            }
+          } else {
+            const filename = path.basename(srcFilePath).replace(/\.(tsx|ts)$/, (match) => {
+              return match === ".tsx" ? `.${outputExt}` : `.${isTsProject ? "ts" : "js"}`;
             });
-            componentCode = transformed?.code || componentCode;
-          }
+            const targetFile = path.join(targetDir, filename);
+
+            let componentCode = await fs.readFile(templateSrc, "utf-8");
+
+            const fileDir = path.dirname(targetFile);
+            const relativeToUtils = path.relative(fileDir, targetUtilsDir).replace(/\\/g, "/");
+            const cnImportPath = isTsProject 
+              ? `${relativeToUtils}/cn` 
+              : `${relativeToUtils}/cn.js`;
+            componentCode = componentCode.replace(/@\/utils\/cn/g, cnImportPath);
+
+            if (!isTsProject) {
+              const transformed = babel.transformSync(componentCode, {
+                presets: ["@babel/preset-typescript"],
+                filename: path.basename(srcFilePath),
+              });
+              componentCode = transformed?.code || componentCode;
+            }
 
-          await fs.ensureDir(targetDir);
-          await fs.writeFile(targetFile, componentCode, "utf-8");
-          console.log(`✅ Created components/${componentData.category}/${filename}`);
-          installedFiles.push(path.join("components", componentData.category, filename));
+            await fs.ensureDir(targetDir);
+            await fs.writeFile(targetFile, componentCode, "utf-8");
+            
+            const relativeTargetFile = path.relative(cwd, targetFile).replace(/\\/g, "/");
+            console.log(`✅ Created ${relativeTargetFile}`);
+            installedFiles.push(path.relative(path.join(cwd, config.baseDir), targetFile).replace(/\\/g, "/"));
+          }
         }
 
         // 4. Update State tracking in config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pejay-ui",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "description": "react ui components",
   "bin": {
@@ -22,6 +22,7 @@
   "dependencies": {
     "@babel/core": "^7.24.0",
     "@babel/preset-typescript": "^7.24.0",
+    "@tanstack/react-query": "^5.100.14",
     "commander": "^12.0.0",
     "fs-extra": "^11.0.0",
     "inquirer": "^9.0.0"

package/registry.json

@@ -2,328 +2,174 @@
   "button": {
     "name": "Button",
     "category": "button",
-    "files": [
-      "templates/button/Button.tsx",
-      "templates/button/tooltip.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ]
+    "files": ["templates/button/Button.tsx", "templates/button/tooltip.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"]
   },
   "form/input": {
     "name": "Input",
     "category": "form",
-    "files": [
-      "templates/form/input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/amount-input": {
     "name": "AmountInput",
     "category": "form",
-    "files": [
-      "templates/form/amount-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/amount-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/checkbox": {
     "name": "Checkbox",
     "category": "form",
-    "files": [
-      "templates/form/checkbox.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/checkbox.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/checkbox-group": {
     "name": "CheckboxGroup",
     "category": "form",
-    "files": [
-      "templates/form/checkbox-group.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ],
-    "dependencies": [
-      "form/checkbox"
-    ]
+    "files": ["templates/form/checkbox-group.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"],
+    "dependencies": ["form/checkbox"]
   },
   "form/date-picker": {
     "name": "DatePicker",
     "category": "form",
-    "files": [
-      "templates/form/date-picker.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/form/date-picker.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
       "lucide-react",
       "@floating-ui/react"
     ],
-    "dependencies": [
-      "select-dropdown/select-input"
-    ]
+    "dependencies": ["select-dropdown/select-input"]
   },
   "form/date-range-picker": {
     "name": "DateRangePicker",
     "category": "form",
-    "files": [
-      "templates/form/date-range-picker.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/form/date-range-picker.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
       "lucide-react",
       "@floating-ui/react"
     ],
-    "dependencies": [
-      "select-dropdown/select-input"
-    ]
+    "dependencies": ["select-dropdown/select-input"]
   },
   "form/email-input": {
     "name": "EmailInput",
     "category": "form",
-    "files": [
-      "templates/form/email-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/email-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/file-input": {
     "name": "FileInput",
     "category": "form",
-    "files": [
-      "templates/form/file-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/file-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/number-input": {
     "name": "NumberInput",
     "category": "form",
-    "files": [
-      "templates/form/number-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/number-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/password-input": {
     "name": "PasswordInput",
     "category": "form",
-    "files": [
-      "templates/form/password-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/password-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/phone-input": {
     "name": "PhoneInput",
     "category": "form",
-    "files": [
-      "templates/form/phone-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/phone-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "form/radio": {
     "name": "Radio",
     "category": "form",
-    "files": [
-      "templates/form/radio.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ]
+    "files": ["templates/form/radio.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"]
   },
   "form/radio-group": {
     "name": "RadioGroup",
     "category": "form",
-    "files": [
-      "templates/form/radio-group.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ],
-    "dependencies": [
-      "form/radio"
-    ]
+    "files": ["templates/form/radio-group.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"],
+    "dependencies": ["form/radio"]
   },
   "form/range-slider": {
     "name": "RangeSlider",
     "category": "form",
-    "files": [
-      "templates/form/range-slider.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ]
+    "files": ["templates/form/range-slider.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"]
   },
   "form/switch": {
     "name": "Switch",
     "category": "form",
-    "files": [
-      "templates/form/switch.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ]
+    "files": ["templates/form/switch.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"]
   },
   "form/textarea": {
     "name": "Textarea",
     "category": "form",
-    "files": [
-      "templates/form/textarea.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge"
-    ]
+    "files": ["templates/form/textarea.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge"]
   },
   "form/time-picker": {
     "name": "TimePicker",
     "category": "form",
-    "files": [
-      "templates/form/time-picker.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/form/time-picker.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
       "lucide-react",
       "@floating-ui/react"
     ],
-    "dependencies": [
-      "select-dropdown/select-input"
-    ]
+    "dependencies": ["select-dropdown/select-input"]
   },
   "form/time-range-picker": {
     "name": "TimeRangePicker",
     "category": "form",
-    "files": [
-      "templates/form/time-range-picker.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/form/time-range-picker.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
       "lucide-react",
       "@floating-ui/react"
     ],
-    "dependencies": [
-      "select-dropdown/select-input"
-    ]
+    "dependencies": ["select-dropdown/select-input"]
   },
   "form/url-input": {
     "name": "UrlInput",
     "category": "form",
-    "files": [
-      "templates/form/url-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
-    "peerDependencies": [
-      "clsx",
-      "tailwind-merge",
-      "lucide-react"
-    ]
+    "files": ["templates/form/url-input.tsx"],
+    "utils": ["cn.ts"],
+    "peerDependencies": ["clsx", "tailwind-merge", "lucide-react"]
   },
   "dropdown/select-input": {
     "name": "SelectInput",
     "category": "select-dropdown",
-    "files": [
-      "templates/select-dropdown/select-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/select-dropdown/select-input.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
@@ -334,17 +180,19 @@
   "dropdown/multiselect-input": {
     "name": "MultiselectInput",
     "category": "select-dropdown",
-    "files": [
-      "templates/select-dropdown/multiselect-input.tsx"
-    ],
-    "utils": [
-      "cn.ts"
-    ],
+    "files": ["templates/select-dropdown/multiselect-input.tsx"],
+    "utils": ["cn.ts"],
     "peerDependencies": [
       "clsx",
       "tailwind-merge",
       "lucide-react",
       "@floating-ui/react"
     ]
+  },
+  "tanstack-query-client": {
+    "name": "TanstackQueryClient",
+    "category": "tanstack-query",
+    "files": ["templates/scaffolds/tanstack-query"],
+    "peerDependencies": ["@tanstack/react-query"]
   }
 }

package/templates/scaffolds/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/scaffolds/tanstack-query/api-mutations.ts

@@ -0,0 +1,15 @@
+import { ModuleMutations } from "./module";
+
+export const apiMutations = {
+  module: ModuleMutations,
+};
+
+export * from "./module";
+
+/* 
+ # NOTE : here you export all the mutations from the module folder so it will be easy to import in components
+
+  const queryClient = useQueryClient();
+  const mutation_name_example = useMutation(ModuleMutations.create_query_name_example(queryClient));
+  mutation_name_example.mutate({input_name: data})
+*/

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.
+*/
+
+