API Reference

Complete API reference for qortex-core and qortex-react. All functions, hooks, and configuration options.

Core API

Framework-agnostic query management functions

registerFetcher(key, options)

Register a data fetcher function for a specific query key

Parameters:

key(string | string[])Query key (string or array)
options(FetcherOptions<T>)Fetcher configuration options

Example:

import { registerFetcher } from "qortex-core";

registerFetcher(["users"], {
  fetcher: async () => {
    const response = await fetch("/api/users");
    return response.json();
  },
  staleTime: 5 * 60 * 1000,
  placeholderData: [],
  equalityStrategy: "deep" // or "shallow"
});

setQueryData(key, data)

Manually update query data

Parameters:

key(string | string[])Query key
data(T)New data to set

Example:

import { setQueryData } from "qortex-core";

// Direct update
setQueryData(["todos"], newTodos);

fetchQuery(key, options?)

Execute a fetch operation with proper error handling and state management

Parameters:

key(string | string[])Query key
options(QueryOptions<T>)Optional query configuration

Example:

import { fetchQuery } from "qortex-core";

// Fetch data manually
const userData = await fetchQuery(["user", userId]);

// With options
const userData = await fetchQuery(["user", userId], {
  staleTime: 10 * 60 * 1000
});

getQueryData(key, options?)

Get current query data without subscribing to updates

Parameters:

key(string | string[])Query key
options(QueryOptions<T>)Optional query configuration

Example:

import { getQueryData } from "qortex-core";

const user = getQueryData(["user", userId]);
const isAuthenticated = getQueryData(["auth", "isAuthenticated"]);

getQueryState(key, options?)

Get comprehensive query state including computed flags

Parameters:

key(string | string[])Query key
options(QueryOptions<T>)Optional query configuration

Example:

import { getQueryState } from "qortex-core";

const state = getQueryState(["users"]);
console.log({
  data: state.data,
  isLoading: state.isLoading,
  isFetching: state.isFetching,
  isError: state.isError,
  isStale: state.isStale
});

invalidateQuery(key)

Mark a query as invalidated, triggering refetch

Parameters:

key(string | string[])Query key to invalidate

Example:

import { invalidateQuery } from "qortex-core";

// Invalidate and refetch
invalidateQuery(["users"]);

// Invalidate specific user
invalidateQuery(["user", userId]);

subscribeQuery(key, callback, options?)

Subscribe to query state changes with flexible callback signatures

Parameters:

key(string | string[])Query key
callback((state: QueryState<T>) => void)Callback function that receives current state
options(QueryOptions<T>)Optional query configuration

Example:

import { subscribeQuery } from "qortex-core";

// Callback receives the current state
const unsubscribe = subscribeQuery(
  ["users"],
  (state) => {
    console.log("Query state changed:", state);
    console.log("Data:", state.data);
    console.log("Loading:", state.isLoading);
    console.log("Success:", state.isSuccess);
  }
);

// With fetcher for automatic type inference
const unsubscribe = subscribeQuery(
  ["users"],
  (state) => {
    console.log("Users:", state.data); // Automatically typed
  },
  { fetcher: fetchUsers }
);

// Cleanup subscription
unsubscribe();

setDefaultConfig(config)

Set global default configuration for all queries

Parameters:

config(DefaultConfig)Default configuration options

Example:

import { setDefaultConfig } from "qortex-core";

setDefaultConfig({
  staleTime: 5 * 60 * 1000,
  refetchOnSubscribe: "stale",
  throttleTime: 100,
  usePreviousDataOnError: false,
  equalityStrategy: "deep"
});

dangerClearCache()

⚠️ DANGER: Clear all cached data and subscriptions (testing only)

Parameters:

Example:

import { dangerClearCache } from "qortex-core";

// ✅ Safe usage in tests
beforeEach(() => {
  dangerClearCache();
});

// ❌ Dangerous usage in production
// dangerClearCache(); // Don't do this!
⚠️

Warning

This method should ONLY be used in testing environments. Using this in production will cause all active queries to lose their data and subscriptions to break.

React Hooks

React-specific hooks for data fetching

useQuery(key, options?)

React hook for query data with full state management

Parameters:

key(string | string[])Query key
options(UseQueryOptions<T>)Optional query options

Returns:

UseQueryResult<T>

Example:

const { data, isLoading, isSuccess, isError, error, refetch } = useQuery(["todos"], {
  refetchOnSubscribe: "stale",
  enabled: true,
  staleTime: 10000
});

useQueryData(key, options?)

React hook for simple data access without loading states

Parameters:

key(string | string[])Query key
options(UseQueryDataOptions<T>)Optional query options

Returns:

T | undefined

Example:

const todos = useQueryData(["todos"]);
const user = useQueryData(["user", userId]);

TypeScript Types

Type definitions and interfaces

QueryKey

Type for query keys - can be string or array of strings/numbers

Example:

type QueryKey = string | readonly (string | number)[];

// Examples:
const key1: QueryKey = "users";
const key2: QueryKey = ["user", 123];
const key3: QueryKey = ["posts", "published", 2024];

Fetcher<T>

Type for data fetching functions

Example:

type Fetcher<T = any> = () => Promise<T> | T;

// Examples:
const userFetcher: Fetcher<User[]> = async () => {
  const response = await fetch("/api/users");
  return response.json();
};

