voyager-react v1.2.11

voyager-react

The easiest way in the entire interstellar space, to consume a REST API. State management included.

Voyager aims to be to REST what Apollo Client is to GraphQL. In this spirit, Voyager also implements state management and maintains a local cache of the data.

For example, after sending a POST request Voyager will automatically update any GET requests that should include the newly created entity. Similarly for PUT and DELETE requests.

Installation

yarn add voyager-react

or

npm install --save voyager-react

Usage

Wrap your application with the <VoyagerProvider> tag

const Main = () => {
  return (
    <VoyagerProvider
      auth="http://localhost:3000/auth"
      url="http://localhost:3000/api/v1"
    >
      <App/>
   </VoyagerProvider>
  )
}

The auth URL must point to a very simple authentication server. Example server coming soon. This URL is used to obtain an API token using the login (see useLogin hook - coming soon). The token shell be used in each subsequent request to the API.

The URL attribute must point the the REST API. This is an (almost) standard REST (example server coming soon).

API

useGet<T=any>(resource: string, options?: Partial<RequestOptions>): [RequestState<T>, GetFunction<T>]

This hook is used to generate a GET request. Filtering, sorting and pagination information will be appended as URL query parameters, using default values if not explicitly provided.

Parms

RequestOptions

QueryParameters

Sort

string, 'asc' | 'desc'

The first string must be a fiend available on the entities to be sorted. The second array items indicates the sorting order.

FilterObj

Filter

[

'eq' | 'neq' | 'regex' | 'in' | 'gt' | 'gte' | 'lt' | 'lte',

string | number | null | Array<string | number | null>

]

A filter consists of an operation, on the first position and a right hand side operator on the second position. So, for example the following FilterObj will get all entries that have the type equal to "fast-food".

{
  type: ["eq", "fast-food"]
}

Return Value

RequestState

Meta

GetFunction\ = (params?: GetFunctionParams) => Promise\

GetFunctionParams

Example

const Restaurants = () => {

  const [{loading, data, err}] = useGet("restaurants", {
    sort_by: ["rating", "desc"],
    query: {
      rating: ["gte", 4],
      location: ["in", ["Bucharest", "Iasi"]]
    }
  })

  if(loading) return null

  if(err) return <p>{err}</p>

  return (
    <div>
      {data.map(r => <RestaurantItem data={r}/>)}
    </div>
  )
}

usePost<T=any>(path: string): [RequestState<T>, HookRunFunction<T>]

usePut<T=any>(path: string): [RequestState<T>, HookRunFunction<T>]

useDelete<T=any>(path: string): [RequestState<T>, HookRunFunction<T>]

These three hooks map to the remaining three verbs in the REST API standard. Their usage is self explanatory.

The RequestState object has been previously described.

HookRunFunction\ = (params?: {id?: string; body?: object) => Promise\

Bonus

usePagination(path: string, options?: Partial<RequestOptions>): [RequestState<T>, GetFunction<T>, NextPageFunction, PrevPageFunction, SeCurrentPageFunction, GetCurrentPage, SetPageSizeFunction]

This hook works exactly the same as the useGet hook, only that it returns more variables. Besides the ones already described, the extra variables returned are functions designed to interact with the pagination of the data.

Not only this hook fetches the requested page, but it will also pre-fetch the next page.

License

MIT © Alexandru Niculae (alexnix)