Add support for random time periods

Author: gamtiq

.babelrc

@@ -2,8 +2,5 @@
     "presets": [
         "es2015"
     ],
-    "plugins": [
-        "add-module-exports"
-    ],
     "sourceMaps": true
 } 

Gruntfile.js

@@ -74,7 +74,6 @@ module.exports = function(grunt) {
                 template: "unit",
                 src: "dist/chronoman.common.js",
                 dest: "dist/chronoman.js",
-                objectToExport: "Timer",
                 globalAlias: "Chronoman"
             }
         },

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2019 Denis Sikuler
+Copyright (c) 2013-2020 Denis Sikuler
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -4,7 +4,7 @@ Utility class to simplify use of timers created by `setTimeout`.
 
 ```js
 var timer = new Timer({
-    period: [100, 200, 300, 400, 500],
+    period: [100, 200, 300, 400, 500, {start: 100, end: 500}],
     repeatQty: 100,
     passToAction: true,
     action: function(tmr) {
@@ -26,10 +26,6 @@ timer.stop();
 
     npm install chronoman
 
-### [JSPM](http://jspm.io)
-
-    jspm install chronoman
-
 ### [Bower](http://bower.io)
 
     bower install chronoman
@@ -46,24 +42,17 @@ Use `dist/chronoman.js` or `dist/chronoman.min.js` (minified version).
 import Timer from "chronoman";
 ```
 
-### Node, JSPM
-
-```js
-var Timer = require("chronoman");
-```
-
-### JSPM
+### Node
 
 ```js
-System.import("chronoman").then(function(Timer) {
-    ...
-});
+var Timer = require("chronoman").Timer;
 ```
 
 ### AMD
 
 ```js
-define(["path/to/dist/chronoman.js"], function(Timer) {
+define(["path/to/dist/chronoman.js"], function(chronoman) {
+    var Timer = chronoman.Timer;
     ...
 });
 ```
