pejay-ui 1.2.2 → 1.3.1

package/templates/scaffolds/redux-store/slices/one.slice.ts

@@ -0,0 +1,202 @@
+import { createSlice } from "@reduxjs/toolkit";
+
+const initialState = {
+  /*  
+   status: "idle" | "loading" | "error" | "success",  
+  */
+  oneData: "",
+  error: "",
+  status: "idle",
+  isLoading: false,
+  isError: false,
+  meta: {
+    requiresAuth: true,
+  },
+};
+
+/* 
+
+import { createAsyncThunk } from "@reduxjs/toolkit";
+
+# NOTE : it can also have asyncThunks to handle async logic like api calls
+
+export const oneAsync = createAsyncThunk(
+  "one/oneAsync",
+  async (_ ,{rejectWithValue,signal}) => {
+    try {
+      const response = await axios.get("backend_api_route",{signal});  
+      return response.data;
+    } catch (error:any) {
+      return rejectWithValue(error.response.data);
+    }
+  }
+);
+
+----------------------------------------------------------------
+(method 1)
+# NOTE : and use it 
+
+const dispatch = useAppDispatch();
+
+const [isLoading, setIsLoading] = useState(false);
+const handleClick = async () => {
+  try {
+      setIsLoading(true);
+    const data = await dispatch(oneAsync()).unwrap();
+    console.log(data);
+  } catch (error) {
+    console.log(error);
+  }finally{
+    setIsLoading(false);
+    dispatch(setStatus("idle"));
+
+  }
+};
+
+
+
+----------------------------------------------------------------
+(method 2)
+# NOTE : other way to call it by using the slice state variable to store data in that and call from there 
+
+in this case we call it via useSelector to get the data
+
+useEffect(() => {
+  dispatch(oneAsync());
+}, [dispatch]);
+
+
+-----------------------------------------------------------------
+# NOTE :
+
+const {status,isloading,isError} = useOne();
+
+useEffect(() => {
+ if(status === "idle"){
+  dispatch(oneAsync());
+ }
+}, [dispatch]);
+
+in this either i manlually make status idel again to dispatch 
+
+or 
+
+useEffect(() => {
+  dispatch(fetchUsers(page));
+}, [page, dispatch]);
+
+use page for some kind of trigger that keep preventing from unwanted api calls
+
+only a page reload or setting the status manually to idle will make the api call again
+
+# NOTE : this above can be also done in (method 1) of calling by removing useState or we can make useState for api loading/error/status etc but that is messy and cannot be handel outside comp or doing it inside hook is also not good as each hook call is treated as new instance  so best way is to either make inital states and handel via reducers custom ones or use extra reducers which is the best way to handel this. only one thing we can do is spread our manipulation data across 3/4 different steps 
+1. inside fullfill extra reducer (for heavy manipulation)
+2. inside selector (memoised data can do some manipulation )
+3. inside hook (optional or for component specifics extraction or manipulation)
+4. inside component (optional for specific element or ui level requirement)
+
+there is another way of data flow 
+
+1. call api , do heavy manipulation in fullfilled state, store data in state
+2. call data in hook (for comp based manipulation further can use useMemo here to avoid unwanted processing of same data)
+3. call in component (if required do further manipulation )
+
+useMemo only preserve manipulated data to save manipulation from rerendering of the component itself not unmount / mount of comp 
+
+in mounting useMemo / hook will lose instances and cached data is destroyed 
+
+When createSelector is useful
+When you want to keep raw data in Redux.
+*/
+
+const oneSlice = createSlice({
+  name: "one",
+  initialState,
+
+  // Manually handling async logic via reducers
+  reducers: {
+    setOne: (state, action) => {
+      state.oneData = action.payload;
+    },
+    setStatus: (state, action) => {
+      state.status = action.payload;
+    },
+    setError: (state, action) => {
+      state.isError = true;
+      state.error = action.payload;
+      state.status = "error";
+    },
+    setIsLoading: (state, action) => {
+      state.isLoading = action.payload;
+      state.status = "pending";
+      state.isError = false;
+      state.error = "";
+    },
+
+    /*
+
+    there is 2 ways to make a async call in redux
+
+    1. Manually handling async logic via reducers
+    2. Using extraReducers
+
+    usually we use extra reducers because is easy what more we can use is use status state for preventing unwnted api calls
+
+
+
+    # NOTE : extraReducers are used to handle async logic like api calls
+    extrareducers : {
+        builder
+        .addCase(oneAsync.pending, (state) => {
+                state.isLoading = true;
+            })
+        .addCase(oneAsync.fulfilled, (state, action) => {
+                state.isLoading = false;
+                const processedData = action.payload;
+                // here manipulates data accordingly and handover to selector.
+                state.oneData = processedData;
+                state.status = "idle";
+            })
+        .addCase(oneAsync.rejected, (state, action) => {
+                state.isLoading = false;
+                state.isError = true;
+                state.error = action.payload;
+                state.status = "error";
+            })
+    }
+
+    */
+  },
+});
+
+export const { setOne } = oneSlice.actions;
+export default oneSlice.reducer;
+
+/* 
+
+a slice has state, reducers, and actions.
+a state => data 
+a reducers => logic on how data changes / basically data manipulation
+a actions => dispatchers to change the data
+
+------------------------------------------------------------
+# NOTE : to dispatch an action
+
+import { useDispatch } from "react-redux";
+import { setOne } from "../slices/one.slice";
+const dispatch = useDispatch();
+dispatch(setOne("hello"));
+
+its basically calling the function defined in reducers with the data
+
+------------------------------------------------------------
+# NOTE : to call a state to get the data in comp we 
+
+import { useSelector } from "react-redux";
+import { type RootState } from "../index";
+const one = useSelector((state: RootState) => state.one.oneData);
+
+this is basically accessing the value from the store.
+
+
+*/

