@gkucmierz/utils 5.1.0 → 5.4.0

package/main.mjs

@@ -41,6 +41,9 @@ import {
 import {
   
 } from './src/developer-utils/get-type.mjs'
+import {
+  detectGridColumns, navigateGrid
+} from './src/developer-utils/grid-navigation.mjs'
 import {
   measurePerformance
 } from './src/developer-utils/measure-performance.mjs'
@@ -50,6 +53,9 @@ import {
 import {
   naturalSearch
 } from './src/developer-utils/natural-search.mjs'
+import {
+  QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual
+} from './src/developer-utils/quorum.mjs'
 import {
   randNormal
 } from './src/developer-utils/rand-normal.mjs'
@@ -60,17 +66,20 @@ import {
   setSafeInterval
 } from './src/developer-utils/set-safe-interval.mjs'
 import {
-  Type, Types, is, of, same
+  Type, Types, is, isCallable, of, same
 } from './src/developer-utils/type.mjs'
 import {
   barycentricCoordinates
 } from './src/geometry/barycentric.mjs'
 import {
-  axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball
+  applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp
 } from './src/geometry/math3d.mjs'
 import {
   matrixAsArray
 } from './src/geometry/matrix.mjs'
+import {
+  OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange
+} from './src/geometry/range-set.mjs'
 import {
   egcd
 } from './src/number-theory/egcd.mjs'
@@ -140,6 +149,12 @@ import {
 import {
   formatBigNumber, formatBigNumberBI, wrapFn
 } from './src/string-arrays/format-big-number.mjs'
+import {
+  parseHeading
+} from './src/string-arrays/parse-heading.mjs'
+import {
+  slugify
+} from './src/string-arrays/slugify.mjs'
 
 export * from './src/automata/langtons-ant.mjs';
 export * from './src/combinatorics/combinations.mjs';
@@ -155,9 +170,11 @@ export * from './src/data-structures/list-node.mjs';
 export * from './src/developer-utils/binary-search.mjs';
 export * from './src/developer-utils/consume-iterator.mjs';
 export * from './src/developer-utils/get-type.mjs';
+export * from './src/developer-utils/grid-navigation.mjs';
 export * from './src/developer-utils/measure-performance.mjs';
 export * from './src/developer-utils/memoize.mjs';
 export * from './src/developer-utils/natural-search.mjs';
+export * from './src/developer-utils/quorum.mjs';
 export * from './src/developer-utils/rand-normal.mjs';
 export * from './src/developer-utils/range-array.mjs';
 export * from './src/developer-utils/set-safe-interval.mjs';
@@ -165,6 +182,7 @@ export * from './src/developer-utils/type.mjs';
 export * from './src/geometry/barycentric.mjs';
 export * from './src/geometry/math3d.mjs';
 export * from './src/geometry/matrix.mjs';
+export * from './src/geometry/range-set.mjs';
 export * from './src/number-theory/egcd.mjs';
 export * from './src/number-theory/factors.mjs';
 export * from './src/number-theory/gcd.mjs';
@@ -188,7 +206,9 @@ export * from './src/string-arrays/bijective-numeration.mjs';
 export * from './src/string-arrays/chunks.mjs';
 export * from './src/string-arrays/copy-case.mjs';
 export * from './src/string-arrays/format-big-number.mjs';
+export * from './src/string-arrays/parse-heading.mjs';
+export * from './src/string-arrays/slugify.mjs';
 
 export default [
-  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, of, same, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
+  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, detectGridColumns, navigateGrid, measurePerformance, memoize, naturalSearch, QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, isCallable, of, same, barycentricCoordinates, applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp, matrixAsArray, OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn, parseHeading, slugify
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "5.1.0",
+  "version": "5.4.0",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -74,7 +74,7 @@
     "docs:build": "jsdoc -c jsdoc.json && cp -r docs/@gkucmierz/utils/*/* docs/ && rm -rf docs/@gkucmierz",
     "docs:open": "open docs/index.html",
     "lint": "eslint .",
-    "prepare": "husky"
+    "prepare": "git config core.hooksPath .githooks || true"
   },
   "repository": {
     "type": "git",
@@ -88,7 +88,6 @@
     "docdash": "^2.0.2",
     "eslint": "^10.1.0",
     "globals": "^17.4.0",
-    "husky": "^8.0.3",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
     "lz-string": "^1.5.0",

package/src/developer-utils/grid-navigation.mjs

@@ -0,0 +1,175 @@
+/**
+ * @module developer-utils
+ */
+
+/**
+ * Resolves the next 0-based index when navigating a 2D grid (matrix) that may contain
+ * trailing gaps in its last row (`totalItems` not divisible by `columns`).
+ *
+ * Pure mathematical/index function — completely independent of the DOM.
+ *
+ * Wrapping configuration hierarchy:
+ * - `wrap` (boolean, default `true`): master default for both axes.
+ * - `wrapHoriz` / `wrapHorizontal` (boolean, optional): overrides `wrap` for horizontal movement (`left` / `right`).
+ * - `wrapVert` / `wrapVertical` (boolean, optional): overrides `wrap` for vertical movement (`up` / `down`).
+ * - `rowStrict` (boolean, default `false`): when `true`, horizontal movement wraps/clamps strictly within the current row instead of reading order.
+ *
+ * When `columns === 1` (single-column layout), `right` behaves identically to `down`
+ * and `left` behaves identically to `up`.
+ *
+ * @param {number} currentIndex - Current active 0-based index (`0 <= currentIndex < totalItems`).
+ * @param {number} totalItems - Total number of items in the grid ($N \ge 0$).
+ * @param {'left'|'right'|'up'|'down'|'ArrowLeft'|'ArrowRight'|'ArrowUp'|'ArrowDown'} direction - Movement direction.
+ * @param {number|Object} [columnsOrOptions=1] - Column count ($C \ge 1$) or options object.
+ * @param {Object} [maybeOptions={}] - Optional configuration when 4th argument is a column count.
+ * @returns {number} Next 0-based index, or `-1` if `totalItems <= 0`.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYEMBuIDm64CmA4jCACYIC+CAZjFGAgEQACOA1gK4DGYIBMAF4B6TnBAAbAM5MA3MGAZseQiXLygA|▶ Try it live in Instacode}
+ */
+export const navigateGrid = (
+  currentIndex,
+  totalItems,
+  direction,
+  columnsOrOptions = 1,
+  maybeOptions = {}
+) => {
+  if (!Number.isFinite(totalItems) || totalItems <= 0) {
+    return -1;
+  }
+
+  const isObj = columnsOrOptions !== null && typeof columnsOrOptions === 'object';
+  const opts = isObj ? columnsOrOptions : (maybeOptions || {});
+  const rawCols = isObj ? opts.columns : columnsOrOptions;
+  const cols = Math.max(1, Math.floor(Number(rawCols) || 1));
+
+  const cur =
+    Number.isFinite(currentIndex) && currentIndex >= 0 && currentIndex < totalItems
+      ? Math.floor(currentIndex)
+      : 0;
+
+  const baseWrap = typeof opts.wrap === 'boolean' ? opts.wrap : true;
+  const wrapHoriz =
+    typeof opts.wrapHorizontal === 'boolean'
+      ? opts.wrapHorizontal
+      : typeof opts.wrapHoriz === 'boolean'
+        ? opts.wrapHoriz
+        : baseWrap;
+  const wrapVert =
+    typeof opts.wrapVertical === 'boolean'
+      ? opts.wrapVertical
+      : typeof opts.wrapVert === 'boolean'
+        ? opts.wrapVert
+        : baseWrap;
+  const rowStrict = Boolean(opts.rowStrict);
+
+  const row = Math.floor(cur / cols);
+  const col = cur % cols;
+
+  let deltaH = 0;
+  let deltaV = 0;
+
+  switch (direction) {
+  case 'right':
+  case 'ArrowRight':
+    deltaH = 1;
+    break;
+  case 'left':
+  case 'ArrowLeft':
+    deltaH = -1;
+    break;
+  case 'down':
+  case 'ArrowDown':
+    deltaV = 1;
+    break;
+  case 'up':
+  case 'ArrowUp':
+    deltaV = -1;
+    break;
+  default:
+    return cur;
+  }
+
+  // Horizontal movement (left / right)
+  if (deltaH !== 0) {
+    if (rowStrict) {
+      const rowStart = row * cols;
+      const rowLen = Math.min(cols, totalItems - rowStart);
+      if (rowLen <= 0) return cur;
+      const nextCol = col + deltaH;
+      if (nextCol >= 0 && nextCol < rowLen) {
+        return rowStart + nextCol;
+      }
+      if (wrapHoriz) {
+        return rowStart + (((nextCol % rowLen) + rowLen) % rowLen);
+      }
+      return cur;
+    }
+
+    const nextIdx = cur + deltaH;
+    if (nextIdx >= 0 && nextIdx < totalItems) {
+      return nextIdx;
+    }
+    if (wrapHoriz) {
+      return ((nextIdx % totalItems) + totalItems) % totalItems;
+    }
+    return cur;
+  }
+
+  // Vertical movement (up / down) along column `col` (handling incomplete last row gaps)
+  const colRows = col < totalItems ? Math.floor((totalItems - 1 - col) / cols) + 1 : 0;
+  if (colRows <= 0) return cur;
+
+  const nextRow = row + deltaV;
+  if (nextRow >= 0 && nextRow < colRows) {
+    return nextRow * cols + col;
+  }
+  if (wrapVert) {
+    const wrappedRow = ((nextRow % colRows) + colRows) % colRows;
+    return wrappedRow * cols + col;
+  }
+  return cur;
+};
+
+/**
+ * Pure higher-order geometric utility that detects the number of columns in the first row
+ * of a 2D layout from an iterable of items and a row-offset projector function.
+ *
+ * Counts how many consecutive leading items share the same row coordinate (`y` / `top`)
+ * within the given `tolerance`. Completely independent of the DOM.
+ *
+ * @param {Iterable<*>} items - Iterable of numbers (row offsets) or arbitrary items.
+ * @param {Function|number} [getRowOffset=(x) => x] - Pure projector `(item, index) => number` (or numeric tolerance if 2nd arg is a number).
+ * @param {number} [tolerance=0] - Maximum allowed absolute difference between an item's row offset and the first item's offset.
+ * @returns {number} Detected number of columns in the first row ($\ge 1$).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICYFM7oMZwOIwioDCUANgK5gB2AzggL4IBmMUYCARAAIDmA1hWxgQ6GAC8A9BTggytTgG5gwDFlwEipSjVrKgA|▶ Try it live in Instacode}
+ */
+export const detectGridColumns = (items, getRowOffset = (x) => x, tolerance = 0) => {
+  if (!items || typeof items[Symbol.iterator] !== 'function') {
+    return 1;
+  }
+
+  const isFn = typeof getRowOffset === 'function';
+  const projector = isFn ? getRowOffset : (x) => x;
+  const tol = Math.max(0, Number(isFn ? tolerance : getRowOffset) || 0);
+
+  let firstOffset = null;
+  let firstRowCount = 0;
+  let idx = 0;
+
+  for (const item of items) {
+    const raw = projector(item, idx++);
+    const offset = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(offset)) {
+      continue;
+    }
+    if (firstOffset === null) {
+      firstOffset = offset;
+      firstRowCount = 1;
+    } else if (Math.abs(offset - firstOffset) <= tol) {
+      firstRowCount += 1;
+    } else {
+      break;
+    }
+  }
+
+  return Math.max(1, firstRowCount);
+};

package/src/developer-utils/quorum.mjs

@@ -0,0 +1,345 @@
+/**
+ * @module developer-utils
+ */
+
+import { is } from './type.mjs';
+
+/**
+ * Default required agreeing datapoints ($K = 4$) in a standard $4\text{-of-}5$ quorum check.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQBEBRAMQEF0AZAFQIGkEBfBAMxijAQCIABAOYBrAK4BjMCACmMAF4B6EXBAAbAM48A3MGAYc+YuSp1G2oA|▶ Try it live in Instacode}
+ */
+export const QUORUM_DEFAULT_K = 4;
+
+/**
+ * Default total independent sources ($N = 5$) in a standard $4\text{-of-}5$ quorum check.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQBEBRAMQEF0AZAFQIDkEBfBAMxijAQCIABAOYBrAK4BjMCACmMAF4B6EXBAAbAM48A3MGAYc+YuSp1G2oA|▶ Try it live in Instacode}
+ */
+export const QUORUM_DEFAULT_N = 5;
+
+/**
+ * Default maximum relative error threshold ($0.01\% = 0.0001 = 1\text{ bp}$) for two datapoints
+ * to be considered equal in a quorum evaluation.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfTwEEANA7AUQBliAVASQDVKDLtscEBfBAMxhQwCAEQABAOYBrAK4BjMCACmMAF4B6GXBAAbAM4iA3MGAYc+ImQo16zVu07ZjQA|▶ Try it live in Instacode}
+ */
+export const QUORUM_MAX_RELATIVE_ERROR = 0.0001;
+
+/**
+ * Default maximum relative error expressed in percent ($0.01\%$).
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfTwEEANA7AUQBliAVASQDVKDLtscCAFAYToQBfBADMYUMAgBEAAQDmAawCuAYzAgApjABeAeiVwQAGwDOUgNzBgGHPiJkKNes1btO2Hv0tA|▶ Try it live in Instacode}
+ */
+export const QUORUM_MAX_RELATIVE_ERROR_PCT = 0.01;
+
+/**
+ * Safe denominator floor near zero to avoid division by zero when comparing $0$ vs $0$.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQC0BRbTAgMQBlMcCSAFAZQElaA5BAXwQDMYUMAgBEAAQDmAawCuAYzAgApjABeAehlwQAGwDOIgNzBgGHPmJkKNOtgYt2mDsaA|▶ Try it live in Instacode}
+ */
+export const QUORUM_ZERO_FLOOR_EPSILON = 1e-9;
+
+/**
+ * Frozen SSoT configuration object for $K\text{-of-}N$ quorum evaluation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQGFMA5AMQEkBxBAXwQDMYowEAiAAQHMBrAVwDGYEAFMYALwD0-OCAA2AZ3YBuYMAw58xMlWpqgA|▶ Try it live in Instacode}
+ */
+export const QUORUM_CONFIG = Object.freeze({
+  DEFAULT_K: QUORUM_DEFAULT_K,
+  DEFAULT_N: QUORUM_DEFAULT_N,
+  MAX_RELATIVE_ERROR: QUORUM_MAX_RELATIVE_ERROR,
+  MAX_RELATIVE_ERROR_PCT: QUORUM_MAX_RELATIVE_ERROR_PCT,
+  ZERO_FLOOR_EPSILON: QUORUM_ZERO_FLOOR_EPSILON
+});
+
+const isFiniteScalar = (v) => is(v, Number) && Number.isFinite(v);
+
+const isNumericVector = (v) =>
+  is(v, Array) && v.length > 0 && v.every((item) => isFiniteScalar(item));
+
+const cleanFloat = (val) => Number(Number(val).toFixed(10));
+
+/**
+ * Computes the symmetric relative error between two numbers or two equal-length numeric vectors:
+ * $$\delta_{\text{rel}}(a, b) = \frac{|a - b|}{\max(|a|, |b|, \varepsilon_{\text{floor}})}$$
+ *
+ * For vectors $\mathbf{a}, \mathbf{b} \in \mathbb{R}^D$, returns the worst-case component-wise
+ * relative error $\max_{d} \delta_{\text{rel}}(a_d, b_d)$.
+ *
+ * @param {number|number[]} a - First value or numeric vector.
+ * @param {number|number[]} b - Second value or numeric vector.
+ * @param {Object} [options={}] - Options object.
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor when both values are near zero.
+ * @returns {number} Relative error in $[0, \infty)$ (`0.0001` corresponds to `0.01%`).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZUgVzgUwEo4A2AhnCAG44CiMMsCAvggGZ1gIBEAAgOYDWmVGBA4YALwD02EIQDOHANzBg6LLgIkylGnRhKgA|▶ Try it live in Instacode}
+ */
+export const computeRelativeError = (
+  a,
+  b,
+  { zeroFloor = QUORUM_ZERO_FLOOR_EPSILON } = {}
+) => {
+  const safeFloor = isFiniteScalar(zeroFloor) && zeroFloor > 0 ? zeroFloor : QUORUM_ZERO_FLOOR_EPSILON;
+
+  if (isFiniteScalar(a) && isFiniteScalar(b)) {
+    if (a === b) return 0;
+    const denom = Math.max(Math.abs(a), Math.abs(b), safeFloor);
+    return Math.abs(a - b) / denom;
+  }
+
+  if (isNumericVector(a) && isNumericVector(b) && a.length === b.length) {
+    let maxErr = 0;
+    for (let i = 0; i < a.length; i++) {
+      const err = computeRelativeError(a[i], b[i], { zeroFloor: safeFloor });
+      if (err > maxErr) maxErr = err;
+    }
+    return maxErr;
+  }
+
+  return Infinity;
+};
+
+/**
+ * Checks whether two datapoints (`a` and `b`) are equal within the maximum relative error
+ * threshold (default `0.01%`, i.e. `maxRelativeError = 0.0001`).
+ *
+ * @param {number|number[]} a - First datapoint.
+ * @param {number|number[]} b - Second datapoint.
+ * @param {Object} [options={}] - Options object.
+ * @param {number} [options.maxRelativeError=0.0001] - Maximum allowed relative error (`0.0001` = `0.01%`).
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor near zero.
+ * @returns {boolean} True if and only if relative error $\le \text{maxRelativeError}$.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JAZwIoFdZbAUQEcsBDAGwQF8EAzGKMBAIgAEBzAaywGMwQBTGAC8A9FjggyaJgG5goTDhh4ipMnKA|▶ Try it live in Instacode}
+ */
+export const isQuorumEqual = (
+  a,
+  b,
+  {
+    maxRelativeError = QUORUM_MAX_RELATIVE_ERROR,
+    zeroFloor = QUORUM_ZERO_FLOOR_EPSILON
+  } = {}
+) => {
+  const safeMax = isFiniteScalar(maxRelativeError) && maxRelativeError >= 0
+    ? maxRelativeError
+    : QUORUM_MAX_RELATIVE_ERROR;
+  return computeRelativeError(a, b, { zeroFloor }) <= safeMax + 1e-15;
+};
+
+const computeClusterMedianScalar = (values) => {
+  const sorted = [...values].sort((x, y) => x - y);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 1) {
+    return sorted[mid];
+  }
+  return cleanFloat((sorted[mid - 1] + sorted[mid]) / 2);
+};
+
+const computeClusterConsensusValue = (values) => {
+  if (values.length === 0) return null;
+  if (isFiniteScalar(values[0])) {
+    return computeClusterMedianScalar(values);
+  }
+  if (isNumericVector(values[0])) {
+    const dim = values[0].length;
+    const out = new Array(dim);
+    for (let d = 0; d < dim; d++) {
+      out[d] = computeClusterMedianScalar(values.map((v) => v[d]));
+    }
+    return out;
+  }
+  return null;
+};
+
+/**
+ * Evaluates a $K\text{-of-}N$ (default $4\text{-of-}5$) quorum across a set of datapoints.
+ *
+ * **Strict Equality-Clique Specification:**
+ * - Two datapoints $v_i, v_j$ are considered equal iff $\delta_{\text{rel}}(v_i, v_j) \le \text{maxRelativeError}$ (default `0.01%` = `0.0001`).
+ * - A subset of datapoints forms an agreeing cluster (clique) $C$ iff **every pair** $i, j \in C$
+ *   is mutually equal within `maxRelativeError` ($\max_{i,j \in C} \delta_{\text{rel}}(v_i, v_j) \le \text{maxRelativeError}$).
+ * - `success: true` is returned **if and only if** the largest mutually-equal clique $C^*$ has size $|C^*| \ge K$
+ *   (e.g., at least $4$ out of $5$ datapoints are mutually equal within $0.01\%$).
+ *
+ * @param {Array<number|number[]|{source?: string, id?: string, value: number|number[]}>} datapoints - Input datapoints.
+ * @param {Object} [options={}] - Quorum configuration options.
+ * @param {number} [options.k=4] - Minimum number of mutually-equal datapoints required for success ($K$).
+ * @param {number} [options.n=5] - Expected total number of independent sources ($N$).
+ * @param {number} [options.maxRelativeError=0.0001] - Maximum relative error tolerance (`0.0001` = `0.01%`).
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor near zero.
+ * @param {boolean} [options.strictN=false] - When `true`, requires `datapoints.length === n` in addition to $|C^*| \ge k$.
+ * @returns {Object} Quorum evaluation result with `success`, `consensusValue`, `maxRelativeError`, `agreeingSources`, and `outliers`.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYDcCGAbArpuVARV1lzAQF8EAzGKCgIgAEBzAa1wGMwRUYAXgHpccENgDOjANzBgGHPkIkyYWUA|▶ Try it live in Instacode}
+ */
+export const evaluateQuorum = (
+  datapoints = [],
+  {
+    k = QUORUM_DEFAULT_K,
+    n = QUORUM_DEFAULT_N,
+    maxRelativeError = QUORUM_MAX_RELATIVE_ERROR,
+    zeroFloor = QUORUM_ZERO_FLOOR_EPSILON,
+    strictN = false
+  } = {}
+) => {
+  const requiredK = Math.max(1, Math.floor(Number(k) || QUORUM_DEFAULT_K));
+  const expectedN = Math.max(requiredK, Math.floor(Number(n) || QUORUM_DEFAULT_N));
+  const safeMaxRelErr =
+    isFiniteScalar(maxRelativeError) && maxRelativeError >= 0
+      ? maxRelativeError
+      : QUORUM_MAX_RELATIVE_ERROR;
+
+  const list = is(datapoints, Array) ? datapoints : [];
+  const valid = [];
+
+  for (let idx = 0; idx < list.length; idx++) {
+    const item = list[idx];
+    const isEntryObj = is(item, Object) && !is(item, Array) && item !== null && 'value' in item;
+    const rawVal = isEntryObj ? item.value : item;
+    const source = isEntryObj && is(item.source || item.id, String)
+      ? String(item.source || item.id)
+      : `source-${idx + 1}`;
+
+    if (isFiniteScalar(rawVal) || isNumericVector(rawVal)) {
+      valid.push({
+        index: idx,
+        source,
+        value: isNumericVector(rawVal) ? [...rawVal] : rawVal
+      });
+    }
+  }
+
+  const m = valid.length;
+  const distMatrix = Array.from({ length: m }, () => new Array(m).fill(0));
+  const adjMatrix = Array.from({ length: m }, () => new Array(m).fill(false));
+
+  for (let i = 0; i < m; i++) {
+    adjMatrix[i][i] = true;
+    for (let j = i + 1; j < m; j++) {
+      const d = computeRelativeError(valid[i].value, valid[j].value, { zeroFloor });
+      distMatrix[i][j] = d;
+      distMatrix[j][i] = d;
+      const eq = d <= safeMaxRelErr + 1e-15;
+      adjMatrix[i][j] = eq;
+      adjMatrix[j][i] = eq;
+    }
+  }
+
+  // Exact maximum clique search (with min internal spread tie-breaker)
+  let bestClique = [];
+  let bestSpread = Infinity;
+
+  const computeCliqueSpread = (clique) => {
+    let maxD = 0;
+    for (let a = 0; a < clique.length; a++) {
+      for (let b = a + 1; b < clique.length; b++) {
+        const d = distMatrix[clique[a]][clique[b]];
+        if (d > maxD) maxD = d;
+      }
+    }
+    return maxD;
+  };
+
+  const searchClique = (startIdx, currentClique) => {
+    if (currentClique.length + (m - startIdx) < bestClique.length) {
+      return;
+    }
+
+    if (currentClique.length > 0) {
+      const spread = computeCliqueSpread(currentClique);
+      if (
+        currentClique.length > bestClique.length ||
+        (currentClique.length === bestClique.length && spread < bestSpread - 1e-15)
+      ) {
+        bestClique = [...currentClique];
+        bestSpread = spread;
+      }
+    }
+
+    for (let next = startIdx; next < m; next++) {
+      let compatible = true;
+      for (let c = 0; c < currentClique.length; c++) {
+        if (!adjMatrix[currentClique[c]][next]) {
+          compatible = false;
+          break;
+        }
+      }
+      if (compatible) {
+        currentClique.push(next);
+        searchClique(next + 1, currentClique);
+        currentClique.pop();
+      }
+    }
+  };
+
+  if (m > 0) {
+    searchClique(0, []);
+  } else {
+    bestSpread = 0;
+  }
+
+  const agreeingEntries = bestClique.map((idx) => valid[idx]);
+  const agreeingValues = agreeingEntries.map((e) => e.value);
+  const agreeingCount = agreeingEntries.length;
+  const nConditionMet = strictN ? list.length === expectedN && m === expectedN : true;
+  const success = Boolean(nConditionMet && agreeingCount >= requiredK);
+  const consensusValue = success ? computeClusterConsensusValue(agreeingValues) : null;
+  const referenceValue = consensusValue !== null
+    ? consensusValue
+    : computeClusterConsensusValue(agreeingValues);
+
+  const bestSet = new Set(bestClique);
+  const outliers = [];
+  for (let i = 0; i < m; i++) {
+    if (!bestSet.has(i)) {
+      const relErr = referenceValue !== null
+        ? computeRelativeError(valid[i].value, referenceValue, { zeroFloor })
+        : Infinity;
+      outliers.push({
+        index: valid[i].index,
+        source: valid[i].source,
+        value: valid[i].value,
+        relativeError: Number.isFinite(relErr) ? cleanFloat(relErr) : Infinity,
+        relativeErrorPct: Number.isFinite(relErr) ? Number((relErr * 100).toFixed(6)) : Infinity
+      });
+    }
+  }
+
+  const safeSpread = Number.isFinite(bestSpread) ? cleanFloat(bestSpread) : 0;
+
+  return {
+    success,
+    quorumReached: success,
+    status: success
+      ? agreeingCount >= expectedN
+        ? 'OK_UNANIMOUS'
+        : 'OK_QUORUM'
+      : 'REJECTED_NO_QUORUM',
+    consensusValue,
+    agreeingCount,
+    requiredK,
+    expectedN,
+    sampleCount: m,
+    maxRelativeError: safeSpread,
+    maxRelativeErrorPct: Number((safeSpread * 100).toFixed(6)),
+    thresholdRelativeError: safeMaxRelErr,
+    thresholdRelativeErrorPct: Number((safeMaxRelErr * 100).toFixed(4)),
+    agreeingIndices: agreeingEntries.map((e) => e.index),
+    agreeingSources: agreeingEntries.map((e) => e.source),
+    agreeingValues,
+    outliers
+  };
+};
+
+/**
+ * Convenience helper for the standard $4\text{-of-}5$ quorum check with $0.01\%$ (`0.0001`)
+ * maximum relative error tolerance.
+ *
+ * @param {Array<number|number[]|{source?: string, id?: string, value: number|number[]}>} datapoints - 5 source datapoints.
+ * @param {Object} [options={}] - Optional overrides (`maxRelativeError`, `strictN`, `zeroFloor`).
+ * @returns {Object} Quorum evaluation result.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYDcCGAbArpuVARV1lzABYoAzAVgQF8FqYowEAiAAQHMBrXAGMwIVDABeAelxwQ2AM4cA3MGAYc+QiTKUatFUA|▶ Try it live in Instacode}
+ */
+export const evaluateQuorum4of5 = (datapoints = [], options = {}) =>
+  evaluateQuorum(datapoints, {
+    ...options,
+    k: QUORUM_DEFAULT_K,
+    n: QUORUM_DEFAULT_N
+  });

package/src/developer-utils/type.mjs

@@ -21,6 +21,10 @@ export class Type {
   static OBJECT = 'object';
   static ARRAY = 'array';
   static FUNCTION = 'function';
+  static ASYNC_FUNCTION = 'asyncfunction';
+  static GENERATOR_FUNCTION = 'generatorfunction';
+  static ASYNC_GENERATOR_FUNCTION = 'asyncgeneratorfunction';
+  static CALLABLE = 'callable';
 
   // 3. Standard Built-ins
   static DATE = 'date';
@@ -56,6 +60,9 @@ export class Type {
     if (Array.isArray(expected)) {
       return expected.some(exp => Type.is(val, exp));
     }
+    if (expected === Type.CALLABLE || expected === 'callable') {
+      return Type.isCallable(val);
+    }
     if (typeof expected === 'function') {
       if (expected === Number) return typeof val === 'number' && !Number.isNaN(val);
       if (expected === Boolean) return typeof val === 'boolean' || val instanceof Boolean;
@@ -70,6 +77,16 @@ export class Type {
     return Type.of(val) === expected;
   }
 
+  /**
+   * Checks if a value is callable (regular function, async function, or generator).
+   * @param {*} val - Value to check.
+   * @returns {boolean} True if the value is any callable function.
+   */
+  static isCallable(val) {
+    const t = Type.of(val);
+    return t === 'function' || t === 'asyncfunction' || t === 'generatorfunction' || t === 'asyncgeneratorfunction';
+  }
+
   /**
    * Compares whether two values have the exact same canonical type.
    * Safely prevents JavaScript traps like typeof NaN === typeof 42 or typeof null === typeof {}.
@@ -109,3 +126,10 @@ export const of = Type.of;
  */
 export const same = Type.same;
 
+/**
+ * Checks if a value is callable (regular function, async function, or generator).
+ * @see {@link Type.isCallable}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JAZwMIEMA2OsBGOApggL4IBmMUYCARAAIDmA1gK4DGYIxMAXgHp2cEDjT0A3MFCZc+IsWlA|▶ Try it live in Instacode}
+ */
+export const isCallable = Type.isCallable;
+