Features

@volverjs/query-vue is a Vue 3 library that provides a simple way to sync the state of your application with a data source. It is designed to be used with pinia and @volverjs/data repository.

Install

``bash


pnpm

pnpm add @volverjs/query-vue

yarn

yarn add @volverjs/query-vue

npm

npm install @volverjs/query-vue --save
`

Getting started

Following examples are based on a RepositoryHttp instance, but you can use any @volverjs/data repository you want.

First of all, you need to initialize pinia in your application, then you can create a store composable using defineStoreRepository():

`ts
import { HttpClient, RepositoryHttp } from '@volverjs/data'
// user-store.ts
import { defineStoreRepository } from '@volverjs/query-vue'

/ Define an User type /
export type User = {
id?: number
username: string
}

/ Create an HttpClient instance /
const httpClient = new HttpClient({
prefixUrl: 'https://my-domain.com'
})

/ Create a RepositoryHttp instance /
const usersRepository = new RepositoryHttp(httpClient, 'users/:id?')

/ Create a store repository composable /
export const useUsersStore = defineStoreRepository(
usersRepository,
// the store name
'users'
)
`

In a component you can use the useUsersStore() composable to get store actions and getters.

Read

read() action allow to read data from the repository:

`vue



`

read() returns an object that contains:

`ts
const {
/ Reactive boolean that indicates if the request is loading /
isLoading,
/ Reactive boolean that indicates if the request has failed /
isError,
/ Reactive boolean that indicates if the request has succeeded /
isSuccess,
/ Reactive error object /
error,
/ Reactive status of the request /
status,
/ Reactive query object /
query,
/ Reactive array of data returned by the repository /
data,
/ Reactive metadata object returned by the repository /
metadata,
/ Reactive first item of the data array /
item,
/ Function to execute the read() action /
execute,
/ Function to stop autoExecute option /
stop,
/ Function to ignore reactive parameters updates /
ignoreUpdates,
/ Function to cleanup the store repository /
cleanup
} = read()
`

$3

read() accepts an optional parameters map.

`ts
const { data } = read({
page: 1
})
`

The parameters map can be reactive, data will be automatically updated on parameters change with autoExecute option:

`ts
const parameters = ref({
page: 1
})
const { data } = read(parameters, {
autoExecute: true
})

// ...

parameters.value = {
page: 2
}
// read() will be re-executed
`

autoExecute can be stopped with stop() function:

`ts
const parameters = ref({
page: 1
})
const { data, stop } = read(parameters, {
autoExecute: true
})

// ...

stop()
// read() will not be re-executed
`

A reactive parameters update can be ignored with ignoreUpdates function:

`ts
const params = ref({
page: 1
})
const { data, ignoreUpdates } = read(params, {
autoExecute: true
})

// ...

ignoreUpdates(() => {
params.value = {
page: 1,
other: 'value'
}
})
`

$3

You can re-execute the read() action by calling the execute() method with a parameters map that will override the current parameters:

`ts
const { data, execute } = read({
sort: 'name',
order: 'asc'
})

// ...

execute({
sort: 'name',
order: 'desc'
})
// read() will be re-executed with the given parameters
`

Persistance can be ignored with the force option:

`ts
const { data, execute } = read({
sort: 'name',
order: 'asc'
})

// ...

execute(true)
// read() will be re-executed ignoring persistance

// ...

execute(
{
sort: 'name',
order: 'desc'
},
true
)
// read() will be re-executed with the given parameters ignoring persistance
`

A read() can be executed later with immediate: false option:

`ts
const { data, execute } = read(
{
page: 1
},
{
// read() will not be executed
immediate: false
}
)

// ...

execute()
// read() will be executed for the first time
`

$3

A read() can be executed when a condition is met with executeWhen option:

`ts
const params = ref({
page: undefined
})
const { data, execute } = read(params, {
executeWhen: computed(() => params.value.page !== undefined)
})

// ...

params.value.page = 1
// read() will be executed
`

executeWhen can also be function that receives the parameters and returns a boolean:

`ts
const params = ref({
page: undefined
})
const { data, execute } = read(params, {
executeWhen: newParams => newParams.page !== undefined
})

// ...

