feat: createMany, updateMany, deleteMany

Author: Akryum

docs/guide/data/cache.md

@@ -89,7 +89,7 @@ You can also use the `store.<collectionName>.clearItem` method:
 store.User.clearItem('abc')
 ```
 
-## Layers
+## Layers <Badge text="New in v0.7" />
 
 A cache layer is a way to create a temporary state modification that can be easily reverted. This is how [optimistic updates](./mutation.md#optimistic-updates) are implemented.
 

docs/guide/data/form.md

@@ -1,6 +1,6 @@
 # Form Objects
 
-## Create Form
+## Create
 
 Instead of creating a new item directly, you can create a *form object* that is very useful to handle the data of a form with the `createForm` method.
 

docs/guide/data/live.md

@@ -2,20 +2,20 @@
 
 rstore provides a set of methods to help build realtime applications. Plugins can use [the relevant hooks](../plugin/hooks.md#subscriptions) to connect to WebSockets, Server-Sent Events, or any other realtime protocol.
 
-## Subscribe
+## Subscribe <Badge text="Changed in v0.7" type="warning" />
 
 Subscriptions are a way to listen for changes in the data store. You can subscribe to a specific collection and plugins will update the store in realtime. You can pass the same parameters than in the [queries](./query.md).
 
 ```ts
 const store = useStore()
 
-store.ChatMessage.subscribe({
+store.ChatMessage.subscribe(q => q({
   params: {
     filter: {
       roomId: 'room1',
     },
   },
-})
+}))
 ```
 
 ## Unsubscribe
@@ -39,21 +39,21 @@ const { meta } = store.ChatMessage.subscribe()
 console.log(meta.value)
 ```
 
-## Live Query
+## Live Query <Badge text="Changed in v0.7" type="warning" />
 
 You can use the `liveQueryFirst` and `liveQueryMany` methods to do both a query and a subscription at the same time.
 
 ```ts
-const { data: user } = store.User.liveQueryFirst('some-id')
+const { data: user } = store.User.liveQuery(q => q.first('some-id'))
 ```
 
 ```ts
-const { data: messages } = store.ChatMessage.liveQueryMany({
+const { data: messages } = store.ChatMessage.liveQuery(q => q.many({
   filter: item => item.roomId === 'room1',
   params: {
     filter: {
       roomId: 'room1',
     },
   },
-})
+}))
 ```

docs/guide/data/module.md

@@ -1,4 +1,4 @@
-# Module
+# Module <Badge text="Changed in v0.7" type="warning" />
 
 In most application, there are cases where some specific logic or state is needed. For example, you may want to handle the current user with a specific key and also have special mutations for login or logout.
 
@@ -180,7 +180,7 @@ const { data: currentUser } = auth.currentUser
 Awaiting a module is always optional. You can use the module without awaiting it, but all necessary code might not have run yet. This is a valid use case if you don't use async component setup for example.
 :::
 
-## Mutations
+## Mutations <Badge text="Changed in v0.7" type="warning" />
 
 You can define mutations using the `defineMutation` function from the module setup function. This is useful for defining actions that modify the state of the module or the store in general.
 

docs/guide/data/mutation.md

@@ -11,6 +11,23 @@ const newTodo = await store.todos.create({
 })
 ```
 
+::: tip
+You can also use the `createForm` method to create a new record. This method returns a form object that you can use to manage the state of the form and submit it when you're ready. See [Forms](./form.md#create-form) for more details.
+:::
+
+## Create Many <Badge text="New in v0.7.3" />
+
+You can create many items at once by using the `createMany` method on the store. This method takes an array of objects with the properties of the records you want to create.
+
+```ts
+const newTodos = await store.todos.createMany([
+  { title: 'New Todo 1', completed: false },
+  { title: 'New Todo 2', completed: false },
+])
+```
+
+It can be useful to batch the create operations into a single fetch request to your backend. See `createMany` in the [plugin hooks](../plugin/hooks.md#createmany).
+
 ## Update
 
 To update an existing record, you can use the `update` method on the store. This method takes an object with the properties you want to update and the key of the record you want to update.
@@ -58,6 +75,23 @@ async function toggle() {
 }
 ```
 
