RetryEngine

RetryEngine (Internal)

Internal Implementation

RetryEngine is an internal module of @soulcache/core. It is not exported from the package root and is not part of the public API. It is used by QueryEngine.executeQuery() for query retries. QueryClient.fetchQuery() does not apply retry configuration.

The RetryEngine provides error classification, backoff strategies, and configurable retry policies.

Usage via QueryEngine

QueryEngine wraps QueryClient with automatic retry support. Note that QueryEngine is internal and not exported from the package root:

// QueryEngine is internal — this module is not available to consumers.
// Query retries are handled by the internal query pipeline.

Usage via MutationEntry

MutationEntry.mutateWithRetry() provides retry logic for mutations as a self-contained retry loop (it does not use RetryEngine):

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() / mutate()

QueryClient.fetchQuery() only accepts { queryKey, queryFn } and does not apply retry configuration. The retry and retryDelay options on QueryClient.mutate() are accepted and forwarded to MutationCache.create(), but they have no effect because QueryClient.mutate() performs a single attempt — use MutationEntry.mutateWithRetry() for retrying mutations.

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