Api 3.9.0

Api module provides a set of composable functions to work with the network requests. This composable has direct integration with Http module.

useQuery

Executes given promise function immediately and set the result to data ref.

interface Query<Data = any> {
  loading: Ref<boolean>
  data: Ref<Data | undefined>
  execute(options?: {
    /**
     * controls whether the response should be assigned to the data ref
     * @default true
     */
    assign?: boolean
    /**
     * controls whether the loading state should not be set before fetching
     * @default false
     */
    silent?: boolean
  }): Promise<Data>
}

interface UseQueryOptions {
  /**
   * controls whether the query should execute immediately
   * @default true
   */
  immediate?: boolean
  /**
   * watch the given source(s) and re-execute the query
   */
  watch?: WatchSource | WatchSource[]
}

function useQuery<Data = any>(
  req: (http: Http) => Promise<Data>,
  options?: UseQueryOptions
): Query<Data>

import { useQuery } from '@globalbrain/sefirot/lib/composables/Api'

const { data, loading } = useQuery((http) => {
  return http.get('/api/users')
})

useGet

Alias to useMutation. Use this method when you want to execute a request on user interaction, but not mutating data. Good example is when downloading a file.

type Get<
  Data = any,
  Args extends any[] = any[]
> = Mutation<Data, Args>

function useGet<Data = any, Args extends any[] = any[]>(
  req: (http: Http, ...args: Args) => Promise<Data>
): Get<Data, Args>

import { useGet } from '@globalbrain/sefirot/lib/composables/Api.vue'

const { execute: download } = useGet((http, path: string) => {
  return http.download(`/api/users/${path}`)
})

download('avatar.png')

useMutation

Creates a composable that can execute given promise function at later time.

interface Mutation<Data = any, Args extends any[] = any[]> {
  loading: Ref<boolean>
  data: Ref<Data | undefined>
  execute(...args: Args): Promise<Data>
}

function useMutation<Data = any, Args extends any[] = any[]>(
  req: (http: Http, ...args: Args) => Promise<Data>
): Mutation<Data, Args>

import { useMutation } from '@globalbrain/sefirot/lib/composables/Api.vue'

const { execute: createUser } = useMutation((http, name: string) => {
  return http.post(`/api/users`, {
    name
  })
})

updateUser(1, 'Jane Doe')