Transaction specification

Transaction Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Assumptions and Limitations
5. Test scenarios
6. References

Revision History

Version	User	Date	Notes
0.1	Milko Venkov	Aug 30, 2018	Initial Draft
0.2	Milko Venkov	Sep 04, 2018	Transaction state
0.3	Milko Venkov	Sep 04, 2018	Update API and functionality
0.4	Milko Venkov	Oct 18, 2018	Test scenarios and API update
0.5	Viktor Slavov	Oct 18, 2018	Update getAggregatedState description
0.6	Milko Venkov	Feb 11, 2020	Update API
0.7	Viktor Aladzhov	Jul, 23, 2020	HierarchicalTransactionService commit method

1. Overview

Objectives

igxTransactionService should be able to plug between given component and its data source. While plugged in igxTransactionService should collect all the transactions performed in the component without send them to the data source. igxTransactionService should be able to update the data source and commit all the transactions when needed.

2. User Stories

As an end user, I want

• there is no end users stories as igxTransactionService should be an Angular Service.

Developer Stories

As a developer, I want to

• be able to enable transaction on a given component
• be able to retrieve all the transactions - transaction log
• be able to get updated state of the data including all transactions in the transaction log
• be able to update data source with all the transactions currently in the transaction log
• be able to undo the last change
• be able to redo the change that was undone
• be able to reset all the transactions in the transaction log
• be able to start adding of pending transactions
• be able to finish adding of pending transactions and commit or discard all pending transactions

3. Functionality

3.1. End User Experience

3.2. Developer Experience

Developers are able to inject the igxTransactionService. Then developers should be able to add transaction to the transaction log. After some transactions are added developers should be able to retrieve updated data source state, including all transactions in the transaction log; update the data source when needed; reset all the transactions in the transaction log; perform undo and redo actions. Developers should be able to add pending transactions. This will allow adding of some transactions without include them in transaction log. At some point developer should be able to commit aggregated state of all pending transaction as a single transaction or dismiss all pending transactions.

Here is what will happen with transaction state when new transactions is added:

• Add transaction type - when adding such a transaction one should not provide initialValue. After successfully adding of such transaction it will be reflected in aggregated state like Add transaction type. If such a transaction is then added with Delete transaction type it will be removed from aggregated state. Adding of Add transaction type with id which already exists in aggregated state will throw an exception;
• Update transaction type - when adding such a transaction one should provide initialValue. After successfully adding of such transaction it will be reflected in aggregated state like Update transaction type. If an aggregated transactions change results in the same as the initialValue then it will not be reflected in the state. One can also update Add transaction type - this will be reflected in aggregated state like Add transaction type. One can also update Update transaction type - this will remain like Update transaction type in aggregated state. If one tries to update Delete transaction type an exception will be thrown.
• Delete transaction type - when adding such a transaction one should provide initialValue. After successfully adding of such transaction it will be reflected in aggregated state like Deleted transaction type. One can also delete Add transaction type, this will remove the record from the aggregated state. One can also delete Update transaction type, this will change the aggregated type to Delete. If one tries to delete Delete transaction type an exception will be thrown.

Here is visual representation of all possible transactions paths:

3.3. API

Properties

TransactionService

Name	Description
enabled	Returns whether transaction is enabled for this service
canUndo	Returns if there are any transactions in the Undo stack
canRedo	Returns if there are any transactions in the Redo stack

Methods

TransactionService

Name	Description	Parameters
add	Adds provided transaction with recordRef if any	transaction, recordRef?
getTransactionLog	Returns an array of all transactions. If id is provided returns last transaction for provided id	id?
undo	Remove the last transaction if any	-
redo	Applies the last undone transaction if any	-
getAggregatedChanges	Returns aggregated changes from all transactions	mergeChanges
getState	Returns the state of the record with provided id	id, pending?
getAggregatedValue	Returns value of the required id including all uncommitted changes	id, mergeChanges
commit	Applies all transactions over the provided data	data, id? or data, primaryKey, childDataKey, id?
clear	Clears all transactions	id?
startPending	Starts pending transactions. All transactions passed after call to startPending will not be added to transaction	-
endPending	Clears all pending transactions and aggregated pending state. If commit is set to true commits pending states as single transaction	commit

HierarchicalTransactionService

The HierarchicalTransactionService inherits all the methods of the TransactionService and adds and overload for the commit method.

Name	Description	Parameters
commit	Applies all transactions over the provided data	data, primaryKey, childDataKey, id?

Events

TransactionService

Name	Description
onStateUpdate	Event fired when transaction state has changed - add transaction, commit all transactions, undo and redo

4. Assumptions and Limitations

There are no any assumptions or limitations.

5. Test Scenarios

• Should initialize transactions log properly.
• Should add transactions to the transactions log.
• Should throw an error when trying to add duplicate transaction.
• Should throw an error when trying to update transaction with no recordRef.
• Should throw an error when trying to delete an already deleted item.
• Should throw an error when trying to update an already deleted item.
• Should get a transaction by transaction id.
• Should add ADD type transaction - all feasible paths
• Should add DELETE type transaction - all feasible paths.
• Should add UPDATE type transaction - all feasible paths.
• Should update data when data is list of objects.
• Should update data when data is list of primitives.
• Should add pending transaction and push it to transaction log.
• Should not add pending transaction and push it to transaction log.

6. References