Query Engine

QueryEngine (Internal)

Internal Implementation

QueryEngine is an internal module of @soulcache/core. It is not exported from the package root and is not part of the public API (@soulcache/core/query does not resolve). The public query API is QueryClient (core) and the useQuery family of hooks (@soulcache/react).

The QueryEngine is a higher-level orchestrator that wraps QueryClient with additional features like automatic retry (via RetryEngine), background refetch intervals, and stale-time-aware cache reads.

Public API

For consumers, query execution is driven through QueryClient:

import { QueryClient } from '@soulcache/core';
 
const client = new QueryClient();
 
const data = await client.fetchQuery({
  queryKey: ['users'],
  queryFn: async () => {
    const res = await fetch('/api/users');
    return res.json();
  },
});

Or through the React adapter:

import { useQuery } from '@soulcache/react';
 
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: async () => {
    const res = await fetch('/api/users');
    return res.json();
  },
});

Key Differences from QueryClient

Feature	QueryClient	QueryEngine (internal)
Retry support	No (retry config not applied)	Yes (via RetryEngine)
Background refetch	No	Yes (via `refetchInterval`)
Stale-time-aware reads	Yes (via `defaultOptions.staleTime`)	Yes (via `staleTime` option)
Abort signal support	No	Yes (passed to `queryFn`)

QueryClient — Primary user-facing API
RetryEngine — Internal retry logic
Cache System
Architecture

Query Engine

QueryEngine (Internal)

Public API

Key Differences from QueryClient

Related

On this page