@gkucmierz/utils 3.0.2 → 3.2.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'
@@ -80,6 +83,9 @@ import {
 import {
   memoize
 } from './src/memoize.mjs'
+import {
+  mobius, mobiusBI
+} from './src/mobius.mjs'
 import {
   mod, modBI
 } from './src/mod.mjs'
@@ -129,6 +135,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';
@@ -150,6 +157,7 @@ export * from './src/math3d.mjs';
 export * from './src/matrix.mjs';
 export * from './src/measure-performance.mjs';
 export * from './src/memoize.mjs';
+export * from './src/mobius.mjs';
 export * from './src/mod.mjs';
 export * from './src/n-choose-k.mjs';
 export * from './src/natural-search.mjs';
@@ -166,5 +174,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, 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
+  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, mobius, mobiusBI, 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.2",
+  "version": "3.2.0",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -44,7 +44,16 @@
     "square-root",
     "tonelli-shanks",
     "trie",
-    "utils"
+    "utils",
+    "chunks",
+    "math3d",
+    "nelder-mead",
+    "particle-swarm",
+    "simulated-annealing",
+    "rand-normal",
+    "format-big-number",
+    "natural-search",
+    "mobius"
   ],
   "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/mobius.mjs

@@ -0,0 +1,31 @@
+import { factors, factorsBI } from './factors.mjs';
+
+/**
+ * Calculates the Mobius function μ(n) of a number.
+ * @param {number} n - A positive integer.
+ * @returns {number} The Mobius function value (1, -1, or 0).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LFARiArgZwQXwQDMYowEAiAAQHMBrLAYzBAFMYAvAeizhABscFANzBgaTLlFA|▶ Try it live in Instacode}
+ */
+export const mobius = n => {
+  if (n < 1) return 0;
+  if (n === 1) return 1;
+  const f = factors(n);
+  const unique = new Set(f);
+  if (unique.size !== f.length) return 0;
+  return f.length % 2 === 0 ? 1 : -1;
+};
+
+/**
+ * Calculates the Mobius function μ(n) of a BigInt.
+ * @param {bigint} n - A positive BigInt.
+ * @returns {number} The Mobius function value (1, -1, or 0).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LFARiArgZwEICSCAvggGYxRgIBEAAgOYDWWAxmCAKYwBeA9FjggANjhoBuYMDSZchSUA|▶ Try it live in Instacode}
+ */
+export const mobiusBI = n => {
+  if (n < 1n) return 0;
+  if (n === 1n) return 1;
+  const f = factorsBI(n);
+  const unique = new Set(f);
+  if (unique.size !== f.length) return 0;
+  return f.length % 2 === 0 ? 1 : -1;
+};