@@ -75,7 +64,7 @@ define(["path/to/dist/chronoman.js"], function(Timer) {
 <script type="text/javascript" src="path/to/dist/chronoman.js"></script>
 <script type="text/javascript">
     // сhronoman is available via Chronoman field of window object
-    var Timer = Chronoman;
+    var Timer = Chronoman.Timer;
     ...
 </script>
 ```
@@ -96,7 +85,7 @@ var tmrOne = new Timer({
 });
 
 var tmrTwo = new Timer();
-tmrTwo.setPeriod([2000, 1500])
+tmrTwo.setPeriod([2000, , {start: 1000, end: 1500}])
     .setRepeatQty(9)
     .setPassToAction(true)
     .setAction({
@@ -138,5 +127,5 @@ This module is inspired by [qooxdoo](http://qooxdoo.org)'s `qx.event.Timer` clas
 
 ## Licence
 
-Copyright (c) 2013-2019 Denis Sikuler  
+Copyright (c) 2013-2020 Denis Sikuler  
 Licensed under the MIT license.

chronoman.js

@@ -11,16 +11,70 @@ if (! Array.isArray) {
     };
 }
 
+/**
+ * Generate random number or randomly select item from specified array.
+ *
+ * @param {Array | number} start
+ *      Array from which an item should be selected
+ *      or minimal point of interval from which random number should be generated.
+ * @param {number} [end=start+1]
+ *      Maximal point of interval from which random number should be generated.
+ * @param {boolean} [bInteger=true]
+ *      Whether integer number should be returned.
+ *      This parameter can be used when value of <code>start</code> parameter is a number.
+ * @return {*}
+ *      Random number when <code>start</code> parameter is a number
+ *      or randomly selected item when <code>start</code> parameter is an array.
+ */
+export function getRandomValue(start, end, bInteger) {
+    var nL, result;
+    if (Array.isArray(start)) {
+        nL = start.length;
+        if (nL) {
+            return start[ nL > 1 ? getRandomValue(0, nL - 1) : 0 ];
+        }
+        return result;
+    }
+
+    if (typeof end !== "number") {
+        end = start + 1;
+    }
+    if (arguments.length < 3) {
+        bInteger = true;
+    }
+    nL = start + ((end - start) * Math.random());
+
+    return bInteger ? Math.round(nL) : nL;
+}
+
 /**
  * @callback module:chronoman~GetPeriodValue
  * @param {module:chronoman~Timer} [timer]
- * @return {Integer | Integer[]}
+ * @return {module:chronoman~SinglePeriodValue | module:chronoman~SinglePeriodValue[]}
+ */
+
+/**
+ * Object describing properties for generating random time period.
+ *
+ * @typedef {Object} module:chronoman~RandomPeriod
+ * @property {Integer} [end]
+ *      Maximal point of interval from which random time period should be generated.
+ * @property {Integer[]} [list]
+ *      Array from which a time period should be selected randomly.
+ * @property {Integer} [start]
+ *      Minimal point of interval from which random time period should be generated.
+ */
+
+/**
+ * Single value determining time period in milliseconds that is used to schedule related action execution.
+ *
+ * @typedef {Integer | module:chronoman~RandomPeriod} module:chronoman~SinglePeriodValue
  */
 
 /**
  * Value determining time period in milliseconds that is used to schedule related action execution.
  *
- * @typedef {Integer | Integer[] | module:chronoman~GetPeriodValue} module:chronoman~PeriodValue
+ * @typedef {module:chronoman~SinglePeriodValue | module:chronoman~SinglePeriodValue[] | module:chronoman~GetPeriodValue} module:chronoman~PeriodValue
  */
 
 /**
@@ -74,9 +128,19 @@ var Timer = function Timer(initValue) {
 
 
 /**
- * Time period in milliseconds, array of periods or function that returns period or array of periods.
+ * Time period in milliseconds, object specifying random time period, array of periods
+ * or function that returns period or array of periods.
  * A related action will be executed when the period is elapsed.
  * <br>
+ * When an object is set the used period is selected randomly.
+ * The object can have the following properties:
+ * - <code>list</code> - a non-empty array of integer numbers from which the period will be selected randomly.
+ * - <code>start</code> - an integer number representing minimal point of interval
+ *      from which random time period should be generated; default value - 0.
+ * - <code>end</code> - an integer number representing maximal point of interval
+ *      from which random time period should be generated; default value - <code>start + 1000</code>.
+ * 
+ * <br>
  * When array of periods is set the used period is selected in the following way:
  * first array item (with index 0) specifies period before first action's execution,
  * second array item (with index 1) specifies period before second action's execution,
@@ -126,23 +190,42 @@ Timer.prototype.setPeriod = function(period) {
 /**
  * Return time period that will be used to schedule related action execution.
  *
+ * @param {module:chronoman~PeriodValue} [value=this.getPeriod()]
+ *      Value that is used to calculation.
  * @return {Integer}
  *      Time period in milliseconds.
  * @method
  * @see {@link module:chronoman~Timer#_period _period}
  * @see {@link module:chronoman~Timer#getPeriod getPeriod}
  * @see {@link module:chronoman~Timer#getExecutionQty getExecutionQty}
  */
-Timer.prototype.getPeriodValue = function() {
+Timer.prototype.getPeriodValue = function(value) {
+    /*jshint laxbreak:true*/
     var execQty;
-    var period = this.getPeriod();
+    var period = value || value === 0
+        ? value
+        : this.getPeriod();
     if (typeof period === "function") {
         period = period(this);
     }
     if (Array.isArray(period)) {
         execQty = this.getExecutionQty();
         period = period[ execQty < period.length ? execQty : period.length - 1 ];
     }
+    if (period && typeof period === "object") {
+        if (period.list && period.list.length) {
+            period = getRandomValue(period.list);
+        }
+        else {
+            if (typeof period.start !== "number") {
+                period.start = 0;
+            }
+            if (typeof period.end !== "number") {
+                period.end = period.start + 1000;
+            }
+            period = getRandomValue(period.start, period.end);
+        }
+    }
     return period;
 };
 
@@ -224,8 +307,9 @@ Timer.prototype.setRepeatQty = function(nQty) {
  * Specifies function that should be called after action execution to determine
  * whether execution should be repeated.
  * If the function returns a true value or non-negative number it means that execution will be repeated.
- * When the function returns non-negative number this number will be used
- * as time period in milliseconds to schedule next action execution.
+ * When the function returns non-negative number, array, object or function this value will be used
+ * to calculate time period in milliseconds to schedule next action execution
+ * (see {@link module:chronoman~Timer#getPeriodValue getPeriodValue}).
  * <br>
  * The timer instance to which the test is associated will be passed as function's parameter.
  *
@@ -348,8 +432,8 @@ Timer.prototype._timeoutId = null;
 /**
  * Schedule related action execution.
  *
- * @param {Integer} [nTimeout]
- *      Time period in milliseconds that is used to schedule action execution.
+ * @param {module:chronoman~PeriodValue} [timeout]
+ *      Time period that is used to schedule action execution.
  *      By default the current value of {@link module:chronoman~Timer#getPeriod period} property is used
  *      to determine time period.
  * @return {Object}
@@ -362,15 +446,9 @@ Timer.prototype._timeoutId = null;
  * @see {@link module:chronoman~Timer#execute execute}
  * @see {@link module:chronoman~Timer#getPeriodValue getPeriodValue}
  */
-Timer.prototype._setTimeout = function(nTimeout) {
+Timer.prototype._setTimeout = function(timeout) {
     "use strict";
-    var period;
-    if (typeof nTimeout === "number") {
-        period = nTimeout;
-    }
-    else {
-        period = this.getPeriodValue();
-    }
+    var period = this.getPeriodValue(timeout);
     if (typeof period === "number") {
         this._timeoutId = setTimeout(this._onTimeoutEnd, period);
     }
@@ -787,7 +865,7 @@ Timer.prototype.execute = function() {
     var action = this.getAction(),
         bPassToAction = this.isPassToAction(),
         repeatTest = this.getRepeatTest(),
-        bActive, period;
+        bActive, period, sType;
     this._clearTimeout();
     if (action) {
         if (typeof action === "function") {
@@ -814,9 +892,14 @@ Timer.prototype.execute = function() {
                     || this.getRepeatQty() >= this._executionQty
                     || (repeatTest
                         && ( (period = repeatTest(this)) || period === 0 )
-                        && (typeof period !== "number" || period >= 0))
+                        && (sType = typeof period)
+                        && (sType !== "number" || period >= 0))
                 ) ) {
-        this._setTimeout(period);
+        this._setTimeout(
+            sType === "number" || sType === "object" || sType === "function"
+                ? period
+                : null
+        );
     }
     else if (bActive && ! this._timeoutId) {
         this.setActive(false);
@@ -889,5 +972,5 @@ Timer.prototype.toString = function() {
 };
 
 // Exports
-
+export { Timer };
 export default Timer;