https://github.com/kidesia/svelte-tiny-query
Tiny query library for Svelte 5. Declarative, reactive, and type-safe.
https://github.com/kidesia/svelte-tiny-query
cache query svelte
Last synced: about 2 months ago
JSON representation
Tiny query library for Svelte 5. Declarative, reactive, and type-safe.
- Host: GitHub
- URL: https://github.com/kidesia/svelte-tiny-query
- Owner: Kidesia
- Created: 2025-03-24T08:23:19.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-03-24T21:28:28.000Z (2 months ago)
- Last Synced: 2025-03-24T22:19:54.213Z (2 months ago)
- Topics: cache, query, svelte
- Language: TypeScript
- Homepage:
- Size: 54.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Svelte Tiny Query 🦄
**Svelte Tiny Query** simplifies working with external data in Svelte 5. Define declarative queries that handle caching, deduping, and reloading — with reactive access to `data`, `loading`, and `error` states.
Built on Svelte 5's reactivity, it’s *tiny* (~1.1kB gzipped), fast, and fully type-safe.
**Features**
- 🚀 Declarative and reactive queries
- 💾 Caching with stale-time support
- 🏃 Auto and manual reloading
- 💥 Loading and error state tracking
- ‼️ Deduplication of identical loads
- 🚧 Easy query invalidation
- ⌨️ Fully typed with TypeScript
## Usage
In your svelte 5 project, install **Svelte Tiny Query**
npm install svelte-tiny-query --save
And use it in your apps.
~~~html
import { createQuery } from 'svelte-tiny-query';
const memeIdeaQuery = createQuery(
['meme-ideas'],
async ({ id }) => {
try {
const memeIdea = await fetchDataSomehow(id);
return { success: true, data: memeIdea };
} catch (e) {
return { success: false, error: 'Oopsie!' };
}
}
);
const queryParam = $state({ id: 1 });
const { query } = memeIdeaQuery(queryParam);
{#if query.loading}
Loading...
{:else if query.error}
Error: {query.error}
{:else}
{query.data.title}
{/if}
{
queryParam.id += 1
}}>
Next Meme Idea
~~~
## Basics
### The Query
A **query** is an abstraction for loading and caching data. It consists of a **loading function** which produces some data, and a **unique key** which identifies that data. Queries expose their reactive `data`, `error`, and `loading` state, along with a `refetch` function.
Svelte Tiny Query uses Svelte 5's `$state` to **cache *all* states of *all* queries**, indexed by their keys. When you use a query, you are essentially getting reactive access to a small part of the global cache based on the current key.
### Keys and Parameters
Queries can have one or zero parameters, and the parameter can be reactive. If it is reactive and the value changes, the query now points to the new bit of global cache and triggers the loading function if appropriate.
The key of a query has to uniquely identify the data that the query produces, and thus depends also on the parameters of the query. In Svelte Tiny Query, the parameter is automatically included in the final key, but you can also use a function to
## API Reference
Svelte Tiny Query only exports 2 functions (`createQuery` and `invalidateQueries`), 2 tiny helpers (`fail` and `succeed`) and one readonly state (`globalLoading`).
### `createQuery`
Creates a query, which then can be used in components.
~~~typescript
(
key: string[] | (P) => string[],
loadFn: (param: P) => LoadResult,
options?: { initialData?: T, staleTime?: number }
) =>
(param: P) => {
query: {
data: T | undefined,
error: E | undefined,
loading: boolean
},
refetch: () => void
}
~~~
You can see 3 generic types in there. `T` is the type of the data that is returned by the loading functioin, `P` is the type of the parameter which is passed into the query function, and `E` is the error which might be returned by the loading function. Let's break it down.
#### Param 1: Key
~~~typescript
key: string[] | (P) => string[]
~~~
The **key** of a query is crucial for caching and invalidating the query. It uniquely identifies the data, and it must be unique — otherwise, different queries may overwrite each other’s state.
- If the key is a function, it receives the query's parameter and returns an array of strings. This allows for dynamic keys, like `["user", "1", "posts"]`.
- If the key is not a function but the query takes a parameter, the **parameter is serialized and appended to the key**. This guarantees that each key is unique and represents the query’s data correctly. In the example above, the key intially is `["meme-ideas", "id:1"]`.
#### Param 2: Loading Function
~~~typescript
loadFn: (param: P) => Promise>
~~~
The **loading function** is responsible for loading data asynchronously. It accepts a parameter `P`, which is the value passed to the query. This parameter can be reactive, and if its value changes, the query will automatically re-initialize.
The function returns a `LoadResult`, which can either be:
- `{ success: true, data: T }`
- `{ success: false, error: E }`
You can use the helper functions `succeed` and `fail` to easily construct these values.
#### Param 3: Options (optional)
~~~typescript
options?: {
initialData: undefined as T | undefined,
staleTime: 0 as number
}
~~~
- **initialData**: This is used as the initial value of `data` in the query, before it has finished loading (instead of undefined). Can be used to implement persisted queries (maybe in localStorage).
- **staleTime**: Defines how long (in milliseconds) before the query is considered stale. Before this time is reached, the query is not automatically reloaded. Defaults to 0 (query always reloads) and can also be set to infinity, to prevent reloads completely.
#### Returns the actual query function
~~~typescript
(param: P) => {
query: {
data: T | undefined,
error: E | undefined,
loading: boolean
},
refetch: () => void
}
~~~
The `createQuery` function returns a query function that gives you access to the reactive state of the query (`data`, `error`, `loading`), and a `refetch` function.
- The query function checks the cache for existing data. If the data is found and not stale, it’s returned immediately.
- If the data isn’t in the cache or is stale, the loading function is triggered. While it’s loading, the `loading` state is set to `true`.
- Once the loading function completes, the query state updates with the new data or error, and the data is cached for future use.
- The `refetch` function can be used to manually reload the data, which will update the cache and reset the state as needed.
- If the query has reactive parameters, a change will trigger a re-initialization, causing a reload based on the new cache key.
### `invalidateQuery`
~~~typescript
(key: string[]) => void
~~~
Invalidates a query and its children by key. If a query is invalidated, and it is active (on a mounted component), its loading function is triggered. This happens, whether the query is stale or not.
If multiple identical queries are invalidated, the loading function is only run once.
### `globalLoading`
~~~typescript
{ count: number }
~~~
Reactive value that holds the number of currently active loadings.
## What is Omited
Svelte Tiny Query also deliberately omits some features that other query libraries offer. These are some of those:
**Query Provider**:
There is no need to set up a query provider. Queries and their caches operate globally in your app.
**Timed and Window Focus Reloading**:
Use `$effect`, `setInterval` (or `addEventListener`) and `refetch` to achieve this yourself.
**Dependent Queries**:
Use `$derived` to achieve dependent queries. But also consider extracting the part of the component that rely on the dependent query into its own component.
**Persisted Queries**:
Use `initialData` and manually persist the data in the loading function.
**Mutations**:
Use `invalidateQueries` anywhere in your app to invalidate queries. This means mutations can just be normal functions.
## Roadmap
While we want to keep the library *tiny*, there are a few things on our plate. If you feel like contributing to this project with issues or pull requests, you are very welcome.
- Optimistic updates (`upateQuery`)
- Retries on error
- Paginated and/or load-more queries
- Query cancellation
- Unused cache clearing (maybe?)
- Tests (d'uh!)
## Thanks
This library exists, because **Svelte 5 is awesome**! It solves the problem of caching almost by itself and allows this library to be so *tiny* and simple.
It also exists because of the (**TanStack Query**)[https://tanstack.com/query] (for which there exists a (svelte variant)[https://tanstack.com/query/latest/docs/framework/svelte/overview]) sparked the idea of the query abstraction in the first place. So thank you TanStack Query!
And last but not least, if you are still reading this, **thank you**! We hope you give it a try and consider contributing.