docs: update documentation for custom data-fetching hooks

src/hooks/data-fetching/beer-comments/useBeerPostComments.ts

@@ -10,7 +10,7 @@ interface UseBeerPostCommentsProps {
 }
 
 /**
- * A custom React hook that fetches comments for a specific beer post.
+ * A custom hook to fetch comments for a specific beer post.
  *
  * @param props - The props object.
  * @param props.pageNum - The page number of the comments to fetch.

src/hooks/data-fetching/beer-likes/useBeerPostLikeCount.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import useSWR from 'swr';
 
 /**
- * Custom hook to fetch the like count for a beer post from the server.
+ * A custom hook to fetch the like count for a beer post from the server.
  *
  * @param beerPostId - The ID of the beer post to fetch the like count for.
  * @returns An object with the following properties:

src/hooks/data-fetching/beer-likes/useCheckIfUserLikesBeerPost.ts

@@ -5,10 +5,9 @@ import useSWR from 'swr';
 import { z } from 'zod';
 
 /**
- * A custom React hook that checks if the current user has liked a beer post by fetching
+ * A custom hook to check if the current user has liked a beer post.
- * data from the server.
  *
- * @param beerPostId The ID of the beer post to check for likes.
+ * @param beerPostId The ID of the beer post.
  * @returns An object with the following properties:
  *
  *   - `error`: The error that occurred while fetching the data.

src/hooks/data-fetching/beer-posts/useBeerPostSearch.ts

@@ -1,8 +1,9 @@
 import BeerPostQueryResult from '@/services/BeerPost/schema/BeerPostQueryResult';
 import useSWR from 'swr';
 import { z } from 'zod';
+
 /**
- * A custom React hook that searches for beer posts that match a given query string.
+ * A custom hook to search for beer posts that match a given query string.
  *
  * @param query The search query string to match beer posts against.
  * @returns An object with the following properties:

src/hooks/data-fetching/beer-posts/useBeerPosts.ts

@@ -4,7 +4,7 @@ import useSWRInfinite from 'swr/infinite';
 import { z } from 'zod';
 
 /**
- * A custom hook using SWR to fetch beer posts from the API.
+ * A custom hook to fetch beer posts from the API.
  *
  * @param options The options to use when fetching beer posts.
  * @param options.pageSize The number of beer posts to fetch per page.

src/hooks/data-fetching/beer-posts/useBeerPostsByBeerStyle.ts

@@ -1,66 +0,0 @@
-import BeerPostQueryResult from '@/services/BeerPost/schema/BeerPostQueryResult';
-import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
-import useSWRInfinite from 'swr/infinite';
-import { z } from 'zod';
-
-interface UseBeerPostsByBeerStyleParams {
-  pageSize: number;
-  beerStyleId: string;
-}
-
-const useBeerPostsByBeerStyle = ({
-  pageSize,
-  beerStyleId,
-}: UseBeerPostsByBeerStyleParams) => {
-  const fetcher = async (url: string) => {
-    const response = await fetch(url);
-    if (!response.ok) {
-      throw new Error(response.statusText);
-    }
-
-    const json = await response.json();
-    const count = response.headers.get('X-Total-Count');
-
-    const parsed = APIResponseValidationSchema.safeParse(json);
-    if (!parsed.success) {
-      throw new Error('API response validation failed');
-    }
-
-    const parsedPayload = z.array(BeerPostQueryResult).safeParse(parsed.data.payload);
-    if (!parsedPayload.success) {
-      throw new Error('API response validation failed');
-    }
-
-    const pageCount = Math.ceil(parseInt(count as string, 10) / pageSize);
-    return {
-      beerPosts: parsedPayload.data,
-      pageCount,
-    };
-  };
-
-  const { data, error, isLoading, setSize, size } = useSWRInfinite(
-    (index) =>
-      `/api/beers/styles/${beerStyleId}/beers?page_num=${
-        index + 1
-      }&page_size=${pageSize}`,
-    fetcher,
-  );
-
-  const beerPosts = data?.flatMap((d) => d.beerPosts) ?? [];
-  const pageCount = data?.[0].pageCount ?? 0;
-  const isLoadingMore = size > 0 && data && typeof data[size - 1] === 'undefined';
-  const isAtEnd = !(size < data?.[0].pageCount!);
-
-  return {
-    beerPosts,
-    pageCount,
-    size,
-    setSize,
-    isLoading,
-    isLoadingMore,
-    isAtEnd,
-    error: error as unknown,
-  };
-};
-
-export default useBeerPostsByBeerStyle;

src/hooks/data-fetching/beer-posts/useBeerPostsByBeerStyles.ts

@@ -8,6 +8,23 @@ interface UseBeerPostsByBeerStyleParams {
   beerStyleId: string;
 }
 
+/**
+ * A custom hook to fetch beer posts by beer style.
+ *
+ * @param options The options for fetching beer posts.
+ * @param options.pageSize The number of beer posts to fetch per page.
+ * @param options.beerStyleId The ID of the beer style to fetch beer posts for.
+ * @returns An object with the following properties:
+ *
+ *   - `beerPosts`: The beer posts fetched from the API.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isAtEnd`: A boolean indicating whether all data has been fetched.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `isLoadingMore`: A boolean indicating whether more data is being fetched.
+ *   - `pageCount`: The total number of pages of data.
+ *   - `setSize`: A function to set the size of the data.
+ *   - `size`: The size of the data.`
+ */
 const useBeerPostsByBeerStyle = ({
   pageSize,
   beerStyleId,

src/hooks/data-fetching/beer-posts/useBeerPostsByBrewery.ts

@@ -9,7 +9,7 @@ interface UseBeerPostsByBreweryParams {
 }
 
 /**
- * A custom hook using SWR to fetch beer posts from the API.
+ * A custom hook to fetch beer posts by brewery.
  *
  * @param options The options to use when fetching beer posts.
  * @param options.pageSize The number of beer posts to fetch per page.

src/hooks/data-fetching/beer-posts/useBeerPostsByUser.ts

@@ -8,6 +8,23 @@ interface UseBeerPostsByUserParams {
   userId: string;
 }
 
+/**
+ * A custom hook to fetch beer posts by user.
+ *
+ * @param options The options for fetching beer posts.
+ * @param options.pageSize The number of beer posts to fetch per page.
+ * @param options.userId The ID of the user to fetch beer posts for.
+ * @returns An object with the following properties:
+ *
+ *   - `beerPosts`: The beer posts fetched from the API.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isAtEnd`: A boolean indicating whether all data has been fetched.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `isLoadingMore`: A boolean indicating whether more data is being fetched.
+ *   - `pageCount`: The total number of pages of data.
+ *   - `setSize`: A function to set the size of the data.
+ *   - `size`: The size of the data.`
+ */
 const useBeerPostsByUser = ({ pageSize, userId }: UseBeerPostsByUserParams) => {
   const fetcher = async (url: string) => {
     const response = await fetch(url);

src/hooks/data-fetching/beer-posts/useBeerRecommendations.ts

@@ -9,7 +9,7 @@ interface UseBeerRecommendationsParams {
 }
 
 /**
- * A custom hook using SWR to fetch beer recommendations from the API.
+ * A custom hook to fetch beer recommendations from the API.
  *
  * @param options The options to use when fetching beer recommendations.
  * @param options.pageSize The number of beer recommendations to fetch per page.

src/hooks/data-fetching/beer-style-comments/useBeerStyleComments.ts

@@ -3,13 +3,31 @@ import APIResponseValidationSchema from '@/validation/APIResponseValidationSchem
 import { z } from 'zod';
 import useSWRInfinite from 'swr/infinite';
 
-interface UseBeerStyleCommentsProps {
+interface UseBeerStyleCommentsOptions {
   id: string;
   pageSize: number;
   pageNum: number;
 }
-
+/**
-const useBeerStyleComments = ({ id, pageSize }: UseBeerStyleCommentsProps) => {
+ * A custom hook to fetch comments for a beer style post.
+ *
+ * @param options The options for fetching comments.
+ * @param options.id The ID of the beer style to fetch comments for.
+ * @param options.pageSize The number of comments to fetch per page.
+ * @param options.pageNum The page number to fetch.
+ * @returns An object with the following properties:
+ *
+ *   - `comments`: The comments fetched from the API.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `isLoadingMore`: A boolean indicating whether more data is being fetched.
+ *   - `isAtEnd`: A boolean indicating whether all data has been fetched.
+ *   - `mutate`: A function to mutate the data.
+ *   - `pageCount`: The total number of pages of data.
+ *   - `setSize`: A function to set the size of the data.
+ *   - `size`: The size of the data.
+ */
+const useBeerStyleComments = ({ id, pageSize }: UseBeerStyleCommentsOptions) => {
   const fetcher = async (url: string) => {
     const response = await fetch(url);
 

src/hooks/data-fetching/beer-style-likes/useBeerStyleLikeCount.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import useSWR from 'swr';
 
 /**
- * Custom hook to fetch the like count for a beer style from the server.
+ * A custom hook to fetch the like count for a beer style post.
  *
  * @param beerStyleId - The ID of the beer style to fetch the like count for.
  * @returns An object with the following properties:

src/hooks/data-fetching/beer-style-likes/useCheckIfUserLikesBeerPost.ts

@@ -5,8 +5,7 @@ import useSWR from 'swr';
 import { z } from 'zod';
 
 /**
- * A custom React hook that checks if the current user has liked a beer style by fetching
+ * A custom hook to check if the current user has liked a beer style.
- * data from the server.
  *
  * @param beerStyleId The ID of the beer style to check for likes.
  * @returns An object with the following properties:

src/hooks/data-fetching/beer-styles/useBeerStyles.ts

@@ -4,7 +4,7 @@ import useSWRInfinite from 'swr/infinite';
 import { z } from 'zod';
 
 /**
- * A custom hook using SWR to fetch beer types from the API.
+ * A custom hook to fetch beer styles posts.
  *
  * @param options The options to use when fetching beer types.
  * @param options.pageSize The number of beer types to fetch per page.

src/hooks/data-fetching/brewery-comments/useBreweryPostComments.ts

@@ -9,7 +9,7 @@ interface UseBreweryPostCommentsProps {
 }
 
 /**
- * A custom React hook that fetches comments for a specific brewery post.
+ * A custom hook to fetch comments for a specific brewery post.
  *
  * @param props - The props object.
  * @param props.pageNum - The page number of the comments to fetch.

src/hooks/data-fetching/brewery-likes/useCheckIfUserLikesBreweryPost.ts

@@ -5,7 +5,7 @@ import useSWR from 'swr';
 import { z } from 'zod';
 
 /**
- * A custom React hook that checks if the current user likes a given brewery post.
+ * A custom hook to check if the current user likes a given brewery post.
  *
  * @param breweryPostId - The ID of the brewery post to check.
  * @returns An object with the following properties:

src/hooks/data-fetching/brewery-posts/useBreweryMapPagePosts.ts

@@ -3,6 +3,22 @@ import APIResponseValidationSchema from '@/validation/APIResponseValidationSchem
 import useSWRInfinite from 'swr/infinite';
 import { z } from 'zod';
 
+/**
+ * A custom hook to fetch brewery posts for the map.
+ *
+ * @param options The options to use when fetching brewery posts.
+ * @param options.pageSize The number of brewery posts to fetch per page.
+ * @returns An object with the following properties:
+ *
+ *   - `breweryPosts`: The brewery posts fetched from the API.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isAtEnd`: A boolean indicating whether all data has been fetched.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `isLoadingMore`: A boolean indicating whether more data is being fetched.
+ *   - `pageCount`: The total number of pages of data.
+ *   - `setSize`: A function to set the size of the data.
+ *   - `size`: The size of the data.
+ */
 const useBreweryMapPagePosts = ({ pageSize }: { pageSize: number }) => {
   const fetcher = async (url: string) => {
     const response = await fetch(url);

src/hooks/data-fetching/brewery-posts/useBreweryPostsByUser.ts

@@ -8,6 +8,23 @@ interface UseBreweryPostsByUserParams {
   userId: string;
 }
 
+/**
+ * A custom hook to fetch brewery posts by a specific user.
+ *
+ * @param options The options to use when fetching brewery posts.
+ * @param options.pageSize The number of brewery posts to fetch per page.
+ * @param options.userId The ID of the user to fetch brewery posts for.
+ * @returns An object with the following properties:
+ *
+ *   - `breweryPosts`: The brewery posts fetched from the API.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isAtEnd`: A boolean indicating whether all data has been fetched.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `isLoadingMore`: A boolean indicating whether more data is being fetched.
+ *   - `pageCount`: The total number of pages of data.
+ *   - `setSize`: A function to set the size of the data.
+ *   - `size`: The size of the data.
+ */
 const useBreweryPostsByUser = ({ pageSize, userId }: UseBreweryPostsByUserParams) => {
   const fetcher = async (url: string) => {
     const response = await fetch(url);

src/hooks/data-fetching/user-follows/useFollowStatus.ts

@@ -2,6 +2,17 @@ import APIResponseValidationSchema from '@/validation/APIResponseValidationSchem
 import useSWR from 'swr';
 import { z } from 'zod';
 
+/**
+ * A custom hook to check if the current user follows a given user.
+ *
+ * @param userFollowedId - The ID of the user to check.
+ * @returns An object with the following properties:
+ *
+ *   - `isFollowed`: A boolean indicating whether the current user follows the user.
+ *   - `error`: The error that occurred while fetching the data.
+ *   - `isLoading`: A boolean indicating whether the data is being fetched.
+ *   - `mutate`: A function to mutate the data.
+ */
 const useFollowStatus = (userFollowedId: string) => {
   const { data, error, isLoading, mutate } = useSWR(
     `/api/users/${userFollowedId}/is-followed`,

src/hooks/data-fetching/user-follows/useGetUsersFollowedByUser.ts

@@ -1,5 +1,5 @@
 /**
- * Custom hook using SWR for fetching users followed by a specific user.
+ * A custom hook to fetch the users followed by a given user.
  *
  * @param options - The options for fetching users.
  * @param [options.pageSize=5] - The number of users to fetch per page. Default is `5`

src/hooks/data-fetching/user-follows/useGetUsersFollowingUser.ts

@@ -9,10 +9,7 @@ interface UseGetUsersFollowingUser {
 }
 
 /**
- * Custom hook using SWR for fetching users followed by a specific user.
+ * A custom hook to fetch users following a user.
- *
- * @example
- *   const { followers, followerCount } = useGetUsersFollowingUser({ userId: '123' });
  *
  * @param options - The options for fetching users.
  * @param [options.pageSize=5] - The number of users to fetch per page. Default is `5`