Class: Transaction

x2node-dbos~ Transaction

Transaction.

Note, that errors thrown by the transaction event listeners are logged, but otherwise are ignored. Also note that the listeners are invoked asynchronously in a process.nextTick(). All that makes the event fired by the transaction good for notifications but not for implementing the main transaction logic.


new Transaction(dbDriver, connection)

Note: The constructor is not available to the client code. Transaction instances are provided by the TxFactory.
Parameters:
Name Type Description
dbDriver module:x2node-dbos.DBDriver DB driver.
connection * DB driver specific connection object.
Fires:

Members


<readonly> connection :*

Underlying DB driver specific connection object associated with the transaction.
Type:
  • *

<readonly> dbDriver :module:x2node-dbos.DBDriver

The database driver.
Type:

<readonly> id :string

Transaction id unique for the process.
Type:
  • string

<readonly> startedOn :Date

Timestamp when the transaction was started.
Type:
  • Date

Methods


commit( [passThrough])

Commit the transaction.
Parameters:
Name Type Argument Description
passThrough * <optional>
Arbitrary value to have the promise to return on success. May not be a promise itself (use promise chaining for that).
Throws:
If the transaction has not been started or if it has already finished.
Type
module:x2node-common.X2UsageError
Returns:
Promise that is resolved with the passThrough value if the transaction committed successfully and is rejected with an error object in the case of failure.
Type
Promise

isActive()

Tell if the transaction is started (and not finished).
Returns:
true if active transaction.
Type
boolean

on(eventName, listener)

Add listener for the specified transaction event.
Parameters:
Name Type Description
eventName string Event name. Can be "begin", "commit" or "rollback".
listener function The listener function. The listener return values are ignored. If any listener throws an error, the error is logged but otherwise the process is not affected. The listeners are called asynchronously in a process.nextTick().
Returns:
This transaction for chaining.
Type
module:x2node-dbos~Transaction

rollback( [passThrough])

Rollback the transaction.
Parameters:
Name Type Argument Description
passThrough * <optional>
Arbitrary value to have the promise to return on both success and failure. May not be a promise itself (use promise chaining for that).
Throws:
If the transaction has not been started or if it has already finished.
Type
module:x2node-common.X2UsageError
Returns:
Promise that is resolved with the passThrough value if the transaction rolled back successfully and is rejected with the same passThrough value in the case of failure. The rollback failure error is only logged.
Type
Promise

rollbackAndReject( [passThrough])

Rollback the transaction and return promise that always rejects.
Parameters:
Name Type Argument Description
passThrough * <optional>
Arbitrary value to have the promise to return on both success and failure. May not be a promise itself (use promise chaining for that).
Throws:
If the transaction has not been started or if it has already finished.
Type
module:x2node-common.X2UsageError
Returns:
Promise that is rejected with the passThrough value if the transaction rolled back successfully and is rejected with the same passThrough value in the case of failure. The rollback failure error is only logged.
Type
Promise

start( [passThrough])

Start the transaction.
Parameters:
Name Type Argument Description
passThrough * <optional>
Arbitrary value to have the promise to return on success. May not be a promise itself (use promise chaining for that).
Throws:
If the transaction is already in progress or if it has already finished.
Type
module:x2node-common.X2UsageError
Returns:
Promise that is resolved with the passThrough value if the transaction started successfully and is rejected with an error object in the case of failure.
Type
Promise

Events


begin

Transaction start event. Fired upon successful transaction start.
Type: string

commit

Transaction commit event. Fired upon successful transaction commit.
Type: string

rollback

Transaction rollback event. Fired upon transaction rollback, whether the rollback was successful or not. If the rollback was unsuccessful, the event listener receives the rollback error.
Type: string