Manage simple transactions in pure JavaScript.
$ npm install transactioner
const Transactioner = require("transactioner");
const transaction = new Transactioner();
const data = { i:0 };
const operation = {
up: () => { data.i++ },
down: () => { data.i-- }
};
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 1
console.log(transaction.undoers.length); // >>> 1
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 2
console.log(transaction.undoers.length); // >>> 2
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 3
console.log(transaction.undoers.length); // >>> 3
transaction.commit();
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 3 // Data is preserved
console.log(transaction.undoers.length); // >>> 0 // And undoers are cleaned
const Transactioner = require("transactioner");
const transaction = new Transactioner();
const data = { i:0 };
const operation = {
up: () => { data.i++ },
down: () => { data.i-- }
};
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 1
console.log(transaction.undoers.length); // >>> 1
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 2
console.log(transaction.undoers.length); // >>> 2
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 3
console.log(transaction.undoers.length); // >>> 3
transaction.rollback();
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> 3 // Data is rolled-back
console.log(transaction.undoers.length); // >>> 0 // Because undoers were executed and cleaned in reverse order
const Transactioner = require("transactioner");
const transaction = new Transactioner();
const data = { i:0 };
const operation = {
up: () => { throw {} },
down: () => { data.i-- }
};
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> -1
Example 4: on transactions committed or rolled-back, a new run, commit or rollback call throws an error
const Transactioner = require("transactioner");
const transaction = new Transactioner();
const data = { i:0 };
const operation = {
up: () => { throw {} },
down: () => { data.i-- }
};
transaction.run(operation);
console.log(data.i); // >>>>>>>>>>>>>>>>>>>>>>> -1
transaction.run(operation); // >>>>>>>>>>>>>>>> throws an ERROR: Transactioner.ERROR_TRANSACTION_STATUS_IS_ROLLEDBACK
transaction.reset();
data.i = 0;
const operation2 = {
up: () => { data.i++ },
down: () => { data.i-- }
};
transaction.run(operation2);
transaction.commit();
transaction.run(operation2); // >>>>>>>>>>>>>>> throws an ERROR: Transactioner.ERROR_TRANSACTION_STATUS_IS_COMMITTED
The examples of this document are tests at test/transactioner.readme.test.js
file.
To have more detailed tests, you can find tests at test/transactioner.api.test.js
file.
Type: class
Description: Class that contains the API of the module.
Type: constructor method
Parameter: t. Optional. Another transactioner instance from which to inherit the state. Take into account that in this case, a copy of the undoers and the state is made for this instance.
Description: The objects of this kind has the ability to run actions, and commit or rollback transactions. They hold a status, which can be unfinished, committed or rolledback.
Type: array <Function>
InitialValue: []
Description: Array containing the functions that roll-back the actions that weer run [but not rolled-back or committed yet].
Type: number
InitialValue: 0 (= Transactioner.STATUS_UNFINISHED
)
Description: Value that represents the current status of the transactioner instance. The available values are:
- 0:
Transactioner.STATUS_UNFINISHED
. The transaction has not been committed or rolled-back. - 1:
Transactioner.STATUS_SUCCESS
. The transaction has been committed. - 2:
Transactioner.STATUS_ERROR
. The transaction has been rolled-back.
When the value of this proprty is not 0, the methods run
, commit
and rollback
will be blocked and will throw errors.
Type: method
Parameters: ...actions
. Objects of the form: { up: <Function>, down: <Function> }
. The up functions are executed in the same call. The down functions are saved until the transactioner instance is:
- rolled-back: in this case, the downs will be called reversedly, or:
- committed: in this case, the downs will be deleted.
The down functions are saved under the transactioner.undoers
array.
Returns: Transactioner:Object
. The instance itself, to make it chainable, so you can:
transactioner
.run({ up: () => {}, down: () => {} })
.run({ up: () => {}, down: () => {} })
.run({ up: () => {}, down: () => {} })
.run({ up: () => {}, down: () => {} })
.commit();
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_COMMITTED
when the transactioner.status is Transactioner.STATUS_SUCCESS
.
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_ROLLEDBACK
when the transactioner.status is Transactioner.STATUS_ERROR
.
Type: method
Returns: Transactioner:Object
. The instance itself, to make it chainable.
Description: Commits the transaction, which means that the status is set to Transactioner.STATUS_SUCCESS, and the undoers are cleared.
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_COMMITTED
when the transactioner.status is Transactioner.STATUS_SUCCESS
.
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_ROLLEDBACK
when the transactioner.status is Transactioner.STATUS_ERROR
.
Type: method
Returns: Transactioner:Object
. The instance itself, to make it chainable.
Description: Commits the transaction, which means that the status is set to Transactioner.STATUS_SUCCESS, and the undoers are cleared.
Type: method
Returns: Transactioner:Object
. The instance itself, to make it chainable.
Description: Rolls back the transaction, which means that the status is set to Transactioner.STATUS_ERROR, and the undoers are executed in the reversed order they were added.
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_COMMITTED
when the transactioner.status is Transactioner.STATUS_SUCCESS
.
Throws: Transactioner.ERROR_TRANSACTION_STATUS_IS_ROLLEDBACK
when the transactioner.status is Transactioner.STATUS_ERROR
.
Throws: Any kind of error, if an undoer throws it.
Type: method
Returns: isTransactionFinished:Boolean.
Description: Returns true
when the transaction has been committed or rolled back, and false if its status is unfinished.
To run the tests, including coverage, you can:
$ cd node_modules/transactioner
$ npm install
$ npm run coverage
To submit issues, you can go here.
This software is under WTFL, which means simply: do what you want.