Query System

The Query System is responsible for orchestrating data fetching, caching, and state management.

Core Concepts

Query Keys

Query keys uniquely identify queries and enable automatic caching:

// Simple key
['users']
 
// Parameterized key
['users', userId]
 
// Complex key
['users', userId, { page: 1, limit: 10 }]

Query Functions

Query functions fetch your data:

const data = await client.fetchQuery({
  queryKey: ['users'],
  queryFn: async () => {
    const response = await fetch('/api/users');
    return response.json();
  },
});

Query States

Queries go through several states:

State	Description
`idle`	Initial state, no fetch in progress
`loading`	Currently fetching for the first time
`success`	Data available
`error`	Fetch failed
`fetching`	Background refetch in progress (stale data available)

The fetchStatus property tracks background refetching separately from the main status.

Usage

Basic Fetch

const data = await client.fetchQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then(r => r.json()),
});

const unsubscribe = client.subscribe(['users'], (snapshot) => {
  console.log(snapshot.data);
  console.log(snapshot.status);
});

Manual Cache Update

client.setQueryData(['users'], (old) => [...old, newUser]);

Invalidation

await client.invalidateQueries(['users']);

Deduplication

SoulCache automatically deduplicates concurrent requests:

// These will only make one network request
const p1 = client.fetchQuery({ queryKey: ['users'], queryFn });
const p2 = client.fetchQuery({ queryKey: ['users'], queryFn });
 
const [data1, data2] = await Promise.all([p1, p2]);

Best Practices

Use descriptive query keys - Make keys meaningful for debugging
Keep keys stable - Don't create new arrays unnecessarily
Set appropriate stale time - Balance freshness vs performance
Handle errors gracefully - Always provide error boundaries
Clean up subscriptions - Unsubscribe when components unmount

Common Mistakes

Creating new key arrays - This breaks deduplication
Missing error handling - Always catch fetch errors
Forgetting cleanup - Unsubscribe to prevent memory leaks
Over-fetching - Use stale time to reduce requests

Query System

On this page