docs: more!

Author: Akryum

docs/guide/data/query.md

@@ -14,6 +14,16 @@ The `queryFirst` and `queryMany` composables return an object with the following
 
 - `refresh`: a function that can be called to refresh the data.
 
+The composables also return a promise so they can be used with async setup.
+
+```vue
+<script setup>
+const store = useStore()
+// Plays nice with Nuxt SSR!
+const { data: todos } = await store.Todo.queryMany()
+</script>
+```
+
 ### Query first
 
 Composable function that reads the first item that matches the key or the filter in the cache and fetches it if not found.
@@ -166,3 +176,80 @@ const { data: todos } = store.Todo.queryMany({
 * `fetch-only` means that the query will only fetch the data from the adapter plugins. The data will be stored in the cache when the query is resolved.
 * `cache-only` means that the query will only fetch the data from the cache.
 * `no-cache` means that the query will not use the cache and only fetch the data from the adapter plugins. No data will be stored in the cache.
+
+## Items list
+
+Usually we write list item components that are used to display a list of items. It is recommended to only pass the key to the list item component and then use `queryFirst` to fetch the data in the list item component. By default the fetch policy is `cache-first`, so the data will be red from the cache in the item component and no unnecessary requests will be made for each items.
+
+The benefits are that the data is co-located with the component that uses it and there is no need to specify the types of the item prop again (usually a simple `id: string | number` is enough). The item component is also easier to potentially reuse in totally different contexts.
+
+::: code-group
+
+```vue [TodoList.vue]
+<script lang="ts" setup>
+const store = useStore()
+const { data: todos } = await store.Todo.queryMany()
+</script>
+
+<template>
+  <!-- Only pass the id here -->
+  <TodoItem
+    v-for="{ id } in todos"
+    :id
+    :key="id"
+  />
+</template>
+```
+
+```vue [TodoItem.vue]
+<script lang="ts" setup>
+const props = defineProps<{
+  // Easy to type prop
+  id: string
+}>()
+
+const store = useStore()
+// No additional request is made here, the data is read from the cache
+const { data: todo } = await store.Todo.queryFirst(props.id)
+// Enjoy inferred types here too!
+</script>
+```
+
+:::
+
+## Co-locating queries
+
+The best of both worlds! You can co-locate the queries with the components that use them, while still enjoying the benefits of a centralized store thanks to the cache -- letting it deduplicating and synchronizing all components. This is a powerful pattern that improves the independence of components and thus their maintainability.
+
+::: code-group
+
+```vue [AppHeader.vue]
+<script lang="ts" setup>
+const store = useStore()
+// The query is co-located with the component, not in a store somewhere else
+const { data: user } = await store.User.queryFirst('user-id')
+</script>
+
+<template>
+  <div>
+    <h1>{{ user.name }}</h1>
+  </div>
+</template>
+```
+
+```vue [UserProfile.vue]
+<script lang="ts" setup>
+const store = useStore()
+// The centralized cache ensures that the data is up to date here too
+const { data: user } = await store.User.queryFirst('user-id')
+</script>
+
+<template>
+  <div>
+    <h1>{{ user.name }}</h1>
+    <p>{{ user.email }}</p>
+  </div>
+</template>
+```
+
+:::

docs/guide/getting-started.md

@@ -4,13 +4,16 @@ rstore is a data store allowing you to handle all data in your application.
 
 Define a data model and then run queries or execute mutations (create, update and delete) on your data.
 
-Its main features are:
+**FEATURES**
 
 - **Normalized reactive cache** to ensure all components are up-to-date
+- **Co-locate queries** within the components that need them
 - **Fully adaptable** with plugins to fetch from any source (REST, GraphQL...)
 - **Scale down** to small prototypes and **scale up** to big enterprise apps
 - Query API designed for **local-first** and **realtime**
+- **Form API** to handle form state and validation
 - **TypeScript support** with full autocomplete
+- **Nuxt module** with devtools
 
 [Learn more](./learn-more.md)
 

docs/guide/learn-more.md

@@ -46,12 +46,13 @@ The reactive normalized cache in rstore is a key feature that ensures your appli
 
 The cache is also reactive, meaning reading from the cache in a `computed` will always keep the components updated. In fact, each time you use `store.Todo.queryMany()` you get a computed ref that reads from the cache.
 
-::: details
-
 The reactive normalized cache in rstore offers several benefits.
 - Consistency is maintained by normalizing the data, ensuring a single source of truth for each item, which prevents duplication and inconsistencies.
 - Reactivity is another advantage, as the cache automatically updates any part of your application that depends on the data whenever changes occur, keeping your UI in sync with the latest state.
 - Efficiency is achieved through the structured format of normalized data, allowing for quicker and less overhead-intensive queries and updates.
+- Co-locating the data requirements with the components that use them is a powerful pattern. By using the `queryMany` and `queryFirst` composables, you can easily fetch and display data in your components without worrying about deduplicating or synchronizing with other components.
+
+::: details Example of cache
 
 Here is what the cache can look like: