@hitch42/applet 0.1.1-beta.7 → 0.1.1-beta.9

package/scaffold/.agents/skills/tanstack-query/references/core/implement-optimistic-updates-and-cache-writes.md

@@ -0,0 +1,168 @@
+---
+name: core/implement-optimistic-updates-and-cache-writes
+description: >
+  Use this when implementing optimistic updates, onMutate rollback context,
+  cancelQueries before writes, setQueryData, setQueriesData, immutable cache writes,
+  mutation rollback, and offline-aware optimistic state.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/write-mutations-and-invalidate-related-queries
+  - core/cancel-queries-and-consume-abort-signals
+sources:
+  - TanStack/query:docs/framework/react/guides/optimistic-updates.md
+  - TanStack/query:docs/framework/react/guides/updates-from-mutation-responses.md
+  - TanStack/query:docs/framework/react/guides/query-cancellation.md
+  - TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+---
+
+## Setup
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+type Todo = { id: number; title: string };
+
+export function useOptimisticAddTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (title: string) => ({ id: Date.now(), title }),
+    onMutate: async (title) => {
+      await queryClient.cancelQueries({ queryKey: ["todos"] });
+      const previous = queryClient.getQueryData<Array<Todo>>(["todos"]);
+      queryClient.setQueryData<Array<Todo>>(["todos"], (old = []) => [...old, { id: -1, title }]);
+      return { previous };
+    },
+    onError: (_error, _title, context) => {
+      queryClient.setQueryData(["todos"], context?.previous);
+    },
+    onSettled: async () => {
+      await queryClient.invalidateQueries({ queryKey: ["todos"] });
+    },
+  });
+}
+```
+
+## Core Patterns
+
+### Write mutation response into detail cache
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useUpdateTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (todo: { id: number; title: string }) => todo,
+    onSuccess: (todo) => queryClient.setQueryData(["todo", todo.id], todo),
+  });
+}
+```
+
+### Update lists immutably
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+queryClient.setQueryData<Array<{ id: number; title: string }>>(["todos"], (old = []) =>
+  old.map((todo) => (todo.id === 1 ? { ...todo, title: "Done" } : todo)),
+);
+```
+
+### Roll back with context
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const previous = queryClient.getQueryData(["todos"]);
+queryClient.setQueryData(["todos"], [{ id: 1, title: "Optimistic" }]);
+queryClient.setQueryData(["todos"], previous);
+```
+
+## Common Mistakes
+
+### CRITICAL Optimistic write without cancellation
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData(["todos"], [{ id: 1, title: "Optimistic" }]);
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+await queryClient.cancelQueries({ queryKey: ["todos"] });
+queryClient.setQueryData(["todos"], [{ id: 1, title: "Optimistic" }]);
+```
+
+An in-flight refetch can overwrite an optimistic write unless it is cancelled first.
+
+Source: TanStack/query:docs/framework/react/guides/optimistic-updates.md
+
+### CRITICAL In-place mutation
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData<Array<{ id: number; done: boolean }>>(["todos"], (old = []) => {
+  old[0].done = true;
+  return old;
+});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData<Array<{ id: number; done: boolean }>>(["todos"], (old = []) =>
+  old.map((todo) => (todo.id === 1 ? { ...todo, done: true } : todo)),
+);
+```
+
+Cache updates must be immutable so observers can detect and share changes correctly.
+
+Source: TanStack/query:docs/framework/react/guides/updates-from-mutation-responses.md
+
+### HIGH Persisted persister loses optimistic mutation
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+queryClient.setMutationDefaults(["updateTodo"], {});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+queryClient.setMutationDefaults(["updateTodo"], {
+  mutationFn: async (todo: { id: number; title: string }) => todo,
+});
+```
+
+Paused persisted mutations need a default mutationFn after hydration because functions cannot be serialized.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+See also: `core/cancel-queries-and-consume-abort-signals` before optimistic writes.

package/scaffold/.agents/skills/tanstack-query/references/core/paginate-and-build-infinite-queries.md

@@ -0,0 +1,188 @@
+---
+name: core/paginate-and-build-infinite-queries
+description: >
+  Use this when implementing pagination, lagged queries, placeholderData,
+  keepPreviousData migration, useInfiniteQuery, initialPageParam,
+  getNextPageParam, getPreviousPageParam, maxPages, pages, or pageParams.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/paginated-queries.md
+  - TanStack/query:docs/framework/react/guides/infinite-queries.md
+  - TanStack/query:docs/framework/react/reference/useInfiniteQuery.md
+  - TanStack/query:docs/reference/InfiniteQueryObserver.md
+  - TanStack/query:docs/eslint/infinite-query-property-order.md
+---
+
+## Setup
+
+```ts
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+
+export function useProjects(page: number) {
+  return useQuery({
+    queryKey: ["projects", page],
+    queryFn: async () => ({ page, projects: [{ id: page }] }),
+    placeholderData: keepPreviousData,
+  });
+}
+```
+
+## Core Patterns
+
+### Build an infinite query
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({
+      nextCursor: pageParam + 1,
+      items: [{ id: pageParam }],
+    }),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+  });
+}
+```
+
+### Bound memory with maxPages
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useBoundedFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({
+      nextCursor: pageParam + 1,
+      items: [{ id: pageParam }],
+    }),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    maxPages: 5,
+  });
+}
+```
+
+### Preserve infinite data shape
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+queryClient.setQueryData(["feed"], {
+  pages: [{ items: [{ id: 1 }], nextCursor: 2 }],
+  pageParams: [1],
+});
+```
+
+## Common Mistakes
+
+### CRITICAL Missing initialPageParam
+
+Wrong:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async () => ({ items: [] }),
+    getNextPageParam: () => 1,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ items: [pageParam] }),
+    initialPageParam: 0,
+    getNextPageParam: () => 1,
+  });
+}
+```
+
+v5 requires an explicit initial page param so pageParams can be serialized and inferred.
+
+Source: TanStack/query:docs/framework/react/guides/infinite-queries.md
+
+### HIGH Overlapping infinite fetches
+
+Wrong:
+
+```tsx
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function Feed() {
+  const query = useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+  return <button onClick={() => query.fetchNextPage()}>More</button>;
+}
+```
+
+Correct:
+
+```tsx
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function Feed() {
+  const query = useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+  return (
+    <button disabled={query.isFetchingNextPage} onClick={() => query.fetchNextPage()}>
+      More
+    </button>
+  );
+}
+```
+
+Only one ongoing fetch should update an infinite query cache at a time unless explicitly overridden.
+
+Source: TanStack/query:docs/framework/react/guides/infinite-queries.md
+
+### HIGH Broken pages shape
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData(["feed"], [{ id: 1 }]);
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData(["feed"], { pages: [[{ id: 1 }]], pageParams: [0] });
+```
+
+Infinite query data must keep `pages` and `pageParams`; refetches expect that shape.
+
+Source: TanStack/query:docs/framework/react/guides/infinite-queries.md

