jsTPS - A JavaScript Transaction Processing System

The jsTPS framework provides an easy to use transaction processing system to assist in the creation of undo/redo systems for JavaScript. Note, the framework uses an ES Modules format.

Front-End Usage

Your application would generally only need one TPS. To start you'll need to create your jsTPS object, so depending on where you put it you'll need to first import it. For example, if for a Web page root you have a js directory you might write:

import { jsTPS } = './js/jstps/index.js'
let tps = new jsTPS();

You would then adjust that path relative to the file making use of it and where you choose to place it in your own directory structure.

Node Installation

Note that this library can be used in any JavaScript context. To make use of the jsTPS framework in your Node application you should install it using:

npm install jstps

Custom Transactions

Note that you will need to define your own transactions for whatever it is that your application aims to do and undo. To do so, define a class that extends jsTPS_Transaction and override the executeDo and executeUndo functions. Also note that this library does not currently do anything to help coordinate anything asynchronous. So, if your transactions will be executing asynchronous do or undo functionality you'll need to manage that yourself. As an example, if we assume that you have defined a class that represents a transaction called MyTransaction, which will be updating the state of some object (we'll just call it itemToUpdate), we might say that we have an event handler that listens for user interactions and when they occur gathers the data associated with the event in changeData and send it to our transaction, which of course it will use to update itemToUpdate when the executeDo is performed and undone when executeUndo is performed. So use of these methods is as easy as:

// IN AN EVENT HANDLER 
let transaction = new MyTransaction(itemToUpdate, changeData);
tps.processTransaction(transaction);

When the user presses an undo button, we might respond with:

tps.undoTransaction();

When the user presses an redo button, we might respond with:

tps.redoTransaction();

Also note that the principle of Foolproof Design says one should not tempt the user with choices that are not selectable, so one should disable undo and redo buttons when those functions are not usable as there are no transactions to do or undo. For this, we might do something like:

document.getElementById("undo-button").disabled = !tps.hasTransactionToUndo();
document.getElementById("redo-button").disabled = !tps.hasTransactionToRedo();

Package Contents

Note that as a public repository, you are free to download and examine the jsTPS package, which really has three components:

Running the Demo

Note that the jsTPS package contains a demo script that shows you how you might define your own transactions for the purpose of undo/redo in a JavaScript application. If you have installed the package for use in your program, you can run the demo using:

node .\node_modules\jstps\bin\demo.js

Or if you have forked the repository you can simply use the following from the root directory:

node .\\bin\demo.js

This will open a menu of choices where you can update an object which will be done using transactions. You can then undo and redo those transactions and the menu employs foolproof design such that undo and redo are only provided as options if they can be used.

Running Tests

Should you fork (or download) the jsTPS project you can also run tests that ensure the API does everything it indends. To run these tests, make sure Vitest is installed and then run the tests using:

npm test

License

This project is licensed under the GNU General Public License v3.0.

You may copy, modify, and distribute this software under the terms of the GPL-3.0. Any derivative works must also be licensed under the GPL-3.0 and include source code when distributed.

See the full license text at GNU GPL v3.0.