package/templates/scaffolds/redux-store/slices/two.slice.ts

@@ -0,0 +1,21 @@
+import { createSlice } from "@reduxjs/toolkit";
+
+const initialState = {
+  twoData: "",
+  meta: {
+    requiresAuth: true,
+  },
+};
+
+const twoSlice = createSlice({
+  name: "two",
+  initialState,
+  reducers: {
+    setTwo: (state, action) => {
+      state.twoData = action.payload;
+    },
+  },
+});
+
+export const { setTwo } = twoSlice.actions;
+export default twoSlice.reducer;

package/templates/scaffolds/redux-store/store.ts

@@ -0,0 +1,38 @@
+import { configureStore } from "@reduxjs/toolkit";
+import {
+  persistStore,
+  FLUSH,
+  REHYDRATE,
+  PAUSE,
+  PERSIST,
+  PURGE,
+  REGISTER,
+} from "redux-persist";
+import rootReducer from "./reducers";
+
+export const store = configureStore({
+  reducer: rootReducer,
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware({
+      serializableCheck: {
+        ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
+      },
+    }) /* .concat(middleware_name) */,
+});
+export const persistor = persistStore(store);
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+export default store;
+
+/* 
+
+Example usage:
+
+import { Provider } from "react-redux";
+import { store } from "./store";
+<Provider store={store}>
+    <App />
+</Provider>
+    
+    
+    */

package/templates/scaffolds/rtk-query/baseApi.ts

@@ -0,0 +1,24 @@
+import { createApi } from "@reduxjs/toolkit/query/react";
+import { baseQuery } from "./baseQuery";
+import { queryTags } from "./queryTags";
+export const baseApi = createApi({
+  reducerPath: "baseApi",
+  baseQuery: baseQuery,
+  tagTypes: queryTags,
+  /* 
+  keepUnusedDataFor: Infinity   //data will never be garbage collected
+  refetchOnReconnect: true,   //refetch on network reconnect
+  refetchOnMountOrArgChange: false,  //refetch on mount or when args change
+  refetchOnFocus: false,      //refetch on focus to tab
+   */
+  endpoints: () => ({}),
+});
+
+/* 
+
+* in reducers.ts of redux store
+const apiReducers = {
+  [baseApi.reducerPath]: baseApi.reducer,
+};
+
+*/

package/templates/scaffolds/rtk-query/baseQuery.ts

@@ -0,0 +1,12 @@
+import { fetchBaseQuery } from "@reduxjs/toolkit/query";
+
+export const baseQuery = fetchBaseQuery({
+  baseUrl: "http://localhost:5001",
+  prepareHeaders: (headers) => {
+    const token = localStorage.getItem("token");
+    if (token) {
+      headers.set("Authorization", `Bearer ${token}`);
+    }
+    return headers;
+  },
+});

package/templates/scaffolds/rtk-query/endpoints/api.one.ts

