pjdev2d-cli 1.0.4 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pjdev2d-cli",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "description": "CLI to install reusable React components like shadcn/ui",
   "main": "bin/cli.js",
@@ -23,6 +23,7 @@
     "@babel/core": "^7.29.0",
     "@babel/preset-react": "^7.28.5",
     "@babel/preset-typescript": "^7.29.7",
+    "@tanstack/react-query": "^5.100.14",
     "@types/react": "^19.2.14",
     "clsx": "^2.1.1",
     "commander": "^14.0.3",

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

@@ -0,0 +1,85 @@
+/* 
+#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";
+
+//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}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...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/tanstack-query/services/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/tanstack-query/services/module/keys.ts

@@ -0,0 +1,13 @@
+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
+ */

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

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

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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,18 @@
+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/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/tanstack-query/services/queries.ts

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