@gkucmierz/utils 1.28.3 → 1.28.7

package/src/list-node.mjs

@@ -1,11 +1,25 @@
 
 
+/**
+ * Represents a node in a singly linked list.
+ */
 export class ListNode {
+  /**
+   * Creates a new ListNode.
+   * @param {*} [val=0] - The value of the node.
+   * @param {ListNode} [next=null] - The next node in the list.
+   */
   constructor(val = 0, next = null) {
     this.val = val;
     this.next = next;
   }
   
+  /**
+   * Converts the linked list to an array.
+   * Detects cycles and throws an error if one is found.
+   * @returns {Array} An array containing the values of the list nodes.
+   * @throws {Error} If a cyclic reference is detected.
+   */
   toArr() {
     const ret = [];
     let node = this;
@@ -19,6 +33,11 @@ export class ListNode {
     return ret;
   }
   
+  /**
+   * Creates a linked list from an iterable.
+   * @param {Iterable} iter - The iterable to create the list from.
+   * @returns {ListNode|null} The head of the created linked list, or null if empty.
+   */
   static fromArr(iter) {
     const head = new ListNode;
     let node = head;

package/src/matrix.mjs

@@ -1,8 +1,11 @@
 
 
-// represent matrix as array using Proxy
-// todo: iterator can be added
-
+/**
+ * Represents a 2D matrix as a flat 1D array using a Proxy.
+ * Allows accessing elements using a single index (row-major order).
+ * @param {Array<Array<*>>} matrix - The 2D matrix to wrap.
+ * @returns {Proxy} A proxy that behaves like a flat array.
+ */
 export const matrixAsArray = matrix => {
   const [h, w] = [matrix.length, matrix[0].length];
   return new Proxy([], {

package/src/memoize.mjs

@@ -1,10 +1,10 @@
 
 /**
- * Memoize function, that builds tree structure for arguments
- * and compares arguments by reference
- * @method
- * @param {Function} Function to memoize
- * @return {Function} Memoized function
+ * Creates a memoized version of a function.
+ * Uses a tree structure to store results based on arguments.
+ * Compares arguments by reference.
+ * @param {Function} fn - The function to memoize.
+ * @returns {Function} The memoized function.
  */
 export const memoize = fn => {
   const maps = [];

package/src/mod.mjs

@@ -10,23 +10,17 @@ const getMod = ZERO => {
 };
 
 /**
- * Python like modulo implementation.
- * It behaves different than JavaScript %
- * with negative values
- * @method
- * @param {Number} Dividend
- * @param {Number} Divisor
- * @return {Number} Modulus
+ * Calculates the modulo of two numbers (Python-like behavior for negative numbers).
+ * @param {number} dividend - The dividend.
+ * @param {number} divisor - The divisor.
+ * @returns {number} The result of the modulo operation.
  */
 export const mod = getMod(0);
 
 /**
- * Python like modulo implementation.
- * It behaves different than JavaScript %
- * with negative values
- * @method
- * @param {BigInt} Dividend
- * @param {BigInt} Divisor
- * @return {BigInt} Modulus
+ * Calculates the modulo of two BigInts (Python-like behavior for negative numbers).
+ * @param {bigint} dividend - The dividend.
+ * @param {bigint} divisor - The divisor.
+ * @returns {bigint} The result of the modulo operation.
  */
 export const modBI = getMod(0n);

package/src/phi.mjs

@@ -31,7 +31,20 @@ const getPhiEuler = factors => {
   };
 };
 
+/**
+ * Euler's Totient Function (Phi).
+ * Counts the positive integers less than or equal to n that are relatively prime to n.
+ * Uses Euler's product formula based on prime factorization.
+ * @param {number} n - The number to calculate phi for.
+ * @returns {number} The value of phi(n).
+ */
 export const phi = getPhiEuler(factors);
+
+/**
+ * Euler's Totient Function (Phi) - BigInt version.
+ * @param {bigint} n - The BigInt to calculate phi for.
+ * @returns {bigint} The value of phi(n).
+ */
 export const phiBI = getPhiEuler(factorsBI);
 
 // export const phi = getPhi(1, 2, gcd);

package/src/pow-mod.mjs

@@ -19,21 +19,21 @@ const getPowMod = (ZERO, ONE, TWO, floor) => {
 };
 
 /**
- * Power like python implementation with optional modulus
- * @method
- * @param {Number} Base
- * @param {Number} Exponent
- * @param [Number] Modulus
- * @return {Number} Power
+ * Calculates the power of a base to an exponent, optionally modulo a number.
+ * Similar to Python's pow(base, exponent, modulus).
+ * @param {number} base - The base number.
+ * @param {number} exponent - The exponent.
+ * @param {number} [modulus] - The optional modulus.
+ * @returns {number} The result of (base ** exponent) % modulus.
  */
 export const powMod = getPowMod(0, 1, 2, n => Math.floor(n));
 
 /**
- * Power like python implementation with optional modulus
- * @method
- * @param {BigInt} Base
- * @param {BigInt} Exponent
- * @param [BigInt] Modulus
- * @return {BigInt} Power
+ * Calculates the power of a base to an exponent, optionally modulo a BigInt.
+ * Similar to Python's pow(base, exponent, modulus).
+ * @param {bigint} base - The base BigInt.
+ * @param {bigint} exponent - The exponent BigInt.
+ * @param {bigint} [modulus] - The optional modulus BigInt.
+ * @returns {bigint} The result of (base ** exponent) % modulus.
  */
 export const powModBI = getPowMod(0n, 1n, 2n, n => n);

package/src/range-array.mjs

@@ -1,6 +1,11 @@
 
 // https://www.codewars.com/kata/57d83dfc950d842dcb00005b/train/javascript
 
+/**
+ * Converts a list of ranges into a flat array of numbers.
+ * @param {Array<Array<number>>} ranges - An array of ranges, where each range is [min, max] or [min].
+ * @returns {Array<number>} An array containing all numbers in the specified ranges.
+ */
 export const range2array = ranges => {
   return ranges.reduce((arr, range) => {
     const min = range[0];
@@ -11,6 +16,13 @@ export const range2array = ranges => {
   }, []);
 };
 
+/**
+ * Converts a sorted array of numbers into a list of ranges.
+ * Consecutive numbers are grouped into a single range [min, max].
+ * Isolated numbers are represented as [num, num].
+ * @param {Array<number>} arr - The sorted array of numbers.
+ * @returns {Array<Array<number>>} An array of ranges.
+ */
 export const array2range = arr => {
   const ranges = [];
   let last = arr[0];

package/src/square-root.mjs

@@ -1,18 +1,16 @@
 
 
 /**
- * Native square root
- * @function
- * @param {Number} number - js double number
- * @return {Number} result
+ * Calculates the square root of a number.
+ * @param {number} n - The number to calculate the square root of.
+ * @returns {number} The square root of n.
  */
 export const squareRoot = n => n ** 0.5;
 
 /**
- * Calculate square root using Newton's formula
- * @function
- * @param {BigInt} number - big integer number
- * @return {BigInt} result
+ * Calculates the integer square root of a BigInt using Newton's method.
+ * @param {bigint} n - The BigInt to calculate the square root of.
+ * @returns {bigint} The integer square root of n.
  */
 export const squareRootBI = n => {
   if (n === 0n) return 0n;

package/src/tonelli-shanks.mjs

@@ -3,8 +3,13 @@ import {
   powModBI,
 } from './pow-mod.mjs';
 
-/* Takes as input an odd prime p and n < p and returns r
- * such that r * r = n [mod p]. */
+/**
+ * Computes the modular square root of n modulo p using the Tonelli-Shanks algorithm.
+ * Solves the congruence r^2 = n (mod p) where p is an odd prime.
+ * @param {bigint} n - The number to find the square root of.
+ * @param {bigint} p - The modulus (must be an odd prime).
+ * @returns {bigint} The square root r such that r^2 = n (mod p), or 0n if no solution exists.
+ */
 export const tonelliShanksBI = (n, p) => {
   let s = 0n;
   let q = p - 1n;