+::: tip
+You can also use the `updateForm` method to update an existing record. This method returns a form object that you can use to manage the state of the form and submit it when you're ready. See [Forms](./form.md#update-form) for more details.
+:::
+
+## Update Many <Badge text="New in v0.7.3" />
+
+You can update many items at once by using the `updateMany` method on the store. This method takes an array of objects with the properties you want to update. Each object must contain the key (or the properties used to [compute the key](../schema/collection.md#item-key)) of the record you want to update.
+
+```ts
+const updatedTodos = await store.todos.updateMany([
+  { id: 'id-1', completed: true },
+  { id: 'id-2', completed: true },
+])
+```
+
+It can be useful to batch the update operations into a single fetch request to your backend. See `updateMany` in the [plugin hooks](../plugin/hooks.md#updatemany).
+
 ## Delete
 
 To delete a record, you can use the `delete` method on the store. This method takes the key of the record you want to delete.
@@ -94,7 +128,17 @@ if (todo) {
 }
 ```
 
-## Optimistic Updates
+## Delete Many <Badge text="New in v0.7.3" />
+
+You can delete many items at once by using the `deleteMany` method on the store. This method takes an array of keys or objects that contain the keys of the records you want to delete.
+
+```ts
+await store.todos.deleteMany(['id-1', 'id-2'])
+```
+
+It can be useful to batch the delete operations into a single fetch request to your backend. See `deleteMany` in the [plugin hooks](../plugin/hooks.md#deletemany).
+
+## Optimistic Updates <Badge text="New in v0.7" />
 
 By default, rstore will try to perform optimistic updates when you create, update or delete a record. This means that the record will be updated in the store immediately, without waiting for the server to confirm the change. If an error is thrown during the mutation, the change will be automatically reverted.
 

docs/guide/data/query.md

@@ -16,7 +16,7 @@ const { data: todos } = store.Todo.query(q => q.many())
 const { data: users } = store.users.query(q => q.many())
 ```
 
-## Query composables
+## Query composables <Badge text="Changed in v0.7" type="warning" />
 
 The query composables are the recommended way to fetch data from the server. They are designed to be used in a Vue component and return a reactive result to be used in the components.
 
@@ -379,7 +379,7 @@ The cache will automatically resolve the relations as soon as the data is availa
 
 Plugins hooked on the `fetchRelations` hook will also be called to potentially fetch the data of the relations. See [Plugin hooks](../plugin/hooks.md#fetching-relations) for more details.
 
-## Customizing Find Options Types
+## Customizing Find Options Types <Badge text="Changed in v0.7" type="warning" />
 
 You can customize the `FindOptions` type used in the `first` and `many` query builder methods and in the `peek*`/`find*` methods by declaring a module augmentation for `@rstore/vue` and extending the `FindOptions` interface.
 

docs/guide/plugin/hooks.md

@@ -210,6 +210,27 @@ hook('createItem', async (payload) => {
 
 :::
 
+### createMany <Badge text="New in v0.7.3" />
+
+This hook is called when rstore needs to create many new items at once when [`createMany()`](../data/mutation.md#create-many) is used.
+
+::: tip
+If no `createMany` hook is defined, rstore will fallback to calling the [`createItem`](#createitem) hook for each item in the array. If hooks for `createMany` are defined but none of them [aborts](#aborting), rstore will also fallback to calling the `createItem` hook for each item. Calling `abort()` or `setResult(value)` with a non-empty array in the `createMany` hook will prevent this behavior.
+:::
+
+```ts
+hook('createMany', async (payload) => {
+  const result = await fetch(`/api/${payload.collection.name}/batch`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(payload.items),
+  }).then(r => r.json())
+  payload.setResult(result)
+})
+```
+
 ### updateItem
 
 This hook is called when rstore needs to update an existing item.
@@ -266,6 +287,40 @@ hook('updateItem', async (payload) => {
 ```
 :::
 
+### updateMany <Badge text="New in v0.7.3" />
+
+This hook is called when rstore needs to update many existing items at once when [`updateMany()`](../data/mutation.md#update-many) is used.
+
+::: tip
+If no `updateMany` hook is defined, rstore will fallback to calling the [`updateItem`](#updateitem) hook for each item in the array. If hooks for `updateMany` are defined but none of them [aborts](#aborting), rstore will also fallback to calling the `updateItem` hook for each item. Calling `abort()` or `setResult(value)` with a non-empty array in the `updateMany` hook will prevent this behavior.
+:::
+
+::: danger
+
+Contrary to `createMany` hook, the `updateMany` hook receives an array of items that already contain their keys:
+
+```ts
+interface Payload {
+  items: Array<{ key: string | number, item: any }>
+  /// ...
+}
+```
+
+:::
+
+```ts
+hook('updateMany', async (payload) => {
+  const result = await fetch(`/api/${payload.collection.name}/batch`, {
+    method: 'PATCH',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(payload.items.map(i => i.item)),
+  }).then(r => r.json())
+  payload.setResult(result)
+})
+```
+
 ### deleteItem
 
 This hook is called when rstore needs to delete an existing item.
@@ -302,7 +357,25 @@ hook('deleteItem', async (payload) => {
 ```
 :::
 
-### Aborting
+### deleteMany <Badge text="New in v0.7.3" />
+
+This hook is called when rstore needs to delete many existing items at once when [`deleteMany()`](../data/mutation.md#delete-many) is used.
+
+It receives an array of keys to delete:
+
+```ts
+hook('deleteMany', async (payload) => {
+  await fetch(`/api/${payload.collection.name}/batch`, {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(payload.keys),
+  })
+})
+```
+
+### Aborting <Badge text="New in v0.7" />
 
 If you have multiple plugins that can handle the same collections, you can abort the remaining callbacks for a *Data handling* hook by calling `abort()` on the payload.
 
@@ -318,7 +391,25 @@ hook('deleteItem', (payload) => {
 ```
 
 ::: info
-For `fetchFirst`, `fetchMany`, `createItem` and `updateItem`, the remaining callbacks are automatically aborted when a non-null result is set with `setResult`. You can override this behavior by passing `{ abort: false }` as the second argument to `setResult`.
+For `fetchFirst`, `fetchMany`, `createItem` and `updateItem`, the remaining callbacks are automatically aborted when a non-null result is set with `setResult`.
+
+```ts
+pluginApi.hook('fetchFirst', async (payload) => {
+  // If the item is non-null,
+  // remaining `fetchFirst` hooks will not be called
+  payload.setResult(cache.get(payload.key))
+  // If `cache.get(payload.key)` is null,
+  // remaining `fetchFirst` hooks will be called
+})
+```
+
+Note that in the above example, adding a condition to call `setResult` is not necessary because it checks if the value is null or empty (for arrays) before aborting the remaining callbacks.
+
+You can prevent this behavior by setting `abort: false` to the second argument of `setResult()`.
+
+```ts
+payload.setResult(cache.get(payload.key), { abort: false })
+```
 :::
 
 ## Fetching relations

docs/guide/plugin/setup.md

@@ -63,7 +63,7 @@ app/
 You can also add an `app/rstore` folder in Nuxt layers! rstore will automatically add those files too.
 :::
 
-## Category
+## Category <Badge text="New in v0.7" />
 
 Plugins can be categorized to define their role in the data flow. The available categories are:
 
@@ -129,6 +129,40 @@ export default definePlugin({
 
 Explore the [Plugin hooks](./hooks.md) for a complete list of available hooks.
 
+### Aborting hook <Badge text="New in v0.7" />
+
+You can abort most the hooks by calling either `setResult()` with a non-null/non-empty value, or `abort()`. This will prevent the remaining plugins from running the same hook. This is useful when you want to short-circuit the data flow, for example when you have a cache plugin that can return the data without needing to call a remote API.
+
+```ts
+pluginApi.hook('fetchFirst', async (payload) => {
+  // If the item is non-null,
+  // remaining `fetchFirst` hooks will not be called
+  payload.setResult(cachedmyCache.get(payload.key))
+})
+```
+
+::: tip
+You can prevent this behavior by setting `abort: false` to the second argument of `setResult()`.
+
+```ts
+payload.setResult(cachedmyCache.get(payload.key), { abort: false })
+```
+
+:::
+
+```ts
+pluginApi.hook('fetchFirst', async (payload) => {
+  if (payload.collection.name === 'SomeSpecialCollection') {
+    // Do something special here
+    await doSomethingSpecial()
+    // Remaining `fetchFirst` hooks will not be called
+    payload.abort()
+  }
+})
+```
+
+See also [Category](#category) and [Sorting plugins](#sorting-plugins). Learn more in [Hooks](./hooks.md#aborting).
+
 ## Scope ID
 
 The scope ID allows filtering which plugins will handle the collection. For example, if a collection has a scope A, only plugins with the scope A will be able to handle it by default. This is very useful to handle multiple data sources.
@@ -190,7 +224,7 @@ export default definePlugin({
 })
 ```
 
-## Sorting plugins
+## Sorting plugins <Badge text="New in v0.7" />
 
 Plugins are sorted based on their dependencies and category. You can specify that a plugin should be loaded before or after another plugin or category using the `before` and `after` options:
 

docs/guide/schema/collection.md

@@ -40,7 +40,7 @@ const store = await createStore({
 
 :::
 
-## Defining a Collection
+## Defining a Collection <Badge text="Changed in v0.7" type="warning" />
 
 For JavaScript, you can use the `defineCollection` utility function to define a collection with auto-completion in your IDE:
 
@@ -88,7 +88,7 @@ const store = await createStore({
 The [currying](https://en.wikipedia.org/wiki/Currying) is necessary to specify the type of the item while still letting TypeScript infer the type of the collection. This is a limitation of TypeScript, and [it might improve in the future](https://github.com/microsoft/TypeScript/issues/26242).
 :::
 
-## Collection hooks
+## Collection hooks <Badge text="New in v0.7" />
 
 You can define hooks on the collection that will be called at different stages of the item lifecycle in the `hooks` option. The available hooks are: