Skip to content

Commit 0a30ea2

Browse files
ElisePatrikainenElisePatrikainen
committed
initial commit
0 parents  commit 0a30ea2

27 files changed

+14703
-0
lines changed

‎.editorconfig

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
root = true
2+
3+
[*]
4+
indent_size = 2
5+
indent_style = space
6+
end_of_line = lf
7+
charset = utf-8
8+
trim_trailing_whitespace = true
9+
insert_final_newline = true
10+
11+
[*.md]
12+
trim_trailing_whitespace = false

‎.eslintignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
dist
2+
node_modules

‎.eslintrc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"root": true,
3+
"extends": ["@nuxt/eslint-config"]
4+
}

‎.gitignore

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Dependencies
2+
node_modules
3+
4+
# Logs
5+
*.log*
6+
7+
# Temp directories
8+
.temp
9+
.tmp
10+
.cache
11+
12+
# Yarn
13+
**/.yarn/cache
14+
**/.yarn/*state*
15+
16+
# Generated dirs
17+
dist
18+
19+
# Nuxt
20+
.nuxt
21+
.output
22+
.data
23+
.vercel_build_output
24+
.build-*
25+
.netlify
26+
27+
# Env
28+
.env
29+
30+
# Testing
31+
reports
32+
coverage
33+
*.lcov
34+
.nyc_output
35+
36+
# VSCode
37+
.vscode/*
38+
!.vscode/settings.json
39+
!.vscode/tasks.json
40+
!.vscode/launch.json
41+
!.vscode/extensions.json
42+
!.vscode/*.code-snippets
43+
44+
# Intellij idea
45+
*.iml
46+
.idea
47+
48+
# OSX
49+
.DS_Store
50+
.AppleDouble
51+
.LSOverride
52+
.AppleDB
53+
.AppleDesktop
54+
Network Trash Folder
55+
Temporary Items
56+
.apdisk

‎.npmrc

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
shamefully-hoist=true
2+
strict-peer-dependencies=false

‎README.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
<!--
2+
Get your module up and running quickly.
3+
4+
Find and replace all on all files (CMD+SHIFT+F):
5+
- Name: UseFetchQuery
6+
- Package name: nuxt-usefetchquery
7+
- Description: A Nuxt module to help caching, synchronizing and updating server state.
8+
-->
9+
10+
# UseFetchQuery
11+
12+
[![npm version][npm-version-src]][npm-version-href]
13+
[![npm downloads][npm-downloads-src]][npm-downloads-href]
14+
[![License][license-src]][license-href]
15+
[![Nuxt][nuxt-src]][nuxt-href]
16+
17+
UseFetchQuery is a Nuxt module providing composables to help caching, synchronizing and updating server state in our applications. It is largely inspired by [TanstackQuery](https://tanstack.com/query/latest) and [SWR](https://swr.vercel.app/), and aims to build the essential functionalities of these libraries on the top of `useFetch` and `useAsyncData`.
18+
19+
<!-- - [✨ &nbsp;Release Notes](/CHANGELOG.md) -->
20+
<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/nuxt-usefetchquery?file=playground%2Fapp.vue) -->
21+
<!-- - [📖 &nbsp;Documentation](https://example.com) -->
22+
23+
## Features
24+
25+
The goal of UseFetchQuery is to provide essential server state management functionalities, such as :
26+
- caching out of the box the data fetch from the server
27+
- setting a life time to our cache (and refreshing the data when the cache is expired)
28+
- refreshing data on window events (focus, reconnection)
29+
- exposing a `fetching` and `refreshing` state to know if the data is being fetch/refreshed
30+
- [TODO] handling pagination cache
31+
32+
## Caching and refreshing
33+
34+
By default, the only cache parameter set is deduping the requests. Nevertheless, you can easily set a cache lifetime to your requests by passing a number (ms) to the `refreshTime` option, which will cache the data and refresh them once they are stale:
35+
36+
```js
37+
const { data, error } = await useFetchQuery(`/api/products`, { refreshTime: 15000 })
38+
// The data will be cached for 15 seconds, and refreshed afterwards
39+
```
40+
41+
Nb: UseFetchQuery does currently not poll data (TODO ?), but re-fetches them in the background once they are stale on the following events :
42+
- new instances of the composable mount
43+
- window events : refocus, reconnection
44+
45+
You can also choose to never revalidate cache, by setting the `refreshTime` option to `infinite` :
46+
47+
```js
48+
const { data, error } = await useFetchQuery(`/api/products`, { refreshTime: 'infinite' })
49+
```
50+
51+
## Refreshing state
52+
53+
By default, refreshing is done on the background. This means that :
54+
- useFetchQuery will first display the stale data, and update them once they are revalidated
55+
- if you use `Suspense`, it will be effective only on the first call, when no data has been fetched yet, and will be disabled on refresh
56+
57+
If you need to display the fetching (on the initial call) or refreshing state, `useFetchQuery` exposes:
58+
- [TODO] a `fetching` ref, which will be set to `true` when the data is being initially fetched
59+
- a `refreshing` ref, which will be set to `true` when the data is being revalidated
60+
61+
```js
62+
const { data, fetching, refreshing } = await useFetchQuery(`/api/products`, { refreshTime: 15000 })
63+
// `fetching` can be used to display a full page loader (skeleton, etc) when there is no data
64+
// `refreshing` can be used to display a smaller loader on revalidation, which would not prevent displaying the stale data meanwhile
65+
```
66+
In case you still want `suspense` to be effective while refreshing, you can set the `suspense` option to `true` :
67+
68+
```js
69+
const { data, error } = await useFetchQuery(`/api/products`, { suspenseOnRefresh: true })
70+
```
71+
72+
Nb: `useFetchQuery` still exposes the `pending` and `status` refs returned by `useFetch`, without altering their behaviour. Therefore, when the data is being fetched or revalidated :
73+
- `pending` which will be set to `true`
74+
- `status` which will be set to `pending`
75+
76+
## Refresh on window events
77+
78+
By default, the data will be revalidated (in the background) on the following events :
79+
- window refocus
80+
- network reconnection
81+
82+
You can disable this behaviour by setting the `refreshOnFocus` and `refreshOnReconnection` options to `false` :
83+
84+
```js
85+
const { data, error } = await useFetchQuery(`/api/products`, { refreshOnFocus: false, refreshOnReconnection: false})
86+
```
87+
88+
## Pagination
89+
90+
TODO 🙃
91+
92+
## Global parameters
93+
94+
TODO 🙃
95+
96+
## Quick Setup
97+
98+
1. Add `nuxt-usefetchquery` dependency to your project
99+
100+
```bash
101+
# Using pnpm
102+
pnpm add -D nuxt-usefetchquery
103+
104+
# Using yarn
105+
yarn add --dev nuxt-usefetchquery
106+
107+
# Using npm
108+
npm install --save-dev nuxt-usefetchquery
109+
```
110+
111+
2. Add `nuxt-usefetchquery` to the `modules` section of `nuxt.config.ts`
112+
113+
```js
114+
export default defineNuxtConfig({
115+
modules: [
116+
'nuxt-usefetchquery'
117+
]
118+
})
119+
```
120+
121+
That's it! You can now use UseFetchQuery in your Nuxt app ✨
122+
123+
## Development
124+
125+
```bash
126+
# Install dependencies
127+
npm install
128+
129+
# Generate type stubs
130+
npm run dev:prepare
131+
132+
# Develop with the playground
133+
npm run dev
134+
135+
# Build the playground
136+
npm run dev:build
137+
138+
# Run ESLint
139+
npm run lint
140+
141+
# Run Vitest
142+
npm run test
143+
npm run test:watch
144+
145+
# Release new version
146+
npm run release
147+
```
148+
149+
<!-- Badges -->
150+
[npm-version-src]: https://img.shields.io/npm/v/nuxt-usefetchquery/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
151+
[npm-version-href]: https://npmjs.com/package/nuxt-usefetchquery
152+
153+
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-usefetchquery.svg?style=flat&colorA=18181B&colorB=28CF8D
154+
[npm-downloads-href]: https://npmjs.com/package/nuxt-usefetchquery
155+
156+
[license-src]: https://img.shields.io/npm/l/nuxt-usefetchquery.svg?style=flat&colorA=18181B&colorB=28CF8D
157+
[license-href]: https://npmjs.com/package/nuxt-usefetchquery
158+
159+
[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
160+
[nuxt-href]: https://nuxt.com

0 commit comments

Comments
 (0)