Deprecate .status in favor of .getPercent()

Author: rstacruz

README.md

@@ -2,7 +2,7 @@
 
 [![Status](https://api.travis-ci.org/rstacruz/nprogress.svg?branch=master)](http://travis-ci.org/rstacruz/nprogress)
 [![npm version](https://img.shields.io/npm/v/nprogress.png)](https://npmjs.org/package/nprogress "View this project on npm")
-[![jsDelivr Hits](https://data.jsdelivr.com/v1/package/npm/nprogress/badge?style=rounded)](https://www.jsdelivr.com/package/npm/nprogress)
+[![jsDelivr hits](https://data.jsdelivr.com/v1/package/npm/nprogress/badge?style=rounded)](https://www.jsdelivr.com/package/npm/nprogress)
 
 > Minimalist progress bar
 
@@ -167,7 +167,11 @@ do anything if _.start()_ isn't called)
 NProgress.done(true);
 ```
 
-**Get the status value:** To get the status value, use `.status`.
+**Get the current percentage:** Use `getPercent()` to get the current value.
+
+```js
+console.log(NProgress.getPercent());
+```
 
 ## Configuration
 
@@ -181,9 +185,7 @@ NProgress.configure({ minimum: 0.1 });
 
 #### `template`
 
-You can change the markup using `template`. To keep the progress
-bar working, keep an element with `role='bar'` in there. See the [default template]
-for reference.
+You can change the markup using `template`. To keep the progress bar working, keep an element with `role='bar'` in there. See the [default template] for reference.
 
 ```js
 NProgress.configure({
@@ -193,8 +195,7 @@ NProgress.configure({
 
 #### `easing` and `speed`
 
-Adjust animation settings using _easing_ (a CSS easing string)
-and _speed_ (in ms). (default: `ease` and `200`)
+Adjust animation settings using _easing_ (a CSS easing string) and _speed_ (in ms). (default: `ease` and `200`)
 
 ```js
 NProgress.configure({ easing: "ease", speed: 500 });

src/nprogress.js

@@ -8,14 +8,31 @@ import {
 } from "./utilities";
 import setCSS from "./css";
 
-const NProgress = {};
+/**
+ * The current progress number from 0...1, or `null` if not started.
+ * @type {number | null}
+ */
+
+let status = null;
 
 /**
- * Last number.
- * @type {null | number}
+ * Returns the current percentage.
+ * @return {number | null
  */
 
-NProgress.status = null;
+function getPercent() {
+  return status;
+}
+
+/**
+ * (Internal) sets the percent value.
+ * This is only used in tests. Please use `set()` instead.
+ * @param {number} value
+ */
+
+function setPercent(value) {
+  status = value;
+}
 
 /**
  * @typedef CSSDefinition
@@ -39,6 +56,25 @@ let Settings = {
     '<div class="bar" role="bar"><div class="peg"></div></div><div class="spinner" role="spinner"><div class="spinner-icon"></div></div>',
 };
 
+/**
+ * Default export for CommonJS and for chaining
+ */
+
+const NProgress = {
+  configure,
+  done,
+  getPercent,
+  inc,
+  isRendered,
+  isStarted,
+  remove,
+  render,
+  set,
+  settings: Settings,
+  start,
+  trickle: inc,
+};
+
 /**
  * Updates configuration.
  *
@@ -74,7 +110,7 @@ function set(n) {
   var started = isStarted();
 
   n = clamp(n, Settings.minimum, 1);
-  NProgress.status = n === 1 ? null : n;
+  setPercent(n === 1 ? null : n);
 
   var progress = render(!started),
     bar = progress.querySelector(Settings.barSelector),
@@ -121,7 +157,7 @@ function set(n) {
 }
 
 function isStarted() {
-  return typeof NProgress.status === "number";
+  return typeof getPercent() === "number";
 }
 
 /**
@@ -132,12 +168,12 @@ function isStarted() {
  *     NProgress.start();
  */
 
-NProgress.start = function () {
-  if (!NProgress.status) set(0);
+function start() {
+  if (!getPercent()) set(0);
 
   var work = function () {
     setTimeout(function () {
-      if (!NProgress.status) return;
+      if (!getPercent()) return;
       inc();
       work();
     }, Settings.trickleSpeed);
@@ -146,7 +182,7 @@ NProgress.start = function () {
   if (Settings.trickle) work();
 
   return NProgress;
-};
+}
 
 /**
  * Hides the progress bar.
@@ -162,13 +198,13 @@ NProgress.start = function () {
  * @param {boolean | null | void} force
  */
 
-NProgress.done = function (force) {
-  if (!force && !NProgress.status) return NProgress;
+function done(force) {
+  if (!force && !getPercent()) return NProgress;
 
   inc(0.3 + 0.5 * Math.random());
   set(1);
   return NProgress;
-};
+}
 
 /**
  * Increments by a random amount.
@@ -178,10 +214,10 @@ NProgress.done = function (force) {
  */
 
 function inc(amount) {
-  var n = NProgress.status;
+  var n = getPercent();
 
   if (!n) {
-    return NProgress.start();
+    return start();
   } else if (n > 1) {
     return;
   } else {
@@ -205,14 +241,16 @@ function inc(amount) {
 }
 
 /**
+ * Returns the parent node as an HTMLElement.
  * @return {HTMLElement}
  */
 
-function getParent() {
+function getParentElement() {
   if (typeof Settings.parent === "string") {
     let parent = document.querySelector(Settings.parent);
     if (!parent)
       throw new Error(`NProgress: Invalid parent '${Settings.parent}'`);
+
     return parent;
   } else {
     return Settings.parent;
@@ -240,10 +278,10 @@ function render(fromStart) {
   if (!bar)
     throw new Error(`NProgress: No bar found for '${Settings.barSelector}'`);
 
-  let perc = fromStart ? "-100" : toBarPerc(NProgress.status || 0);
+  let perc = fromStart ? "-100" : toBarPerc(getPercent() || 0);
 
   /** @type HTMLElement */
-  let parent = getParent();
+  let parent = getParentElement();
 
   /** @type HTMLElement | null */
   let spinner;
@@ -289,28 +327,24 @@ function isRendered() {
   return !!document.getElementById("nprogress");
 }
 
-// Default export for commonjs / import NProgress
-NProgress.configure = configure;
-NProgress.inc = inc;
-NProgress.isRendered = isRendered;
-NProgress.isStarted = isStarted;
-NProgress.remove = remove;
-NProgress.render = render;
-NProgress.set = set;
-NProgress.settings = Settings;
-NProgress.trickle = inc;
-
-// Export for ESM
+/*
+ * Export for ESM
+ */
+
 export {
   configure,
-  inc,
+  done,
+  getPercent,
   inc as trickle,
+  inc,
   isRendered,
   isStarted,
   remove,
   render,
   set,
+  setPercent as _setPercent,
   Settings as settings,
+  start,
 };
 
 export default NProgress;

src/nprogress.test.js

@@ -1,4 +1,4 @@
-import NProgress from "./nprogress";
+import NProgress, { _setPercent } from "./nprogress";
 
 jest.useFakeTimers();
 
@@ -17,7 +17,7 @@ beforeEach(() => {
 
 afterEach(() => {
   remove(qs("#nprogress"));
-  NProgress.status = null;
+  _setPercent(null);
   Object.assign(NProgress.settings, defaults);
 });
 
@@ -40,17 +40,17 @@ describe("set()", () => {
 
   it("must respect minimum", () => {
     NProgress.set(0);
-    expect(NProgress.status).toEqual(NProgress.settings.minimum);
+    expect(NProgress.getPercent()).toEqual(NProgress.settings.minimum);
   });
 
   it("must clamp to minimum", () => {
     NProgress.set(-100);
-    expect(NProgress.status).toEqual(NProgress.settings.minimum);
+    expect(NProgress.getPercent()).toEqual(NProgress.settings.minimum);
   });
 
   it("must clamp to maximum", () => {
     NProgress.set(400);
-    expect(NProgress.status).toEqual(null);
+    expect(NProgress.getPercent()).toEqual(null);
   });
 });
 
@@ -63,7 +63,7 @@ describe(".start()", function () {
 
   it("must respect minimum", function () {
     NProgress.start();
-    expect(NProgress.status).toEqual(NProgress.settings.minimum);
+    expect(NProgress.getPercent()).toEqual(NProgress.settings.minimum);
   });
 });
 
@@ -120,24 +120,24 @@ describe(".inc()", function () {
 
   it("should start with minimum", function () {
     NProgress.inc();
-    expect(NProgress.status).toEqual(NProgress.settings.minimum);
+    expect(NProgress.getPercent()).toEqual(NProgress.settings.minimum);
   });
 
   it("should increment", function () {
     NProgress.start();
 
-    let start = NProgress.status;
+    let start = NProgress.getPercent();
     NProgress.inc();
 
-    expect(NProgress.status).toBeGreaterThan(start);
+    expect(NProgress.getPercent()).toBeGreaterThan(start);
   });
 
   it("should never reach 1.0", function () {
     for (let i = 0; i < 100; ++i) {
       NProgress.inc();
     }
 
-    expect(NProgress.status).toBeLessThan(1);
+    expect(NProgress.getPercent()).toBeLessThan(1);
   });
 });