package/scaffold/.agents/skills/tanstack-query/references/core/seed-placeholder-select-and-transform-data.md

@@ -0,0 +1,188 @@
+---
+name: core/seed-placeholder-select-and-transform-data
+description: >
+  Use this when choosing initialData, initialDataUpdatedAt, placeholderData,
+  keepPreviousData, select, data transformation, cache seeding, detail-from-list
+  seeding, or derived query data.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/initial-query-data.md
+  - TanStack/query:docs/framework/react/guides/placeholder-query-data.md
+  - TanStack/query:docs/framework/react/guides/render-optimizations.md
+  - TanStack/query:docs/framework/react/reference/queryOptions.md
+---
+
+## Setup
+
+```ts
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+
+export function useProjects(page: number) {
+  return useQuery({
+    queryKey: ["projects", page],
+    queryFn: async () => ({ page, items: [{ id: page }] }),
+    placeholderData: keepPreviousData,
+  });
+}
+```
+
+## Core Patterns
+
+### Seed detail data from a list
+
+```ts
+import { QueryClient, useQuery } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function useTodo(todoId: number) {
+  return useQuery({
+    queryKey: ["todo", todoId],
+    queryFn: async () => ({ id: todoId, title: "Fresh" }),
+    initialData: () =>
+      queryClient
+        .getQueryData<Array<{ id: number; title: string }>>(["todos"])
+        ?.find((todo) => todo.id === todoId),
+  });
+}
+```
+
+### Select the smallest shape
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodoCount() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }, { id: 2 }],
+    select: (todos) => todos.length,
+  });
+}
+```
+
+### Transform in the query function for cache-wide shape
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export const todosOptions = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async () =>
+    [{ id: 1, title: "ship" }].map((todo) => ({
+      ...todo,
+      title: todo.title.toUpperCase(),
+    })),
+});
+```
+
+## Common Mistakes
+
+### HIGH initialData overwrite assumption
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo() {
+  return useQuery({
+    queryKey: ["todo", 1],
+    queryFn: async () => ({ id: 1, title: "Server" }),
+    initialData: { id: 1, title: "Always" },
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo() {
+  return useQuery({
+    queryKey: ["todo", 1],
+    queryFn: async () => ({ id: 1, title: "Server" }),
+    placeholderData: { id: 1, title: "Temporary" },
+  });
+}
+```
+
+`initialData` is persisted to cache as real data; placeholder data is observer-local.
+
+Source: TanStack/query:docs/framework/react/guides/initial-query-data.md
+
+### HIGH v4 keepPreviousData option
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function usePage(page: number) {
+  return useQuery({
+    queryKey: ["page", page],
+    queryFn: async () => ({ page }),
+    keepPreviousData: true,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+
+export function usePage(page: number) {
+  return useQuery({
+    queryKey: ["page", page],
+    queryFn: async () => ({ page }),
+    placeholderData: keepPreviousData,
+  });
+}
+```
+
+v5 replaced the `keepPreviousData` option with `placeholderData: keepPreviousData`.
+
+Source: TanStack/query:docs/framework/react/guides/migrating-to-v5.md
+
+### MEDIUM Throwing in select
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useFirstTodo() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [] as Array<{ id: number }>,
+    select: (todos) => todos[0].id,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useFirstTodo() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [] as Array<{ id: number }>,
+    select: (todos) => todos[0]?.id ?? null,
+  });
+}
+```
+
+`select` transforms successful data; it is not the right place to model fetch errors.
+
+Source: TanStack/query:docs/framework/react/guides/render-optimizations.md
+
+See also: `lifecycle/ssr-hydration-and-streaming` for SSR tradeoffs compared to hydration.

package/scaffold/.agents/skills/tanstack-query/references/core/selectors-and-derived-state.md

@@ -0,0 +1,145 @@
+---
+name: core/selectors-and-derived-state
+description: >
+  Use this when selecting, transforming, or deriving data from TanStack Query:
+  select functions, selector memoization, fine-grained subscriptions, structural
+  sharing, queryOptions composition with select, and deriving client state from
+  server state instead of syncing it through effects.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/seed-placeholder-select-and-transform-data
+  - framework/shape-data-and-render-efficiently
+sources:
+  - TanStack/query:docs/framework/react/guides/render-optimizations.md
+  - TanStack/query:docs/framework/react/reference/queryOptions.md
+---
+
+## Core Patterns
+
+Use `select` to subscribe a component to the data shape it actually needs while keeping the full response in the cache.
+
+### Select a stable slice
+
+```tsx
+import { queryOptions, useSuspenseQuery } from "@tanstack/react-query";
+
+const productOptions = (id: string) =>
+  queryOptions({
+    queryKey: ["product", id],
+    queryFn: () => fetchProduct(id),
+  });
+
+function ProductTitle({ id }: { id: string }) {
+  const title = useSuspenseQuery({
+    ...productOptions(id),
+    select: (product) => product.title,
+  });
+
+  return <h1>{title.data}</h1>;
+}
+```
+
+### Stabilize expensive selectors
+
+```tsx
+const selectAverageRating = (products: Array<Product>) => expensiveAverage(products);
+
+function ProductSummary({ filters }: { filters: ProductFilters }) {
+  return useSuspenseQuery({
+    ...productsOptions(filters),
+    select: selectAverageRating,
+  });
+}
+```
+
+Use `React.useCallback` when the selector closes over component props. Move it outside the component when it has no dependencies.
+
+### Derive client state instead of syncing it
+
+```tsx
+const selectedUser = usersQuery.data?.find((user) => user.id === selectedUserId);
+const visibleSelectedUserId = selectedUser ? selectedUserId : null;
+```
+
+When server data changes, derived values update naturally during render.
+
+## Common Mistakes
+
+### HIGH Syncing derived state through an effect
+
+Wrong:
+
+```tsx
+React.useEffect(() => {
+  if (!users?.some((user) => user.id === selectedUserId)) {
+    setSelectedUserId(null);
+  }
+}, [users, selectedUserId]);
+```
+
+Correct:
+
+```tsx
+const selectedUser = users?.find((user) => user.id === selectedUserId);
+const visibleSelectedUserId = selectedUser ? selectedUserId : null;
+```
+
+Prefer deriving client state from server state during render when no side effect is required.
+
+### MEDIUM Inline expensive select reruns on unrelated renders
+
+Wrong:
+
+```tsx
+useSuspenseQuery({
+  ...productsOptions(filters),
+  select: (data) => expensiveSuperTransformation(data),
+});
+```
+
+Correct:
+
+```tsx
+const selectProducts = (data: Array<Product>) => expensiveSuperTransformation(data);
+
+useSuspenseQuery({
+  ...productsOptions(filters),
+  select: selectProducts,
+});
+```
+
+TanStack Query reruns `select` when data changes or the selector function identity changes.
+
+### MEDIUM Using select to throw domain errors
+
+Wrong:
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  select: (todos) => {
+    if (!todos.length) throw new Error("No todos");
+    return todos;
+  },
+});
+```
+
+Correct:
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: async () => {
+    const todos = await fetchTodos();
+    if (!todos.length) throw new Error("No todos");
+    return todos;
+  },
+});
+```
+
+`select` transforms successful data. Query errors belong in the query function.
+
+Source: TanStack/query:docs/framework/react/guides/render-optimizations.md