- 🕶 Track what changed in your form
- 🌎 Send on backend only fields which changed
- 📦 Build multiple requests only for items that have been changed/removed/added
- 🦾 Type Strong: Written in TypeScript
Build large forms and send all requests in one take. Combination of useTrackedInstance and useCollection can manage very large form with entities which deeply related each other. You can control what data should be sent to the server so that only what has changed is sent. Tracked instance is not so much about managing forms, but about building and optimizing queries.
npm i tracked-instance
Supports Vue 3.x only
Track everything what was changed
const {data, changedData, isDirty, loadData, reset} = useTrackedInstance({
name: 'Jack',
isActive: false
})Do some changes and see only changed field in changedData. Then set previous value and see what changedData is empty. That guaranty what you always get real changes
data.value.name = 'John'
console.log(isDirty.value) // true
console.log(changedData.value) // {name: 'John'}
data.value.name = 'Jack'
console.log(isDirty.value) // false
console.log(changedData.value) // undefinedRollback initial value:
data.value.name = 'John'
reset()
console.log(data.value) // { name: 'Jack', isActive: false }
console.log(isDirty.value) // false
console.log(changedData.value) // undefinedAll changes should be replaced by new loaded data. The data will be considered not dirty
data.value.name = 'John'
data.value.isActive = true
loadData({
name: 'Joe',
isActive: false
})
console.log(isDirty.value) // false
console.log(data.value) // { name: 'Joe', isActive: false }Can accept primitive values or arrays
useTrackedInstance(false)
useTrackedInstance([1,2,3])<script setup>
import {useTrackedInstance} from 'tracked-instance'
const {data, changedData, isDirty, reset, loadData} = useTrackedInstance({
title: '',
year: null,
isPublished: false,
details: {
// should be updated by loadData
}
})
// update initial data without make form dirty
loadData({
id: 1,
title: 'The Dark Knight',
year: 2008,
isPublished: true,
details: {
director: {
name: 'Christopher Nolan' // form see changes in nested values
}
}
})
const saveChanges = () => {
loadData(data.value)
}
</script>
<template>
<div>isDirty: {{ isDirty }}</div>
<hr />
<button @click="reset">♻️ Reset</button>
<form @submit.prevent="saveChanges">
<input
v-model="data.title"
type="text"
/>
<input
v-model.number="data.year"
type="number"
/>
<input
v-model="data.isPublished"
type="checkbox"
/>
<input
v-model="data.details.director.name"
type="text"
/>
<button
type="submit"
:disabled="!isDirty"
>
💾 Save changes
</button>
</form>
<h2>Changed data:</h2>
<pre>{{ changedData }}</pre>
</template>
const {isDirty, add, items, remove, reset, loadData} = useCollection()
loadData([{name: 'Jack'}, {name: 'John'}, {name: 'Joe'}])Should be dirty on make some changes, remove or add item
items.value[0].instance.data.value.name = 'Stepan'
console.log(isDirty.value) // true Add new item:
const addedItem = add({name: 'Taras'})
console.log(addedItem) // {instance: TrackedInstance<{name: 'Taras'}>, isRemoved: false, isNew: true, meta: {}}}Add new item in specific position:
add({name: 'Taras'}, 0)Item should be softly removed and can be reverted by reset()
remove(0)
remove(0, true) // hard removeReset all changes including changing data on each item
reset()Item meta. Additional custom fields which can watch on item instance. If set then should be applied to each item which was added by add() or loadData()
const {add, items} = useCollection(instance => ({
isValidName: computed(() => instance.data.value.name.length > 0)
}))
add({name: ''})
console.log(items.value[0].meta.isValidName.value) // false<script setup>
import {ref} from 'vue'
import {useCollection} from 'tracked-instance'
const {isDirty, add, items, remove, reset, loadData} = useCollection()
loadData([{name: 'Jack'}, {name: 'John'}, {name: 'Joe'}])
const newUserName = ref('')
const saveChanges = () => {
loadData(
items.value
.filter(item => !item.isRemoved.value)
.map((item) => item.instance.data.value)
)
}
</script>
<template>
<button
:disabled="!isDirty"
@click="saveChanges"
>
💾 Save changes
</button>
<button @click="reset">♻️ Reset</button>
<hr />
<div>isDirty: {{ isDirty }}</div>
<div>
Add new user:
<input
v-model="newUserName"
type="text"
/>
<button @click="add({name: newUserName}); newUserName = ''">➕ Add user</button>
</div>
<ul>
<template v-for="(item, index) in items">
<li v-if="!item.isRemoved.value">
<input
v-model="item.instance.data.value.name"
type="text"
/>
<button @click="remove(index)">🗑 Remove</button>
<button
v-if="!item.isNew.value"
@click="item.instance.reset()"
>
♻️ Reset
</button>
isNew: {{ item.isNew.value }}
</li>
</template>
</ul>
Removed items:
<ul>
<li v-for="item in items.filter((i) => i.isRemoved.value)">
{{ item.instance.data.value.name }}
<button @click="item.isRemoved.value = false">♻️ Rollback</button>
</li>
</ul>
</template>- data - tracked data
- changeData - includes only modified fields from data, considers nested objects and arrays
- isDirty - weather instance has some changes
- loadData - rewrite data and clear dirty state
- reset - rollback changes at the last point when the instance was not isDirty
- items - array of
CollectionItem - isDirty - weather collection includes some changes (add/remove/change)
- add - add new item
- remove - soft remove item by index. Soft removed items should be deleted permanently after load data. Can be reverted by reset. If passed second param isHardRemove can be deleted permanently.
- loadData - accepts array of data for each item. Rewrite each instance data and clear dirty state
- reset - rollback changes at the last point when the instance was not isDirty
interface CollectionItem {
instance: TrackedInstance
isRemoved: Ref<boolean>
isNew: Ref<boolean> //weather is new instance. Field can be changed manually or changed in loadData in second argument
meta: Record<string, any>
remove: (isHardRemove?: boolean) => void
}