@hitch42/applet 0.1.1-beta.1 → 0.1.1-beta.11

package/scaffold/.agents/skills/tanstack-query/references/compositions/persist-offline-and-restore-caches.md

@@ -0,0 +1,181 @@
+---
+name: compositions/persist-offline-and-restore-caches
+description: >
+  Use this when using persistQueryClient, PersistQueryClientProvider,
+  createSyncStoragePersister, createAsyncStoragePersister, experimental
+  fine-grained persisters, offline mutations, resumePausedMutations, maxAge,
+  gcTime, and restore races.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/tune-defaults-freshness-retries-and-refetching
+  - core/write-mutations-and-invalidate-related-queries
+sources:
+  - TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+  - TanStack/query:docs/framework/react/plugins/createSyncStoragePersister.md
+  - TanStack/query:docs/framework/react/plugins/createAsyncStoragePersister.md
+  - TanStack/query:docs/framework/react/plugins/createPersister.md
+  - TanStack/query:docs/framework/react/guides/network-mode.md
+---
+
+## Setup
+
+```tsx
+import * as React from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 24 * 60 * 60 * 1000 } },
+});
+
+const persister = createSyncStoragePersister({
+  storage: window.localStorage,
+});
+
+export function AppProviders(props: { children: React.ReactNode }) {
+  return (
+    <PersistQueryClientProvider client={queryClient} persistOptions={{ persister }}>
+      {props.children}
+    </PersistQueryClientProvider>
+  );
+}
+```
+
+## Core Integration Patterns
+
+### Resume paused mutations after restore
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+
+queryClient.setMutationDefaults(["todos"], {
+  mutationFn: async (todo: { id: number; title: string }) => todo,
+});
+
+export function resumeMutations() {
+  return queryClient.resumePausedMutations();
+}
+```
+
+### Align cache lifetime with persistence
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { gcTime: 7 * 24 * 60 * 60 * 1000 },
+  },
+});
+```
+
+### Use networkMode for offline-first writes
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSaveDraft() {
+  return useMutation({
+    mutationKey: ["saveDraft"],
+    mutationFn: async (draft: { body: string }) => draft,
+    networkMode: "offlineFirst",
+  });
+}
+```
+
+## Common Mistakes
+
+### HIGH gcTime shorter than maxAge
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 5 * 60 * 1000 } },
+});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 24 * 60 * 60 * 1000 } },
+});
+```
+
+Persisted data can be garbage-collected before the persister maxAge can restore it.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+### CRITICAL Rendering before restore
+
+Wrong:
+
+```tsx
+import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+export function App(props: { children: React.ReactNode }) {
+  return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+}
+```
+
+Correct:
+
+```tsx
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
+
+const queryClient = new QueryClient();
+const persister = createSyncStoragePersister({ storage: window.localStorage });
+
+export function App(props: { children: React.ReactNode }) {
+  return (
+    <PersistQueryClientProvider client={queryClient} persistOptions={{ persister }}>
+      {props.children}
+    </PersistQueryClientProvider>
+  );
+}
+```
+
+The persistence provider prevents query fetching while restore is in progress.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+### CRITICAL Missing default mutationFn
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+queryClient.setMutationDefaults(["saveDraft"], {
+  mutationFn: async (draft: { body: string }) => draft,
+});
+```
+
+Paused persisted mutations cannot resume without a serializable mutation key mapped to a default mutationFn.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+See also: `core/tune-defaults-freshness-retries-and-refetching` for gcTime and networkMode.

package/scaffold/.agents/skills/tanstack-query/references/compositions/query-data-and-forms.md

@@ -0,0 +1,156 @@
+---
+name: compositions/query-data-and-forms
+description: >
+  Use this when integrating TanStack Query data and mutations with forms:
+  initial server state, editable client state, dirty fields, background updates,
+  submit prevention, invalidation, reset-after-save, validation errors, and
+  avoiding blind copies from Query cache into local form state.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/write-mutations-and-invalidate-related-queries
+  - core/selectors-and-derived-state
+sources:
+  - TanStack/query:docs/framework/react/guides/mutations.md
+  - TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+---
+
+## Core Patterns
+
+Treat form state as client state after the user starts editing. Server state can initialize the form, but it should not be copied blindly on every query update.
+
+### Initial data only
+
+Use this when one user owns the form and background updates are not useful while editing.
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+function PersonDetail({ id }: { id: string }) {
+  const queryClient = useQueryClient();
+  const person = useQuery({
+    queryKey: ["person", id],
+    queryFn: () => fetchPerson(id),
+    staleTime: Infinity,
+  });
+
+  const updatePerson = useMutation({
+    mutationFn: savePerson,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["person", id] }),
+  });
+
+  if (!person.data) return <p>Loading...</p>;
+  return (
+    <PersonForm
+      person={person.data}
+      isSaving={updatePerson.isPending}
+      onSubmit={updatePerson.mutate}
+    />
+  );
+}
+```
+
+### Derived server plus client state
+
+Use this when background updates should remain visible for untouched fields.
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+function PersonName({ id }: { id: string }) {
+  const { data } = useQuery({
+    queryKey: ["person", id],
+    queryFn: () => fetchPerson(id),
+  });
+  const [draft, setDraft] = React.useState<{ firstName?: string }>({});
+
+  if (!data) return <p>Loading...</p>;
+
+  return (
+    <input
+      value={draft.firstName ?? data.firstName}
+      onChange={(event) => setDraft({ firstName: event.target.value })}
+    />
+  );
+}
+```
+
+### Reset after awaited invalidation
+
+```tsx
+const mutation = useMutation({
+  mutationFn: savePerson,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["person", id] }),
+});
+
+function submit(values: PersonFormValues) {
+  mutation.mutate(values, { onSuccess: () => resetFormDraft() });
+}
+```
+
+Return the invalidation promise from `onSuccess` or `onSettled` when the saved server state must be back in the cache before the form resets.
+
+## Common Mistakes
+
+### HIGH Initializing form defaults before query data exists
+
+Wrong:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["person", id],
+  queryFn: () => fetchPerson(id),
+});
+const [draft, setDraft] = React.useState(data);
+```
+
+Correct:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["person", id],
+  queryFn: () => fetchPerson(id),
+});
+if (!data) return <p>Loading...</p>;
+return <PersonForm initialPerson={data} />;
+```
+
+The first render usually has no query data. Split the form boundary or derive field values from query data plus draft state.
+
+### HIGH Background refetch overwrites or hides dirty client state
+
+Wrong:
+
+```tsx
+React.useEffect(() => {
+  setDraft(personQuery.data);
+}, [personQuery.data]);
+```
+
+Correct:
+
+```tsx
+const shownFirstName = draft.firstName ?? personQuery.data?.firstName ?? "";
+```
+
+Do not synchronize every server update into the draft. Derive displayed values or intentionally opt out of background updates for initial-only forms.
+
+### MEDIUM Form submit can run twice
+
+Wrong:
+
+```tsx
+<button type="submit">Save</button>
+```
+
+Correct:
+
+```tsx
+<button type="submit" disabled={mutation.isPending}>
+  Save
+</button>
+```
+
+Use mutation state to block duplicate writes while a submission is in flight.

package/scaffold/.agents/skills/tanstack-query/references/core/build-query-abstractions.md

@@ -0,0 +1,130 @@
+---
+name: core/build-query-abstractions
+description: >
+  Use this when creating TanStack Query abstractions: queryOptions factories,
+  feature-local key modules, custom hooks built on top of options factories,
+  TypeScript inference, avoiding wide UseQueryOptions wrappers, and sharing
+  query configuration across hooks, loaders, prefetches, and QueryClient calls.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+sources:
+  - TanStack/query:docs/framework/react/guides/query-options.md
+  - TanStack/query:docs/framework/react/typescript.md
+---
+
+## Core Patterns
+
+Prefer a `queryOptions` factory as the base abstraction. Hooks, loaders, prefetches, suspense queries, and `QueryClient` calls can all consume it.
+
+```ts
+import { queryOptions, useQuery, useSuspenseQuery } from "@tanstack/react-query";
+
+export function invoiceOptions(id: number) {
+  return queryOptions({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+    staleTime: 60_000,
+  });
+}
+
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+
+export function useSuspenseInvoice(id: number) {
+  return useSuspenseQuery(invoiceOptions(id));
+}
+```
+
+Compose one-off options at the usage site:
+
+```ts
+const invoice = useQuery({
+  ...invoiceOptions(id),
+  select: (data) => data.createdAt,
+  throwOnError: true,
+});
+```
+
+## Common Mistakes
+
+### HIGH Custom hook is the only abstraction
+
+Wrong:
+
+```ts
+export function useInvoice(id: number) {
+  return useQuery({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+  });
+}
+```
+
+Correct:
+
+```ts
+export function invoiceOptions(id: number) {
+  return queryOptions({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+  });
+}
+
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+```
+
+Custom hooks cannot run in route loaders, server prefetches, or event handlers. Options factories can.
+
+### HIGH Wide UseQueryOptions wrapper breaks inference
+
+Wrong:
+
+```ts
+function useInvoice(id: number, options?: Partial<UseQueryOptions<Invoice>>) {
+  return useQuery({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+    ...options,
+  });
+}
+```
+
+Correct:
+
+```ts
+useQuery({
+  ...invoiceOptions(id),
+  select: (invoice) => invoice.createdAt,
+});
+```
+
+Let `queryOptions` and usage-site composition preserve `select` inference.
+
+### MEDIUM Wrapper hides Query result state
+
+Wrong:
+
+```ts
+export function useInvoice(id: number) {
+  const { data } = useQuery(invoiceOptions(id));
+  return data;
+}
+```
+
+Correct:
+
+```ts
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+```
+
+Keep the Query result surface available unless the abstraction owns every loading, error, and refetch behavior.
+
+Source: TanStack/query:docs/framework/react/guides/queries.md

package/scaffold/.agents/skills/tanstack-query/references/core/cancel-queries-and-consume-abort-signals.md

@@ -0,0 +1,176 @@
+---
+name: core/cancel-queries-and-consume-abort-signals
+description: >
+  Use this when handling query cancellation, AbortSignal, cancelQueries,
+  CancelledError, rollback after consumed signals, fetch cancellation, axios
+  cancellation, and optimistic update overwrite prevention.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/query-cancellation.md
+  - TanStack/query:docs/reference/QueryClient.md
+  - TanStack/query:packages/query-core/src/retryer.ts
+---
+
+## Setup
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(todoId: string) {
+  return useQuery({
+    queryKey: ["todo", todoId],
+    queryFn: async ({ signal }) => {
+      const response = await fetch(`/api/todos/${todoId}`, { signal });
+      return response.json() as Promise<{ id: string; title: string }>;
+    },
+  });
+}
+```
+
+## Core Patterns
+
+### Cancel before optimistic writes
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export async function prepareTodoWrite() {
+  await queryClient.cancelQueries({ queryKey: ["todos"] });
+}
+```
+
+### Consume one signal across nested fetches
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export const todosWithDetailsOptions = queryOptions({
+  queryKey: ["todos-with-details"],
+  queryFn: async ({ signal }) => {
+    const todos = await fetch("/api/todos", { signal }).then(
+      (response) => response.json() as Promise<Array<{ id: string }>>,
+    );
+    return Promise.all(
+      todos.map((todo) =>
+        fetch(`/api/todos/${todo.id}`, { signal }).then((response) => response.json()),
+      ),
+    );
+  },
+});
+```
+
+### Cancel by query key
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function cancelTodos() {
+  return queryClient.cancelQueries({ queryKey: ["todos"] });
+}
+```
+
+## Common Mistakes
+
+### HIGH Ignoring AbortSignal
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => fetch(`/api/todos/${id}`).then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+TanStack Query provides an AbortSignal; the request is only cancelled if the query function consumes it.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md
+
+### HIGH Assuming unmount cancels
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useReport() {
+  return useQuery({
+    queryKey: ["report"],
+    queryFn: async () => fetch("/api/report").then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useReport() {
+  return useQuery({
+    queryKey: ["report"],
+    queryFn: async ({ signal }) => fetch("/api/report", { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Unused queries can continue and populate cache unless the signal is consumed.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md
+
+### HIGH Suspense cancellation expected
+
+Wrong:
+
+```ts
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useSuspenseQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Cancellation limitations apply to Suspense hooks; use non-suspense queries when cancellation behavior is required.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md