ghcopilot-hub 1.0.0

package/hub/skills/tanstack/references/resilience-patterns.md

@@ -0,0 +1,110 @@
+# Resilience Patterns (TanStack Flow)
+
+Load this file when implementing async UX behavior, route-level error handling, or mutation failure feedback.
+
+## 1) Suspense + Skeleton for Initial Route Data
+
+Use this when route data is preloaded with `ensureQueryData`.
+
+```tsx
+import { Suspense } from "react";
+
+import { ProductListPage } from "@/presentation/product/ProductList.page";
+import { ProductListSkeleton } from "@/presentation/product/components/ProductListSkeleton";
+
+export const ProductListWithFallback = () => {
+  return (
+    <Suspense fallback={<ProductListSkeleton />}>
+      <ProductListPage />
+    </Suspense>
+  );
+};
+```
+
+Guidelines:
+
+- Skeleton shape should mirror real layout to avoid jarring transitions.
+- Do not add route-initial `isLoading` branches in the page if Suspense already wraps it.
+
+## 2) Route Error Boundary (404 vs 500 + Retry)
+
+Use this for routes that fetch remote data in `loader`.
+
+```tsx
+import { createFileRoute, useRouter } from "@tanstack/react-router";
+
+import { productQueries } from "@/application/product/product.queries";
+import { NotFoundPage } from "@/presentation/shared/components/NotFoundPage";
+import { RouteErrorPage } from "@/presentation/shared/components/RouteErrorPage";
+
+const isNotFoundError = (error: unknown) => error instanceof Error && error.message.includes("404");
+
+function ProductsErrorBoundary({ error }: { error: unknown }) {
+  const router = useRouter();
+
+  if (isNotFoundError(error)) {
+    return <NotFoundPage />;
+  }
+
+  return <RouteErrorPage title="Unable to load products" onRetry={() => router.invalidate()} />;
+}
+
+export const Route = createFileRoute("/products")({
+  loader: async ({ context: { queryClient }, params }) => {
+    await queryClient.ensureQueryData(productQueries.detail(params.productId));
+  },
+  errorComponent: ProductsErrorBoundary,
+  component: ProductsPage,
+});
+```
+
+Guidelines:
+
+- Throw from loader to boundary instead of swallowing errors.
+- Classify not-found paths separately from generic failures.
+- Retry should invalidate route/query state, not force full page reload.
+
+## 3) Mutation Error Feedback without Page Crash
+
+Use this for write operations (forms, toggles, destructive actions).
+
+```typescript
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { productKeys } from "@/application/product/product.queries";
+import { ProductRepository } from "@/infrastructure/product/product.repository";
+
+export const useUpdateProduct = (
+  onSuccessFeedback: (message: string) => void,
+  onErrorFeedback: (message: string) => void
+) => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ProductRepository.update,
+    onSuccess: async (updated) => {
+      await queryClient.invalidateQueries({
+        queryKey: productKeys.detail(updated.id),
+      });
+      onSuccessFeedback("Product updated");
+    },
+    onError: () => {
+      onErrorFeedback("Failed to update product. Please retry.");
+    },
+  });
+};
+```
+
+Guidelines:
+
+- Keep user-entered state when mutation fails.
+- Keep feedback adapters (toast/snackbar) in Presentation and inject callbacks.
+- Prefer focused feedback (toast/inline message) over global crash UI.
+- Retry should be user-driven and explicit.
+
+## Decision Checklist
+
+- Is this route-initial data? Use Suspense + boundary.
+- Is this a user write action? Use mutation `onError` feedback.
+- Is this a recoverable not-found case? Route-level typed not-found UI.
+- Is this transient infra failure? Show retry action and preserve user context.

package/hub/skills/tanstack/references/suspense-consumption-examples.md