@@ -0,0 +1,82 @@
+import { baseApi } from "../baseApi";
+import { invalidateTagIdOnSuccess } from "../queryTags";
+
+export const apiOne = baseApi.injectEndpoints({
+  endpoints: (builder) => ({
+    // very basic fetch function
+    fetchData: builder.query({
+      query: () => "/data",
+      providesTags: [],
+    }),
+    // with params method 1
+    fetchData2: builder.query({
+      query: ({ id }) => `/data/${id}`,
+      providesTags: (_result, error, { id }) =>
+        error ? [] : [{ type: "Data", id }],
+    }),
+    // with params method 2
+    fetchData3: builder.query({
+      query: ({ id, name }) => ({
+        url: `/data`,
+        method: "GET",
+        params: { id, name },
+      }),
+      // manipulate response before it is sent to the component
+      transformResponse: (response) => {
+        /*  manipulate here */
+        return response.data;
+      },
+      providesTags: [],
+    }),
+
+    /* =================================== */
+
+    postData: builder.mutation({
+      query: (body) => ({
+        url: "/data",
+        method: "POST",
+        body,
+      }),
+      invalidatesTags: invalidateTagIdOnSuccess("Data"),
+    }),
+  }),
+});
+
+export const {
+  useFetchDataQuery,
+  useFetchData2Query,
+  useFetchData3Query,
+  usePostDataMutation,
+} = apiOne;
+
+/*
+
+    ? Query Calls
+    
+    *call in components
+    const { data, isLoading, isFetching, isError, error } = useFetchDataQuery();
+
+    *refetch every 5 seconds
+    const { data } = useFetchDataQuery({},{
+    pollingInterval: 5000, 
+    });
+
+    *get specific data from array of objects
+    const { user } = useFetchDataQuery({},{  
+    selectFromResult: ({ data }) => ({
+        user: data?.find((u) => u.id === 2),
+    }),
+    });
+
+
+    // ==================================== //
+
+    ? MUTATIONS
+
+    * call in components
+    const [postData] = usePostDataMutation();
+    await postData({ name: "John",});
+
+
+
+  */

package/templates/scaffolds/rtk-query/endpoints/index.ts

@@ -0,0 +1 @@
+export * from "./api.one";

package/templates/scaffolds/rtk-query/middlewares.ts

@@ -0,0 +1,11 @@
+import { baseApi } from "./baseApi";
+
+export const apiMiddleware = [baseApi.middleware];
+
+/* 
+
+    *in store.ts
+middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(...apiMiddleware)
+
+*/

package/templates/scaffolds/rtk-query/queryTags.ts

@@ -0,0 +1,13 @@
+export const queryTags = ["Data"] as const;
+
+type TagType = (typeof queryTags)[number];
+
+/** Invalidate tag ids only when the mutation succeeds (skip on error). */
+export function invalidateTagIdOnSuccess(...types: TagType[]) {
+  return (
+    _result: unknown,
+    error: unknown,
+    arg: { id: string | number },
+  ) =>
+    error ? [] : types.map((type) => ({ type, id: arg.id }));
+}

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

@@ -1,68 +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>
-  );
-}
-```
-*/
-
-
+/* 
+#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-queries.ts

@@ -58,28 +58,9 @@ return <ModuleComponent data={data} />;
 }
 
 # NOTE : Wrapping
- <ErrorBoundary fallback={<div>Failed to load Stats</div>}>
 <Suspense fallback={<FallBackComponent />}>
   <ModuleComponent />
 </Suspense>
-  </ErrorBoundary>
-
-  this is comp level error boundary in case of api fails then suspense bubbeling up will touch this first and stops 
-  in case this is not present then the router level
-  so in this way we can only show a particaular comp failed to load not entore page
-
-
-
-
-
-  Manually (Option A - useQuery):
-
-Code: if (error) return <ErrorComponent />
-Behavior: Bypasses Error Boundaries. Component-level and router-level boundaries never trigger.
-Automatically (Option B - useSuspenseQuery or useQuery with throwOnError: true):
-
-Code: Component throws the error during render.
-Behavior: The error bubbles up. It triggers the nearest Error Boundary (either your component-level boundary if you wrapped it, or falls back to the router-level boundary).
 
 ---------------------------------------------------------------------------------------------------
 

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

@@ -9,6 +9,10 @@ export async function apiRequest<T>(
   // const token = typeof window !== "undefined" ? localStorage.getItem("token") : null;
   const token = null;
 
+  /*
+  # NOTE: RequestInit options are spread first so each call can pass signal, method, body, or headers.
+  The final headers spread lets a specific request override defaults when an endpoint needs it.
+  */
   const response = await fetch(`${API_CONFIG.baseUrl}${endpoint}`, {
     ...options,
     headers: {
@@ -18,6 +22,10 @@ export async function apiRequest<T>(
     },
   });
 
+  /*
+  # NOTE: This template assumes every successful response returns JSON.
+  If your API uses 204 No Content or empty delete responses, guard response.status before calling json().
+  */
   if (!response.ok) throw new Error(`Error Code ${response.status}`);
   return (await response.json()) as T;
 }

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

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