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

Try on playground

<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

Try on playground

<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
}