Browse Source

chore(gui-v2): add comments to `useApi`

pull/2877/head
braks 2 years ago
parent
commit
f2229e9bac
  1. 18
      packages/nc-gui-v2/composables/useApi/index.ts
  2. 20
      packages/nc-gui-v2/composables/useGlobal/index.ts

18
packages/nc-gui-v2/composables/useApi/index.ts

@ -14,6 +14,7 @@ interface UseApiReturn<D = any, R = any> {
onResponse: EventHook<AxiosResponse<D, R>>['on']
}
/** {@link Api} options */
interface CreateApiOptions {
baseURL?: string
}
@ -27,10 +28,27 @@ export function createApiInstance<SecurityDataType = any>(options: CreateApiOpti
}
interface UseApiProps<D = any> {
/** additional axios config for requests */
axiosConfig?: MaybeRef<AxiosRequestConfig<D>>
/** {@link Api} options */
apiOptions?: CreateApiOptions
}
/**
* Api composable that provides loading, error and response refs, as well as event hooks for error and response.
*
* You can use this composable to generate a fresh api instance with its own loading and error refs.
*
* Any request called by useApi will be pushed into the global requests state and which toggles the global loading state.
*
* @example
* ```js
* const { api, isLoading, error, response, onError, onResponse } = useApi()
*
* const onSignIn = async () => {
* const { token } = await api.auth.signIn(form)
* }
*/
export function useApi<Data = any, RequestConfig = any>(props: UseApiProps<Data> = {}): UseApiReturn<Data, RequestConfig> {
const state = useGlobal()

20
packages/nc-gui-v2/composables/useGlobal/index.ts

@ -2,13 +2,15 @@ import { useGlobalState } from './state'
import { useGlobalActions } from './actions'
import type { UseGlobalReturn } from './types'
import { useGlobalGetters } from './getters'
import { toRefs, useNuxtApp, watch } from '#imports'
import { useNuxtApp, watch } from '#imports'
/**
* Global state is injected by {@link import('~/plugins/state') state} plugin into our nuxt app (available as `$state`).
* Manual initialization is unnecessary and should be avoided.
* You can still call `useGlobal` to receive the `$state` object and access the global state.
* If it's not available yet, a new global state object is created and injected into the nuxt app.
*
* The state is stored in {@link WindowLocalStorage localStorage}, so it will be available even if the user closes the browser tab.
* Part of the state is stored in {@link WindowLocalStorage localStorage}, so it will be available even if the user closes the browser tab.
* Check the {@link StoredState StoredState} type for more information.
*
* @example
* ```js
@ -19,6 +21,18 @@ import { toRefs, useNuxtApp, watch } from '#imports'
* const token = $state.token.value
* const user = $state.user.value
* ```
*
* @example
* ```js
* import { useGlobal } from '#imports'
*
* const globalState = useGlobal()
*
* cont token = globalState.token.value
* const user = globalState.user.value
*
* console.log(state.isLoading.value) // isLoading = true if any api request is still running
* ```
*/
export const useGlobal = (): UseGlobalReturn => {
const { $state, provide } = useNuxtApp()

Loading…
Cancel
Save