@gkucmierz/utils 4.1.0 → 5.0.0

package/README.md

@@ -1,9 +1,11 @@
 # @gkucmierz/utils
 
-[![Socket Badge](https://socket.dev/api/badge/npm/package/@gkucmierz/utils)](https://socket.dev/npm/package/@gkucmierz/utils)
-![NPM Version](https://img.shields.io/npm/v/@gkucmierz/utils)
-![License](https://img.shields.io/npm/l/@gkucmierz/utils)
-![Downloads](https://img.shields.io/npm/dm/@gkucmierz/utils)
+[![NPM Version](https://img.shields.io/npm/v/@gkucmierz/utils?color=3b82f6&logo=npm)](https://www.npmjs.com/package/@gkucmierz/utils)
+[![Socket Security](https://img.shields.io/badge/Security-Socket.dev-7036fe?logo=socket&logoColor=white)](https://socket.dev/npm/package/@gkucmierz/utils)
+[![Tests](https://img.shields.io/badge/Tests-153%20passed-22c55e?logo=jasmine&logoColor=white)](https://gitea.7u.pl/gkucmierz/utils)
+[![Downloads](https://img.shields.io/npm/dm/@gkucmierz/utils?color=8b5cf6)](https://www.npmjs.com/package/@gkucmierz/utils)
+[![License](https://img.shields.io/npm/l/@gkucmierz/utils?color=f59e0b)](https://gitea.7u.pl/gkucmierz/utils)
+[![Node Version](https://img.shields.io/node/v/@gkucmierz/utils?color=43853d&logo=node.js&logoColor=white)](https://nodejs.org)
 
 A collection of useful utility functions and data structures for solving algorithmic tasks, competitive programming, and everyday development.
 
@@ -75,12 +77,12 @@ 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
 
-Full API documentation with examples is available at:
-👉 **[https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)**
+- **Production Docs**: 👉 **[https://docs-utils.7u.pl](https://docs-utils.7u.pl)**
+- **GitHub Pages Mirror**: [https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)
 
 ## 🔗 Repository
 - **Internal Gitea**: [https://gitea.7u.pl/gkucmierz/utils](https://gitea.7u.pl/gkucmierz/utils)

package/main.mjs

@@ -56,6 +56,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'
@@ -154,6 +157,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 +186,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, 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
 ];

package/package.json

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

package/src/data-structures/ConflatingQueue.mjs

@@ -39,10 +39,9 @@ export class ConflatingQueue {
    * Enqueues an asynchronous task associated with a specific key.
    * If a pending task with the same key already exists, it is superseded by the new task.
    *
-   * @template T
    * @param {string|number|symbol} key - Unique identifier for task coalescing.
-   * @param {() => Promise<T>|T} taskFn - The async/sync function to execute.
-   * @returns {Promise<T|{ superseded: boolean }>} Resolves with task result or `{ superseded: true }`.
+   * @param {Function} taskFn - The async or sync function to execute.
+   * @returns {Promise<*|{ superseded: boolean }>} Resolves with task result or `{ superseded: true }`.
    */
   enqueue(key, taskFn) {
     if (typeof taskFn !== 'function') {

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;
+