tracked-instance
v1.0.21
Published
Build large forms and track all changes
Downloads
460
Maintainers
Readme
Tracked instance
🚀 Features
- 🕶 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
Description
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.
Install
npm i tracked-instance
Support
Supports Vue 3.x only
Usage
Tracked instance
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) // undefined
Rollback initial value:
data.value.name = 'John'
reset()
console.log(data.value) // { name: 'Jack', isActive: false }
console.log(isDirty.value) // false
console.log(changedData.value) // undefined
All 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])
Real-world example
<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>
Collection
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 remove
Reset 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
Real-world example
<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>
Documentation
TrackedInstance
- 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
Collection
- 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
}