AsyncStatus JS

Manages the status of an async process.

• Built-in TypeScript declarations.
• Built-in Javascript / TypeScript map declarations.
• Comprehensive unit testing.
• Available at npmjs.com
• Source Code

Table Of Content

• Installation
  • As project dependency
  • As script dependency
• Basic usage snippets
  • async / await
  • Observable
• Status management / Class interface
  • Use
  • Check attempt stats
  • Check current state
  • Check last outcome state
  • Measure the time
• Final notes
• Examples

Installation

As project dependency

npm i @bugtamer/async-status

Available at npmjs.com

As script dependency

'require' demo example

const bugtamer = require("@bugtamer/async-status")
const dataAsyncStatus = new bugtamer.AsyncStatus();

or

const bugtamer = require("@bugtamer/async-status/lib/async-status")
const dataAsyncStatus = new bugtamer.AsyncStatus();

'import' demo example

import { AsyncStatus } from '@bugtamer/async-status/lib/async-status';
const dataAsyncStatus = new AsyncStatus();

Basic usage snippets

async / await

dataAsyncStatus.start();
try {
    data = await fetchData();
    dataAsyncStatus.end();
} catch (error) {
    dataAsyncStatus.abort();
}

Observable

dataAsyncStatus.start();
const subscription = fetchData().subscribe(
    response => {
        data = response;
        dataAsyncStatus.end();
    },
    error => {
        dataAsyncStatus.abort();
    }
);

Status management / Class interface

Use

| Current State | Method called / Sentence | Outcome | | ------------- | ------------------------ | -------------- | | | new AsyncStatus() | idle state | | idle | start() | ongoing state | | ongoing | end() | idle state | | ongoing | abort() | idle state | | ongoing | start() | Throw an error | | idle | end() | Throw an error | | idle | abort() | Throw an error |

Do not try to manage these errors, just fix your code. They point out that some method should never have called.

Check attempt stats

| Sentence | Description | |---------------------------------------|------------------------------------------| | dataAsyncStatus.attempts | returns the number of calls to start() | | dataAsyncStatus.successfulAttempts | returns the number of calls to end() | | dataAsyncStatus.failedAttempts | returns the number of calls to abort() | | dataAsyncStatus.resetAttemptStats() | all previous counters are set to 0 |

Check current state

In this section we understand by call a call to any of the following methods: start(), end() or abort().

Idle State

There is no process activity.

| dataAsyncStatus.isIdle | Returns | |-----------------------------------------------------------------------------|---------| | When start() was never executed or the last call was end() or abort() | true | | In any other case | false |

Ongoing state

There is a process in progress.

| dataAsyncStatus.isOngoing | Returns | |---------------------------------------------------------------------------------------------------|---------| | When the last call was start() and therefore neither end() nor abort() have been called yet | true | | In any other case | false |

Check last outcome state

In this section we understand by call a call to any of the following methods: start(), end() or abort().

A successful outcome

| dataAsyncStatus.wasSuccessful | Returns | |-----------------------------------------|---------| | When end() was the last method called | true | | In any other case | false |

A failed outcome

| dataAsyncStatus.wasFailed | Returns | |-------------------------------------------|---------| | When abort() was the last method called | true | | In any other case | false |

Measure the time

In milliseconds (ms):

| dataAsyncStatus.elapsedTime | Returns | |-------------------------------------------------------------------------------|------------------------------------------------------------------| | when start() was never called | AsyncStatus.UNDEFINED_TIME (-1) | | when start() was called but end() or abort() has not yet been called | Time elapsed since the call to start() to current time | | when start() was called and eventually end() or abort() was also called | Elapsed time from call to start() to end() or abort() call |

Final notes

• Using a single instance of AsyncStatus to control multiple independent asynchronous processes that overlap in time could lead to erratic behavior in your program.

• start() throws an error when is called more than Number.MAX_SAFE_INTEGER times (although is nearly unreachable).

Examples

• Angular demo example
• Check out the following example at RunKit:

// const bugtamer = require("@bugtamer/async-status/lib/async-status")
const bugtamer = require("@bugtamer/async-status")


function showStats(asyncStatus, message) {
    console.log(message)
    console.log(`  - Attempts:     ${asyncStatus.attempts}`)
    console.log(`    - successful: ${asyncStatus.successfulAttempts}`)
    console.log(`    - failed:     ${asyncStatus.failedAttempts}`)
    console.log(`  - State:`)
    console.log(`    - idle:       ${asyncStatus.isIdle}`)
    console.log(`    - ongoing:    ${asyncStatus.isOngoing}`)
    console.log(`  - Outcome:`)
    console.log(`    - successful: ${asyncStatus.wasSuccessful}`)
    console.log(`    - failed:     ${asyncStatus.wasFailed}`)
    console.log(`  - Time elapsed: ${asyncStatus.elapsedTime} ms`)
}


// Let's show where the Internation Space Station currently is.
console.log("Let's see where the ISS is with Node " + process.version);

// We can use any package from NPM since they are all built in.
var getJSON = require("async-get-json"); 


const status = new bugtamer.AsyncStatus();
showStats(status, 'new AsyncStatus()')

status.start()
showStats(status, 'start()')


const url = "http://api.open-notify.org/iss-now.json"; // change it to make it fail
try {
    // And we can use ES7 async/await to pull the ISS's position from the open API.
    var result = await getJSON(url);

    status.end()
    showStats(status, 'end()')
} catch (error) {
    status.abort()
    showStats(status, 'abort()')
}


if (!!result) {
    // RunKit will automatically display the last statement and try to find its best representation:
    result.iss_position;
}

Example output

Let's see where the ISS is with Node v14.20.1
new AsyncStatus()
  - Attempts:     0
    - successful: 0
    - failed:     0
  - State:
    - idle:       true
    - ongoing:    false
  - Outcome:
    - successful: false
    - failed:     false
  - Time elapsed: -1 ms
start()
  - Attempts:     1
    - successful: 0
    - failed:     0
  - State:
    - idle:       false
    - ongoing:    true
  - Outcome:
    - successful: false
    - failed:     false
  - Time elapsed: 1 ms
end()
  - Attempts:     1
    - successful: 1
    - failed:     0
  - State:
    - idle:       true
    - ongoing:    false
  - Outcome:
    - successful: true
    - failed:     false
  - Time elapsed: 75 ms