@gkucmierz/utils 4.1.1 → 5.1.0

package/README.md

@@ -77,7 +77,7 @@ This library provides a wide range of mathematical functions and data structures
   - `binarySearch`: Various binary search implementations (exact, lower bound, upper bound).
   - `naturalSearch`: Natural sorting/search utility for human-readable string comparisons.
   - `range2array`, `array2range`: Convert between ranges and arrays.
-  - `getType`: Precise dynamic type checking.
+  - `Type`, `is`, `of`, `same`: High-performance runtime type detection, introspection, and safe comparison system (v5.0.0).
 
 ## 📚 Documentation
 

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
@@ -56,6 +59,9 @@ import {
 import {
   setSafeInterval
 } from './src/developer-utils/set-safe-interval.mjs'
+import {
+  Type, Types, is, of, same
+} from './src/developer-utils/type.mjs'
 import {
   barycentricCoordinates
 } from './src/geometry/barycentric.mjs'
@@ -142,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';
@@ -154,6 +161,7 @@ export * from './src/developer-utils/natural-search.mjs';
 export * from './src/developer-utils/rand-normal.mjs';
 export * from './src/developer-utils/range-array.mjs';
 export * from './src/developer-utils/set-safe-interval.mjs';
+export * from './src/developer-utils/type.mjs';
 export * from './src/geometry/barycentric.mjs';
 export * from './src/geometry/math3d.mjs';
 export * from './src/geometry/matrix.mjs';
@@ -182,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, 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": "4.1.1",
+  "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 {};

package/src/developer-utils/type.mjs

@@ -0,0 +1,111 @@
+/**
+ * @module developer-utils
+ */
+
+/**
+ * Robust, highly-optimized type detection, introspection, and comparison system.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICoE8IFMEF8EBmMUYCARAAIDmA1gK4DGYIWMAXgPR1wgA2AzmQDcwYBmwigA|▶ Try it live in Instacode}
+ */
+export class Type {
+  // 1. Bottom values & Primitives
+  static UNDEFINED = 'undefined';
+  static NULL = 'null';
+  static BOOLEAN = 'boolean';
+  static NUMBER = 'number';
+  static NAN = 'nan';
+  static BIGINT = 'bigint';
+  static STRING = 'string';
+  static SYMBOL = 'symbol';
+
+  // 2. Core Objects & Callables
+  static OBJECT = 'object';
+  static ARRAY = 'array';
+  static FUNCTION = 'function';
+
+  // 3. Standard Built-ins
+  static DATE = 'date';
+  static REGEXP = 'regexp';
+  static ERROR = 'error';
+  static PROMISE = 'promise';
+
+  // 4. Collections
+  static MAP = 'map';
+  static SET = 'set';
+  static WEAKMAP = 'weakmap';
+  static WEAKSET = 'weakset';
+  static WEAKREF = 'weakref';
+
+  /**
+   * Returns the canonical runtime type of any value as a lowercase string.
+   * Differentiates NaN ('nan') from valid numbers ('number'), distinguishes 'array', 'null', 'date', etc.
+   * @param {*} val - Value to check.
+   * @returns {string} The canonical type string.
+   */
+  static of(val) {
+    if (Number.isNaN(val)) return Type.NAN;
+    return Object.prototype.toString.call(val).slice(8, -1).toLowerCase();
+  }
+
+  /**
+   * Checks if a value matches an expected type (by string constant, Constructor, or union array).
+   * @param {*} val - Value to check.
+   * @param {string|Function|Array<string|Function>} expected - Expected type, constructor, or union array.
+   * @returns {boolean}
+   */
+  static is(val, expected) {
+    if (Array.isArray(expected)) {
+      return expected.some(exp => Type.is(val, exp));
+    }
+    if (typeof expected === 'function') {
+      if (expected === Number) return typeof val === 'number' && !Number.isNaN(val);
+      if (expected === Boolean) return typeof val === 'boolean' || val instanceof Boolean;
+      if (expected === String) return typeof val === 'string' || val instanceof String;
+      if (expected === BigInt) return typeof val === 'bigint' || (typeof Object(val) === 'object' && val instanceof BigInt);
+      if (expected === Symbol) return typeof val === 'symbol' || (typeof Object(val) === 'object' && val instanceof Symbol);
+      if (expected === Array) return Array.isArray(val);
+      if (expected === Function) return typeof val === 'function';
+      if (expected === Object) return val !== null && (typeof val === 'object' || typeof val === 'function');
+      return val instanceof expected;
+    }
+    return Type.of(val) === expected;
+  }
+
+  /**
+   * Compares whether two values have the exact same canonical type.
+   * Safely prevents JavaScript traps like typeof NaN === typeof 42 or typeof null === typeof {}.
+   * @param {*} a - First value.
+   * @param {*} b - Second value.
+   * @returns {boolean} True if both values share the same type.
+   */
+  static same(a, b) {
+    return Type.of(a) === Type.of(b);
+  }
+}
+
+/**
+ * Alias for the {@link Type} class.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICoE8IFMDOCC+CAZjFGAgEQACA5gNYCuAxmCFjAF4D0DcIANjgoBuYMAzYcooA|▶ Try it live in Instacode}
+ */
+export const Types = Type;
+
+/**
+ * Checks if a value matches an expected type.
+ * @see {@link Type.is}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JAZwQXwQMxlMBAIgAEBzAawFcBjMEAUxgC8B6KuEAGzSIG5goNAKA|▶ Try it live in Instacode}
+ */
+export const is = Type.is;
+
+/**
+ * Returns the canonical runtime type of any value.
+ * @see {@link Type.of}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4KgMwQXwWmUwIBEAAgOYDWArgMZggCmMAXgPSVwgA2AzoQNzBg6AUA|▶ Try it live in Instacode}
+ */
+export const of = Type.of;
+
+/**
+ * Compares whether two values have the exact same canonical type.
+ * @see {@link Type.same}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM4EMwFMEF8EBmMUYCARAAIDmA1gK4DGYIWMAXgPR1wgA2qZANzBgGbMKA|▶ Try it live in Instacode}
+ */
+export const same = Type.same;
+