Bible Tanstack Query Mutation

Scope MUST match folder/subcomponent hierarchy:

Entity: Plural for lists (Projects), singular for single items (Project).

Return Structure

return {
    query,           // Always return full query object
    projects,        // Raw data (array or single item)
    projectsMap,     // Optional: Map for O(1) lookup
};

Full Example

import { useQuery } from "@tanstack/react-query";
import { QueryKeys } from "@/utils/query/queryKeys";

// 1. Extract query function OUTSIDE hook for type inference
const createProjectsQuery = (orgId: string) =>
    // Data layer call — see your backend skill
    fetchProjects(orgId);

// 2. Infer type from query shape
export type PageDashboard_Projects_QueryData = Awaited<ReturnType<typeof createProjectsQuery>>;

// 3. Hook
export const useQ_PageDashboard_Projects = ({ organizationId }: { organizationId: string }) => {
    const query = useQuery({
        enabled: !!organizationId,
        queryKey: [...QueryKeys.projects.list(), { organizationId }],
        queryFn: () => createProjectsQuery(organizationId),
    });

    const projects = useMemo(() => query.data || [], [query.data]);
    const projectsMap = useMemo(
        () => projects.reduce((acc, p) => ({ ...acc, [p.id]: p }), {} as Record<string, PageDashboard_Projects_QueryData[number]>),
        [projects],
    );

    return { query, projects, projectsMap };
};

QueryKeys Pattern

Use .list() for list queries and .record(id) for single-record queries.

// LIST — fetches multiple rows
queryKey: [...QueryKeys.projects.list(), { organizationId }];

// RECORD — fetches one row by ID
queryKey: [...QueryKeys.projects.record(projectId)];

// Single record with joined arrays (1 project + N files)
queryKey: [...QueryKeys.projects.record(projectId), ...QueryKeys.files.list()];

Join Strategy

Query Key Factory for Mutation Reuse

Export query key factory when mutations need cache access:

// Export factory (NOT a hook)
export const PageDashboard_Project_QueryKey = (projectId: string) =>
    [...QueryKeys.projects.record(projectId)] as const;

// Use in query hook
queryKey: PageDashboard_Project_QueryKey(projectId);

// Use in mutation for optimistic updates
const queryKey = PageDashboard_Project_QueryKey(variables.id);
queryClient.setQueryData(queryKey, optimisticValue);

Minimal Processing Principle

Query hooks do MINIMAL transformation. Components handle business logic.

Allowed: Null coalescing (query.data || []), map building, useMemo wrappers.

Forbidden: Flattening/reshaping data, extracting nested arrays, business logic (isOwner, permissions), cross-hook merging.

// ✅ Components handle logic inline
{qProject.project?.owner_id === currentUserId && <OwnerBadge />}

// ❌ Don't compute in hooks
const isOwner = useMemo(() => project?.owner_id === userId, [...]);

DRY exception: Extract a const when the same check repeats 3+ times in the component.

Hook Composition

Compose hooks to avoid deeply nested joins:

export const useQ_PageDashboard_Organizations = () => {
    const qMe = useQ_Me();
    const orgIds = useMemo(() => qMe.user?.memberships?.map((m) => m.org_id) || [], [qMe.user]);
    const qOrgs = useQ_Tables_Organizations({ ids: orgIds });
    return { query: qMe.query, organizations: qOrgs.organizations };
};

Mutation Hook Pattern

Naming

Hook: useM_[Scope]_[EntityAction] | Variable: m[EntityAction] (drop scope)

Actions: Explicit suffix: Create, Update, Delete, Upload

Create Pattern

import { useMutation } from "@tanstack/react-query";

export type UseM_PageDashboard_ProjectCreate_Params = {
    organization_id: string;
    name: string;
    description?: string;
};

export const useM_PageDashboard_ProjectCreate = () => {
    const mutation = useMutation({
        mutationFn: async (body: UseM_PageDashboard_ProjectCreate_Params) => {
            // Data layer call — see your backend skill
            return await createProject(body);
        },
        onSuccess: () => {
            // User feedback — see your UI framework skill
        },
        onError: (error) => {
            console.error("Error creating project:", error);
            // User feedback — see your UI framework skill
        },
    });

    return { mutation };
};

Update/Delete Pattern

Separates record ID (hook params) from mutable data (mutationFn params):

export type UseM_PageDashboard_ProjectUpdate_Params = { projectId: string };
export type UseM_PageDashboard_ProjectUpdate_Body = Partial<{ name: string; description: string }>;

export const useM_PageDashboard_ProjectUpdate = ({ projectId }: UseM_PageDashboard_ProjectUpdate_Params) => {
    const mutation = useMutation({
        mutationKey: ["projects", "update", projectId],
        mutationFn: async (body: UseM_PageDashboard_ProjectUpdate_Body) => {
            // Data layer call — see your backend skill
            return await updateProject(projectId, body);
        },
        onSuccess: () => { /* feedback */ },
        onError: (error) => { console.error(error); /* feedback */ },
    });

    return { mutation };
};

mutate vs mutateAsync

• mutate — normal button clicks, fire-and-forget
• mutateAsync — when you need to await (modal confirmations, sequential operations)

Error Handling

// ❌ Logging twice
if (error) { console.error(error); throw error; }  // Logged here
onError: (error) => console.error(error);            // And here!

// ✅ Throw in mutationFn, let onError handle logging + feedback
if (error) throw error;
onError: (error) => { console.error(error); /* feedback */ };

Anti-Patterns

Onboarding

Decisions

• Cache invalidation strategy: manual, realtime, or hybrid (project-specific)

Scaffolding

Create QueryKeys factory:

• Path: src/utils/query/queryKeys.ts
• Template:

export const QueryKeys = {
    // Add tables as your project grows:
    // projects: {
    //     all: () => ["projects"],
    //     list: () => [...QueryKeys.projects.all(), "list"],
    //     record: (id: string) => [...QueryKeys.projects.all(), id],
    // },
};

Create AtLeastOne utility type (for update body types):

• Path: src/types/utility.types.ts
• Template:

export type AtLeastOne<T, U = { [K in keyof T]: Pick<T, K> }> = Partial<T> & U[keyof U];