@gkucmierz/utils 1.30.3 → 1.32.1

package/README.md

@@ -1,5 +1,6 @@
 # @gkucmierz/utils
 
+[![Socket Badge](https://socket.dev/api/badge/npm/package/@gkucmierz/utils)](https://socket.dev/npm/package/@gkucmierz/utils)
 ![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)

package/main.mjs

@@ -14,6 +14,9 @@ import {
 import {
   binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl
 } from './src/binary-search.mjs'
+import {
+  consumeIteratorNonBlocking
+} from './src/consume-iterator.mjs'
 import {
   copyCase
 } from './src/copy-case.mjs'
@@ -47,6 +50,9 @@ import {
 import {
   ListNode
 } from './src/list-node.mjs'
+import {
+  axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball
+} from './src/math3d.mjs'
 import {
   matrixAsArray
 } from './src/matrix.mjs'
@@ -56,6 +62,15 @@ import {
 import {
   mod, modBI
 } from './src/mod.mjs'
+import {
+  naturalSearch
+} from './src/natural-search.mjs'
+import {
+  nelderMead
+} from './src/nelder-mead.mjs'
+import {
+  particleSwarmOptimization
+} from './src/particle-swarm.mjs'
 import {
   phi, phiBI
 } from './src/phi.mjs'
@@ -65,21 +80,22 @@ import {
 import {
   array2range, range2array
 } from './src/range-array.mjs'
+import {
+  simulatedAnnealing
+} from './src/simulated-annealing.mjs'
 import {
   squareRoot, squareRootBI
 } from './src/square-root.mjs'
 import {
   tonelliShanksBI
 } from './src/tonelli-shanks.mjs'
-import {
-  naturalSearch
-} from './src/natural-search.mjs'
 
 export * from './src/SetCnt.mjs';
 export * from './src/Trie.mjs';
 export * from './src/base64.mjs';
 export * from './src/bijective-numeration.mjs';
 export * from './src/binary-search.mjs';
+export * from './src/consume-iterator.mjs';
 export * from './src/copy-case.mjs';
 export * from './src/egcd.mjs';
 export * from './src/factors.mjs';
@@ -91,16 +107,20 @@ export * from './src/heap.mjs';
 export * from './src/herons-formula.mjs';
 export * from './src/lcm.mjs';
 export * from './src/list-node.mjs';
+export * from './src/math3d.mjs';
 export * from './src/matrix.mjs';
 export * from './src/memoize.mjs';
 export * from './src/mod.mjs';
+export * from './src/natural-search.mjs';
+export * from './src/nelder-mead.mjs';
+export * from './src/particle-swarm.mjs';
 export * from './src/phi.mjs';
 export * from './src/pow-mod.mjs';
 export * from './src/range-array.mjs';
+export * from './src/simulated-annealing.mjs';
 export * from './src/square-root.mjs';
 export * from './src/tonelli-shanks.mjs';
-export * from './src/natural-search.mjs';
 
 export default [
-  SetCnt, Trie, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, copyCase, egcd, factors, factorsBI, formatBigNumber, formatBigNumberBI, wrapFn, gcd, gcdBI, getType, gpn, gpnBI, Heap, heronsFormula, heronsFormulaBI, lcm, lcmBI, ListNode, matrixAsArray, memoize, mod, modBI, phi, phiBI, powMod, powModBI, array2range, range2array, squareRoot, squareRootBI, tonelliShanksBI, naturalSearch
+  SetCnt, Trie, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, copyCase, egcd, factors, factorsBI, formatBigNumber, formatBigNumberBI, wrapFn, gcd, gcdBI, getType, gpn, gpnBI, Heap, heronsFormula, heronsFormulaBI, lcm, lcmBI, ListNode, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, memoize, mod, modBI, naturalSearch, nelderMead, particleSwarmOptimization, phi, phiBI, powMod, powModBI, array2range, range2array, simulatedAnnealing, squareRoot, squareRootBI, tonelliShanksBI
 ];

package/package.json

@@ -1,31 +1,34 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "1.30.3",
+  "version": "1.32.1",
+  "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
-    "utils",
     "algorithms",
-    "math",
-    "number-theory",
+    "base64",
+    "bijective",
+    "binary-search",
+    "competitive-programming",
+    "data-structures",
+    "factors",
     "gcd",
+    "heap",
+    "iterator",
+    "javascript",
     "lcm",
-    "factors",
-    "phi",
+    "math",
+    "memoize",
     "mod",
+    "node",
+    "non-blocking",
+    "number-theory",
+    "phi",
     "pow-mod",
-    "binary-search",
-    "heap",
-    "trie",
-    "base64",
-    "bijective",
-    "tonelli-shanks",
-    "square-root",
-    "memoize",
     "range-array",
-    "javascript",
-    "node",
-    "competitive-programming",
-    "data-structures"
+    "square-root",
+    "tonelli-shanks",
+    "trie",
+    "utils"
   ],
   "files": [
     "main.mjs",
@@ -35,20 +38,25 @@
   "scripts": {
     "test": "jasmine",
     "watch": "nodemon --exec 'npm test'",
-    "main": "node scripts/generate_main.mjs",
     "docs": "npm run docs:build; npm run docs:open",
+    "build:main": "node scripts/generate_main.mjs",
     "docs:build": "jsdoc -c jsdoc.json --readme README.md",
-    "docs:open": "open docs/index.html"
+    "docs:open": "open docs/index.html",
+    "lint": "eslint .",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gkucmierz/utils"
+    "url": "git+https://gitea.7u.pl/gkucmierz/utils.git"
   },
   "author": "Grzegorz Kućmierz",
   "license": "MIT",
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "docdash": "^2.0.2",
-    "husky": "^8.0.1",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "husky": "^8.0.3",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
     "nodemon": "^3.1.14"

package/src/consume-iterator.mjs

@@ -0,0 +1,26 @@
+/**
+ * Consume iterator values asynchronously utilizing macro-task queue
+ * to prevent Event Loop blocking.
+ *
+ * @param {Iterator} iter - Iterator object with .next() method returning {value, done}
+ * @param {function} progressFn - Callback function executed for each iteration Step
+ * @returns {Promise} - Resolves when the iterator is fully consumed
+ */
+export const consumeIteratorNonBlocking = (iter, progressFn) => {
+  return new Promise((resolve, reject) => {
+    const loop = () => {
+      try {
+        const { value, done } = iter.next();
+        if (done) {
+          resolve();
+        } else {
+          progressFn(value);
+          setTimeout(loop, 0);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    };
+    loop();
+  });
+};

package/src/math3d.mjs

@@ -0,0 +1,66 @@
+/**
+ * Pure 3D Math Engine for Arcball/Trackball raw matrix transformations
+ */
+
+export const crossProduct = (u, v) => [
+  u[1]*v[2] - u[2]*v[1],
+  u[2]*v[0] - u[0]*v[2],
+  u[0]*v[1] - u[1]*v[0]
+];
+
+export const dotProduct = (u, v) => u[0]*v[0] + u[1]*v[1] + u[2]*v[2];
+
+export const normalize = (v) => {
+  const len = Math.hypot(v[0], v[1], v[2]);
+  if (len === 0) return [0, 0, 0];
+  return [v[0]/len, v[1]/len, v[2]/len];
+};
+
+export const projectToTrackball = (x, y, radius = 1) => {
+  const d2 = x*x + y*y;
+  const r2 = radius * radius;
+  if (d2 <= r2 * 0.5) {
+     return normalize([x, y, Math.sqrt(r2 - d2)]);
+  } else {
+     return normalize([x, y, (r2 * 0.5) / Math.sqrt(d2)]);
+  }
+};
+
+export const axisAngleToMatrix4 = (axis, angle) => {
+  const [x, y, z] = normalize(axis);
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const t = 1 - c;
+
+  // Column-major array mapping (standard for WebGL and Three.js matrices)
+  return [
+    c + x*x*t,     y*x*t + z*s,   z*x*t - y*s,   0,
+    x*y*t - z*s,   c + y*y*t,     z*y*t + x*s,   0,
+    x*z*t + y*s,   y*z*t - x*s,   c + z*z*t,     0,
+    0,             0,             0,             1
+  ];
+};
+
+export const multiplyMatrix4 = (a, b) => {
+  const out = new Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      let sum = 0;
+      for (let i = 0; i < 4; i++) {
+         sum += a[i*4 + r] * b[c*4 + i]; // Note: column-major alignment
+      }
+      out[c*4 + r] = sum;
+    }
+  }
+  return out;
+};
+
+export const getRotationMatrixFromVectors = (u, v) => {
+  const axis = crossProduct(u, v);
+  if (axis[0] === 0 && axis[1] === 0 && axis[2] === 0) {
+      return [1,0,0,0,  0,1,0,0,  0,0,1,0,  0,0,0,1]; // Identity
+  }
+  const dot = dotProduct(u, v);
+  const angle = Math.acos(Math.max(-1, Math.min(1, dot)));
+  return axisAngleToMatrix4(axis, angle);
+};

package/src/nelder-mead.mjs

@@ -0,0 +1,95 @@
+/**
+ * Nelder-Mead Simplex Algorithm (Direct Search Gradient-Free Optimization)
+ * Maximizes continuous N-dimensional spaces through contraction and expansion.
+ * 
+ * @param {Function} evaluate - function(paramsArray) => Number (score to maximize)
+ * @param {Array<Array<Number>>} bounds - [[min1, max1], ... ] bounds per dimension
+ * @param {Object} options - { steps: 30, onProgress: async (state) => {} }
+ * @returns {Promise<{bestParams: Array<Number>, bestScore: Number}>}
+ */
+export const nelderMead = async (evaluate, bounds, options = {}) => {
+  const steps = options.steps || 30;
+  const onProgress = options.onProgress || (async () => {});
+  const dim = bounds.length;
+
+  let simplex = [];
+  let baseCoords = bounds.map(b => b[0] + (b[1] - b[0]) * 0.5); // Start directly centered
+
+  // To build an initial N-dimensional simplex, we require N+1 vertices
+  for (let i = 0; i <= dim; i++) {
+    let p = [...baseCoords];
+    if (i > 0) {
+      // Offset each dimension successively to form the simplex
+      let range = bounds[i-1][1] - bounds[i-1][0];
+      p[i-1] += range * 0.2; // 20% span stretch
+    }
+    for(let d=0; d<dim; d++) p[d] = Math.max(bounds[d][0], Math.min(bounds[d][1], p[d]));
+    
+    simplex.push({ position: p, score: evaluate(p) });
+  }
+
+  const alpha = 1.0; // Reflection
+  const gamma = 2.0; // Expansion
+  const rho = 0.5;   // Contraction
+  const sigma = 0.5; // Shrink
+
+  for (let step = 0; step < steps; step++) {
+    // Sort descending layout (Simplex optimization seeks maximization)
+    simplex.sort((a, b) => b.score - a.score);
+    
+    let best = simplex[0];
+    let worst = simplex[dim];
+    let secondWorst = simplex[dim - 1];
+
+    // Compute the spatial centroid of all nodes excluding the worst
+    let centroid = new Array(dim).fill(0);
+    for (let i = 0; i < dim; i++) {
+      for (let d = 0; d < dim; d++) centroid[d] += simplex[i].position[d];
+    }
+    for (let d = 0; d < dim; d++) centroid[d] /= dim;
+
+    // Reflection Hook
+    let xr = centroid.map((c, d) => c + alpha * (c - worst.position[d]));
+    xr = xr.map((v, d) => Math.max(bounds[d][0], Math.min(bounds[d][1], v)));
+    let rScore = evaluate(xr);
+
+    if (rScore > best.score) {
+      // Expansion Hook
+      let xe = centroid.map((c, d) => c + gamma * (xr[d] - c));
+      xe = xe.map((v, d) => Math.max(bounds[d][0], Math.min(bounds[d][1], v)));
+      let eScore = evaluate(xe);
+      simplex[dim] = eScore > rScore ? { position: xe, score: eScore } : { position: xr, score: rScore };
+    } else if (rScore > secondWorst.score) {
+      // Reflected vertex outperforms second-worst node
+      simplex[dim] = { position: xr, score: rScore };
+    } else {
+      // Contraction Hook (if reflection completely failed)
+      let xc = centroid.map((c, d) => c + rho * (worst.position[d] - c));
+      xc = xc.map((v, d) => Math.max(bounds[d][0], Math.min(bounds[d][1], v)));
+      let cScore = evaluate(xc);
+      if (cScore > worst.score) {
+        simplex[dim] = { position: xc, score: cScore };
+      } else {
+        // Complete Simplex Shrinkage towards the primary maximum best point
+        for (let i = 1; i <= dim; i++) {
+          simplex[i].position = simplex[i].position.map((v, d) => best.position[d] + sigma * (v - best.position[d]));
+          simplex[i].position = simplex[i].position.map((v, d) => Math.max(bounds[d][0], Math.min(bounds[d][1], v)));
+          simplex[i].score = evaluate(simplex[i].position);
+        }
+      }
+    }
+    
+    simplex.sort((a, b) => b.score - a.score);
+    
+    await onProgress({
+      step,
+      totalSteps: steps,
+      bestScore: simplex[0].score,
+      bestParams: simplex[0].position,
+      simplexVisNodes: simplex.map(s => s.position)
+    });
+  }
+
+  simplex.sort((a, b) => b.score - a.score);
+  return { bestParams: simplex[0].position, bestScore: simplex[0].score };
+};

package/src/particle-swarm.mjs

@@ -0,0 +1,84 @@
+/**
+ * Particle Swarm Optimization (PSO)
+ * A stochastic, population-based metaheuristic for maximizing complex multidimensional bounds.
+ * 
+ * @param {Function} evaluate - function(paramsArray) => Number (score to maximize)
+ * @param {Array<Array<Number>>} bounds - [[min1, max1], [min2, max2], ...] bounds per dimension
+ * @param {Object} options - { particles: 10, steps: 30, w: 0.5, c1: 1.5, c2: 1.5, onProgress: async (state) => {} }
+ * @returns {Promise<{bestParams: Array<Number>, bestScore: Number}>}
+ */
+export const particleSwarmOptimization = async (evaluate, bounds, options = {}) => {
+  const numParticles = options.particles || 12;
+  const steps = options.steps || 30;
+  const w = options.w || 0.5; // Inertia weight
+  const c1 = options.c1 || 1.5; // Cognitive (local) best weight
+  const c2 = options.c2 || 1.5; // Social (global) best weight
+  const onProgress = options.onProgress || (async () => {});
+
+  let swarm = [];
+  let globalBestParams = null;
+  let globalBestScore = -Infinity;
+
+  // Initialize swarm
+  for (let i = 0; i < numParticles; i++) {
+    let position = bounds.map(b => b[0] + Math.random() * (b[1] - b[0]));
+    let velocity = bounds.map(b => (Math.random() * 2 - 1) * (b[1] - b[0]) * 0.1); // Small initial velocity
+    let score = evaluate(position);
+    
+    let particle = {
+      position,
+      velocity,
+      bestPosition: [...position],
+      bestScore: score
+    };
+    swarm.push(particle);
+    
+    if (score > globalBestScore) {
+      globalBestScore = score;
+      globalBestParams = [...position];
+    }
+  }
+
+  for (let i = 0; i < steps; i++) {
+    for (let p of swarm) {
+      for (let d = 0; d < bounds.length; d++) {
+        let r1 = Math.random();
+        let r2 = Math.random();
+        
+        // Velocity update matrix
+        p.velocity[d] = w * p.velocity[d] + 
+                        c1 * r1 * (p.bestPosition[d] - p.position[d]) + 
+                        c2 * r2 * (globalBestParams[d] - p.position[d]);
+        
+        // Position update
+        p.position[d] = p.position[d] + p.velocity[d];
+        
+        // Enforce physical parameter bounds
+        p.position[d] = Math.max(bounds[d][0], Math.min(bounds[d][1], p.position[d]));
+      }
+      
+      let score = evaluate(p.position);
+      
+      // Update local cognitive best
+      if (score > p.bestScore) {
+        p.bestScore = score;
+        p.bestPosition = [...p.position];
+      }
+      // Update social swarm global best
+      if (score > globalBestScore) {
+        globalBestScore = score;
+        globalBestParams = [...p.position];
+      }
+    }
+    
+    await onProgress({
+      step: i,
+      totalSteps: steps,
+      bestScore: globalBestScore,
+      bestParams: globalBestParams,
+      swarm: swarm // Expose for 3D visualizers (Radar scatter generation)
+    });
+  }
+
+  return { bestParams: globalBestParams, bestScore: globalBestScore };
+};

package/src/simulated-annealing.mjs

@@ -0,0 +1,57 @@
+/**
+ * Simulated Annealing (Derivative-Free Stochastic Optimization)
+ * Maximizes the evaluate function payload.
+ * 
+ * @param {Function} evaluate - function(paramsArray) => Number (score to maximize)
+ * @param {Array<Array<Number>>} bounds - [[min1, max1], [min2, max2], ...] bounds per dimension
+ * @param {Object} options - { steps: 100, initialTemp: 100, finalTemp: 0.1, onProgress: async (state) => {} }
+ * @returns {Promise<{bestParams: Array<Number>, bestScore: Number}>}
+ */
+export const simulatedAnnealing = async (evaluate, bounds, options = {}) => {
+  const steps = options.steps || 100;
+  const initialTemp = options.initialTemp || 100.0;
+  const finalTemp = options.finalTemp || 0.1;
+  const onProgress = options.onProgress || (async () => {});
+
+  let currentParams = bounds.map(b => (b[0] + b[1]) / 2);
+  let currentScore = evaluate(currentParams);
+  
+  let bestParams = [...currentParams];
+  let bestScore = currentScore;
+
+  for (let i = 0; i < steps; i++) {
+    let temp = initialTemp * Math.pow((finalTemp / initialTemp), (i / steps));
+    let noiseScale = temp / initialTemp; // Gradually reduce the noise field radius
+    
+    let candidateParams = currentParams.map((p, idx) => {
+      let b = bounds[idx];
+      let range = b[1] - b[0];
+      let nv = p + (Math.random() * 2 - 1) * (range * 0.2) * noiseScale;
+      return Math.max(b[0], Math.min(b[1], nv)); // enforce bounds constraint
+    });
+    
+    let candidateScore = evaluate(candidateParams);
+    
+    // Acceptance criteria (accept worse scores with diminishing probability to escape local maxima)
+    if (candidateScore > currentScore || Math.random() < Math.exp((candidateScore - currentScore) / temp)) {
+      currentParams = candidateParams;
+      currentScore = candidateScore;
+      
+      if (candidateScore > bestScore) {
+        bestScore = candidateScore;
+        bestParams = [...currentParams];
+      }
+    }
+    
+    await onProgress({
+      step: i,
+      totalSteps: steps,
+      score: currentScore,
+      bestScore: bestScore,
+      params: currentParams,
+      bestParams: bestParams
+    });
+  }
+  
+  return { bestParams, bestScore };
+};