You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Introduced `useQuery` and `useStatus` composables which include compilable query support. Deprecated `usePowerSyncQuery`, `usePowerSyncWatchedQuery`, and `usePowerSyncStatus`.
Copy file name to clipboardExpand all lines: packages/vue/README.md
+69-36Lines changed: 69 additions & 36 deletions
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,7 @@ app.use(powerSyncPlugin);
23
23
app.mount('#app');
24
24
```
25
25
26
-
###Overriding the PowerSync instance
26
+
## Overriding the PowerSync instance
27
27
28
28
The `createPowerSyncPlugin` function is designed for setting up a PowerSync client that is available across your entire Vue application. It's the recommended approach for package setup. However, there may be situations where an app-wide setup isn't suitable, or you need a different PowerSync client for specific parts of your application.
29
29
@@ -43,7 +43,7 @@ providePowerSync(db);
43
43
</script>
44
44
```
45
45
46
-
###Accessing PowerSync
46
+
## Accessing PowerSync
47
47
48
48
The provided PowerSync client is available with the `usePowerSync` composable.
The `usePowerSyncQuery` composable provides a static view of a given query. You can use refs as parameters instead to automatically refresh the query when they change. The composable exposes reactive variables for the results, the loading state and error state, as well as a refresh callback that can be invoked to rerun the query manually.
70
+
The `useQuery` composable provides a dynamic view of a given query. The data will automatically update when a dependent table is updated.
71
+
72
+
You can use refs as parameters to refresh the query when they change. The composable exposes reactive variables for the results as well as the loading, fetching, and and error states. Note that `isLoading` indicates that the initial result is being retrieved and `isFetching` indicates the query is fetching data, which could be for the initial load or any time when the query is re-evaluating due to a change in a dependent table.
71
73
72
74
```Vue
73
75
// TodoListDisplayQuery.vue
74
76
<script setup>
75
-
import { usePowerSyncQuery } from '@powersync/vue';
77
+
import { usePowerSync, useQuery } from '@powersync/vue';
<li v-for="l in list" :key="l.id">{{ l.name }}</li>
88
97
</ul>
89
-
<button @click="refresh">Refresh</button>
98
+
<button @click="addList">Add list</button>
90
99
</template>
91
100
```
92
101
93
-
### Watched Queries
102
+
### Static query
94
103
95
-
The `usePowerSyncWatchedQuery` composable provides a dynamic view of a given query. The data will automatically update when a dependent table is updated.
96
-
97
-
You can use refs as parameters to refresh the query when they change. The composable exposes reactive variables for the results as well as the loading, fetching, and and error states. Note that `loading` initicates that the initial result is being retrieved and `fetching` indicates the query is fetching data, which could be for the initial load or any time when the query is re-evaluating due to a change in a dependent table.
104
+
The `useQuery` composable can be configured to only execute initially and not every time changes to dependent tables are detected. The query can be manually re-executed by using the returned `refresh` function.
98
105
99
106
```Vue
100
-
// TodoListDisplayWatchedQuery.vue
107
+
// TodoListDisplayStaticQuery.vue
101
108
<script setup>
102
-
import { usePowerSync, usePowerSyncWatchedQuery } from '@powersync/vue';
<li v-for="l in list" :key="l.id">{{ l.name }}</li>
122
-
</ul>
123
-
<button @click="addList">Add list</button>
123
+
```
124
+
125
+
### TypeScript Support
126
+
127
+
A type can be specified for each row returned by `useQuery`. Remember to declare `lang="ts"` when defining a `script setup` block.
128
+
129
+
```Vue
130
+
// TodoListDisplayStaticQueryTypeScript.vue
131
+
<script setup lang="ts">
132
+
import { useQuery } from '@powersync/vue';
133
+
134
+
const { data } = useQuery<{ id: string, name: string }>('SELECT id, name FROM lists');
135
+
</script>
136
+
137
+
<template>
138
+
<ul>
139
+
<li v-for="l in data" :key="l.id">{{ l.name }}</li>
140
+
</ul>
124
141
</template>
125
142
```
126
143
127
-
### Connection Status
144
+
You are also able to use a compilable query (e.g. [Kysely queries](https://github.com/powersync-ja/powersync-js/tree/main/packages/kysely-driver)) as a query argument in place of a SQL statement string.
145
+
146
+
```Vue
147
+
// TodolistDisplayQueryKysely.vue
148
+
<script setup lang="ts">
149
+
import { usePowerSync, useQuery } from '@powersync/vue';
150
+
import { wrapPowerSyncWithKysely } from '@powersync/kysely-driver';
151
+
import { Database } from '@/library/powersync/AppSchema';
152
+
153
+
const powerSync = usePowerSync();
154
+
const db = wrapPowerSyncWithKysely<Database>(powerSync.value);
155
+
156
+
const { data } = useQuery(db.selectFrom('lists').selectAll().where('name', 'like', '%Shopping%'));
157
+
</script>
158
+
```
159
+
160
+
## Connection Status
128
161
129
-
The `usePowerSyncStatus` composable provides general connectivity information such as the connection status, whether the initial full sync has completed, when the last sync completed, and whether any data is being uploaded or downloaded.
162
+
The `useStatus` composable provides general connectivity information such as the connection status, whether the initial full sync has completed, when the last sync completed, and whether any data is being uploaded or downloaded.
130
163
131
164
```Vue
132
165
// ConnectionStatus.vue
133
166
<script setup>
134
-
import { usePowerSyncStatus } from '@powersync/vue';
167
+
import { useStatus } from '@powersync/vue';
135
168
136
-
const { status } = usePowerSyncStatus();
169
+
const status = useStatus();
137
170
</script>
138
171
139
172
<template>
@@ -150,7 +183,7 @@ const { status } = usePowerSyncStatus();
150
183
151
184
### Top-level setup block
152
185
153
-
The `usePowersync`, `usePowerSyncQuery`, `usePowerSyncWatchedQuery`, and `usePowerSyncStatus` composables are meant to be invoked in the top-level setup block. Vue expects certain Composition API functions, like `inject` which this package depends on, to be resolved in the setup context and not inside nested or asynchronous functions. For use cases where you need to do this, you should access the PowerSync `AbstractPowerSyncDatabase` instance directly - like exporting it as singleton after configuring Vue with it in `main.js`.
186
+
The `usePowersync`, `useQuery`, and `useStatus` composables are meant to be invoked in the top-level setup block. Vue expects certain Composition API functions, like `inject` which this package depends on, to be resolved in the setup context and not inside nested or asynchronous functions. For use cases where you need to do this, you should access the PowerSync `AbstractPowerSyncDatabase` instance directly - like exporting it as singleton after configuring Vue with it in `main.js`.
154
187
155
188
Incorrect Usage Example:
156
189
Using PowerSync composables in a nested function of a component.
0 commit comments