const syncFetcher: Fetcher<string> = () => "Hello World";

QueryOptions<T>

Configuration options for queries

Example:

type QueryOptions<T = any> = {
  enabled?: boolean;
  refetchOnSubscribe?: "always" | "stale" | false;
  fetcher?: Fetcher<T>;
  equalityFn?: EqualityFn<T>;
  staleTime?: number;
  signal?: AbortSignal;
  placeholderData?: T;
  usePreviousDataOnError?: boolean;
  usePlaceholderOnError?: boolean;
};

QueryState<T>

Return type for query state

Example:

type QueryState<T = any, E = Error> = {
  data?: T;
  error?: E;
  status: QueryStatus;
  updatedAt?: number;
  isStale: boolean;
  isPlaceholderData: boolean;
  isLoading: boolean;
  isFetching: boolean;
  isError: boolean;
  isSuccess: boolean;
  refetch: () => Promise<T>;
};

QueryStatus

Possible query status values

Example:

type QueryStatus = "idle" | "fetching" | "success" | "error";

// Usage in components:
const { status } = useQuery(["users"]);
if (status === "fetching") return <Spinner />;
if (status === "error") return <ErrorMessage />;
if (status === "success") return <DataComponent />;

EqualityFn<T>

Function type for data equality comparison

Example:

type EqualityFn<T = any> = (a: T | undefined, b: T | undefined) => boolean;

// Example custom equality function:
const arrayEquality: EqualityFn<User[]> = (a, b) => {
  return a?.length === b?.length && 
         a?.every((user, index) => user.id === b?.[index]?.id);
};

EqualityStrategy

Built-in equality comparison strategies - persists across all API calls

Example:

type EqualityStrategy = "shallow" | "deep";

// Shallow equality (default): compares only top-level properties
// Deep equality: recursively compares nested objects and arrays

// Usage:
registerFetcher(["users"], {
  fetcher: fetchUsers,
  equalityStrategy: "deep" // or "shallow"
});

// The strategy is automatically reused in all other API calls:
setQueryData(["users"], newData); // Uses "deep" strategy
getQueryData(["users"]);          // Uses "deep" strategy
getQueryState(["users"]);         // Uses "deep" strategy

DefaultConfig

Global configuration options

Example:

type DefaultConfig = {
  enabled?: boolean;
  refetchOnSubscribe?: "always" | "stale" | false;
  staleTime?: number;
  usePreviousDataOnError?: boolean;
  usePlaceholderOnError?: boolean;
  equalityFn?: EqualityFn<any>;
  equalityStrategy?: "shallow" | "deep";
  throttleTime?: number;
};

Utility Functions

Helper functions and utilities

serializeKey(key)

Convert query key to string for internal use

Parameters:

key(QueryKey)Query key to serialize

Example:

import { serializeKey } from "qortex-core";

const key1 = serializeKey("users"); // "users"
const key2 = serializeKey(["user", 123]); // "user,123"
const key3 = serializeKey(["posts", "published"]); // "posts,published"

Configuration

Configuration options and types

FetcherOptions<T>

Options for registering a fetcher

Properties:

fetcher(Fetcher<T>)Function that fetches data
staleTime?(number)Time before data is considered stale (ms)
placeholderData?(T)Data to show while loading
equalityFn?((a: T, b: T) => boolean)Function to compare data equality
equalityStrategy?("shallow" | "deep")Strategy for data equality comparison - persists across all API calls (default: "shallow")

UseQueryOptions<T>

Options for useQuery hook

Properties:

refetchOnSubscribe?("stale" | "always" | false)When to refetch on subscription
enabled?(boolean)Whether the query is enabled
staleTime?(number)Time before data is considered stale
equalityStrategy?("shallow" | "deep")Strategy for data equality comparison - persists across all API calls (default: "shallow")
placeholderData?(T)Data to show while loading

DefaultConfig

Global default configuration

Properties:

staleTime?(number)Default stale time for all queries
refetchOnSubscribe?("stale" | "always" | false)Default refetch behavior
throttleTime?(number)Default throttle time for duplicate requests
usePreviousDataOnError?(boolean)Keep previous data on error
equalityStrategy?("shallow" | "deep")Default equality strategy for all queries

TypeScript Types

Type definitions for better development experience

Core Types

// Core types
type Fetcher<T> = (key: string | string[]) => Promise<T>;
type EqualityFn<T> = (a: T, b: T) => boolean;

// Query result types
interface UseQueryResult<T> {
  data: T | undefined;
  isLoading: boolean;
  isFetching: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
  status: 'idle' | 'fetching' | 'success' | 'error';
  isStale: boolean;
  updatedAt: number | null;
  isPlaceholderData: boolean;
}

// Configuration types
interface FetcherOptions<T> {
  fetcher: Fetcher<T>;
  staleTime?: number;
  placeholderData?: T;
  equalityFn?: EqualityFn<T>;
}

interface UseQueryOptions<T> {
  refetchOnSubscribe?: 'stale' | 'always' | false;
  enabled?: boolean;
  fetcher?: Fetcher<T>;
  staleTime?: number;
  placeholderData?: T;
  usePreviousDataOnError?: boolean;
  usePlaceholderOnError?: boolean;
}

Need More Help?

Check out our guides and examples to learn more about using qortex effectively.

Basic Usage GuideConfiguration Guide