@scayle/storefront-nuxt/dist/runtime/composables/core/useRpc.d.ts

Nuxt integration for the SCAYLE Commerce Engine and Storefront API

import type { RpcContext, RpcMethodName, RpcMethodParameters, RpcMethodReturnType } from '@scayle/storefront-core';
import { useAsyncData } from 'nuxt/app';
import type { AsyncDataOptions, NuxtApp } from 'nuxt/app';
import type { MaybeRefOrGetter } from 'vue';
/**
 * Extracts keys from a type `T` as an array of strings.
 *
 * @template T The type from which to extract keys.
 */
export type KeysOf<T> = Array<T extends T ? (keyof T extends string ? keyof T : never) : never>;
/**
 * Normalized return type of a RPC method, excluding its `Response` object.
 *
 * @template N The RPC Method Name.
 */
export type NormalizedRpcResponse<N extends RpcMethodName> = Exclude<Awaited<RpcMethodReturnType<N>>, Response>;
/**
 * Representation of options for the `useRpc` composable, extending `AsyncDataOptions`.
 *
 * @template N The RPC Method Name.
 * @template DataT The data type. Defaults to `NormalizedRpcResponse<N>`.
 * @template PickKeys The keys to pick from `DataT`. Defaults to all keys of `DataT`.
 * @template DefaultT  The default value type. Defaults to `null`.
 * @template ResponseT The response type. Defaults to `NormalizedRpcResponse<N>`.
 */
export type UseRpcOptions<N extends RpcMethodName, DataT = NormalizedRpcResponse<N>, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null, ResponseT = NormalizedRpcResponse<N>> = AsyncDataOptions<ResponseT, DataT, PickKeys, DefaultT>;
/**
 * Type of the key parameter for the `useRpc` composable.
 */
export type UseRpcCacheKey = Parameters<typeof useAsyncData>[0];
/**
 * Return type of the `useRpc` composable, extending `ExtendedAsyncData`.
 *
 * @template N The RPC Method Name.
 * @template DataT The data type. Defaults to `NormalizedRpcResponse<N>`.
 * @template PickKeys The keys to pick from `DataT.` Defaults to all keys of `DataT`.
 * @template DefaultT The default value type. Defaults to `null`.
 * @template ResponseT The response type. Defaults to `NormalizedRpcResponse<N>`.
 */
export type UseRpcReturn<N extends RpcMethodName, DataT = NormalizedRpcResponse<N>, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null, ResponseT = NormalizedRpcResponse<N>> = ExtendedAsyncData<ResponseT, unknown, DataT, PickKeys, DefaultT>;
export type Status = 'idle' | 'pending' | 'success' | 'error';
type AsyncData<ResT, ErrorT = unknown, DataT = ResT, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null> = ReturnType<typeof useAsyncData<ResT, ErrorT, DataT, PickKeys, DefaultT>>;
type AwaitedAsyncData<ResT, ErrorT = unknown, DataT = ResT, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null> = Awaited<AsyncData<ResT, ErrorT, DataT, PickKeys, DefaultT>>;
/**
 * Extended `AsyncData` type, adding a promise to the result.
 *
 * @template ResT The response type.
 * @template ErrorT The error type. Defaults to `unknown`.
 * @template DataT The data type. Defaults to `ResT`.
 * @template PickKeys The keys to pick from `DataT`. Defaults to all keys of `DataT`.
 * @template DefaultT The default value type. Defaults to `null`.
 */
export type ExtendedAsyncData<ResT, ErrorT = unknown, DataT = ResT, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null> = AwaitedAsyncData<ResT, ErrorT, DataT, PickKeys, DefaultT> & Promise<AwaitedAsyncData<ResT, ErrorT, DataT, PickKeys, DefaultT>>;
export declare const defaultCachedData: <ResponseT>(key: string, nuxtApp: NuxtApp) => ResponseT | undefined;
/**
 * `useRpc` is a wrapper around `useAsyncData` for registered RPC methods.
 *
 * This composable provides a declarative approach to data fetching by wrapping
 * `useAsyncData` for registered RPC methods. It handles the fetch state,
 * automatically executes the RPC method, and returns the result or any errors.
 * Many Storefront composables utilize `useRpc` as lightweight wrappers around provided RPC methods.
 *
 * The parameters for the RPC call can be passed as a raw value, a ref, or a function.  If a reactive ref or function is provided,
 * `useRpc` will automatically re-fetch the data when the parameters change.
 *
 * By default, `useRpc` utilizes a shared cache, so all instances called with the same key will share the same data.  This behavior can be
 * disabled globally via the `disableDefaultGetCachedDataOverride` option in the public runtime config, or individually per call using the `options` parameter.
 *
 * @see https://nuxt.com/docs/api/composables/use-async-data#params
 * @see https://scayle.dev/en/core-documentation/storefront-guide/storefront-application/technical-foundation/rpc-methods#userpc
 *
 * @param method The name of the RPC method to call (e.g., 'useBrand).
 * @param key A unique key for caching, persisting the data between server and client,
 *            and de-duplicating requests (e.g., 'use-brand').
 * @param params The parameters for the RPC method. Can be a value, a `Ref`,
 *               or a function. If reactive, changes will trigger a re-fetch.
 *                - When passed as a raw value, the parameters are set at the point
 *                 `useRpc` is called. Subsequent `refresh` calls will use the same params.
 *                - When passed as a function, the function will be invoked each
 *                  time `refresh` is called to get the params.
 *                - When passed as a Ref, a watcher wil be added that
 *                  calls `refresh` each time params change.
 * @param options Options for `useAsyncData`, including `watch`, `getCachedData`,
 *                and more. Can be used to control caching behavior. By default,
 *                `useRpc` will set `immediate` to `false` and will pass `[params]`
 *                to `watch` if `params` is a `Ref`.
 *
 *  @returns An object containing the `data`, `status`, and other properties from
 *           `useAsyncData`, as well as a promise that resolves to the data.
 *
 * @example
 * ```typescript
 *   import { useRpc } from '#storefront/composables'
 *
 *    const { data: shopId, fetching } = useRpc('getShopId', 'current-shop-id')
 * ```
 */
export declare function useRpc<N extends RpcMethodName, DataT = NormalizedRpcResponse<N>, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null, ResponseT = NormalizedRpcResponse<N>>(method: N, key: UseRpcCacheKey, params?: MaybeRefOrGetter<RpcMethodParameters<N> extends RpcContext ? undefined : RpcMethodParameters<N>>, options?: UseRpcOptions<N, DataT, PickKeys, DefaultT, ResponseT>): ExtendedAsyncData<ResponseT, unknown, DataT, PickKeys, DefaultT>;
export {};