@gkucmierz/utils 2.1.0 → 2.3.1

package/README.md

@@ -13,10 +13,6 @@ A collection of useful utility functions and data structures for solving algorit
 npm install @gkucmierz/utils
 ```
 
-## 🚀 What's New in v2.0.0
-- **Combinatorics Arsenal**: High-performance, memory-safe O(1) generators powered by native `BigInt`.
-- **OOP Encapsulation**: `Heap` and `Trie` data structures were refactored into robust ES6 Classes (`new Heap()`, `new Trie()`).
-
 ## ✨ Features
 
 This library provides a wide range of mathematical functions and data structures, including:
@@ -47,6 +43,7 @@ This library provides a wide range of mathematical functions and data structures
   - `gpn`: Generalized Pentagonal Numbers.
   - `heronsFormula`: Triangle area calculation.
   - `squareRoot`: Integer square root using Newton's method.
+  - `goldenRatio`, `goldenRatioBI`: The Golden Ratio calculation (with arbitrary precision support).
 
 - **Automata & Simulation**:
   - `createLangtonsAnt`, `createUnlimitedGrid`: Infinite 2D grid and Langton's Ant cellular automaton engine (Project Euler 349 compatible).
@@ -58,6 +55,7 @@ This library provides a wide range of mathematical functions and data structures
   - `bijectiveNumeration`: Bijective base-k numeration system.
 
 - **Developer Utilities**:
+  - `measurePerformance`: A micro-benchmarking tool for high-iteration performance testing.
   - `setSafeInterval`: A safe, asynchronous alternative to `setInterval` that prevents overlapping executions and supports immediate yielding.
   - `consumeIteratorNonBlocking`: Yield consumption macro-tasks queue resolver for heavy computations.
   - `memoize`: Function memoization based on arguments.

package/main.mjs

@@ -41,6 +41,9 @@ import {
 import {
   getType
 } from './src/get-type.mjs'
+import {
+  goldenRatio, goldenRatioBI
+} from './src/golden-ratio.mjs'
 import {
   gpn, gpnBI
 } from './src/gpn.mjs'
@@ -71,6 +74,9 @@ import {
 import {
   matrixAsArray
 } from './src/matrix.mjs'
+import {
+  measurePerformance
+} from './src/measure-performance.mjs'
 import {
   memoize
 } from './src/memoize.mjs'
@@ -131,6 +137,7 @@ export * from './src/factors.mjs';
 export * from './src/format-big-number.mjs';
 export * from './src/gcd.mjs';
 export * from './src/get-type.mjs';
+export * from './src/golden-ratio.mjs';
 export * from './src/gpn.mjs';
 export * from './src/gray-code.mjs';
 export * from './src/heap.mjs';
@@ -141,6 +148,7 @@ export * from './src/list-node.mjs';
 export * from './src/lucas-lehmer.mjs';
 export * from './src/math3d.mjs';
 export * from './src/matrix.mjs';
+export * from './src/measure-performance.mjs';
 export * from './src/memoize.mjs';
 export * from './src/mod.mjs';
 export * from './src/n-choose-k.mjs';
@@ -158,5 +166,5 @@ export * from './src/square-root.mjs';
 export * from './src/tonelli-shanks.mjs';
 
 export default [
-  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, createLangtonsAnt, createUnlimitedGrid, lcm, lcmBI, ListNode, lucasLehmerBI, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, memoize, mod, modBI, nChooseK, naturalSearch, nelderMead, particleSwarmOptimization, permutations, permutationsIterator, phi, phiBI, powMod, powModBI, randNormal, array2range, range2array, setSafeInterval, 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, goldenRatio, goldenRatioBI, gpn, gpnBI, bin2gray, gray2bin, Heap, heronsFormula, heronsFormulaBI, createLangtonsAnt, createUnlimitedGrid, lcm, lcmBI, ListNode, lucasLehmerBI, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, measurePerformance, memoize, mod, modBI, nChooseK, naturalSearch, nelderMead, particleSwarmOptimization, permutations, permutationsIterator, phi, phiBI, powMod, powModBI, randNormal, array2range, range2array, setSafeInterval, simulatedAnnealing, squareRoot, squareRootBI, tonelliShanksBI
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "2.1.0",
+  "version": "2.3.1",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -9,11 +9,13 @@
     "base64",
     "bijective",
     "binary-search",
+    "benchmark",
     "combinations",
     "competitive-programming",
     "data-structures",
     "factors",
     "gcd",
+    "golden-ratio",
     "gray-code",
     "heap",
     "iterator",

package/src/golden-ratio.mjs

@@ -0,0 +1,38 @@
+import { squareRootBI } from './square-root.mjs';
+
+/**
+ * The standard float approximation of the Golden Ratio (phi).
+ * @constant {number}
+ */
+export const goldenRatio = ((5 ** 0.5) + 1) / 2;
+
+/**
+ * Calculates the Golden Ratio (phi) to an arbitrary precision using BigInt.
+ * Returns a boxed BigInt object with an overridden toString() method to 
+ * automatically format the output with the correct decimal point placement.
+ * 
+ * @param {number|bigint} precision - The number of decimal places to calculate.
+ * @returns {BigInt} A boxed BigInt representing the Golden Ratio scaled by 10^precision.
+ * @throws {Error} If precision is negative.
+ */
+export const goldenRatioBI = precision => {
+  if (precision < 0) throw new Error('Precision cannot be negative');
+  const p = BigInt(precision);
+  const exp = 10n ** p;
+  
+  // (sqrt(5 * exp^2) + exp) / 2
+  const result = (squareRootBI(5n * exp * exp) + exp) / 2n;
+  
+  // Wrap primitive BigInt in an Object (Boxing)
+  const boxedResult = Object(result);
+  boxedResult.toString = () => {
+    const str = result.toString();
+    if (precision === 0) return str;
+    
+    // The Golden Ratio is ~1.618, so the integer part is always '1'.
+    // The length of str is exactly precision + 1.
+    return str.slice(0, 1) + '.' + str.slice(1);
+  };
+  
+  return boxedResult;
+};

package/src/measure-performance.mjs

@@ -0,0 +1,21 @@
+/**
+ * Measures the execution time of a given function by running it multiple times.
+ * Useful for micro-benchmarking and performance comparison.
+ * 
+ * @param {Function} fn - The function to benchmark.
+ * @param {number} [steps=1e8] - The number of iterations to run the function.
+ * @param {string} [memo='noop'] - A descriptive label for the benchmark result.
+ * @returns {Object} An object containing the `memo` and the `duration` (in milliseconds).
+ */
+export const measurePerformance = (fn, steps = 1e8, memo = 'noop') => {
+  const t1 = Date.now();
+  while (steps--) {
+    fn();
+  }
+  const t2 = Date.now();
+  
+  return {
+    memo,
+    duration: t2 - t1
+  };
+};