@gqty/react/query/useQuery.d.ts

The No-GraphQL Client for React

import { GQtyError, prepass, type BaseGeneratedSchema, type GQtyClient, type GeneratedSchemaObject, type RetryOptions } from 'gqty';
import { type LegacyFetchPolicy, type OnErrorHandler } from '../common';
import type { ReactClientOptionsWithDefaults } from '../utils';
export interface UseQueryPrepareHelpers<GeneratedSchema extends {
    query: object;
}> {
    readonly prepass: typeof prepass;
    readonly query: GeneratedSchema['query'];
}
export interface UseQueryOptions<TSchema extends BaseGeneratedSchema> {
    /**
     * Defines how a query should fetch from the cache and network.
     *
     * - `default`: Serves the cached contents when it is fresh, and if they are
     * stale within `staleWhileRevalidate` window, fetches in the background and
     * updates the cache. Or simply fetches on stale cache or cache miss. During
     * SWR, a successful fetch will not notify cache updates. New contents are
     * served on next query.
     * - `no-store`: Always fetch and does not update on response.
     * GQty creates a temporary cache at query-level which immediately expires.
     * - `reload`: Always fetch, updates on response.
     * - `no-cache`: Same as `reload`, for GraphQL does not support conditional
     * requests.
     * - `force-cache`: Serves the cached contents regardless of staleness. It
     * fetches on cache miss or a stale cache, updates cache on response.
     * - `only-if-cached`: Serves the cached contents regardless of staleness,
     * throws a network error on cache miss.
     *
     * _It takes effort to make sure the above stays true for all supported
     * frameworks, please consider sponsoring so we can dedicate even more time on
     * this._
     */
    cachePolicy?: RequestCache;
    /** Custom GraphQL extensions to be exposed to the query fetcher. */
    extensions?: Record<string, unknown>;
    /**
     * Allow fetches when the browser is minified or hidden. When disabled, use
     * the `refetchOnWindowVisible` option or call `$refetch()` to fetch.
     */
    fetchInBackground?: boolean;
    /** Specify the value of $state.isLoading before the first fetch. */
    initialLoadingState?: boolean;
    /** Enable this to update $state.isLoading or suspense during refetches. */
    notifyOnNetworkStatusChange?: boolean;
    /**
     * A callback function that is called when an error occurs in the query
     * fetcher, and `maxRetries` is reached.
     */
    onError?: OnErrorHandler;
    /**
     * Specify a custom GraphQL operation name in the query. This separates the
     * query from the internal query batcher, resulting a standalone fetch for
     * easier debugging.
     */
    operationName?: string;
    /**
     * Making selections before the component is rendered, allowing Suspense
     * to happen during first render.
     */
    prepare?: (helpers: UseQueryPrepareHelpers<TSchema>) => void;
    /**
     * Soft-refetch on the specified interval, skip this option to disable.
     */
    refetchInterval?: number;
    /**
     * Soft-refetch when the browser regains connectivity.
     *
     * @default true
     */
    refetchOnReconnect?: boolean;
    /**
     * Soft-refetch on render.
     *
     * @default true
     */
    refetchOnRender?: boolean;
    /**
     * Soft-refetch when user comes back to the browser tab.
     *
     * @default true
     */
    refetchOnWindowVisible?: boolean;
    /** Retry strategy upon fetch failures. */
    retryPolicy?: RetryOptions;
    /**
     * Changes rendering in the following ways,
     * 1. Suspenses the component during query fetch.
     * 2. Throws the latest fetch error for error boundaries.
     *
     * @default false
     */
    suspense?: boolean;
    /** @deprecated Use `retryPolicy` instead. */
    retry?: RetryOptions;
    /** @deprecated Use `cachePolicy` instead. */
    fetchPolicy?: LegacyFetchPolicy;
    /** @deprecated Use `staleWhileRevalidate` in the Cache options. */
    staleWhileRevalidate?: boolean | object | number | string | null;
}
export interface UseQueryState {
    /** The current loading state when suspense is disabled. */
    readonly isLoading: boolean;
    /**
     * Latest scheduler Error, for more in-depth error management use
     * `useMetaState` hook
     */
    error?: GQtyError;
}
export type Writeable<T> = {
    -readonly [P in keyof T]: T[P];
};
export type UseQueryReturnValue<GeneratedSchema extends {
    query: object;
}> = GeneratedSchema['query'] & {
    $state: UseQueryState;
    $refetch: (
    /**
     * Hard refetch, ignoring current cache freshness.
     *
     * @default true
     */
    ignoreCache?: boolean) => Promise<unknown>;
};
export interface UseQuery<GeneratedSchema extends {
    query: GeneratedSchemaObject;
}> {
    (options?: UseQueryOptions<GeneratedSchema>): UseQueryReturnValue<GeneratedSchema>;
}
export declare const createUseQuery: <TSchema extends BaseGeneratedSchema>(client: GQtyClient<TSchema>, { defaults: { initialLoadingState: defaultInitialLoadingState, suspense: defaultSuspense, staleWhileRevalidate: defaultStaleWhileRevalidate, retry: defaultRetry, }, }: ReactClientOptionsWithDefaults) => UseQuery<TSchema>;