package.dist.mutation.index.d.mts Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of swr Show documentation
React Hooks library for remote data fetching
The newest version!
import { Key, Arguments, SWRResponse } from 'swr/_internal';

type FetcherResponse = Data | Promise;
type FetcherOptions = Readonly<{
    arg: ExtraArg;
}>;
type MutationFetcher = SWRKey extends () => infer Arg | null | undefined | false ? (key: Arg, options: FetcherOptions) => FetcherResponse : SWRKey extends null | undefined | false ? never : SWRKey extends infer Arg ? (key: Arg, options: FetcherOptions) => FetcherResponse : never;
type SWRMutationConfiguration = {
    revalidate?: boolean | ((data: Data, key: Arguments) => boolean);
    populateCache?: boolean | ((result: Data, currentData: SWRData | undefined) => SWRData);
    optimisticData?: SWRData | ((currentData?: SWRData) => SWRData);
    rollbackOnError?: boolean | ((error: unknown) => boolean);
    fetcher?: MutationFetcher;
    onSuccess?: (data: Data, key: string, config: Readonly>) => void;
    onError?: (err: Error, key: string, config: Readonly>) => void;
};
type RemoveUndefined = T extends undefined ? never : T;
type IsUndefinedIncluded = undefined extends T ? true : false;
interface TriggerWithArgs {
    (extraArgument: ExtraArg, options?: SWRMutationConfiguration): Promise;
    (extraArgument: ExtraArg, options?: SWRMutationConfiguration & {
        throwOnError: true;
    }): Promise>;
    (extraArgument: ExtraArg, options?: SWRMutationConfiguration & {
        throwOnError: false;
    }): Promise;
}
interface TriggerWithOptionsArgs {
    (extraArgument?: ExtraArg, options?: SWRMutationConfiguration): Promise;
    (extraArgument?: ExtraArg, options?: SWRMutationConfiguration & {
        throwOnError: true;
    }): Promise>;
    (extraArgument?: ExtraArg, options?: SWRMutationConfiguration & {
        throwOnError: false;
    }): Promise;
}
interface TriggerWithoutArgs {
    (extraArgument?: null, options?: SWRMutationConfiguration): Promise;
    (extraArgument?: null, options?: SWRMutationConfiguration & {
        throwOnError: true;
    }): Promise>;
    (extraArgument?: null, options?: SWRMutationConfiguration & {
        throwOnError: false;
    }): Promise;
}
interface SWRMutationResponse extends Pick, 'data' | 'error'> {
    /**
     * Indicates if the mutation is in progress.
     */
    isMutating: boolean;
    /**
     * Function to trigger the mutation. You can also pass an extra argument to
     * the fetcher, and override the options for the mutation hook.
     */
    trigger: [ExtraArg] extends [never] ? TriggerWithoutArgs : IsUndefinedIncluded extends true ? TriggerWithOptionsArgs : TriggerWithArgs;
    /**
     * Function to reset the mutation state (`data`, `error`, and `isMutating`).
     */
    reset: () => void;
}
interface SWRMutationHook {
    (
    /**
     * The key of the resource that will be mutated. It should be the same key
     * used in the `useSWR` hook so SWR can handle revalidation and race
     * conditions for that resource.
     */
    key: SWRMutationKey, 
    /**
     * The function to trigger the mutation that accepts the key, extra argument
     * and options. For example:
     *
     * ```jsx
     * (api, data) => fetch(api, {
     *   method: 'POST',
     *   body: JSON.stringify(data)
     * })
     * ```
     */
    fetcher: MutationFetcher, 
    /**
     * Extra options for the mutation hook.
     */
    options?: SWRMutationConfiguration): SWRMutationResponse;
    (
    /**
     * The key of the resource that will be mutated. It should be the same key
     * used in the `useSWR` hook so SWR can handle revalidation and race
     * conditions for that resource.
     */
    key: SWRMutationKey, 
    /**
     * The function to trigger the mutation that accepts the key, extra argument
     * and options. For example:
     *
     * ```jsx
     * (api, data) => fetch(api, {
     *   method: 'POST',
     *   body: JSON.stringify(data)
     * })
     * ```
     */
    fetcher: MutationFetcher, 
    /**
     * Extra options for the mutation hook.
     */
    options?: SWRMutationConfiguration & {
        throwOnError: false;
    }): SWRMutationResponse;
    (
    /**
     * The key of the resource that will be mutated. It should be the same key
     * used in the `useSWR` hook so SWR can handle revalidation and race
     * conditions for that resource.
     */
    key: SWRMutationKey, 
    /**
     * The function to trigger the mutation that accepts the key, extra argument
     * and options. For example:
     *
     * ```jsx
     * (api, data) => fetch(api, {
     *   method: 'POST',
     *   body: JSON.stringify(data)
     * })
     * ```
     */
    fetcher: MutationFetcher, 
    /**
     * Extra options for the mutation hook.
     */
    options?: SWRMutationConfiguration & {
        throwOnError: true;
    }): SWRMutationResponse;
}

/**
 * A hook to define and manually trigger remote mutations like POST, PUT, DELETE and PATCH use cases.
 *
 * @link https://swr.vercel.app/docs/mutation
 * @example
 * ```jsx
 * import useSWRMutation from 'swr/mutation'
 *
 * const {
 *   data,
 *   error,
 *   trigger,
 *   reset,
 *   isMutating
 * } = useSWRMutation(key, fetcher, options?)
 * ```
 */
declare const useSWRMutation: SWRMutationHook;

export { type MutationFetcher, type SWRMutationConfiguration, type SWRMutationHook, type SWRMutationResponse, type TriggerWithArgs, type TriggerWithOptionsArgs, type TriggerWithoutArgs, useSWRMutation as default };