params.value.page = 1
// read() will be executed
`

$3

read() accepts the following options:

`ts
const {
data
// ...
} = read(
/ The parameters map (default: undefined) /
params,
/ The options object (default: undefined) /
{
/*
* The name of the query (default: undefined)
* if not defined, the query name will be generated
*/
name: undefined,
/*
* Group all queries executed by the same read() action
* and exposes all items in data (default: false)
* Can be useful when you need to display a list of items
* (ex. inifinite scroll)
*/
group: false,
/*
* Store query results in a
* separate directory (default: false)
*/
directory: false,
/*
* Keep the query alive when
* the component is unmounted (default: false)
*/
keepAlive: false,
/*
* Execute the read() action immediately (default: true)
*/
immediate: true,
/*
The query cache time in milliseconds (default: 60 60 * 1000)
*/
persistence: 60 60 1000,
/*
* A boolean reactive parameter (or a function) that indicates
* when the read() action should be executed (default: undefined)
* For example:
* executeWhen: (newParams) => newParams.id !== undefined
* Or:
* executeWhen: computed(() => parameters.value.id !== undefined)
*/
executeWhen: undefined,
/*
* Automatically execute the read() action
* on reactive parameters change (default: false)
*/
autoExecute: false,
/*
* The query auto execute throttle
* in milliseconds (default: 0)
*/
autoExecuteDebounce: 0,
/*
* Automatically execute the read() action
* on window focus (default: false)
*/
autoExecuteOnWindowFocus: false,
/*
* Automatically execute the read() action
* on document visibility change (default: false)
*/
autoExecuteOnDocumentVisibility: false,
}
)
`

Submit

submit() action allow to create or update data from the repository. Generally, has the same behavior of read() action but requires a payload parameter.

`vue



`

submit() returns an object that contains:

`ts
const {
/ Reactive boolean that indicates if the request is loading /
isLoading,
/ Reactive boolean that indicates if the request has failed /
isError,
/ Reactive boolean that indicates if the request has succeeded /
isSuccess,
/ Reactive error object /
error,
/ Reactive status of the request /
status,
/ Reactive query object /
query,
/ Reactive array of data returned by the repository /
data,
/ Reactive metadata object returned by the repository /
metadata,
/ Reactive first item of the data array /
item,
/ Function to execute the submit() action /
execute,
/ Function to stop autoExecute option /
stop,
/ Function to ignore reactive parameters updates /
ignoreUpdates,
/ Function to cleanup the store repository /
cleanup
} = submit()
`

$3

submit() accepts the following options:

`ts
const {
isSuccess
// ...
} = submit(
/ The submit payload (required) /
payload,
/ The parameters map (default: undefined) /
params,
/ The options object (default: undefined) /
{
/*
* The name of the query (default: undefined)
* if not defined, the query name will be generated
*/
name: undefined,
/*
* Keep the query alive when
* the component is unmounted (default: false)
*/
keepAlive: false,
/*
* Execute the submit() action immediately (default: true)
*/
immediate: true,
/*
* A boolean reactive parameter (or a function) that indicates
* when the submit() action should be executed (default: undefined)
* For example:
* executeWhen: (newPayload, newParams) => newParams.id !== undefined
* Or:
* executeWhen: computed(() => parameters.value.id !== undefined)
*/
executeWhen: undefined,
/*
* Automatically execute the submit() action
* on reactive parameters change (default: false)
*/
autoExecute: false,
/*
* The query auto execute throttle
* in milliseconds (default: 0)
*/
autoExecuteDebounce: 0,
/*
* Automatically execute the submit() action
* on window focus (default: false)
*/
autoExecuteOnWindowFocus: false,
/*
* Automatically execute the submit() action
* on document visibility change (default: false)
*/
autoExecuteOnDocumentVisibility: false,
}
)
`

As read() also submit() can be executed later too with immediate: false option:

`vue



`

Remove

remove() action allow to delete data from the repository:

`vue



`

remove() returns an object that contains:

`ts
const {
/ Reactive boolean that indicates if the request is loading /
isLoading,
/ Reactive boolean that indicates if the request has failed /
isError,
/ Reactive boolean that indicates if the request has succeeded /
isSuccess,
/ Reactive error object /
error,
/ Reactive status of the request /
status,
/ Function to execute the remove() action /
execute,
} = remove({
// ...
})
`

$3

remove() accepts the following options:

`ts
const {
isSuccess
// ...
} = remove(
/ The parameters map (required) /
params,
/ The options object (default: undefined) /
{
/ Execute the remove() action immediately (default: true) /
immediate: true
}
)
`

Components

@volverjs/query-vue also exposes some useful components:

$3

ReadProvider is a component that allows to use read() action in a component tree:

`vue



`

ReadProvider exposes all the properties returned by read() in the v-slot scope and accepts the following props:

`vue

`

$3

SubmitProvider is a component that allows to use submit() action in a component tree:

`vue



`

SubmitProvider exposes all the properties returned by submit() in the v-slot scope and accepts the following props:

`vue

`

The v-model directive provides a two-way binding so the reactive payload object will be updated when the submit() action is executed (for example with the server response).

By default SubmitProvider will not execute the submit() action immediately, but you can change this behavior with immediate option.

$3

RemoveProvider is a component that allows to use remove() action in a component tree:

`vue



`

RemoveProvider exposes all the properties returned by remove() in the v-slot scope and accepts the following props:

`vue

`

By default RemoveProvider will not execute the remove() action immediately, but you can change this behavior with immediate option.

Acknoledgements

@volverjs/query-vue is inspired by React Query`.

License

MIT