RetryEngine

RetryEngine (Internal)

Internal Implementation

RetryEngine is an internal module used by MutationEntry.mutateWithRetry(). It is not currently integrated into the query fetch pipeline (QueryClient.fetchQuery() does not support retry configuration).

The RetryEngine provides error classification, backoff strategies, and configurable retry policies. It is used by QueryEngine.executeQuery() for query retries and MutationEntry.mutateWithRetry() for mutation retries.

Usage via QueryEngine

QueryEngine wraps QueryClient with automatic retry support:

import { QueryEngine } from '@soulcache/core/query';
 
const engine = new QueryEngine({ staleTime: 5000 });
 
const data = await engine.executeQuery({
  queryKey: ['users'],
  queryFn: async (signal) => {
    const res = await fetch('/api/users', { signal });
    return res.json();
  },
  retry: {
    maxRetries: 3,
    baseDelay: 1000,
    maxDelay: 30000,
    backoff: 'exponential',
    jitter: true,
  },
});

Usage via MutationEntry

The primary way to use retry logic for mutations is through MutationEntry.mutateWithRetry():

const entry = mutationCache.create({
  mutationId: 'mut-1',
  mutationFn: async (vars) => {
    const res = await fetch('/api/users', { method: 'POST', body: JSON.stringify(vars) });
    return res.json();
  },
});
 
// Execute with retry
const data = await entry.mutateWithRetry({ name: 'John' }, 3, 1000);

RetryConfig (Internal)

The internal RetryConfig interface used by RetryEngine:

Option	Default	Description
`maxRetries`	`3`	Maximum retry attempts
`baseDelay`	`1000`	Base delay in milliseconds
`maxDelay`	`30000`	Maximum delay cap
`backoff`	`'exponential'`	Backoff strategy
`jitter`	`true`	Add random jitter

QueryClient.fetchQuery()

QueryClient.fetchQuery() only accepts { queryKey, queryFn } and does not support retry configuration. For query retries, use QueryEngine.executeQuery() instead. The retry and retryDelay parameters in QueryClient.mutate() are accepted but not currently passed through to MutationEntry.

Retry Concepts

Error Classification

Errors are classified into categories:

Class	Description
`network`	Connection failures
`timeout`	Request timeouts
`server`	5xx errors
`client`	4xx errors
`abort`	Cancelled requests
`unknown`	Unclassified errors

Backoff Strategies

Strategy	Behavior
`exponential`	Delay doubles each attempt
`linear`	Delay increases linearly
`constant`	Fixed delay

Best Practices

Retry Guidelines

Use exponential backoff — Prevents overwhelming the server
Add jitter — Prevents thundering herd
Set reasonable retries — Don't retry forever
Handle final failure — Always handle exhausted retries

RetryEngine

On this page