@@ -0,0 +1,82 @@
+# Suspense Consumption Examples
+
+Use these examples in `src/application/{feature}/hooks` and `src/presentation/{feature}`.
+
+## A. Application Hook for Route Search Data
+
+```typescript
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { getRouteApi } from "@tanstack/react-router";
+
+import { productQueries } from "@/application/product/product.queries";
+import { usePreferencesStore } from "@/application/product/store/preferences.store";
+
+const productsRouteApi = getRouteApi("/products/");
+
+export const useProductsFromRoute = () => {
+  const search = productsRouteApi.useSearch();
+  const storeId = usePreferencesStore((state) => state.storeId);
+
+  if (!storeId) {
+    throw new Error("storeId is required to fetch products");
+  }
+
+  return useSuspenseQuery(productQueries.list(storeId, search));
+};
+```
+
+## B. Presentation Page Consuming Application Hook
+
+```tsx
+import { useProductsFromRoute } from "@/application/product/hooks/useProductsFromRoute";
+
+export const ProductListPage = () => {
+  const { data } = useProductsFromRoute();
+
+  return (
+    <section>
+      <h1>Products</h1>
+      <ul>
+        {data.items.map((product) => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+    </section>
+  );
+};
+```
+
+## C. Partial Refresh Pattern
+
+When the page has route-critical data and local UI interactions:
+
+- Keep initial data preload in loader + `ensureQueryData`.
+- Use query-keyed local controls for client-side refetches.
+- Avoid returning to manual `isLoading` guards for first render.
+
+## D. Suspense Rules
+
+- Prefer Suspense path for first route render data.
+- Keep error handling in route boundaries or route-level components.
+- Reserve direct presentation-level `useSuspenseQuery` for very simple pages.
+
+## E. Route Entry Fallback Composition
+
+```tsx
+import { Suspense } from "react";
+
+import { ProductListPage } from "@/presentation/product/ProductList.page";
+import { ProductListSkeleton } from "@/presentation/product/components/ProductListSkeleton";
+
+export const ProductListRouteView = () => (
+  <Suspense fallback={<ProductListSkeleton />}>
+    <ProductListPage />
+  </Suspense>
+);
+```
+
+Guidelines:
+
+- Keep fallback shape aligned to page layout.
+- Avoid parallel manual `isLoading` branches for the same initial route data.
+- See [resilience-patterns.md](resilience-patterns.md) for error boundary and retry patterns.

