TanStack Query

Documentation: tanstack.com/query | Use context7 for API reference

Centralize API calls in api.svelte.ts per feature using TanStack Query with @exceptionless/fetchclient .

Query Basics

// src/lib/features/organizations/api.svelte.ts import { createQuery, createMutation, useQueryClient, } from "@tanstack/svelte-query"; import { useFetchClient, type ProblemDetails, } from "@exceptionless/fetchclient";

export function getOrganizationsQuery() { const client = useFetchClient();

return createQuery(() => ({
    queryKey: ["organizations"],
    queryFn: async () => {
        const response =
            await client.getJSON<Organization[]>("/organizations");
        if (!response.ok) {
            throw response.problem;
        }
        return response.data!;
    },
}));

}

Query Keys Convention

Use a queryKeys factory per feature for type safety and consistency:

// From src/lib/features/webhooks/api.svelte.ts export const queryKeys = { type: ["Webhook"] as const, id: (id: string | undefined) => [...queryKeys.type, id] as const, ids: (ids: string[] | undefined) => [...queryKeys.type, ...(ids ?? [])] as const, project: (id: string | undefined) => [...queryKeys.type, "project", id] as const, deleteWebhook: (ids: string[] | undefined) => [...queryKeys.ids(ids), "delete"] as const, postWebhook: () => [...queryKeys.type, "post"] as const, };

Common patterns:

// Resource list ["organizations"]["projects"][ // Single resource ("organizations", organizationId) ][("projects", projectId)][ // Nested resources ("organizations", organizationId, "projects") ][("projects", projectId, "events")][ // Filtered queries ("events", { projectId, status: "open" }) ];

Using Queries in Components

<script lang="ts"> import { getOrganizationsQuery } from '$features/organizations/api.svelte';

const organizationsQuery = getOrganizationsQuery();

</script>

{#if organizationsQuery.isPending} <LoadingSpinner /> {:else if organizationsQuery.isError} <ErrorMessage error={organizationsQuery.error} /> {:else} {#each organizationsQuery.data as org} <OrganizationCard {org} /> {/each} {/if}

Mutations

export function createOrganizationMutation() { const client = useFetchClient(); const queryClient = useQueryClient();

return createMutation(() => ({
    mutationFn: async (data: CreateOrganizationRequest) => {
        const response = await client.postJSON<Organization>(
            "/organizations",
            data,
        );
        if (!response.ok) {
            throw response.problem;
        }
        return response.data!;
    },
    onSuccess: () => {
        // Invalidate and refetch organizations list
        queryClient.invalidateQueries({ queryKey: ["organizations"] });
    },
}));

}

Using Mutations

<script lang="ts"> import { createOrganizationMutation } from '$features/organizations/api.svelte';

const createMutation = createOrganizationMutation();

async function handleCreate(data: CreateOrganizationRequest) {
    try {
        const org = await createMutation.mutateAsync(data);
        goto(`/organizations/${org.id}`);
    } catch (error) {
        // Error handled by form or toast
    }
}

</script>

<Button onclick={() => handleCreate(formData)} disabled={createMutation.isPending}

{createMutation.isPending ? 'Creating...' : 'Create'}

</Button>

Naming Conventions

Functions follow HTTP verb prefixes:

// Queries (GET) export function getOrganizationsQuery() { ... } export function getOrganizationQuery(id: string) { ... } export function getProjectEventsQuery(projectId: string) { ... }

// Mutations export function postOrganizationMutation() { ... } // CREATE export function patchOrganizationMutation() { ... } // UPDATE export function deleteOrganizationMutation() { ... } // DELETE

Dependent Queries

export function getProjectQuery(projectId: string) { const client = useFetchClient();

return createQuery(() => ({
    queryKey: ["projects", projectId],
    queryFn: async () => {
        const response = await client.getJSON<Project>(
            `/projects/${projectId}`,
        );
        if (!response.ok) throw response.problem;
        return response.data!;
    },
    enabled: !!projectId, // Only run when projectId is truthy
}));

}

Optimistic Updates

export function updateOrganizationMutation() { const client = useFetchClient(); const queryClient = useQueryClient();

return createMutation(() => ({
    mutationFn: async ({
        id,
        data,
    }: {
        id: string;
        data: UpdateOrganizationRequest;
    }) => {
        const response = await client.patchJSON<Organization>(
            `/organizations/${id}`,
            data,
        );
        if (!response.ok) throw response.problem;
        return response.data!;
    },
    onMutate: async ({ id, data }) => {
        // Cancel in-flight queries
        await queryClient.cancelQueries({
            queryKey: ["organizations", id],
        });

        // Snapshot previous value
        const previous = queryClient.getQueryData<Organization>([
            "organizations",
            id,
        ]);

        // Optimistically update
        queryClient.setQueryData(
            ["organizations", id],
            (old: Organization) => ({
                ...old,
                ...data,
            }),
        );

        return { previous };
    },
    onError: (err, variables, context) => {
        // Rollback on error
        if (context?.previous) {
            queryClient.setQueryData(
                ["organizations", variables.id],
                context.previous,
            );
        }
    },
    onSettled: (data, error, { id }) => {
        // Always refetch after mutation
        queryClient.invalidateQueries({ queryKey: ["organizations", id] });
    },
}));

}

Prefetching

export function prefetchOrganization(id: string) { const client = useFetchClient(); const queryClient = useQueryClient();

return queryClient.prefetchQuery({
    queryKey: ["organizations", id],
    queryFn: async () => {
        const response = await client.getJSON<Organization>(
            `/organizations/${id}`,
        );
        if (!response.ok) throw response.problem;
        return response.data!;
    },
});

}

WebSocket-Driven Invalidation

Invalidate queries when WebSocket messages arrive:

// From src/lib/features/webhooks/api.svelte.ts import type { WebSocketMessageValue } from "$features/websockets/models"; import { QueryClient } from "@tanstack/svelte-query";

export async function invalidateWebhookQueries( queryClient: QueryClient, message: WebSocketMessageValue<"WebhookChanged">, ) { const { id, organization_id, project_id } = message;

if (id) {
    await queryClient.invalidateQueries({ queryKey: queryKeys.id(id) });
}

if (project_id) {
    await queryClient.invalidateQueries({
        queryKey: queryKeys.project(project_id),
    });
}

// Fallback: invalidate all if no specific keys
if (!id && !organization_id && !project_id) {
    await queryClient.invalidateQueries({ queryKey: queryKeys.type });
}

}

Wire up in WebSocket handler:

// In WebSocket message handler onMessage("WebhookChanged", (message) => { invalidateWebhookQueries(queryClient, message); });