ezpbarsjs

ezpbars is a service which generates accurate progress bars for remote activities using actual runtime data across runs.

Prerequisites

This project requires NodeJS (version 8 or later) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
8.19.3
v18.12.0

Table of contents

• ezpbarsjs
  • Prerequisites
  • Table of contents
  • Getting Started
  • Installation
  • Usage
    • Serving the app
    • Running the tests
    • Building a distribution version
  • API
    • Spinner
    • LinearOverallProgressBar
    • StandardProgressDisplay
  • Contributing
  • Credits
  • Built With
  • Versioning

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites

Start with cloning this repo on your local machine:

$ git clone https://github.com/ORG/PROJECT.git
$ cd PROJECT

To install and set up the library, run:

$ npm install -S myLib

Or if you prefer using Yarn:

$ yarn add --dev myLib

Usage

Serving the app

$ npm start

Running tests

$ npm test

Building a distribution version

$ npm run build

This task will create a distribution version of the project inside your local build/ folder

API

waitForCompletion

waits for the given trace to complete, sending progress information to the given progress bar. typically, the progress bar would react to the changes by updating the UI, such as by literally drawing a progress bar, or just using a spinner, or some combination based on context

after this is done, you can get the result of the request from your backend

import { waitForCompletion, StandardProgressDisplay } from 'ezpbarsjs';

const pbar = new StandardProgressDisplay();
document.body.appendChild(pbar.element);
const response = await fetch(
  'https://ezpbars.com/api/1/examples/job',
  {
    method: 'POST',
    headers: { "content-type": "application/json; charset=UTF-8" },
    body: JSON.stringify({
      duration: 5,
      stdev: 1,
    })}
)
/** @type {{uid: str, sub: str, pbar_name: str}} */
const data = await response.json();
const getResult = async () => {
  const response = await fetch(`https://ezpbars.com/api/1/examples/job?uid=${data.uid}`)
  const result = await response.json();
  if (result.status === 'complete') {
    return result.data;
  }
  return null;
}
const pollResult = async () => (await getResult()) !== null;
await waitForCompletion({sub: data.sub, pbarName: data.pbar_name, uid: data.uid, pbar, pollResult});
console.log(await getResult());

Learn More

Arguments

• pbarName - the name of the progress bar to wait for completion of
• uid - the uid of the trace to watch
• sub - the identifier for the account the progress bar belongs to
• pbar - the progress bar that's being rendered. For example, a StandardProgressDisplay (defaults to null)
• domain - the domain to make the websocket connection to (defaults to ezpbars.com)
• ssl - indicates the scheme to use for the websocket connection where true is wss and false is ws (defaults to true)
• pollResult - checks if your backend is finished processing the trace; used as a fallback if ezpbars is not available. typically, this is implemented using a fetch to your backend, in the same way that you would normally get the result after this library notifies you that the result is ready

Spinner

shows a basic spinner requires spinner.css

document.getElementByTagName('body').appendChild(
  (() => {
    const spinner = new Spinner();
    return spinner.element;
  })()
);

Learn More

LinearOverallProgressBar

shows a basic linear progress bar for the overall progress

document.getElementByTagName('body').appendChild(
  (() => {
    const progressBar = new LinearOverallProgressBar();
    return progressBar.element;
  })()
);

Learn More

StandardProgressDisplay

shows a standard progress display in which a linear progress bar is shown while there is positive time remaining and a spinner is shown otherwise requires spinner.css

document.getElementByTagName('body').appendChild(
  (() => {
    const pbar = new StandardProgressDisplay();
    return pbar.element;
  })()
);

Learn More

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Add your changes: git add .
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin my-new-feature
6. Submit a pull request 😎

Credits

• Amanda Moore
• Timothy Moore

Built With

• Jest - for testing
• Babel - for transpiling
• TypeScript - for type checking

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.