chore: refactor API lib

Author: bartstc

.claude/rules/architecture.md

@@ -52,14 +52,14 @@ Each feature follows feature slice architecture patterns with four layers:
 
 - **components/** - UI components, presentational and decoupled from business logic (application) and router state. Data access is only through `providers/`.
 - **application/** - Business logic, portable state management (stores, FSMs, form validation), custom hooks. Should not depend on router state or external APIs directly (only through `providers/`).
-- **providers/** - Data fetching, external APIs, platform/SDK interactions, commands/mutations, and API type definitions (DTOs). Library-specific code (React Query, SWR, etc.) must not leak beyond this layer.
+- **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, and DTOs sourced from `src/lib/api/`. Library-specific code (React Query, etc.) must not leak beyond this layer.
 - **models/** - Domain type definitions, utilities, and type mapping functions.
 
 **Dependency rule:** `components/` and `application/` import from `models/` and `providers/`. `providers/` and `models/` have no internal feature dependencies.
 
 ## API Layer
 
-`src/lib/api/` is the global home for all HTTP logic: query/mutation hooks, loaders, query keys, and DTOs, organised by resource. Feature `providers/` do not implement API logic — they re-export selectively from `src/lib/api/` to decouple feature internals from the global API structure. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
+`src/lib/api/` is the global home for all HTTP logic: `queryOptions` factories, loaders, mutation hooks, query keys, and DTOs, organised by resource. Query files expose `queryOptions` factories (no `useQuery` hooks — hook composition belongs in `providers/`). Feature `providers/` compose hooks on top of those factories and re-export them for feature slice. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
 
 ## Key Patterns
 

.github/instructions/architecture.instructions.md

@@ -49,14 +49,14 @@ Each feature follows feature slice architecture patterns with four layers:
 
 - **components/** - UI components, presentational and decoupled from business logic (application) and router state. Data access is only through `providers/`.
 - **application/** - Business logic, portable state management (stores, FSMs, form validation), custom hooks. Should not depend on router state or external APIs directly (only through `providers/`).
-- **providers/** - Data fetching, external APIs, platform/SDK interactions, commands/mutations, and API type definitions (DTOs). Library-specific code (React Query, SWR, etc.) must not leak beyond this layer.
+- **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, and DTOs sourced from `src/lib/api/`. Library-specific code (React Query, etc.) must not leak beyond this layer.
 - **models/** - Domain type definitions, utilities, and type mapping functions.
 
 **Dependency rule:** `components/` and `application/` import from `models/` and `providers/`. `providers/` and `models/` have no internal feature dependencies.
 
-## API Layer
+### API Layer
 
-`src/lib/api/` is the global home for all HTTP logic: query/mutation hooks, loaders, query keys, and DTOs, organised by resource. Feature `providers/` do not implement API logic — they re-export selectively from `src/lib/api/` to decouple feature internals from the global API structure. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
+`src/lib/api/` is the global home for all HTTP logic: `queryOptions` factories, loaders, mutation hooks, query keys, and DTOs, organised by resource. Query files expose `queryOptions` factories (no `useQuery` hooks — hook composition belongs in `providers/`). Feature `providers/` compose hooks on top of those factories and re-export them for feature slice. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
 
 ### Key Patterns
 

src/features/carts/providers/use-cart-products-query.ts

@@ -1,4 +1,10 @@
-export {
-  useCartProductsQuery,
-  cartProductsLoader,
-} from "@/lib/api/carts/{cart-id}/cart-products-query";
+import { keepPreviousData } from "@tanstack/react-query";
+
+import { cartProductsQuery } from "@/lib/api/carts/{cart-id}/cart-products-query";
+import { useQuery } from "@/lib/query";
+
+export { cartProductsLoader } from "@/lib/api/carts/{cart-id}/cart-products-query";
+export { cartProductsQuery };
+
+export const useCartProductsQuery = (cartId: string) =>
+  useQuery({ ...cartProductsQuery(cartId), placeholderData: keepPreviousData });

src/features/products/providers/product-query.ts

@@ -1,5 +1,8 @@
-export {
-  getProductQuery,
-  useProductQuery,
-  productLoader,
-} from "@/lib/api/products/{product-id}/product-query";
+import { productQuery } from "@/lib/api/products/{product-id}/product-query";
+import { useQuery } from "@/lib/query";
+
+export { productLoader } from "@/lib/api/products/{product-id}/product-query";
+export { productQuery };
+
+export const useProductQuery = (productId: string) =>
+  useQuery(productQuery(productId));

src/features/products/providers/products-query.ts

@@ -1,4 +1,9 @@
-export {
-  useProductsQuery,
-  productsLoader,
-} from "@/lib/api/products/products-list/products-list-query";
+import { productsQuery } from "@/lib/api/products/products-list/products-list-query";
+import { useQuery } from "@/lib/query";
+import type { QueryParams } from "@/types/query-params";
+
+export { productsLoader } from "@/lib/api/products/products-list/products-list-query";
+export { productsQuery };
+
+export const useProductsQuery = (params?: QueryParams) =>
+  useQuery(productsQuery(params));

src/lib/api/carts/{cart-id}/cart-products-query.ts

@@ -1,8 +1,8 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { queryOptions } from "@tanstack/react-query";
 
-import { getProductQuery } from "@/lib/api/products/{product-id}/product-query";
+import type { ProductDto } from "@/lib/api/products/{product-id}/product-dto";
 import { httpService } from "@/lib/http";
-import { queryClient, useQuery } from "@/lib/query";
+import { queryClient } from "@/lib/query";
 
 import { cartQueryKeys } from "../cart-query-keys";
 
@@ -14,39 +14,32 @@ interface IResponse {
   products: CartProductDto[];
 }
 
-const getCartProductsQuery = (cartId: string) => ({
-  queryKey: cartQueryKeys.products(cartId),
-  queryFn: async (): Promise<IResponse> => {
-    const cart = await httpService.get<CartDto>(`carts/${cartId}`);
-
-    const productPromises = cart.products.map((product) =>
-      getProductQuery(product.productId.toString()).queryFn()
-    );
-
-    const products = await Promise.all(productPromises);
-
-    return {
-      date: cart.date,
-      products: products.map((product) => ({
-        ...product,
-        quantity:
-          cart.products.find(
-            (cartProduct) => cartProduct.productId === product.id
-          )?.quantity ?? 0,
-      })),
-    };
-  },
-});
-
-export const useCartProductsQuery = (
-  cartId: string,
-  options?: UseQueryOptions<IResponse>
-) => {
-  return useQuery({
-    ...getCartProductsQuery(cartId),
-    ...options,
+const cartProductsQuery = (cartId: string) =>
+  queryOptions({
+    queryKey: cartQueryKeys.products(cartId),
+    queryFn: async (): Promise<IResponse> => {
+      const cart = await httpService.get<CartDto>(`carts/${cartId}`);
+
+      const products = await Promise.all(
+        cart.products.map((product) =>
+          httpService.get<ProductDto>(`products/${product.productId}`)
+        )
+      );
+
+      return {
+        date: cart.date,
+        products: products.map((product) => ({
+          ...product,
+          quantity:
+            cart.products.find(
+              (cartProduct) => cartProduct.productId === product.id
+            )?.quantity ?? 0,
+        })),
+      };
+    },
   });
-};
 
 export const cartProductsLoader = async (cartId: string) =>
-  queryClient.ensureQueryData(getCartProductsQuery(cartId));
+  queryClient.ensureQueryData(cartProductsQuery(cartId));
+
+export { cartProductsQuery };

src/lib/api/carts/{cart-id}/cart-query.ts

@@ -1,26 +1,18 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { queryOptions } from "@tanstack/react-query";
 
 import { httpService } from "@/lib/http";
-import { queryClient, useQuery } from "@/lib/query";
+import { queryClient } from "@/lib/query";
 
 import { cartQueryKeys } from "../cart-query-keys";
 
 import type { CartDto } from "./cart-dto";
 
-export const getCartQuery = (cartId: string) => ({
-  queryKey: cartQueryKeys.detail(cartId),
-  queryFn: (): Promise<CartDto> => httpService.get<CartDto>(`carts/${cartId}`),
-});
-
-export const useCartQuery = (
-  cartId: string,
-  options?: UseQueryOptions<CartDto>
-) => {
-  return useQuery({
-    ...getCartQuery(cartId),
-    ...options,
+export const cartQuery = (cartId: string) =>
+  queryOptions({
+    queryKey: cartQueryKeys.detail(cartId),
+    queryFn: (): Promise<CartDto> =>
+      httpService.get<CartDto>(`carts/${cartId}`),
   });
-};
 
 export const cartLoader = async (cartId: string) =>
-  queryClient.ensureQueryData(getCartQuery(cartId));
+  queryClient.ensureQueryData(cartQuery(cartId));

src/lib/api/products/products-list/products-list-query.ts

@@ -1,8 +1,8 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { queryOptions } from "@tanstack/react-query";
 
 import { buildUrl } from "@/lib/build-url";
 import { httpService } from "@/lib/http";
-import { queryClient, useQuery } from "@/lib/query";
+import { queryClient } from "@/lib/query";
 import type { Meta } from "@/types/meta";
 import type { QueryParams } from "@/types/query-params";
 
@@ -16,27 +16,20 @@ interface ICollection {
   meta: Meta;
 }
 
-const getProductsQuery = (params: QueryParams = defaultParams) => ({
-  queryKey: productsQueryKeys.list(params),
-  queryFn: (): Promise<ICollection> =>
-    httpService.get<ProductDto[]>(buildUrl("products", params)).then((res) => ({
-      products: res,
-      meta: {
-        ...params,
-        total: 20,
-      },
-    })),
-});
-
-export const useProductsQuery = (
-  params: QueryParams = defaultParams,
-  options?: Omit<UseQueryOptions<ICollection>, "queryKey" | "queryFn">
-) => {
-  return useQuery({
-    ...getProductsQuery(params),
-    ...options,
+export const productsQuery = (params: QueryParams = defaultParams) =>
+  queryOptions({
+    queryKey: productsQueryKeys.list(params),
+    queryFn: (): Promise<ICollection> =>
+      httpService
+        .get<ProductDto[]>(buildUrl("products", params))
+        .then((res) => ({
+          products: res,
+          meta: {
+            ...params,
+            total: 20,
+          },
+        })),
   });
-};
 
 export const productsLoader = async (params: QueryParams = defaultParams) =>
-  queryClient.ensureQueryData(getProductsQuery(params));
+  queryClient.ensureQueryData(productsQuery(params));

src/lib/api/products/{product-id}/product-query.ts

@@ -1,27 +1,18 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { queryOptions } from "@tanstack/react-query";
 
 import { httpService } from "@/lib/http";
-import { queryClient, useQuery } from "@/lib/query";
+import { queryClient } from "@/lib/query";
 
 import { productsQueryKeys } from "../products-query-keys";
 
 import type { ProductDto } from "./product-dto";
 
-export const getProductQuery = (productId: string) => ({
-  queryKey: productsQueryKeys.detail(productId),
-  queryFn: (): Promise<ProductDto> =>
-    httpService.get<ProductDto>(`products/${productId}`),
-});
-
-export const useProductQuery = (
-  productId: string,
-  options?: UseQueryOptions<ProductDto>
-) => {
-  return useQuery({
-    ...getProductQuery(productId),
-    ...options,
+export const productQuery = (productId: string) =>
+  queryOptions({
+    queryKey: productsQueryKeys.detail(productId),
+    queryFn: (): Promise<ProductDto> =>
+      httpService.get<ProductDto>(`products/${productId}`),
   });
-};
 
 export const productLoader = async (productId: string) =>
-  queryClient.ensureQueryData(getProductQuery(productId));
+  queryClient.ensureQueryData(productQuery(productId));

src/pages/Products/index.tsx

@@ -1,5 +1,4 @@
 import { Button } from "@chakra-ui/react";
-import { keepPreviousData } from "@tanstack/react-query";
 import { Settings } from "lucide-react";
 import { useState } from "react";
 
@@ -19,9 +18,7 @@ const ProductsPage = () => {
   const t = useTranslations("pages.products");
 
   const [params, setParams] = useState<QueryParams>(defaultParams);
-  const { data, isFetching } = useProductsQuery(params, {
-    placeholderData: keepPreviousData,
-  });
+  const { data, isFetching } = useProductsQuery(params);
 
   const noMoreProducts = data.meta.total <= params.limit;