Source: collections/Stack.js

  1. const { Collection, CollectionEvent } = require('./Collection')
  2. , { Resolve } = require('../tools/Resolve')
  3. , { EqualityComparer } = require('./EqualityComparer')
  4. , { Observable, fromEvent } = require('rxjs')
  5. , symbolStackPush = Symbol('stackPush')
  6. , symbolStackPop = Symbol('stackPop')
  7. , symbolStackPopBottom = Symbol('stackPopBottom');
  10. /**
  11.  * @template T
  12.  * @author Sebastian Hönel <development@hoenel.net>
  13.  */
  14. class Stack extends Collection {
  15. 	/**
  16. 	 * Creates a new, empty Stack<T>.
  17. 	 * 
  18. 	 * @param {EqualityComparer<T>} [eqComparer] Optional. Defaults To EqualityComparer<T>.default.
  19. 	 */
  20. 	constructor(eqComparer = EqualityComparer.default) {
  21. 		super(eqComparer);
  22. 		
  23. 		/** @type {Observable<T>} */
  24. 		this.observablePush = Object.freeze(fromEvent(this, symbolStackPush));
  25. 		/** @type {Observable<T>} */
  26. 		this.observablePop = Object.freeze(fromEvent(this, symbolStackPop));
  27. 		/** @type {Observable<T>} */
  28. 		this.observablePopBottom = Object.freeze(fromEvent(this, symbolStackPopBottom));
  29. 	};
  31. 	/**
  32. 	 * Push an item to the top of the Stack.
  33. 	 * 
  34. 	 * @param {T} item 
  35. 	 * @returns {this}
  36. 	 */
  37. 	push(item) {
  38. 		this._items.push(item);
  39. 		this.emit(symbolStackPush, new CollectionEvent(item));
  40. 		return this;
  41. 	};
  43. 	/**
  44. 	 * @throws {Error} If the Stack is empty.
  45. 	 * @returns {T} The item at the top of the Stack (the item
  46. 	 * inserted last).
  47. 	 */
  48. 	pop() {
  49. 		if (this.isEmpty) {
  50. 			throw new Error('The Stack is empty.');
  51. 		}
  52. 		
  53. 		const item = this._items.pop();
  54. 		this.emit(symbolStackPop, new CollectionEvent(item));
  55. 		return item;
  56. 	};
  58. 	/**
  59. 	 * @throws {Error} If the Stack is empty.
  60. 	 * @returns {T} The item at the bottom of the Stack (the item
  61. 	 * inserted first).
  62. 	 */
  63. 	popBottom() {
  64. 		if (this.isEmpty) {
  65. 			throw new Error('The Stack is empty.');
  66. 		}
  68. 		const item = this._items.shift();
  69. 		this.emit(symbolStackPopBottom, new CollectionEvent(item));
  70. 		return item;
  71. 	};
  73. 	/**
  74. 	 * @throws {Error} If the Stack is empty.
  75. 	 * @returns {T} The item on top of the Stack without popping it.
  76. 	 */
  77. 	peek() {
  78. 		if (this.isEmpty) {
  79. 			throw new Error('The Stack is empty.');
  80. 		}
  82. 		return this._items[this.size - 1];
  83. 	};
  85. 	/**
  86. 	 * @throws {Error} If the Stack is empty.
  87. 	 * @returns {T} The item at the bottom of the Stack without popping it.
  88. 	 */
  89. 	peekBottom() {
  90. 		if (this.isEmpty) {
  91. 			throw new Error('The Stack is empty.');
  92. 		}
  94. 		return this._items[0];
  95. 	};
  96. };
  99. class ConstrainedStack extends Stack {
  100. 	/**
  101. 	 * Creates a new, empty Stack<T>.
  102. 	 * 
  103. 	 * @param {Number} [maxSize] Optional. Defaults to Number.MAX_SAFE_INTEGER. Use
  104. 	 * this parameter to limit the maximum amount of elements this Stack can hold.
  105. 	 * When the limit is reached and items are being further pushed, the
  106. 	 * ConstrainedStack will pop items from the BOTTOM. I.e., when pushing a new item
  107. 	 * to the top of the Stack when it is full, will discard one item at its bottom.
  108. 	 * This parameter must be a positive integer larger than zero.
  109. 	 * @param {EqualityComparer<T>} [eqComparer] Optional. Defaults To
  110. 	 * EqualityComparer<T>.default.
  111. 	 */
  112. 	constructor(maxSize = Number.MAX_SAFE_INTEGER, eqComparer = EqualityComparer.default) {
  113. 		super(eqComparer);
  114. 		
  115. 		this._maxSize = 1;
  116. 		this.maxSize = maxSize;
  117. 	};
  118. 	
  120. 	/**
  121. 	 * @type {Number}
  122. 	 */
  123. 	get maxSize() {
  124. 		return this._maxSize;
  125. 	};
  127. 	/**
  128. 	 * Sets the maximum size of this ConstrainedStack. If currently there are more
  129. 	 * items, the stack will pop items from the bottom until the number of items
  130. 	 * does not longer exceed the new maximum size. The items will be popped from
  131. 	 * the BOTTOM.
  132. 	 * 
  133. 	 * @param {Number} value The new value for maxSize. Must be an integer equal
  134. 	 * to or larger than 1.
  135. 	 * @throws {Error} If parameter value is not a number or less than one (1).
  136. 	 * @type {void}
  137. 	 */
  138. 	set maxSize(value) {
  139. 		if (!Resolve.isTypeOf(value, Number) || !Number.isInteger(value)) {
  140. 			throw new Error(`The value given for maxSize is not a number.`);
  141. 		}
  142. 		
  143. 		if (value < 1) {
  144. 			throw new Error(`The value given is less than 1: ${value}`);
  145. 		}
  147. 		this._maxSize = value;
  148. 		this._truncate();
  149. 	};
  151. 	/**
  152. 	 * @returns {this}
  153. 	 */
  154. 	_truncate() {
  155. 		let excess = this.size - this.maxSize;
  156. 		while (excess > 0) {
  157. 			// Triggers/emits symbol for poppong items from bottom.
  158. 			this.popBottom();
  159. 			excess--;
  160. 		}
  161. 		
  162. 		return this;
  163. 	};
  165. 	/**
  166. 	 * Push an item to the top of the Stack. If, after pushing this item,
  167. 	 * the Stack is larger than its specified maximum size, it will discard
  168. 	 * an item from the BOTTOM.
  169. 	 * 
  170. 	 * @override
  171. 	 * @inheritdoc
  172. 	 * @param {T} item 
  173. 	 * @returns {this}
  174. 	 */
  175. 	push(item) {
  176. 		super.push(item);
  177. 		return this._truncate();
  178. 	};
  179. };
  182. module.exports = Object.freeze({
  183. 	Stack,
  184. 	ConstrainedStack,
  185. 	symbolStackPop,
  186. 	symbolStackPush,
  187. 	symbolStackPopBottom
  188. });