@gkucmierz/utils 3.0.1 → 3.1.0

package/README.md

@@ -45,14 +45,25 @@ This library provides a wide range of mathematical functions and data structures
   - `squareRoot`: Integer square root using Newton's method.
   - `goldenRatio`, `goldenRatioBI`: The Golden Ratio calculation (with arbitrary precision support).
 
+- **Optimization & Machine Learning**:
+  - `nelderMead`: Nelder-Mead (simplex) optimization algorithm for multi-dimensional functions.
+  - `particleSwarmOptimization`: PSO algorithm for global optimization.
+  - `simulatedAnnealing`: Probabilistic technique for approximating the global optimum of a given function.
+
+- **Math & 3D Geometry**:
+  - `math3d`: Utilities for 3D vector and matrix math (`crossProduct`, `dotProduct`, `normalize`, `multiplyMatrix4`, `projectToTrackball`, `getRotationMatrixFromVectors`).
+  - `randNormal`: Normal (Gaussian) distribution random number generator (Box-Muller transform).
+
 - **Automata & Simulation**:
   - `createLangtonsAnt`, `createUnlimitedGrid`: Infinite 2D grid and Langton's Ant cellular automaton engine (Project Euler 349 compatible).
 
 - **String & Encoding & Arrays**:
+  - `chunks`, `chunksIterator`, `chunksAsyncIterator`: Synchronous and asynchronous array/string chunking generators.
   - `base64`: Base64 and Base64Url encoding/decoding.
   - `copyCase`: Match case of a string to another.
   - `arrayHistogram`: Creates Map mappings counting absolute frequencies across any `Iterable`.
   - `bijectiveNumeration`: Bijective base-k numeration system.
+  - `formatBigNumber`: Intelligent formatting for massively large numbers with suffixes.
 
 - **Developer Utilities**:
   - `measurePerformance`: A micro-benchmarking tool for high-iteration performance testing.
@@ -60,6 +71,7 @@ This library provides a wide range of mathematical functions and data structures
   - `consumeIteratorNonBlocking`: Yield consumption macro-tasks queue resolver for heavy computations.
   - `memoize`: Function memoization based on arguments.
   - `binarySearch`: Various binary search implementations (exact, lower bound, upper bound).
+  - `naturalSearch`: Natural sorting/search utility for human-readable string comparisons.
   - `range2array`, `array2range`: Convert between ranges and arrays.
   - `getType`: Precise dynamic type checking.
 

package/main.mjs

@@ -17,6 +17,9 @@ import {
 import {
   binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl
 } from './src/binary-search.mjs'
+import {
+  chunks, chunksAsyncIterator, chunksIterator
+} from './src/chunks.mjs'
 import {
   combinations, combinationsIterator
 } from './src/combinations.mjs'
@@ -42,7 +45,7 @@ import {
   getType
 } from './src/get-type.mjs'
 import {
-  goldenRatio, goldenRatioBI
+  goldenRatio, goldenRatioBI, goldenRatioStr
 } from './src/golden-ratio.mjs'
 import {
   gpn, gpnBI
@@ -129,6 +132,7 @@ 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/chunks.mjs';
 export * from './src/combinations.mjs';
 export * from './src/consume-iterator.mjs';
 export * from './src/copy-case.mjs';
@@ -166,5 +170,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, 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
+  SetCnt, Trie, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, chunks, chunksAsyncIterator, chunksIterator, combinations, combinationsIterator, consumeIteratorNonBlocking, copyCase, egcd, factors, factorsBI, formatBigNumber, formatBigNumberBI, wrapFn, gcd, gcdBI, getType, goldenRatio, goldenRatioBI, goldenRatioStr, 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": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -44,7 +44,15 @@
     "square-root",
     "tonelli-shanks",
     "trie",
-    "utils"
+    "utils",
+    "chunks",
+    "math3d",
+    "nelder-mead",
+    "particle-swarm",
+    "simulated-annealing",
+    "rand-normal",
+    "format-big-number",
+    "natural-search"
   ],
   "files": [
     "main.mjs",

package/src/chunks.mjs

@@ -0,0 +1,64 @@
+export const chunks = (input, size = 1) => {
+  if (size < 1) size = 1;
+  
+  if (typeof input === 'string' || Array.isArray(input)) {
+    const numChunks = Math.ceil(input.length / size);
+    const result = new Array(numChunks);
+    for (let i = 0, offset = 0; i < numChunks; ++i, offset += size) {
+      result[i] = input.slice(offset, offset + size);
+    }
+    return result;
+  }
+
+  // Fallback for other synchronous iterables (Sets, Maps, custom iterators)
+  const result = [];
+  let currentChunk = [];
+  for (const item of input) {
+    currentChunk.push(item);
+    if (currentChunk.length === size) {
+      result.push(currentChunk);
+      currentChunk = [];
+    }
+  }
+  if (currentChunk.length > 0) {
+    result.push(currentChunk);
+  }
+  return result;
+};
+
+export function* chunksIterator(iterable, size = 1) {
+  if (size < 1) size = 1;
+  
+  const isString = typeof iterable === 'string';
+  let currentChunk = [];
+  
+  for (const item of iterable) {
+    currentChunk.push(item);
+    if (currentChunk.length === size) {
+      yield isString ? currentChunk.join('') : currentChunk;
+      currentChunk = [];
+    }
+  }
+  
+  if (currentChunk.length > 0) {
+    yield isString ? currentChunk.join('') : currentChunk;
+  }
+}
+
+export async function* chunksAsyncIterator(asyncIterable, size = 1) {
+  if (size < 1) size = 1;
+  
+  let currentChunk = [];
+  
+  for await (const item of asyncIterable) {
+    currentChunk.push(item);
+    if (currentChunk.length === size) {
+      yield currentChunk;
+      currentChunk = [];
+    }
+  }
+  
+  if (currentChunk.length > 0) {
+    yield currentChunk;
+  }
+}

package/src/golden-ratio.mjs

@@ -9,11 +9,9 @@ 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.
+ * @returns {BigInt} A primitive BigInt representing the Golden Ratio scaled by 10^precision.
  * @throws {Error} If precision is negative.
  * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOZQDYBMCmA7AJQEM4QoAhASQQF8EAzGKMBAIgAFUBrAVwGMwIHDABeAeh6kMAZ1YBuYMHTZ8xUhUoKgA|▶ Try it live in Instacode}
  */
@@ -24,17 +22,22 @@ export const goldenRatioBI = precision => {
   
   // (sqrt(5 * exp^2) + exp) / 2
   const result = (squareRootBI(5n * exp * exp) + exp) / 2n;
+  return result;
+};
+
+/**
+ * Calculates the Golden Ratio (phi) to an arbitrary precision and returns it as a formatted string.
+ * @param {number|bigint} precision - The number of decimal places to calculate.
+ * @returns {string} The formatted Golden Ratio string (e.g., '1.618...').
+ * @throws {Error} If precision is negative.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOZQDYBMCmA7AJQEM4QoBlOGBAXwQDMYowEAiAAVQGsBXAYzAgcMAF4B6HqQwBnVgG5gwdNnzFSFKgqA|▶ Try it live in Instacode}
+ */
+export const goldenRatioStr = precision => {
+  if (precision < 0) throw new Error('Precision cannot be negative');
+  const str = goldenRatioBI(precision).toString();
+  if (precision === 0 || precision === 0n) return str;
   
-  // 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;
+  // 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);
 };