package/hub/skills/tanstack-query/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: tanstack-query
+description: >
+  Advanced TanStack Query v5 extensions. Trigger: when implementing advanced Query patterns, v5 migrations, cache
+  optimizations, mutation lifecycle handling, or query error propagation strategies.
+license: Apache-2.0
+metadata:
+  author: jmgomezdev
+  version: "1.0"
+---
+
+## Required Base
+
+This skill **always** applies **after** the tanstack skill and **never** contradicts it.
+
+- Direct reference: use the tanstack skill as the mandatory foundation.
+- Everything not mentioned here follows tanstack rules.
+
+## Objective
+
+Provide advanced rules, v5 issue prevention, and cache optimization patterns that complement the
+“render-as-you-fetch” flow defined in tanstack.
+
+## Dependencies
+
+- Base skill: tanstack
+- Packages: @tanstack/react-query
+
+## Render-as-you-fetch Alignment (tanstack)
+
+This skill **extends** the render-as-you-fetch flow defined in the tanstack skill:
+
+- Define `queryOptions` / `infiniteQueryOptions` in Application.
+- Use Router loaders with `queryClient.ensureQueryData` / `ensureInfiniteQueryData`.
+- Prefer consuming in Presentation via an Application hook that wraps `useSuspenseQuery` /
+  `useSuspenseInfiniteQuery`. Use direct hooks only for very simple cases.
+- Never fetch server data in `useEffect`.
+
+## References
+
+- Base tanstack skill: [.github/skills/tanstack/SKILL.md](../tanstack/SKILL.md)
+- Advanced patterns and hooks: [references/advanced-hooks.md](references/advanced-hooks.md)
+- Cache strategies: [references/cache-strategies.md](references/cache-strategies.md)
+- Best practices: [references/best-practices.md](references/best-practices.md)
+- Common patterns: [references/common-patterns.md](references/common-patterns.md)
+- Top errors & fixes: [references/top-errors.md](references/top-errors.md)
+- Resilience and mutations: [references/resilience-and-mutations.md](references/resilience-and-mutations.md)
+- TypeScript patterns: [references/typescript.md](references/typescript.md)
+- v4 → v5 migration: [references/migration-v5.md](references/migration-v5.md)
+- Testing: [references/testing.md](references/testing.md)
+
+## Reference Router (Mandatory Loading)
+
+Loading protocol:
+
+1. Pick one scenario first.
+2. MANDATORY: read only the selected reference before implementing.
+3. Do NOT load all references by default.
+4. If blocked, load exactly one additional reference.
+
+| Scenario                                                                     | MANDATORY Reference                                                              | Do NOT Load (unless needed) |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------- |
+| Advanced hook composition (`useQueries`, `useMutationState`, infinite hooks) | [references/advanced-hooks.md](references/advanced-hooks.md)                     | `migration-v5.md`           |
+| Cache lifetimes, invalidation, refetch strategy                              | [references/cache-strategies.md](references/cache-strategies.md)                 | `migration-v5.md`           |
+| v5 migration and API breakages                                               | [references/migration-v5.md](references/migration-v5.md)                         | `advanced-hooks.md`         |
+| Query errors, callback confusion, common pitfalls                            | [references/top-errors.md](references/top-errors.md)                             | `testing.md`                |
+| Mutation resilience and feedback ownership                                   | [references/resilience-and-mutations.md](references/resilience-and-mutations.md) | `migration-v5.md`           |
+| Query typing constraints and TS inference                                    | [references/typescript.md](references/typescript.md)                             | `cache-strategies.md`       |
+
+## Compatibility Checklist with tanstack
+
+Before applying this skill, confirm:
+
+1. Use of queryOptions and loaders per tanstack.
+2. Object syntax in hooks.
+3. Query keys as arrays.
+4. Suspense + loaders for required data.
+
+## Quick Application (Summary)
+
+- `useMutationState` for global tracking.
+- `networkMode` for offline/PWA.
+- `useQueries` with `combine` for aggregated parallel results.
+- `infiniteQueryOptions` and `maxPages` for efficient pagination.
+- v5 issue prevention (removed callbacks, `gcTime`, `isPending`).
+
+## Essential Rules (Must)
+
+- Use object syntax and array query keys everywhere.
+- Keep route-required data in the tanstack flow (Application `queryOptions` → Loader `ensureQueryData` →
+  Presentation `useSuspenseQuery`).
+- Set `staleTime` by data volatility and `gcTime` by revisit frequency.
+- Invalidate with precise keys after mutations; use `refetchType: 'all'` only when inactive queries must refetch.
+- Optimistic updates require: `cancelQueries` → snapshot → optimistic `setQueryData` → rollback on error →
+  invalidate on settle.
+- Infinite queries must set `initialPageParam`; `maxPages` requires bi-directional pagination.
+- Use `useQueries` for optional/secondary data, not required route data.
+- Use `prefetchQuery` only for optional navigation (hover/background), never for required route data.
+- Keep mutation feedback layer-safe: inject feedback callbacks or return mutation state; do not import presentation
+  toasts in Application hooks.
+
+## TanStack Query v5 — Critical Rules, Issues, and Anti‑Patterns
+
+> These rules **extend** the tanstack skill. If there is a conflict, tanstack wins.
+
+### Critical Rules (Always Do)
+
+✅ Use object syntax in all hooks:
+
+```tsx
+useQuery({ queryKey, queryFn, ...options });
+useMutation({ mutationFn, ...options });
+```
+
+✅ Query keys always as arrays:
+
+```tsx
+queryKey: ["todos"];
+queryKey: ["todos", id];
+queryKey: ["todos", { filter }];
+```
+
+✅ Configure `staleTime` appropriately for the use case.
+
+✅ Use `isPending` for initial loading state.
+
+✅ Always throw `Error` in `queryFn` on failure.
+
+✅ Invalidate queries after mutations with `queryClient.invalidateQueries`.
+
+✅ Use `queryOptions` for reusable patterns.
+
+✅ Use `gcTime`, not `cacheTime`.
+
+### Forbidden (Never Do)
+
+❌ v4 syntax (array/function).
+
+❌ Callbacks in queries (`onSuccess`, `onError`, `onSettled`) - this does not apply to mutations.
+
+❌ `cacheTime`, `isLoading` for initial state, `keepPreviousData`, `useErrorBoundary`.
+
+❌ Using `enabled` with `useSuspenseQuery`.
+
+❌ Omitting `initialPageParam` in infinite queries.
+
+❌ Relying on `refetchOnMount: false` for errored queries (use `retryOnMount: false`).
+
+### Known Issues and Prevention
+
+#### #2 Query callbacks removed
+
+- **Problem:** callbacks do not exist in v5 queries.
+- **Prevention:** use `useEffect` with `data`.
+- **Note:** mutation callbacks remain valid and are expected for optimistic flows and feedback.
+
+#### #3 `status: loading` → `pending`
+
+- **Problem:** UI out of sync.
+- **Prevention:** use `isPending` for initial load.
+
+#### #4 `cacheTime` → `gcTime`
+
+- **Problem:** type errors.
+- **Prevention:** replace with `gcTime`.
+
+#### #5 `useSuspenseQuery` + `enabled`
+
+- **Problem:** `enabled` not available.
+- **Prevention:** conditional rendering outside the hook.
+
+#### #6 `initialPageParam` required
+
+- **Problem:** type errors.
+- **Prevention:** set `initialPageParam` explicitly.
+
+#### #7 `keepPreviousData` removed
+
+- **Prevention:** `placeholderData: keepPreviousData`.
+
+#### #8 Default Error type
+
+- **Prevention:** throw `Error` or type the error explicitly.
+
+#### #12 Mutation callback signature change (v5.89.0+)
+
+- **Problem:** callbacks receive 4 parameters.
+- **Prevention:** use `(data, variables, onMutateResult, context)` signature.
+
+#### #13 Readonly query keys break partial matching (v5.90.8)
+
+- **Prevention:** upgrade to v5.90.9+.
+
+#### #14 `useMutationState` loses inference
+
+- **Prevention:** cast in `select`.
+
+#### #15 Cancellation in StrictMode with `fetchQuery`
+
+- **Prevention:** expected behavior; use `staleTime: Infinity` to keep it observed.
+
+#### #16 `invalidateQueries` only refetches active queries
+
+- **Prevention:** use `refetchType: 'all'` if you need inactive ones.
+
+### Community Tips
+
+#### Different options in the same query
+
+- “Last write wins” for future options.
+- **Recommended:** compute options on render using functions.
+
+#### `refetch()` is not for new parameters
+
+- **Rule:** change parameters in the `queryKey` and let Query refetch.
+
+### Anti‑Patterns (FORBIDDEN)
+
+```ts
+// Do not store server state in Zustand/Redux
+// Do not use string query keys
+// Do not use cacheTime
+// Do not use isLoading for initial state
+// Do not invalidate EVERYTHING indiscriminately
+// Do not forget cancelQueries in optimistic updates
+// Do not mutate cache data directly
+// Do not fetch in useEffect
+// Do not import presentation feedback adapters (toast/snackbar) into application mutation hooks
+```
+
+> For complete examples, see the tanstack skill.
+
+## Quality Gate (Self-Check)
+
+Before finishing, verify:
+
+- Query hooks use v5 object syntax and array query keys.
+- Route-critical reads still follow loader + Suspense flow from `tanstack`.
+- Query callbacks are not used (mutations may use callbacks).
+- Mutation feedback does not import presentation adapters into Application hooks.
+- Invalidation uses key factories and avoids broad indiscriminate invalidation.

