@gkucmierz/utils 1.28.3 → 1.28.8

package/README.md

@@ -1,11 +1,62 @@
+# @gkucmierz/utils
 
-### Install
+![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)
+
+A collection of useful utility functions and data structures for solving algorithmic tasks, competitive programming, and everyday development.
+
+## 📦 Installation
 
 ```bash
-npm i @gkucmierz/utils
+npm install @gkucmierz/utils
 ```
 
-### Docs
+## 🚀 Features
+
+This library provides a wide range of mathematical functions and data structures, including:
+
+- **Data Structures**:
+  - `SetCnt`: A set-like structure with element counting.
+  - `Trie`: Efficient prefix tree implementation.
+  - `Heap`: Min-heap priority queue.
+  - `ListNode`: Linked list node implementation.
+  - `matrixAsArray`: 2D matrix representation as a flat array.
+
+- **Number Theory**:
+  - `gcd`, `lcm`: Greatest Common Divisor and Least Common Multiple (supports BigInt).
+  - `factors`: Prime factorization.
+  - `phi`: Euler's totient function.
+  - `mod`, `powMod`: Modular arithmetic with Python-like behavior for negative numbers.
+  - `egcd`: Extended Euclidean Algorithm.
+  - `tonelliShanksBI`: Modular square root algorithm.
+
+- **Sequences & Formulas**:
+  - `gpn`: Generalized Pentagonal Numbers.
+  - `heronsFormula`: Triangle area calculation.
+  - `squareRoot`: Integer square root using Newton's method.
+
+- **String & Encoding**:
+  - `base64`: Base64 and Base64Url encoding/decoding.
+  - `copyCase`: Match case of a string to another.
+  - `bijectiveNumeration`: Bijective base-k numeration system.
+
+- **Utilities**:
+  - `memoize`: Function memoization based on arguments.
+  - `binarySearch`: Various binary search implementations (exact, lower bound, upper bound).
+  - `range2array`, `array2range`: Convert between ranges and arrays.
+  - `getType`: Precise type checking.
+
+## 📚 Documentation
+
+Full documentation with examples is available at:
+👉 **[https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)**
+
+## 🔗 Links
+
+- **NPM Package**: [https://www.npmjs.com/package/@gkucmierz/utils](https://www.npmjs.com/package/@gkucmierz/utils)
+- **GitHub Repository**: [https://github.com/gkucmierz/utils](https://github.com/gkucmierz/utils)
 
-[https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)
+## 📄 License
 
+MIT

package/package.json

@@ -1,7 +1,36 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "1.28.3",
+  "version": "1.28.8",
   "description": "Usefull functions for solving programming tasks",
+  "keywords": [
+    "utils",
+    "algorithms",
+    "math",
+    "number-theory",
+    "gcd",
+    "lcm",
+    "factors",
+    "phi",
+    "mod",
+    "pow-mod",
+    "binary-search",
+    "heap",
+    "trie",
+    "base64",
+    "bijective",
+    "tonelli-shanks",
+    "square-root",
+    "memoize",
+    "range-array",
+    "javascript",
+    "node",
+    "competitive-programming",
+    "data-structures"
+  ],
+  "files": [
+    "main.mjs",
+    "src/"
+  ],
   "main": "main.mjs",
   "scripts": {
     "test": "jasmine",
@@ -22,6 +51,6 @@
     "husky": "^8.0.1",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
-    "nodemon": "^2.0.20"
+    "nodemon": "^3.1.14"
   }
 }

package/src/SetCnt.mjs

@@ -1,28 +1,47 @@
-// set-like data structure built using map
-// with elements counter.
-// .delete - removes one element
-// .deleteAll - removes all occurrences
-// .cnt - get element occurrences
-
+/**
+ * Set-like data structure built using Map with elements counter.
+ * Allows adding multiple occurrences of the same element.
+ */
 export class SetCnt {
   #map = new Map();
   
+  /**
+   * Creates a new SetCnt instance.
+   * @param {Iterable} [iter] - An iterable object to initialize the set with.
+   */
   constructor(iter) {
     for (const el of iter ?? []) {
       this.add(el);
     }
   }
 
+  /**
+   * Adds an element to the set.
+   * Increments the counter for the element.
+   * @param {*} el - The element to add.
+   * @returns {SetCnt} The SetCnt instance.
+   */
   add(el) {
     const cnt = this.cnt(el);
     this.#map.set(el, cnt + 1);
     return this;
   }
 
+  /**
+   * Checks if an element exists in the set.
+   * @param {*} el - The element to check.
+   * @returns {boolean} True if the element exists, false otherwise.
+   */
   has(el) {
     return this.#map.has(el);
   }
 
+  /**
+   * Removes one occurrence of an element from the set.
+   * If the count reaches 0, the element is removed completely.
+   * @param {*} el - The element to remove.
+   * @returns {boolean} True if the element was removed (or count decremented), false if it didn't exist.
+   */
   delete(el) {
     if (!this.#map.has(el)) return false;
     const cnt = this.cnt(el);
@@ -31,31 +50,58 @@ export class SetCnt {
     return true;
   }
   
+  /**
+   * Removes all occurrences of an element from the set.
+   * @param {*} el - The element to remove.
+   * @returns {boolean} True if the element was removed, false otherwise.
+   */
   deleteAll(el) {
     this.#map.delete(el);
     return true;
   }
 
+  /**
+   * Gets the number of occurrences of an element.
+   * @param {*} el - The element to check.
+   * @returns {number} The count of the element.
+   */
   cnt(el) {
     return this.#map.get(el) ?? 0;
   }
   
+  /**
+   * Returns an iterator over the elements in the set.
+   * Each element is yielded as many times as its count.
+   * @returns {Iterator} An iterator over the elements.
+   */
   *[Symbol.iterator]() {
     for (const el of this.#map) {
       yield el;
     }
   }
 
+  /**
+   * Returns the SetCnt instance itself (for compatibility with Map-like interfaces).
+   * @returns {SetCnt} The SetCnt instance.
+   */
   entries() {
     return this;
   }
 
+  /**
+   * Returns an iterator over the unique elements in the set.
+   * @returns {Iterator} An iterator over the unique elements.
+   */
   *values() {
     for (const [el, cnt] of this.#map) {
       yield el;
     }
   }
 
+  /**
+   * Returns an iterator over the counts of the elements.
+   * @returns {Iterator} An iterator over the counts.
+   */
   *keys() {
     for (const [el, cnt] of this.#map) {
       yield cnt;

package/src/Trie.mjs

@@ -1,10 +1,21 @@
 
-// stric = true - remove removes whole unused data structure
-// stric = false - quick remove (data structure can grow fast)
+/**
+ * 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.
+ */
 export const Trie = (words = [], strict = true) => {
   const HAS = 0;
   const MAP = 1;
   const data = [false, new Map()];
+  
+  /**
+   * 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;
     for (let i = 0; i < word.length; ++i) {
@@ -34,6 +45,12 @@ export const Trie = (words = [], strict = true) => {
   const findNode = word => {
     return 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);
     const rev = nodes.reverse();
@@ -58,7 +75,19 @@ export const Trie = (words = [], strict = true) => {
     }
     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];
+  
+  /**
+   * 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 => {
     const res = [];
     const loop = (node, str = '') => {
@@ -73,6 +102,10 @@ export const Trie = (words = [], strict = true) => {
   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,
   };
 };

package/src/base64.mjs

@@ -1,4 +1,10 @@
 
+/**
+ * Encodes a string to Base64.
+ * Handles Unicode characters correctly.
+ * @param {string} string - The string to encode.
+ * @returns {string} The Base64 encoded string.
+ */
 export const toBase64 = string => {
   const codeUnits = new Uint16Array(string.length);
   for (let i = 0; i < codeUnits.length; i++) {
@@ -7,6 +13,12 @@ export const toBase64 = string => {
   return btoa(String.fromCharCode(...new Uint8Array(codeUnits.buffer)));
 };
 
+/**
+ * Decodes a Base64 string.
+ * Handles Unicode characters correctly.
+ * @param {string} encoded - The Base64 encoded string.
+ * @returns {string} The decoded string.
+ */
 export const fromBase64 = encoded => {
   const binary = atob(encoded);
   const bytes = new Uint8Array(binary.length);
@@ -20,6 +32,12 @@ const toUrl = {
   '+': '-',
   '/': '_',
 };
+/**
+ * Encodes a string to Base64Url format.
+ * Replaces '+' with '-' and '/' with '_'.
+ * @param {string} string - The string to encode.
+ * @returns {string} The Base64Url encoded string.
+ */
 export const toBase64Url = string => {
   return toBase64(string).replace(/[\+\/]/g, c => toUrl[c]);
 };
@@ -28,6 +46,12 @@ const fromUrl = {
   '-': '+',
   '_': '/',
 };
+/**
+ * Decodes a Base64Url string.
+ * Replaces '-' with '+' and '_' with '/'.
+ * @param {string} encoded - The Base64Url encoded string.
+ * @returns {string} The decoded string.
+ */
 export const fromBase64Url = encoded => {
   return fromBase64(encoded.replace(/[\-\_]/g, c => fromUrl[c]));
 };

package/src/bijective-numeration.mjs

@@ -1,4 +1,10 @@
 
+/**
+ * Converts a number to a bijective base-k string.
+ * @param {number} num - The number to convert.
+ * @param {string} [alpha='12'] - The alphabet to use for the conversion.
+ * @returns {string} The bijective base-k string representation.
+ */
 export const num2bijective = (num, alpha = '12') => {
   const len = alpha.length;
   let c = 0;
@@ -17,6 +23,12 @@ export const num2bijective = (num, alpha = '12') => {
   return res.join('');
 };
 
+/**
+ * Converts a bijective base-k string to a number.
+ * @param {string} str - The bijective base-k string to convert.
+ * @param {string} [alpha='12'] - The alphabet used for the conversion.
+ * @returns {number} The numeric value of the string.
+ */
 export const bijective2num = (str, alpha = '12') => {
   const map = new Map([...alpha].map((c, i) => [c, i]));
   let res = 0;
@@ -26,6 +38,12 @@ export const bijective2num = (str, alpha = '12') => {
   }, 0);
 };
 
+/**
+ * Converts a BigInt to a bijective base-k string.
+ * @param {bigint} num - The BigInt to convert.
+ * @param {string} [alpha='12'] - The alphabet to use for the conversion.
+ * @returns {string} The bijective base-k string representation.
+ */
 export const num2bijectiveBI = (num, alpha = '12') => {
   const len = BigInt(alpha.length);
   let c = 0n;
@@ -44,6 +62,12 @@ export const num2bijectiveBI = (num, alpha = '12') => {
   return res.join('');
 };
 
+/**
+ * Converts a bijective base-k string to a BigInt.
+ * @param {string} str - The bijective base-k string to convert.
+ * @param {string} [alpha='12'] - The alphabet used for the conversion.
+ * @returns {bigint} The BigInt value of the string.
+ */
 export const bijective2numBI = (str, alpha = '12') => {
   const map = new Map([...alpha].map((c, i) => [c, BigInt(i)]));
   let res = 0n;

package/src/binary-search.mjs

@@ -1,6 +1,10 @@
 
-// binary search array exact element
-// in sorted array
+/**
+ * Performs a binary search for an exact element in a sorted array.
+ * @param {Array<number>} arr - The sorted array to search in.
+ * @param {number} target - The element to search for.
+ * @returns {number} The index of the element if found, otherwise -1.
+ */
 export const binarySearchArr = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
@@ -20,7 +24,12 @@ export const binarySearchArr = (arr, target) => {
   return -1;
 };
 
-// binary search array less or equal element
+/**
+ * Performs a binary search for the largest element less than or equal to the target.
+ * @param {Array<number>} arr - The sorted array to search in.
+ * @param {number} target - The target value.
+ * @returns {number} The index of the found element.
+ */
 export const binarySearchLE = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
@@ -38,7 +47,12 @@ export const binarySearchLE = (arr, target) => {
   return -1;
 };
 
-// binary search array greater or equal element
+/**
+ * Performs a binary search for the smallest element greater than or equal to the target.
+ * @param {Array<number>} arr - The sorted array to search in.
+ * @param {number} target - The target value.
+ * @returns {number} The index of the found element.
+ */
 export const binarySearchGE = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
@@ -56,7 +70,13 @@ export const binarySearchGE = (arr, target) => {
   return 0;
 };
 
-// binary search for range of elements in array inclusive
+/**
+ * Performs a binary search for a range of elements inclusive of the target.
+ * Uses binarySearchGE and binarySearchLE.
+ * @param {Array<number>} arr - The sorted array to search in.
+ * @param {number} target - The target value.
+ * @returns {Array<number>} An array containing the start and end indices of the range [start, end].
+ */
 export const binarySearchRangeIncl = (arr, target) => {
   return [
     binarySearchGE(arr, target),

package/src/copy-case.mjs

@@ -1,10 +1,10 @@
 
 /**
- * Copy the case of a string into another.
- * @method
- * @param {string} target String to change the case.
- * @param {string} source Source of case pattern.
- * @return {string} Converted string.
+ * Copies the case pattern from one string to another.
+ * Handles lower case, upper case, and capitalized strings.
+ * @param {string} word - The string to change the case of.
+ * @param {string} from - The source string providing the case pattern.
+ * @returns {string} The converted string.
  */
 export const copyCase = (word, from) => {
   const isLower = w => w.toLowerCase() === w;

package/src/egcd.mjs

@@ -1,4 +1,12 @@
 
+/**
+ * Extended Euclidean Algorithm.
+ * Computes the greatest common divisor (GCD) of a and b,
+ * and the coefficients of Bézout's identity.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number[]} An array [gcd, x, y] such that ax + by = gcd.
+ */
 export const egcd = (a, b) => {
   let [x, y] = [0, 1];
   let [u, v] = [1, 0];

package/src/factors.mjs

@@ -1,9 +1,8 @@
 
 /**
- * Prime factorization
- * @function
- * @param {Number} number
- * @return {Number} result
+ * Calculates the prime factorization of a number.
+ * @param {number} n - The number to factorize.
+ * @returns {number[]} An array of prime factors.
  */
 export const factors = n => {
   if (n < 2) return [];
@@ -22,10 +21,9 @@ export const factors = n => {
 };
 
 /**
- * Prime factorization (BigInt version)
- * @function
- * @param {BigInt} number
- * @return {BigInt} result
+ * Calculates the prime factorization of a BigInt.
+ * @param {bigint} n - The BigInt to factorize.
+ * @returns {bigint[]} An array of prime factors as BigInts.
  */
 export const factorsBI = n => {
   if (n < 2n) return [];

package/src/gcd.mjs

@@ -16,17 +16,17 @@ const getGCD = ZERO => {
 };
 
 /**
- * Calculate GCD - Greatest Common Divisor
- * @method
- * @param {Number} Natural number
- * @return {Number} GCD
+ * Calculates the Greatest Common Divisor (GCD) of two numbers.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} The GCD of a and b.
  */
 export const gcd = getGCD(0);
 
 /**
- * Calculate GCD - Greatest Common Divisor (BigInt version)
- * @method
- * @param {BigInt} Natural BigInt number
- * @return {BigInt} GCD
+ * Calculates the Greatest Common Divisor (GCD) of two BigInts.
+ * @param {bigint} a - The first BigInt.
+ * @param {bigint} b - The second BigInt.
+ * @returns {bigint} The GCD of a and b.
  */
 export const gcdBI = getGCD(0n);

package/src/get-type.mjs

@@ -1,6 +1,10 @@
 
-// better js typeof
-
+/**
+ * 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.
+ */
 export const getType = val => {
   const str = Object.prototype.toString.call(val);
   return str.slice(8, -1).toLowerCase();

package/src/gpn.mjs

@@ -10,5 +10,19 @@ const getGpn = (zero, one, two, three) => {
   };
 };
 
+/**
+ * Generalized Pentagonal Numbers (GPN).
+ * Formula: P_k = k(3k - 1) / 2
+ * The sequence includes k = 0, 1, -1, 2, -2, 3, -3...
+ * https://oeis.org/A001318
+ * @param {number} n - The index of the sequence (0-based).
+ * @returns {number} The n-th generalized pentagonal number.
+ */
 export const gpn = getGpn(0, 1, 2, 3);
+
+/**
+ * Generalized Pentagonal Numbers (GPN) - BigInt version.
+ * @param {bigint} n - The index of the sequence (0-based).
+ * @returns {bigint} The n-th generalized pentagonal number.
+ */
 export const gpnBI = getGpn(0n, 1n, 2n, 3n);

package/src/heap.mjs

@@ -1,4 +1,10 @@
 
+/**
+ * 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.
+ */
 export const Heap = (valFn = n => n) => {
   const arr = [-1];
 
@@ -14,7 +20,17 @@ export const Heap = (valFn = n => n) => {
   };
   
   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];
@@ -40,7 +56,17 @@ export const Heap = (valFn = n => n) => {
       }
       return res;
     },
+    
+    /**
+     * Returns the number of elements in the heap.
+     * @returns {number} The size of the heap.
+     */
     size: () => 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),
   };
 };

package/src/herons-formula.mjs

@@ -9,5 +9,22 @@ const getHeronsFormula = (four, sq) => (a, b, c) => {
   return sq((a + b + c) * (-a + b + c) * (a - b + c) * (a + b - c)) / four;
 };
 
+/**
+ * Calculates the area of a triangle given the lengths of its three sides.
+ * Uses Heron's formula.
+ * @param {number} a - Length of side a.
+ * @param {number} b - Length of side b.
+ * @param {number} c - Length of side c.
+ * @returns {number} The area of the triangle.
+ */
 export const heronsFormula = getHeronsFormula(4, n => n ** 0.5);
+
+/**
+ * Calculates the area of a triangle given the lengths of its three sides (BigInt version).
+ * Returns the integer part of the area (truncated).
+ * @param {bigint} a - Length of side a.
+ * @param {bigint} b - Length of side b.
+ * @param {bigint} c - Length of side c.
+ * @returns {bigint} The area of the triangle.
+ */
 export const heronsFormulaBI = getHeronsFormula(4n, squareRootBI);

package/src/lcm.mjs

@@ -10,5 +10,18 @@ const getLcm = gcd => {
   return (a, b) => a * b / gcd(a, b);
 }
 
+/**
+ * Calculates the Least Common Multiple (LCM) of two numbers.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} The LCM of a and b.
+ */
 export const lcm = getLcm(gcd);
+
+/**
+ * Calculates the Least Common Multiple (LCM) of two BigInts.
+ * @param {bigint} a - The first BigInt.
+ * @param {bigint} b - The second BigInt.
+ * @returns {bigint} The LCM of a and b.
+ */
 export const lcmBI = getLcm(gcdBI);