@burstjs/monitor

@burstjs/monitor

A monitor to watch for specific changes on the Burst blockchain

Due to average blocktime of 240 seconds, transactions stay pending for a certain time. It is a repeating pattern to watch for such changes and waiting for confirmation. This package simplifies this task.

As additional feature, a monitor is serializable, that means it can be stored e restored. This is especially useful for web applications, as it allows reloading pages without losing the ability to check whether a transaction is still pending or already concluded.

Installation

@burstjs/monitor can be used with NodeJS or Web. Two formats are available

Using with NodeJS and/or modern web frameworks

Install using npm:

npm install @burstjs/monitor

or using yarn:

yarn add @burstjs/monitor

Example

import {Monitor} from '@burstjs/monitor'
import {composeApi} from "@burstjs/core";

// A method that checks if an account exists
// > IMPORTANT: Do not use closures, when you need to serialize the monitor
async function tryFetchAccount() {
    const BurstApi = composeApi({ nodeHost: 'https://testnet.burstcoin.network:6876/'})
    try{
        const {account} = await BurstApi.account.getAccount('1234')
        return account;
    }catch (e){
        // ignore error
        return null;
    }
}

// A comparing function to check if a certain condition for the returned data from fetch function
// is true. If it's true the monitor stops
function checkIfAccountExists(account) {
    return account !== null;
}

// Create your monitor
const monitor = new Monitor({
    asyncFetcherFn: tryFetchAccount,
    compareFn: checkIfAccountExists,
    intervalSecs: 10, // polling interval in seconds
    key: 'monitor-account',
    timeoutSecs: 2 * 240 // when reached timeout the monitor stops
});
// starts monitor
monitor.start();

// called when `checkIfAccountExists` returns true
monitor.onFulfilled(() => {
    console.log('Yay, account active');
});

// called when `timeoutSecs` is reached
monitor.onTimeout(() => {
    console.log('Hmm, something went wrong');
});

Using in classic <script>

Each package is available as bundled standalone library using IIFE. This way burstJS can be used also within <script>-Tags. This might be useful for Wordpress and/or other PHP applications.

Just import the package using the HTML <script> tag.

<script src='https://cdn.jsdelivr.net/npm/@burstjs/monitor/dist/burstjs.monitor.min.js'></script>

Example

const monitor = new b$monitor.Monitor({
    //...
});
monitor.start()
monitor.onFulFilled(() => {
    //...
})

Monitor Serialization

TO DO

---

See more here:

@burstjs/monitor Online Documentation

---

API Reference

monitor

The generic monitor class.

A monitor can be used to check periodically for a certain situation, e.g. confirmation of a transaction, activation on an account, or even something completely different.

Example: (checking for the existence of an account aka account activation)

// A method that checks if an account exists
// > IMPORTANT: Do not use closures, when you need to serialize the monitor
async function tryFetchAccount() {
   const BurstApi = composeApi({ nodeHost: 'https://testnet.burstcoin.network:6876/'})
   try{
       const {account} = await BurstApi.account.getAccount('1234')
       return account;
   }catch (e){
       // ignore error
       return null;
   }
}
// A comparing function to check if a certain condition for the returned data from fetch function
// is true. If it's true the monitor stops
function checkIfAccountExists(account) {
return account !== null;
}
// Create your monitor
const monitor = new Monitor<Account>({
asyncFetcherFn: tryFetchAccount,
compareFn: checkIfAccountExists,
intervalSecs: 10, // polling interval in seconds
key: 'monitor-account',
timeoutSecs: 2 * 240 // when reached timeout the monitor stops
})
.onFulfilled(() => {
// called when checkIfAccountExists returns true
console.log('Yay, account active');
})
.onTimeout(() => {
// called when timeoutSecs is reached
console.log('Hmm, something went wrong');
}).start();

• monitor
  • ~Monitor
    • new Monitor(args)
    • instance
      • .startTime
      • .intervalSecs
      • .key
      • .timeoutSecs
      • .serialize()
      • .hasStarted() ⇒
      • .isExpired() ⇒
      • .start()
      • .stop()
      • .onTimeout(fn)
      • .onFulfilled(fn)
    • static
      • .deserialize(serializedMonitor, autoStart) ⇒

monitor~Monitor

Kind: inner class of monitor

• ~Monitor
  • new Monitor(args)
  • instance
    • .startTime
    • .intervalSecs
    • .key
    • .timeoutSecs
    • .serialize()
    • .hasStarted() ⇒
    • .isExpired() ⇒
    • .start()
    • .stop()
    • .onTimeout(fn)
    • .onFulfilled(fn)
  • static
    • .deserialize(serializedMonitor, autoStart) ⇒

new Monitor(args)

The monitors constructor

Param	Description
args	The arguments

monitor.startTime

The start timestamp if started, or -1

Kind: instance property of Monitor

monitor.intervalSecs

The interval

Kind: instance property of Monitor

monitor.key

The key aka identifier

Kind: instance property of Monitor

monitor.timeoutSecs

The timeout

Kind: instance property of Monitor

monitor.serialize()

Serializes the monitor, such it can be stored. This serializes also the asyncFetcher and compareFn It is important that these functions are not closures, i.e. the must not reference outer data/variables, otherwise the behavior on deserialization is not deterministic

Kind: instance method of Monitor

monitor.hasStarted() ⇒

Kind: instance method of Monitor
Returns:

true, if monitor was started and is running

monitor.isExpired() ⇒

Kind: instance method of Monitor
Returns:

true, if a started monitor timed out.

monitor.start()

Starts the monitor

Kind: instance method of Monitor

monitor.stop()

Stops the monitor

Kind: instance method of Monitor

monitor.onTimeout(fn)

Callback function for timeout event. You can add multiple event listener if you want

Kind: instance method of Monitor

Param	Description
fn	The callback

monitor.onFulfilled(fn)

Callback function for fulfilled event. You can add multiple event listener if you want

Kind: instance method of Monitor

Param	Description
fn	The callback

Monitor.deserialize(serializedMonitor, autoStart) ⇒

Deserializes a serialized monitor

Kind: static method of Monitor
Returns:

The monitor instance

See:

[[Monitor.serialize]]

Param	Default	Description
serializedMonitor		The serialized monitor
autoStart	true	If monitor was started on serialization the monitor starts automatically, if set true (default)