@gkucmierz/utils 1.32.1 → 2.0.0

package/main.mjs

@@ -5,6 +5,9 @@ import {
 import {
   Trie
 } from './src/Trie.mjs'
+import {
+  arrayHistogram
+} from './src/array-histogram.mjs'
 import {
   fromBase64, fromBase64Url, toBase64, toBase64Url
 } from './src/base64.mjs'
@@ -14,6 +17,9 @@ import {
 import {
   binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl
 } from './src/binary-search.mjs'
+import {
+  combinations, combinationsIterator
+} from './src/combinations.mjs'
 import {
   consumeIteratorNonBlocking
 } from './src/consume-iterator.mjs'
@@ -38,6 +44,9 @@ import {
 import {
   gpn, gpnBI
 } from './src/gpn.mjs'
+import {
+  bin2gray, gray2bin
+} from './src/gray-code.mjs'
 import {
   Heap
 } from './src/heap.mjs'
@@ -62,6 +71,9 @@ import {
 import {
   mod, modBI
 } from './src/mod.mjs'
+import {
+  nChooseK
+} from './src/n-choose-k.mjs'
 import {
   naturalSearch
 } from './src/natural-search.mjs'
@@ -71,6 +83,9 @@ import {
 import {
   particleSwarmOptimization
 } from './src/particle-swarm.mjs'
+import {
+  permutations, permutationsIterator
+} from './src/permutations.mjs'
 import {
   phi, phiBI
 } from './src/phi.mjs'
@@ -92,9 +107,11 @@ import {
 
 export * from './src/SetCnt.mjs';
 export * from './src/Trie.mjs';
+export * from './src/array-histogram.mjs';
 export * from './src/base64.mjs';
 export * from './src/bijective-numeration.mjs';
 export * from './src/binary-search.mjs';
+export * from './src/combinations.mjs';
 export * from './src/consume-iterator.mjs';
 export * from './src/copy-case.mjs';
 export * from './src/egcd.mjs';
@@ -103,6 +120,7 @@ export * from './src/format-big-number.mjs';
 export * from './src/gcd.mjs';
 export * from './src/get-type.mjs';
 export * from './src/gpn.mjs';
+export * from './src/gray-code.mjs';
 export * from './src/heap.mjs';
 export * from './src/herons-formula.mjs';
 export * from './src/lcm.mjs';
@@ -111,9 +129,11 @@ export * from './src/math3d.mjs';
 export * from './src/matrix.mjs';
 export * from './src/memoize.mjs';
 export * from './src/mod.mjs';
+export * from './src/n-choose-k.mjs';
 export * from './src/natural-search.mjs';
 export * from './src/nelder-mead.mjs';
 export * from './src/particle-swarm.mjs';
+export * from './src/permutations.mjs';
 export * from './src/phi.mjs';
 export * from './src/pow-mod.mjs';
 export * from './src/range-array.mjs';
@@ -122,5 +142,5 @@ export * from './src/square-root.mjs';
 export * from './src/tonelli-shanks.mjs';
 
 export default [
-  SetCnt, Trie, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, copyCase, egcd, factors, factorsBI, formatBigNumber, formatBigNumberBI, wrapFn, gcd, gcdBI, getType, gpn, gpnBI, Heap, heronsFormula, heronsFormulaBI, lcm, lcmBI, ListNode, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, memoize, mod, modBI, naturalSearch, nelderMead, particleSwarmOptimization, phi, phiBI, powMod, powModBI, array2range, range2array, simulatedAnnealing, squareRoot, squareRootBI, tonelliShanksBI
+  SetCnt, Trie, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, combinations, combinationsIterator, consumeIteratorNonBlocking, copyCase, egcd, factors, factorsBI, formatBigNumber, formatBigNumberBI, wrapFn, gcd, gcdBI, getType, gpn, gpnBI, bin2gray, gray2bin, Heap, heronsFormula, heronsFormulaBI, lcm, lcmBI, ListNode, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, memoize, mod, modBI, nChooseK, naturalSearch, nelderMead, particleSwarmOptimization, permutations, permutationsIterator, phi, phiBI, powMod, powModBI, array2range, range2array, simulatedAnnealing, squareRoot, squareRootBI, tonelliShanksBI
 ];

package/package.json

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

package/src/Trie.mjs

@@ -1,111 +1,121 @@
-
 /**
  * Creates a Trie (prefix tree) data structure.
- * @param {string[]} [words=[]] - Initial words to add to the Trie.
- * @param {boolean} [strict=true] - If true, removing a word cleans up unused nodes.
- *                                  If false, removal is faster but may leave unused nodes.
- * @returns {object} The Trie instance with methods.
+ * Implemented as a proper ES6 Class to fix prototyping documentation and encapsulate nodes.
  */
-export const Trie = (words = [], strict = true) => {
-  const HAS = 0;
-  const MAP = 1;
-  const data = [false, new Map()];
+export class Trie {
+  static #HAS = 0;
+  static #MAP = 1;
+
+  #data = [false, new Map()];
+  #strict;
+
+  /**
+   * Initializes the Trie class object.
+   * @param {string[]} [words=[]] - Initial words to add to the Trie.
+   * @param {boolean} [strict=true] - If true, removing a word cleans up unused nodes.
+   *                                  If false, removal is faster but may leave unused nodes.
+   */
+  constructor(words = [], strict = true) {
+    this.#strict = strict;
+    words.forEach(word => this.add(word));
+  }
   
   /**
    * Adds a word to the Trie.
    * @param {string} word - The word to add.
    * @returns {boolean} True if the word was added (didn't exist before), false otherwise.
    */
-  const add = word => {
-    let node = data;
+  add(word) {
+    let node = this.#data;
     for (let i = 0; i < word.length; ++i) {
       const char = word[i];
-      if (!node[MAP]) node[MAP] = new Map();
-      const child = node[MAP].get(char) ?? [false];
-      node[MAP].set(char, child);
+      if (!node[Trie.#MAP]) node[Trie.#MAP] = new Map();
+      const child = node[Trie.#MAP].get(char) ?? [false];
+      node[Trie.#MAP].set(char, child);
       node = child;
     }
-    if (node[HAS]) return false;
-    node[HAS] = true;
+    if (node[Trie.#HAS]) return false;
+    node[Trie.#HAS] = true;
     return true;
-  };
-  const listNodes = word => {
-    const nodes = [data];
+  }
+
+  #listNodes(word) {
+    const nodes = [this.#data];
     for (let i = 0; i < word.length; ++i) {
       const node = nodes.at(-1);
       const char = word[i];
-      if (!node[MAP]?.has(char)) {
+      if (!node[Trie.#MAP]?.has(char)) {
         nodes.push([false]);
         break;
       }
-      nodes.push(node[MAP].get(char));
+      nodes.push(node[Trie.#MAP].get(char));
     }
     return nodes;
-  };
-  const findNode = word => {
-    return listNodes(word).at(-1);
-  };
+  }
+
+  #findNode(word) {
+    return this.#listNodes(word).at(-1);
+  }
   
   /**
    * Removes a word from the Trie.
    * @param {string} word - The word to remove.
    * @returns {boolean} True if the word was removed, false if it didn't exist.
    */
-  const remove = word => {
-    const nodes = listNodes(word);
+  remove(word) {
+    const nodes = this.#listNodes(word);
     const rev = nodes.reverse();
-    const removed = rev.at(0)[HAS];
-    rev.at(0)[HAS] = false;
-    if (!strict) return removed;
+    const removed = rev.at(0)[Trie.#HAS];
+    rev.at(0)[Trie.#HAS] = false;
+    if (!this.#strict) return removed;
     for (let i = 0; i < rev.length; ++i) {
       const node = rev[i];
       const first = i === 0;
-      const noMap = !node[MAP];
-      const size1 = node[MAP]?.size <= 1;
       if (first) {
-        if (node[MAP]) break;
+        if (node[Trie.#MAP]) break;
       } else {
-        if (node[MAP]?.size <= 1) {
-          delete node[MAP];
+        if (node[Trie.#MAP]?.size <= 1) {
+          delete node[Trie.#MAP];
         } else {
           break;
         }
       }
-      if (node[HAS]) break;
+      if (node[Trie.#HAS]) break;
     }
     return removed;
-  };
+  }
   
   /**
    * Checks if a word exists in the Trie.
    * @param {string} word - The word to check.
    * @returns {boolean} True if the word exists, false otherwise.
    */
-  const has = word => findNode(word)[HAS];
+  has(word) {
+    return this.#findNode(word)[Trie.#HAS];
+  }
   
   /**
    * Returns all words in the Trie that start with the given prefix.
    * @param {string} begin - The prefix to search for.
    * @returns {string[]} An array of words starting with the prefix.
    */
-  const get = begin => {
+  get(begin) {
     const res = [];
     const loop = (node, str = '') => {
       if (!node) return;
-      if (node[HAS]) res.push(begin + str);
-      const map = node[MAP] || new Map();
-      [...map].map(([char, node]) => loop(node, str + char));
+      if (node[Trie.#HAS]) res.push(begin + str);
+      const map = node[Trie.#MAP] || new Map();
+      [...map].forEach(([char, n]) => loop(n, str + char));
     };
-    loop(findNode(begin));
+    loop(this.#findNode(begin));
     return res;
-  };
-  words.map(word => add(word));
-  return {
-    add, has, get, remove,
-    /**
-     * Returns the internal data structure of the Trie.
-     * @returns {Array} The root node of the Trie.
-     */
-    getData: () => data,
-  };
-};
+  }
+  
+  /**
+   * Returns the internal data structure of the Trie.
+   * @returns {Array} The root node of the Trie.
+   */
+  getData() {
+    return this.#data;
+  }
+}

package/src/array-histogram.mjs

@@ -0,0 +1,17 @@
+/**
+ * Generates a Map with unique elements and their occurring frequencies.
+ * Transforms an array into a Map of (key -> quantity) using an optional mapping callback.
+ * 
+ * @param {Array} arr Target array
+ * @param {function} pick Projection callback (defaults to identity function)
+ * @returns {Map} Histogram mapping
+ */
+export const arrayHistogram = (iter, pick = el => el) => {
+  const quant = new Map();
+  for (const obj of iter) {
+    const el = pick(obj);
+    const cnt = quant.get(el) ?? 0;
+    quant.set(el, cnt + 1);
+  }
+  return quant;
+};

package/src/combinations.mjs

@@ -0,0 +1,41 @@
+/**
+ * Generates all possible combinations of size n from a set of size k without repetition.
+ * Yields arrays of indices representing the current combination.
+ * 
+ * Optimized with lexicographic progression to skip invalid states, 
+ * running in O(1) amortized time per sequence instead of O(k^n).
+ *
+ * @param {number} n Size of the combination
+ * @param {number} k Size of the set to choose from (indices 0 to k-1)
+ * @yields {number[]} Array of indices
+ */
+export const combinationsIterator = function* (n, k) {
+  if (n > k || n < 0) return;
+  const arr = new Array(n).fill(0).map((_, i) => i);
+  yield arr.slice();
+  
+  while (true) {
+    let i = n - 1;
+    while (i >= 0 && arr[i] === k - n + i) {
+      i--;
+    }
+    if (i < 0) break;
+    arr[i]++;
+    for (let j = i + 1; j < n; j++) {
+      arr[j] = arr[j - 1] + 1;
+    }
+    yield arr.slice();
+  }
+};
+
+/**
+ * Returns all combinations synchronously.
+ * WARNING: Calling this with mathematically large sets will overflow local RAM.
+ * 
+ * @param {number} n Size of the combination
+ * @param {number} k Size of the set
+ * @returns {Array<number[]>} Array containing all combinations
+ */
+export const combinations = (n, k) => {
+  return [...combinationsIterator(n, k)];
+};

package/src/gray-code.mjs

@@ -0,0 +1,28 @@
+/**
+ * Internal logic for toggling bit state based on MSB progression.
+ */
+const convertBit = (p, v, i) => {
+  p[i] = i && p[i-1] ? 1 - v : v;
+  return p;
+};
+
+/**
+ * Transforms an array of binary bits into Gray Code.
+ * 
+ * @param {Array<number|boolean>} bits Binary representation (MSB at index 0)
+ * @returns {Array<number>} Array of Gray code bits
+ */
+export const bin2gray = (bits) => {
+  // Cloning array mathematically to prevent pure-function reference mutation
+  return [...bits].reduceRight(convertBit, [...bits]);
+};
+
+/**
+ * Decodes a Gray code array back into standard binary formatting.
+ * 
+ * @param {Array<number|boolean>} gray Gray Code representation
+ * @returns {Array<number>} Decoded original binary bits
+ */
+export const gray2bin = (gray) => {
+  return [...gray].reduce(convertBit, [...gray]);
+};

package/src/heap.mjs

@@ -1,72 +1,83 @@
-
 /**
  * Creates a Min Heap data structure.
- * @param {Function} [valFn] - A function to extract the comparison value from an element.
- *                             Defaults to identity (n => n).
- * @returns {object} The Heap instance with methods.
+ * Implemented as a ES6 Class to fix prototyping documentation 
+ * and properly encapsulate internal mechanics.
  */
-export const Heap = (valFn = n => n) => {
-  const arr = [-1];
+export class Heap {
+  #arr = [-1];
+  #valFn;
+
+  /**
+   * Initializes the Heap class object.
+   * @param {Function} [valFn] - A function to extract the comparison value from an element. Defaults to identity (n => n).
+   */
+  constructor(valFn = n => n) {
+    this.#valFn = valFn;
+  }
 
-  const up = idx => {
+  #up(idx) {
     while (idx > 1) {
       const ni = idx / 2 | 0;
-      if (valFn(arr[idx]) < valFn(arr[ni])) {
-        [arr[idx], arr[ni]] = [arr[ni], arr[idx]];
+      if (this.#valFn(this.#arr[idx]) < this.#valFn(this.#arr[ni])) {
+        [this.#arr[idx], this.#arr[ni]] = [this.#arr[ni], this.#arr[idx]];
       }
       idx = ni;
     }
     return idx;
-  };
-  
-  return {
-    /**
-     * Adds an element to the heap.
-     * @param {*} el - The element to add.
-     * @returns {number} The new index of the added element.
-     */
-    add: el => up(arr.push(el) - 1),
+  }
 
-    /**
-     * Removes and returns the minimum element (root) from the heap.
-     * @returns {*} The minimum element.
-     */
-    take: () => {
-      const len = arr.length;
-      if (len <= 1) return [][0];
-      let idx = 1;
-      const res = arr[idx];
-      while (idx < len) {
-        const ia = idx * 2;
-        const ib = idx * 2 + 1;
-        if (ia >= len) break;
-        if (ib >= len || valFn(arr[ia]) < valFn(arr[ib])) {
-          arr[idx] = arr[ia];
-          idx = ia;
-        } else {
-          arr[idx] = arr[ib];
-          idx = ib;
-        }
-      }
-      if (idx === arr.length - 1) {
-        arr.pop();
+  /**
+   * Adds an element to the heap.
+   * @param {*} el - The element to add.
+   * @returns {number} The new index of the added element.
+   */
+  add(el) {
+    return this.#up(this.#arr.push(el) - 1);
+  }
+
+  /**
+   * Removes and returns the minimum element (root) from the heap.
+   * @returns {*} The minimum element.
+   */
+  take() {
+    const len = this.#arr.length;
+    if (len <= 1) return [][0];
+    let idx = 1;
+    const res = this.#arr[idx];
+    while (idx < len) {
+      const ia = idx * 2;
+      const ib = idx * 2 + 1;
+      if (ia >= len) break;
+      if (ib >= len || this.#valFn(this.#arr[ia]) < this.#valFn(this.#arr[ib])) {
+        this.#arr[idx] = this.#arr[ia];
+        idx = ia;
       } else {
-        arr[idx] = arr.pop();
-        up(idx);
+        this.#arr[idx] = this.#arr[ib];
+        idx = ib;
       }
-      return res;
-    },
-    
-    /**
-     * Returns the number of elements in the heap.
-     * @returns {number} The size of the heap.
-     */
-    size: () => arr.length - 1,
+    }
+    if (idx === this.#arr.length - 1) {
+      this.#arr.pop();
+    } else {
+      this.#arr[idx] = this.#arr.pop();
+      this.#up(idx);
+    }
+    return res;
+  }
+
+  /**
+   * Returns the number of elements in the heap.
+   * @returns {number} The size of the heap.
+   */
+  size() {
+    return this.#arr.length - 1;
+  }
 
-    /**
-     * Returns the internal array representation of the heap (excluding the dummy first element).
-     * @returns {Array} The heap elements.
-     */
-    data: () => arr.slice(1),
-  };
-};
+  /**
+   * Returns the internal array representation of the heap (excluding the dummy first element).
+   * @returns {Array} The heap elements.
+   */
+  data() {
+    return this.#arr.slice(1);
+  }
+}

package/src/n-choose-k.mjs

@@ -0,0 +1,31 @@
+/**
+ * Newton's formula (Binomial Coefficient) n choose k.
+ * Evaluates the number of possible combinations.
+ * Built strictly on BigInt and optimized iterative fraction reduction 
+ * to prevent RAM and precision loss during massive factorial expansions.
+ * 
+ * @param {number|bigint|string} n Total elements
+ * @param {number|bigint|string} k Elements to pick
+ * @returns {bigint} Total possible subset combinations
+ */
+export const nChooseK = (n, k) => {
+  const bigN = BigInt(n);
+  const bigK = BigInt(k);
+  
+  if (bigK < 0n || bigK > bigN) return 0n;
+  if (bigK === 0n || bigK === bigN) return 1n;
+
+  // Optimization: dynamically reduce the factorial expansion
+  // equivalent to (n! / (k! * (n-k)!)), shrinking the multiplication loops.
+  const kMin = bigK > (bigN - bigK) ? (bigN - bigK) : bigK;
+
+  let numerator = 1n;
+  let denominator = 1n;
+
+  for (let i = 1n; i <= kMin; ++i) {
+    numerator *= (bigN - i + 1n);
+    denominator *= i;
+  }
+  
+  return numerator / denominator;
+};

package/src/permutations.mjs

@@ -0,0 +1,34 @@
+/**
+ * Creates a permutations generator from a specified size or an array of elements.
+ * 
+ * @param {number|Array} sizeOrArr Integer size or an array of items
+ * @yields {Array} Re-arranged array of items/indices
+ */
+export const permutationsIterator = function*(sizeOrArr) {
+  const arr = Array.isArray(sizeOrArr) ? [...sizeOrArr] : new Array(sizeOrArr).fill(0).map((_, i) => i);
+  const size = arr.length;
+
+  const gen = function*(res, used, shift) {
+    const len = size - used;
+    if (len === 0) {
+      yield res;
+      return;
+    }
+    for (let i = 0; i < len; ++i) {
+      yield* gen([...res, shift[i]], used + 1, [...shift.slice(0, i), ...shift.slice(i + 1)]);
+    }
+  };
+
+  yield* gen([], 0, arr);
+};
+
+/**
+ * Returns all permutations synchronously.
+ * WARNING: Generates size! (factorial) elements. Scales in O(N!). 
+ * 
+ * @param {number|Array} sizeOrArr 
+ * @returns {Array<Array>} Array of permutation sets
+ */
+export const permutations = (sizeOrArr) => {
+  return [...permutationsIterator(sizeOrArr)];
+};