Source: Progress.js

  1. const EventEmitter = require('events').EventEmitter
  2. , Rx = require('rxjs')
  3. , Observable = Rx.Observable
  4. , fromEvent = Rx.fromEvent
  5. , symbolProgress = Symbol('progress');
  8. /**
  9.  * A class used to report progress of any kind. Supports events through
  10.  * EventEmitter, own callbacks or being used as an Observable.
  11.  * 
  12.  * @template T
  13.  */
  14. class Progress extends EventEmitter {
  15. 	/**
  16. 	 * @param {callbackHandler<T>} handler a callback to be invoked for every
  17. 	 * progress reported. If not provided, you may subscribe to the events of
  18. 	 * this class or use the provided Observable.
  19. 	 */
  20. 	constructor(handler = void 0) {
  21. 		super();
  22. 		this.handler = handler;
  23. 		/** @type {T} */
  24. 		this.last = void 0;
  25. 	};
  27. 	/**
  28. 	 * Report the current progress, which is then broadcast to all listeners
  29. 	 * and passed to this handler.
  30. 	 * 
  31. 	 * @param {T} progress the item that represents the progress
  32. 	 * @returns {Progress} this
  33. 	 */
  34. 	reportProgress(progress) {
  35. 		this.last = progress;
  36. 		setTimeout(() => {
  37. 			this.emit(symbolProgress, progress);
  38. 			if (this.handler instanceof Function) {
  39. 				this.handler(progress);
  40. 			}
  41. 		}, 0);
  42. 		return this;
  43. 	};
  45. 	/**
  46. 	 * Returns an Rx.Observable that will emit events whenever they
  47. 	 * are reported to its subscribers.
  48. 	 * 
  49. 	 * @type {Observable<T>}
  50. 	 */
  51. 	get observable() {
  52. 		return fromEvent(this, symbolProgress);
  53. 	};
  54. };
  57. /**
  58.  * A simple class to report numeric progress within a range
  59.  * (typically [0, 1]), but any other positive range is good, too.
  60.  */
  61. class ProgressNumeric extends Progress {
  62. 	/**
  63. 	 * @param {Number} progressMin the lowest possible value for the progress
  64. 	 * @param {Number} progressMax the largest possible value for the progress
  65. 	 * @param {callbackHandler<number>} handler a callback to be invoked for every
  66. 	 * progress reported. If not provided, you may subscribe to the events of
  67. 	 * this class or use the provided Observable.
  68. 	 */
  69. 	constructor(progressMin = 0, progressMax = 1, handler = void 0) {
  70. 		super(handler);
  71. 		const t = '[object Number]', v = x => Object.prototype.toString.call(x);
  73. 		if (v(progressMin) !== t || v(progressMax) !== t
  74. 			|| isNaN(progressMin) || isNaN(progressMax)) {
  75. 			throw new Error('Both progressMin and progressMax must be numeric.');
  76. 		}
  77. 		if (progressMin < 0 || progressMax < progressMin) {
  78. 			throw new Error('Both progressMin and progressMax must be positive and progressMax must be greater than progressMin.');
  79. 		}
  81. 		this.progressMin = progressMin;
  82. 		this.progressMax = progressMax;
  83. 		this.progressRange = progressMax - progressMin;
  84. 	};
  86. 	/**
  87. 	 * @type {Number}
  88. 	 */
  89. 	get percent() {
  90. 		return this.last === void 0 ? 0 :
  91. 			(this.last - this.progressMin) / this.progressRange;
  92. 	};
  94. 	/**
  95. 	 * @override
  96. 	 * @inheritdoc
  97. 	 * @param {Number} progress the numeric progress
  98. 	 * @returns {this}
  99. 	 */
  100. 	reportProgress(progress) {
  101. 		if (isNaN(progress) || progress < this.progressMin || progress > this.progressMax) {
  102. 			throw new Error(`The value "${progress}" is out of range.`);
  103. 		}
  105. 		return super.reportProgress(progress);
  106. 	};
  107. };
  109. module.exports = Object.freeze({
  110. 	Progress,
  111. 	ProgressNumeric,
  112. 	symbolProgress
  113. });