Skip to content

bugtamer/async-status-js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

52 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AsyncStatus JS

Manages the status of an async process.

Table Of Content

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

// 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