Vue3-axios-idb-vuex-sync NPM

About The Project

This vuex store module aims to provide basic CRUD functionality for large datasets.

Features:

Stores data in idb at client side and synchronizes the idb on startup with the backend. Only changed entites will be loaded.
Indexes entites by ID
Provides Get, Delete, Save, Create functionality
We lowered initial page loading from 9 seconds to 200 ms

Getting Started

Installation

npm install vue3-axios-idb-vuex-sync -save

Installation Axios

Axios is needed for this project and needs to be correctly configured. Here is the recommended configuration:

install package

npm install axios -save

in main.js

axios.defaults.baseURL = import.meta.env.VITE_BACKEND_URL;

in .env.development (+ .env.production)

VITE_BACKEND_URL=http://localhost:8080/

Usage

endpointName: in these examples can be replaced to anything moduleName: for consistency normaly the same as endpoint name. This is the name of the Vuex store module

in store.js

import { createBackendIdbVuexDataSync } from 'vue3-axios-idb-vuex-sync';
...
export default createStore({
 modules: {
   'moduleName': createBackendIdbVuexDataSync(
       { endpoint: 'endpointName' },
     )
   },
});

in any component

   import { onMounted, computed } from 'vue';
   import { useStore } from 'vuex';
   ...
   const allEntites = computed(() => store.getters['moduleName/all']);
   ...
   onMounted(() => {
    store.dispatch('moduleName/initialize');
   });
   ...
   function deleteItem(id) {
     store.dispatch('moduleName/delete', { id })
   }

backend API needed

This plugin expects the following endpoints under your backend URL:

POST /endpointName/ Creating an new entity Expects entity as JSON in body Returns saved entity as JSON
GET /endpointName/ Get a list of ALL entities - as JSON list
GET /endpointName/?lastCacheUpdate={timestampInMs} Get a list of all entities that have been changed since {timestampInMs} - as JSON list
PUT /endpointName/{itemId} Saves an existing entity Expects entity as JSON in body Returns saved entity as JSON
DELETE /endpointName/{itemId} Deletes an entity Expects no body and returns nothing

These are currently not configurable for consistency reasons. If you have a legacy API and need other endpoints feel free to make a pull request :)

frontend API

Options for backendDataSync

Attribute	Description	Default	Optional
endpoint	used to identify the backend URLs	-	false
dbVersion	Version of the IDB - this should be increased on breaking entity changes	1	true
initDataItemCallback	This callback will be called after initialization for every NEW entity.This callback is used to transform entites and to do expensive precalculations.For example: Date formating and status calculationsThere is no need to make a deep copy of the entity. Just add / change new properties and return the entity.Parameters:1. ONE new entity the backend sends	-	true
dataChangedCallback	this callback will be called whenever an item was savedParameters:1. store2. saved entity the backend sends	-	true
successCallback	will be called whenever an action (loading, delete, create, update) was successfull. This is normaly used to show success messages.Parameters:1. task name (one of: loading, delete, create, update)2. store	-	true
startLoadingCallback	This callback is used to show a loading overlay. It should return a method to hide the overlay.	-	true
namespaced	If the module should be namespaced or not	false	true
indexes	list of indexes that should be build up. Array of objects with attributes 'column' and 'unique'.There is always an unique index with the idColumn build up. No need to add it here.	[]	true
idColumn	name of the column to identify entities	'id'	true
autoRefresh	turns the auto refresh on or off	false	true
autoRefreshInverallMs	interval in ms whenever new entities should be automatically fetched	10000	true

Getters

Name	Parameters	Description
all	-	returns all entities
byId	itemId	returns an entity based on the value of the idColumn
byIndex	{index, values}index: index namevalues: array of values to look up in the indexes	returns entities based on values in indexes. See Option 'indexes'
lastCacheUpdate	-	timestamp on the last time the cache was updated

Actions

moduleName/loadData

Needs to be called to initialize the module on application startup. All parameters are optional Parameters: showSuccess: default true. Determinates if the successCallback should be called. initData: Array of Entities that (can be) loaded from another source. This should normaly not be used. Used in case we bundle initialization requests to the backend into one init call. initCacheData: Same use case as above but contains data from idb

moduleName/update

Updates one entity by its id. Also removes it from IDB Parameters: Object with id property. Will be send like this to backend.

moduleName/add

Creates one entity. Also removes it from IDB Parameters: Object that will be send like this to backend.

moduleName/delete

Deletes one entity by its id. Also removes it from IDB Parameters: Object with id property

Roadmap

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!