@gkucmierz/utils 5.0.0 → 5.1.0

package/main.mjs

@@ -20,6 +20,9 @@ import {
 import {
   SetCnt
 } from './src/data-structures/SetCnt.mjs'
+import {
+  Stack
+} from './src/data-structures/Stack.mjs'
 import {
   Trie
 } from './src/data-structures/Trie.mjs'
@@ -36,7 +39,7 @@ import {
   consumeIteratorNonBlocking
 } from './src/developer-utils/consume-iterator.mjs'
 import {
-  getType
+  
 } from './src/developer-utils/get-type.mjs'
 import {
   measurePerformance
@@ -145,6 +148,7 @@ export * from './src/combinatorics/n-choose-k.mjs';
 export * from './src/combinatorics/permutations.mjs';
 export * from './src/data-structures/ConflatingQueue.mjs';
 export * from './src/data-structures/SetCnt.mjs';
+export * from './src/data-structures/Stack.mjs';
 export * from './src/data-structures/Trie.mjs';
 export * from './src/data-structures/heap.mjs';
 export * from './src/data-structures/list-node.mjs';
@@ -186,5 +190,5 @@ export * from './src/string-arrays/copy-case.mjs';
 export * from './src/string-arrays/format-big-number.mjs';
 
 export default [
-  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, getType, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, of, same, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
+  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, of, same, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [

package/src/data-structures/Stack.mjs

@@ -0,0 +1,100 @@
+/**
+ * @module data-structures
+ */
+
+/**
+ * High-performance, LIFO (Last-In-First-Out) Stack data structure.
+ * Encapsulates an internal private array (#items) to prevent index tampering
+ * and optimize V8 memory locality and fast push/pop operations.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMpwIYGMDWCC+CAZjFGAgEQACA5jgK5ZggCmMAXgPT1wgA2AZwoBuYMHTYcooA|▶ Try it live in Instacode}
+ */
+export class Stack {
+  #items = [];
+
+  /**
+   * Creates a new Stack instance.
+   * @param {Iterable} [iter] - An optional iterable object to initialize the stack with.
+   */
+  constructor(iter) {
+    for (const el of iter ?? []) {
+      this.push(el);
+    }
+  }
+
+  /**
+   * Pushes one or more items onto the top of the stack.
+   * @param {...*} items - Elements to push onto the stack.
+   * @returns {Stack} The Stack instance for fluent method chaining.
+   */
+  push(...items) {
+    this.#items.push(...items);
+    return this;
+  }
+
+  /**
+   * Removes and returns the item from the top of the stack.
+   * @returns {*|undefined} The top item, or undefined if the stack is empty.
+   */
+  pop() {
+    return this.#items.pop();
+  }
+
+  /**
+   * Returns the item from the top of the stack without removing it.
+   * @returns {*|undefined} The top item, or undefined if the stack is empty.
+   */
+  peek() {
+    return this.#items[this.#items.length - 1];
+  }
+
+  /**
+   * Checks whether the stack is empty.
+   * @returns {boolean} True if the stack contains no items, false otherwise.
+   */
+  isEmpty() {
+    return this.#items.length === 0;
+  }
+
+  /**
+   * Gets the number of items currently in the stack.
+   * @returns {number} The number of items in the stack.
+   */
+  get size() {
+    return this.#items.length;
+  }
+
+  /**
+   * Gets the number of items currently in the stack (Array length compatibility alias).
+   * @returns {number} The number of items in the stack.
+   */
+  get length() {
+    return this.#items.length;
+  }
+
+  /**
+   * Removes all items from the stack.
+   * @returns {Stack} The Stack instance for fluent method chaining.
+   */
+  clear() {
+    this.#items.length = 0;
+    return this;
+  }
+
+  /**
+   * Returns a shallow copy of the stack items as an Array from bottom to top.
+   * @returns {Array} Array of items from bottom to top.
+   */
+  toArray() {
+    return [...this.#items];
+  }
+
+  /**
+   * Iterates through stack items from top to bottom (LIFO order).
+   * @returns {Iterator}
+   */
+  *[Symbol.iterator]() {
+    for (let i = this.#items.length - 1; i >= 0; i--) {
+      yield this.#items[i];
+    }
+  }
+}

package/src/developer-utils/get-type.mjs

@@ -1,16 +1,2 @@
-/**
- * @module developer-utils
- */
-
-
-/**
- * Returns the type of the value as a lowercase string.
- * More specific than the typeof operator (e.g., distinguishes 'array', 'null', 'date').
- * @param {*} val - The value to check.
- * @returns {string} The type of the value.
- * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYFM4BUCeF0IC+CAZjFGAgEQACqA1gK4DGYI6MAXgPSNwgAbAM5UA3MGAZsedOKA|▶ Try it live in Instacode}
- */
-export const getType = val => {
-  const str = Object.prototype.toString.call(val);
-  return str.slice(8, -1).toLowerCase();
-};
+// Deprecated - removed in v5.0.0 in favor of ./type.mjs
+export {};