Usage

Pinia ORM Axios adds a new repository composable useAxiosRepo with an asynchronous method api(), when called, instantiates a new axios request for a repository. From these requests, repositories are able to persist data to the store automatically.

For example, a useAxiosRepo(User) model may typically want to fetch all users and persist the response to the store. Pinia ORM Axios can achieve this by performing a simple request:

await useAxiosRepo(User).api().get('https://example.com/api/users')

Performing Requests

Pinia ORM Axios supports the most commonly used axios request methods. These methods accept the same argument signature as their axios counterparts with the exception that the config can be expanded with additional plugin options.

Supported Methods

Here is a list of supported request methods:

useAxiosRepo(User).api().get(url, config)
useAxiosRepo(User).api().post(url, data, config)
useAxiosRepo(User).api().put(url, data, config)
useAxiosRepo(User).api().patch(url, data, config)
useAxiosRepo(User).api().delete(url, config)
useAxiosRepo(User).api().request(config)

Arguments given are passed on to the corresponding axios request method.

  • url is the server URL that will be used for the request.
  • data is the data to be sent as the request body (where applicable).
  • config is the plugin config options and also any valid axios request config options.

Request Configuration

You can pass any of the plugin's options together with any axios request options for a request method.

For example, let's configure the following get request:

useAxiosRepo(User).api().get('/api/users', {
  baseURL: 'https://example.com/',
  dataKey: 'result'
})

The baseURL is an axios request option which will be prepended to the request URL (unless the URL is absolute).

The dataKey is a plugin option which informs the plugin of the resource key your elements may be nested under in the response body.

Please refer to the list of supported request methods above to determine where the config argument can be given in the corresponding request method.

See also: Configurations

Persisting Response Data

By default, the response data from a request is automatically saved to the store corresponding to the model the request is made on.

For example, let's perform a basic get request on a useAxiosRepo(User) model:

useAxiosRepo(User).api().get('https://example.com/api/users')

The response body of the request may look like the following:

[
  {
    "id": 1,
    "name": "John Doe",
    "age": 24
  },
  {
    "id": 2,
    "name": "Jane Doe",
    "age": 21
  }
]

Pinia ORM Axios will automatically save this data to the store, and the users entity in the store may now look like the following:

{
  users: {
    data: {
      1: { id: 1, name: 'John Doe', age: 24 },
      2: { id: 2, name: 'Jane Doe', age: 21 }
    }
  }
}

Under the hood, the plugin will persist data to the store by determining which records require inserting and which require updating.

If you do not want to persist response data automatically, you can defer persistence by configuring the request with the { save: false } option.

You may configure Pinia ORM Axios to persist data using an alternative Pinia ORM persist method other than the default save. For example, you can use insert:

useAxiosRepo(User).api().get('/api/users', { persistBy: 'insert' })

See also:

Delete Requests

::: warning When performing a delete request, the plugin will not remove the corresponding entities from the store. It is not always possible to determine which record is to be deleted and often HTTP DELETE requests are performed on a resource URL. :::

If you want to delete a record from the store after performing a delete request, you must pass the delete option with the ID of the entity.

useAxiosRepo(User).api().delete('/api/users/1', {
  delete: 1
})

See also: Configurations - delete

Handling Responses

Every request performed will return a Response object as the resolved value. This object is responsible for carrying and handling the response body and ultimately executing actions such as persisting data to the store.

The Response object contains two noteworthy properties:

  • entities is the list of entities persisted to the store by Pinia ORM.
  • response is the original axios response schema.

You may access these properties through the returned value:

const result = await useAxiosRepo(User).api().get('/api/users')
// Retrieving the response status.
result.response.status // 200
// Entities persisted to the store from the response body.
result.entities // { users: [{ ... }] }

See also: API Reference - Response

Transforming Data

You can configure the plugin to perform transformation on the response data, using the dataTransformer configuration option, before it is persisted to the store.

For example, your API response may conform to the JSON:API specification but may not match the schema for your useAxiosRepo(User) model. In such cases you may want to reformat the response data in a manner in which Pinia ORM can normalize.

The dataTransformer method can also be used to hook into response data before it is persisted to the store, allowing you to access other response properties such as response headers, as well as manipulate the data as you see fit.

To demonstrate how you may use this option, let's assume your response body looks like this:

{
  ok: true,
  record: {
    id: 1,
    name: 'John Doe'
  }
}

The following example intercepts the response using a dataTransformer method to extract the data to be persisted from the nested property.

useAxiosRepo(User).api().get('/api/users', {
  dataTransformer: (response) => {
    return response.data.record
  }
})

See also: Configurations - dataTransformer

Deferring Persistence

By default, the response data from a request is automatically saved to the store but this may not always be desired.

To prevent persisting data to the store, define and set the save option to false. The Response object conveniently provides save() method which allows you to persist the data at any time.

For example, you might want to check if the response contains any errors:

// Prevent persisting response data to the store.
const result = await useAxiosRepo(User).api().get('/api/users', {
  save: false
})
// Throw an error.
if (result.response.data.error) {
  throw new Error('Something is wrong.')
}
// Otherwise continue to persist to the store.
result.save()

When deferring persistence you can also determine whether the response data has been persisted to the store using the convenient isSaved property:

const result = await useAxiosRepo(User).api().get('/api/users', {
  save: false
})
result.isSaved // false
await result.save()
result.isSaved // true

See also:

Table of Contents