package/hub/skills/tanstack-query/references/advanced-hooks.md

@@ -0,0 +1,126 @@
+# Advanced TanStack Query Patterns (v5)
+
+> These practices **complement** the tanstack skill. They do not replace or contradict its rules.
+
+## useMutationState — Global mutation tracking
+
+Access mutation state from any component without prop drilling:
+
+```tsx
+import { useMutationState } from "@tanstack/react-query";
+
+function GlobalLoadingIndicator() {
+  const pendingMutations = useMutationState({
+    filters: { status: "pending" },
+    select: (mutation) => mutation.state.variables,
+  });
+
+  if (pendingMutations.length === 0) return null;
+  return <div>Saving {pendingMutations.length} items...</div>;
+}
+
+// Filter by mutationKey
+const todoMutations = useMutationState({
+  filters: { mutationKey: ["addTodo"] },
+});
+```
+
+### Typing note
+
+Due to fuzzy inference, `mutation.state.variables` can be `unknown`. See issue #14 in the tanstack-query SKILL.md.
+
+## Network Mode — Offline/PWA support
+
+Control behavior when offline:
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      networkMode: "offlineFirst",
+    },
+  },
+});
+
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  networkMode: "always",
+});
+```
+
+| Mode               | Behavior                                    |
+| ------------------ | ------------------------------------------- |
+| `online` (default) | Only fetches when online                    |
+| `always`           | Always tries (local APIs or service worker) |
+| `offlineFirst`     | Uses cache first, fetches when back online  |
+
+**Paused state detection:**
+
+```tsx
+const { isPending, fetchStatus } = useQuery(...)
+// isPending + fetchStatus === 'paused' = offline, waiting for network
+```
+
+## useQueries with combine
+
+Combine results from parallel queries (use for optional/secondary data, not required route data):
+
+```tsx
+const results = useQueries({
+  queries: userIds.map((id) => ({
+    queryKey: ['user', id],
+    queryFn: () => fetchUser(id),
+  })),
+  combine: (results) => ({
+    data: results.map((r) => r.data),
+    pending: results.some((r) => r.isPending),
+    error: results.find((r) => r.error)?.error,
+  }),
+});
+
+if (results.pending) return <Loading />;
+console.log(results.data);
+
+> For required route data, keep the tanstack render-as-you-fetch flow: Application `queryOptions` → Loader `ensureQueryData` → Presentation `useSuspenseQuery`.
+```
+
+## infiniteQueryOptions helper
+
+Typed factory for infinite queries (parallel to queryOptions):
+
+```tsx
+import {
+  infiniteQueryOptions,
+  prefetchInfiniteQuery,
+  useInfiniteQuery,
+} from "@tanstack/react-query";
+
+const todosInfiniteOptions = infiniteQueryOptions({
+  queryKey: ["todos", "infinite"],
+  queryFn: ({ pageParam }) => fetchTodosPage(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+});
+
+useInfiniteQuery(todosInfiniteOptions);
+useSuspenseInfiniteQuery(todosInfiniteOptions);
+prefetchInfiniteQuery(queryClient, todosInfiniteOptions);
+```
+
+## maxPages — Memory optimization
+
+Limit cached pages for infinite queries:
+
+```tsx
+useInfiniteQuery({
+  queryKey: ["posts"],
+  queryFn: ({ pageParam }) => fetchPosts(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+  getPreviousPageParam: (firstPage) => firstPage.prevCursor,
+  maxPages: 3,
+});
+```
+
+**Rule:** `maxPages` requires bi-directional pagination.