@gkucmierz/utils 5.0.0 → 5.4.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,8 +39,11 @@ import {
   consumeIteratorNonBlocking
 } from './src/developer-utils/consume-iterator.mjs'
 import {
-  getType
+  
 } from './src/developer-utils/get-type.mjs'
+import {
+  detectGridColumns, navigateGrid
+} from './src/developer-utils/grid-navigation.mjs'
 import {
   measurePerformance
 } from './src/developer-utils/measure-performance.mjs'
@@ -47,6 +53,9 @@ import {
 import {
   naturalSearch
 } from './src/developer-utils/natural-search.mjs'
+import {
+  QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual
+} from './src/developer-utils/quorum.mjs'
 import {
   randNormal
 } from './src/developer-utils/rand-normal.mjs'
@@ -57,17 +66,20 @@ import {
   setSafeInterval
 } from './src/developer-utils/set-safe-interval.mjs'
 import {
-  Type, Types, is, of, same
+  Type, Types, is, isCallable, of, same
 } from './src/developer-utils/type.mjs'
 import {
   barycentricCoordinates
 } from './src/geometry/barycentric.mjs'
 import {
-  axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball
+  applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp
 } from './src/geometry/math3d.mjs'
 import {
   matrixAsArray
 } from './src/geometry/matrix.mjs'
+import {
+  OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange
+} from './src/geometry/range-set.mjs'
 import {
   egcd
 } from './src/number-theory/egcd.mjs'
@@ -137,6 +149,12 @@ import {
 import {
   formatBigNumber, formatBigNumberBI, wrapFn
 } from './src/string-arrays/format-big-number.mjs'
+import {
+  parseHeading
+} from './src/string-arrays/parse-heading.mjs'
+import {
+  slugify
+} from './src/string-arrays/slugify.mjs'
 
 export * from './src/automata/langtons-ant.mjs';
 export * from './src/combinatorics/combinations.mjs';
@@ -145,15 +163,18 @@ 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';
 export * from './src/developer-utils/binary-search.mjs';
 export * from './src/developer-utils/consume-iterator.mjs';
 export * from './src/developer-utils/get-type.mjs';
+export * from './src/developer-utils/grid-navigation.mjs';
 export * from './src/developer-utils/measure-performance.mjs';
 export * from './src/developer-utils/memoize.mjs';
 export * from './src/developer-utils/natural-search.mjs';
+export * from './src/developer-utils/quorum.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';
@@ -161,6 +182,7 @@ 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';
+export * from './src/geometry/range-set.mjs';
 export * from './src/number-theory/egcd.mjs';
 export * from './src/number-theory/factors.mjs';
 export * from './src/number-theory/gcd.mjs';
@@ -184,7 +206,9 @@ export * from './src/string-arrays/bijective-numeration.mjs';
 export * from './src/string-arrays/chunks.mjs';
 export * from './src/string-arrays/copy-case.mjs';
 export * from './src/string-arrays/format-big-number.mjs';
+export * from './src/string-arrays/parse-heading.mjs';
+export * from './src/string-arrays/slugify.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, detectGridColumns, navigateGrid, measurePerformance, memoize, naturalSearch, QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, isCallable, of, same, barycentricCoordinates, applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp, matrixAsArray, OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange, 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, parseHeading, slugify
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "5.0.0",
+  "version": "5.4.0",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -74,7 +74,7 @@
     "docs:build": "jsdoc -c jsdoc.json && cp -r docs/@gkucmierz/utils/*/* docs/ && rm -rf docs/@gkucmierz",
     "docs:open": "open docs/index.html",
     "lint": "eslint .",
-    "prepare": "husky"
+    "prepare": "git config core.hooksPath .githooks || true"
   },
   "repository": {
     "type": "git",
@@ -88,7 +88,6 @@
     "docdash": "^2.0.2",
     "eslint": "^10.1.0",
     "globals": "^17.4.0",
-    "husky": "^8.0.3",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
     "lz-string": "^1.5.0",

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/grid-navigation.mjs

@@ -0,0 +1,175 @@
+/**
+ * @module developer-utils
+ */
+
+/**
+ * Resolves the next 0-based index when navigating a 2D grid (matrix) that may contain
+ * trailing gaps in its last row (`totalItems` not divisible by `columns`).
+ *
+ * Pure mathematical/index function — completely independent of the DOM.
+ *
+ * Wrapping configuration hierarchy:
+ * - `wrap` (boolean, default `true`): master default for both axes.
+ * - `wrapHoriz` / `wrapHorizontal` (boolean, optional): overrides `wrap` for horizontal movement (`left` / `right`).
+ * - `wrapVert` / `wrapVertical` (boolean, optional): overrides `wrap` for vertical movement (`up` / `down`).
+ * - `rowStrict` (boolean, default `false`): when `true`, horizontal movement wraps/clamps strictly within the current row instead of reading order.
+ *
+ * When `columns === 1` (single-column layout), `right` behaves identically to `down`
+ * and `left` behaves identically to `up`.
+ *
+ * @param {number} currentIndex - Current active 0-based index (`0 <= currentIndex < totalItems`).
+ * @param {number} totalItems - Total number of items in the grid ($N \ge 0$).
+ * @param {'left'|'right'|'up'|'down'|'ArrowLeft'|'ArrowRight'|'ArrowUp'|'ArrowDown'} direction - Movement direction.
+ * @param {number|Object} [columnsOrOptions=1] - Column count ($C \ge 1$) or options object.
+ * @param {Object} [maybeOptions={}] - Optional configuration when 4th argument is a column count.
+ * @returns {number} Next 0-based index, or `-1` if `totalItems <= 0`.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYEMBuIDm64CmA4jCACYIC+CAZjFGAgEQACOA1gK4DGYIBMAF4B6TnBAAbAM5MA3MGAZseQiXLygA|▶ Try it live in Instacode}
+ */
+export const navigateGrid = (
+  currentIndex,
+  totalItems,
+  direction,
+  columnsOrOptions = 1,
+  maybeOptions = {}
+) => {
+  if (!Number.isFinite(totalItems) || totalItems <= 0) {
+    return -1;
+  }
+
+  const isObj = columnsOrOptions !== null && typeof columnsOrOptions === 'object';
+  const opts = isObj ? columnsOrOptions : (maybeOptions || {});
+  const rawCols = isObj ? opts.columns : columnsOrOptions;
+  const cols = Math.max(1, Math.floor(Number(rawCols) || 1));
+
+  const cur =
+    Number.isFinite(currentIndex) && currentIndex >= 0 && currentIndex < totalItems
+      ? Math.floor(currentIndex)
+      : 0;
+
+  const baseWrap = typeof opts.wrap === 'boolean' ? opts.wrap : true;
+  const wrapHoriz =
+    typeof opts.wrapHorizontal === 'boolean'
+      ? opts.wrapHorizontal
+      : typeof opts.wrapHoriz === 'boolean'
+        ? opts.wrapHoriz
+        : baseWrap;
+  const wrapVert =
+    typeof opts.wrapVertical === 'boolean'
+      ? opts.wrapVertical
+      : typeof opts.wrapVert === 'boolean'
+        ? opts.wrapVert
+        : baseWrap;
+  const rowStrict = Boolean(opts.rowStrict);
+
+  const row = Math.floor(cur / cols);
+  const col = cur % cols;
+
+  let deltaH = 0;
+  let deltaV = 0;
+
+  switch (direction) {
+  case 'right':
+  case 'ArrowRight':
+    deltaH = 1;
+    break;
+  case 'left':
+  case 'ArrowLeft':
+    deltaH = -1;
+    break;
+  case 'down':
+  case 'ArrowDown':
+    deltaV = 1;
+    break;
+  case 'up':
+  case 'ArrowUp':
+    deltaV = -1;
+    break;
+  default:
+    return cur;
+  }
+
+  // Horizontal movement (left / right)
+  if (deltaH !== 0) {
+    if (rowStrict) {
+      const rowStart = row * cols;
+      const rowLen = Math.min(cols, totalItems - rowStart);
+      if (rowLen <= 0) return cur;
+      const nextCol = col + deltaH;
+      if (nextCol >= 0 && nextCol < rowLen) {
+        return rowStart + nextCol;
+      }
+      if (wrapHoriz) {
+        return rowStart + (((nextCol % rowLen) + rowLen) % rowLen);
+      }
+      return cur;
+    }
+
+    const nextIdx = cur + deltaH;
+    if (nextIdx >= 0 && nextIdx < totalItems) {
+      return nextIdx;
+    }
+    if (wrapHoriz) {
+      return ((nextIdx % totalItems) + totalItems) % totalItems;
+    }
+    return cur;
+  }
+
+  // Vertical movement (up / down) along column `col` (handling incomplete last row gaps)
+  const colRows = col < totalItems ? Math.floor((totalItems - 1 - col) / cols) + 1 : 0;
+  if (colRows <= 0) return cur;
+
+  const nextRow = row + deltaV;
+  if (nextRow >= 0 && nextRow < colRows) {
+    return nextRow * cols + col;
+  }
+  if (wrapVert) {
+    const wrappedRow = ((nextRow % colRows) + colRows) % colRows;
+    return wrappedRow * cols + col;
+  }
+  return cur;
+};
+
+/**
+ * Pure higher-order geometric utility that detects the number of columns in the first row
+ * of a 2D layout from an iterable of items and a row-offset projector function.
+ *
+ * Counts how many consecutive leading items share the same row coordinate (`y` / `top`)
+ * within the given `tolerance`. Completely independent of the DOM.
+ *
+ * @param {Iterable<*>} items - Iterable of numbers (row offsets) or arbitrary items.
+ * @param {Function|number} [getRowOffset=(x) => x] - Pure projector `(item, index) => number` (or numeric tolerance if 2nd arg is a number).
+ * @param {number} [tolerance=0] - Maximum allowed absolute difference between an item's row offset and the first item's offset.
+ * @returns {number} Detected number of columns in the first row ($\ge 1$).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICYFM7oMZwOIwioDCUANgK5gB2AzggL4IBmMUYCARAAIDmA1hWxgQ6GAC8A9BTggytTgG5gwDFlwEipSjVrKgA|▶ Try it live in Instacode}
+ */
+export const detectGridColumns = (items, getRowOffset = (x) => x, tolerance = 0) => {
+  if (!items || typeof items[Symbol.iterator] !== 'function') {
+    return 1;
+  }
+
+  const isFn = typeof getRowOffset === 'function';
+  const projector = isFn ? getRowOffset : (x) => x;
+  const tol = Math.max(0, Number(isFn ? tolerance : getRowOffset) || 0);
+
+  let firstOffset = null;
+  let firstRowCount = 0;
+  let idx = 0;
+
+  for (const item of items) {
+    const raw = projector(item, idx++);
+    const offset = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(offset)) {
+      continue;
+    }
+    if (firstOffset === null) {
+      firstOffset = offset;
+      firstRowCount = 1;
+    } else if (Math.abs(offset - firstOffset) <= tol) {
+      firstRowCount += 1;
+    } else {
+      break;
+    }
+  }
+
+  return Math.max(1, firstRowCount);
+};