@gkucmierz/utils 2.3.1 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "2.3.1",
+  "version": "3.0.1",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -55,7 +55,7 @@
     "test": "jasmine",
     "watch": "nodemon --exec 'npm test'",
     "docs": "npm run docs:build; npm run docs:open",
-    "build:main": "node scripts/generate_main.mjs",
+    "build:main": "node scripts/generate_main.mjs && node scripts/generate_instacode_links.mjs",
     "docs:build": "jsdoc -c jsdoc.json && cp -r docs/@gkucmierz/utils/*/* docs/ && rm -rf docs/@gkucmierz",
     "docs:open": "open docs/index.html",
     "lint": "eslint .",
@@ -76,6 +76,7 @@
     "husky": "^8.0.3",
     "jasmine": "^4.4.0",
     "jsdoc": "^4.0.4",
+    "lz-string": "^1.5.0",
     "nodemon": "^3.1.14"
   }
 }

package/src/SetCnt.mjs

@@ -1,6 +1,7 @@
 /**
  * Set-like data structure built using Map with elements counter.
  * Allows adding multiple occurrences of the same element.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMoFM4GEB2iC+CAZjFGAgEQACA5gNYCuAxmCOjAF4D0DcIANgGcKAbmDAM2PGKA|▶ Try it live in Instacode}
  */
 export class SetCnt {
   #map = new Map();

package/src/Trie.mjs

@@ -1,6 +1,7 @@
 /**
  * Creates a Trie (prefix tree) data structure.
  * Implemented as a proper ES6 Class to fix prototyping documentation and encapsulate nodes.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4ICoxAUwQXwQMxijAQCIABAcwGsBXAYzCxgC8B6WuEAGwGdSA3MGDosQoA|▶ Try it live in Instacode}
  */
 export class Trie {
   static #HAS = 0;

package/src/array-histogram.mjs

@@ -5,6 +5,7 @@
  * @param {Array} arr Target array
  * @param {function} pick Projection callback (defaults to identity function)
  * @returns {Map} Histogram mapping
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIYxqgngCRAZzigHNMwEBfBAMxinICIABYgawFcBjMEAUxgBeAenZwQAG3wMA3MGDpMuAkVKowsoA|▶ Try it live in Instacode}
  */
 export const arrayHistogram = (iter, pick = el => el) => {
   const quant = new Map();

package/src/base64.mjs

@@ -4,6 +4,7 @@
  * Handles Unicode characters correctly.
  * @param {string} string - The string to encode.
  * @returns {string} The Base64 encoded string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LlAQgQwM4FMBsALAgL4IBmMUYCARAAIDmA1gK4DGYIuMAXgPSs4IADbZaAbmDA0WPESlA|▶ Try it live in Instacode}
  */
 export const toBase64 = string => {
   const codeUnits = new Uint16Array(string.length);
@@ -18,6 +19,7 @@ export const toBase64 = string => {
  * Handles Unicode characters correctly.
  * @param {string} encoded - The Base64 encoded string.
  * @returns {string} The decoded string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGYymAQgQwM4CmAbACwIC+aGYCARAAIDmA1gK4DGYIBMAXgPSs4IADZ5aAbmDB0mXIVJSgA|▶ Try it live in Instacode}
  */
 export const fromBase64 = encoded => {
   const binary = atob(encoded);
@@ -37,6 +39,7 @@ const toUrl = {
  * Replaces '+' with '-' and '/' with '_'.
  * @param {string} string - The string to encode.
  * @returns {string} The Base64Url encoded string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LlAQgQwM4FMBsALAKowA2CAvggGYxRgIBEAAgOYDWArgMZgi4YALwD0XOCDLYmAbmDA0WPEVJk5QA|▶ Try it live in Instacode}
  */
 export const toBase64Url = string => {
   return toBase64(string).replace(/[\+\/]/g, c => toUrl[c]);
@@ -51,6 +54,7 @@ const fromUrl = {
  * Replaces '-' with '+' and '_' with '/'.
  * @param {string} encoded - The Base64Url encoded string.
  * @returns {string} The decoded string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGYymAQgQwM4CmAbACwCqMANggL5oZgIBEAAgOYDWArgMZggEYALwD0XOCEp4mAbmDB0mXIVIVKcoA|▶ Try it live in Instacode}
  */
 export const fromBase64Url = encoded => {
   return fromBase64(encoded.replace(/[\-\_]/g, c => fromUrl[c]));

package/src/bijective-numeration.mjs

@@ -4,6 +4,7 @@
  * @param {number} num - The number to convert.
  * @param {string} [alpha='12'] - The alphabet to use for the conversion.
  * @returns {string} The bijective base-k string representation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYFcwCYBGIBWApgMZwgBuhCAvggGYxRgIBEAAgOYDW6xYIhGAC8A9OjIAbAM4sA3MGAZseIqQqF5QA|▶ Try it live in Instacode}
  */
 export const num2bijective = (num, alpha = '12') => {
   const len = alpha.length;
@@ -28,6 +29,7 @@ export const num2bijective = (num, alpha = '12') => {
  * @param {string} str - The bijective base-k string to convert.
  * @param {string} [alpha='12'] - The alphabet used for the conversion.
  * @returns {number} The numeric value of the string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgFYFMDGcQBuWATAHYCuYCAvggGYxRUBEAAgOYDW5OYIWMAF4B6cvgA2AZ2YBuYMHTY8hEhTBygA|▶ Try it live in Instacode}
  */
 export const bijective2num = (str, alpha = '12') => {
   const map = new Map([...alpha].map((c, i) => [c, i]));
@@ -43,6 +45,7 @@ export const bijective2num = (str, alpha = '12') => {
  * @param {bigint} num - The BigInt to convert.
  * @param {string} [alpha='12'] - The alphabet to use for the conversion.
  * @returns {string} The bijective base-k string representation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYFcwCYBGIBWApgMZwgBuhAQgJIIC+CAZjFGAgEQACA5gNbpiYEIRgAvAPToyAGwDOHANzBgGbHiKkK1GsqA|▶ Try it live in Instacode}
  */
 export const num2bijectiveBI = (num, alpha = '12') => {
   const len = BigInt(alpha.length);
@@ -67,6 +70,7 @@ export const num2bijectiveBI = (num, alpha = '12') => {
  * @param {string} str - The bijective base-k string to convert.
  * @param {string} [alpha='12'] - The alphabet used for the conversion.
  * @returns {bigint} The BigInt value of the string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgFYFMDGcQBuWATAHYCuYAQgJIIC+CAZjFGAgEQACA5gNbkcYEFhgAvAPTl8AGwDOHANzBg6bHkIkK1GsqA|▶ Try it live in Instacode}
  */
 export const bijective2numBI = (str, alpha = '12') => {
   const map = new Map([...alpha].map((c, i) => [c, BigInt(i)]));

package/src/binary-search.mjs

@@ -4,12 +4,13 @@
  * @param {Array<number>} arr - The sorted array to search in.
  * @param {number} target - The element to search for.
  * @returns {number} The index of the element if found, otherwise -1.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgHYEMYE8DKApjgMYAWAgjDAgL4IBmMUYCARAAIDmA1gK4kwIQjABeAej5wQAGwDObANzBg6bHiKlK1ZUA|▶ Try it live in Instacode}
  */
 export const binarySearchArr = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
   while (b - a > 0) {
-    const mid = (a + b) / 2 | 0;
+    const mid = Math.trunc((a + b) / 2);
     const val = arr[mid];
     if (target < val) {
       b = mid;
@@ -29,12 +30,13 @@ export const binarySearchArr = (arr, target) => {
  * @param {Array<number>} arr - The sorted array to search in.
  * @param {number} target - The target value.
  * @returns {number} The index of the found element.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgHYEMYE8DKApjgMYAWAMgKIIC+CAZjFGAgEQACA5gNYCuJMCEIwAXgHo+cEABsAzmwDcwYOmx4ipSlWVA|▶ Try it live in Instacode}
  */
 export const binarySearchLE = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
   while (b - a > 0) {
-    const mid = (a + b) / 2 | 0;
+    const mid = Math.trunc((a + b) / 2);
     const val = arr[mid];
     if (target < val) {
       b = mid;
@@ -52,12 +54,13 @@ export const binarySearchLE = (arr, target) => {
  * @param {Array<number>} arr - The sorted array to search in.
  * @param {number} target - The target value.
  * @returns {number} The index of the found element.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgHYEMYE8DKApjgMYAWA4gKIIC+CAZjFGAgEQACA5gNYCuJMCEIwAXgHo+cEABsAzmwDcwYOmx4ipSlWVA|▶ Try it live in Instacode}
  */
 export const binarySearchGE = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
   while (b - a > 0) {
-    const mid = (a + b) / 2 | 0;
+    const mid = Math.trunc((a + b) / 2);
     const val = arr[mid];
     if (target > val) {
       a = mid;
@@ -76,6 +79,7 @@ export const binarySearchGE = (arr, target) => {
  * @param {Array<number>} arr - The sorted array to search in.
  * @param {number} target - The target value.
  * @returns {Array<number>} An array containing the start and end indices of the range [start, end].
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgHYEMYE8DKApjgMYAWASlhgOaECSGJANggL4IBmMUYCARAAEaAawCuJMCEIwAXgHoxcEMwDO-ANzBg6bHiKlK1OoxZagA|▶ Try it live in Instacode}
  */
 export const binarySearchRangeIncl = (arr, target) => {
   return [
@@ -89,7 +93,7 @@ const binarySearchL = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
   while (b - a > 0) {
-    const mid = (a + b) / 2 | 0;
+    const mid = Math.trunc((a + b) / 2);
     const val = arr[mid];
     if (target <= val) {
       b = mid;
@@ -107,7 +111,7 @@ const binarySearchG = (arr, target) => {
   let [a, b] = [0, arr.length];
   let lm;
   while (b - a > 0) {
-    const mid = (a + b) / 2 | 0;
+    const mid = Math.trunc((a + b) / 2);
     const val = arr[mid];
     if (target >= val) {
       a = mid;

package/src/combinations.mjs

@@ -8,6 +8,7 @@
  * @param {number} n Size of the combination
  * @param {number} k Size of the set to choose from (indices 0 to k-1)
  * @yields {number[]} Array of indices
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZTAIxAOwIZwhQ4DOAknAKYwGwIC+CAZjBggEQACA5gNYCuqMCGoAvAPT9CAGxLsA3MGDosuAkVIVqtGIqA|▶ Try it live in Instacode}
  */
 export const combinationsIterator = function* (n, k) {
   if (n > k || n < 0) return;
@@ -35,6 +36,7 @@ export const combinationsIterator = function* (n, k) {
  * @param {number} n Size of the combination
  * @param {number} k Size of the set
  * @returns {Array<number[]>} Array containing all combinations
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZTAIxAOwIZwhQ4DOCAvggGYwYIBEAAgOYDWArqmCAKYwBeAenaEANiXoBuYMHRZcBIqWlA|▶ Try it live in Instacode}
  */
 export const combinations = (n, k) => {
   return [...combinationsIterator(n, k)];

package/src/consume-iterator.mjs

@@ -5,6 +5,7 @@
  * @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
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZQHYGcCuYCmAknPjAIZywBymAQgDZSoDWIGA5ggL4IBmMUMAgBEAAXbMcqMCFIAvAPQ44IelmEBuYMHTY8REuUowaGBk1YctQA|▶ Try it live in Instacode}
  */
 export const consumeIteratorNonBlocking = (iter, progressFn) => {
   return new Promise((resolve, reject) => {

package/src/copy-case.mjs

@@ -5,6 +5,7 @@
  * @param {string} word - The string to change the case of.
  * @param {string} from - The source string providing the case pattern.
  * @returns {string} The converted string.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZQgTwMIEMDOApggL4IBmMUYCARAAIDmA1gK6pgiEwBeA9KzggANvloBuYMHRY8RSUA|▶ Try it live in Instacode}
  */
 export const copyCase = (word, from) => {
   const isLower = w => w.toLowerCase() === w;

package/src/egcd.mjs

@@ -6,12 +6,13 @@
  * @param {number} a - The first number.
  * @param {number} b - The second number.
  * @returns {number[]} An array [gcd, x, y] such that ax + by = gcd.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYHMDGATBBfBAMxijAQCIABdAawFdMwRUYAvAejrhABsBncgG5gwDDmFA|▶ Try it live in Instacode}
  */
 export const egcd = (a, b) => {
   let [x, y] = [0, 1];
   let [u, v] = [1, 0];
   while (a !== 0) {
-    const [q, r] = [b/a | 0, b%a];
+    const [q, r] = [Math.trunc(b / a), b % a];
     const [m, n] = [x - u * q, y - v * q];
     [b, a, x, y, u, v] = [a, r, u, v, m, n];
   }

package/src/factors.mjs

@@ -3,6 +3,7 @@
  * Calculates the prime factorization of a number.
  * @param {number} n - The number to factorize.
  * @returns {number[]} An array of prime factors.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGYEMDGdYGcEC+aMUYCARAAIDmA1gK6ZggCmMAXgPT1wgA2ucgG5gwDNjwigA|▶ Try it live in Instacode}
  */
 export const factors = n => {
   if (n < 2) return [];
@@ -24,6 +25,7 @@ export const factors = n => {
  * Calculates the prime factorization of a BigInt.
  * @param {bigint} n - The BigInt to factorize.
  * @returns {bigint[]} An array of prime factors as BigInts.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGYEMDGdYGcBCAkggL5oxRgIBEAAgOYDWArpmCAKYwBeA9M3BAAbXNQDcwYBmx4iEoA|▶ Try it live in Instacode}
  */
 export const factorsBI = n => {
   if (n < 2n) return [];

package/src/format-big-number.mjs

@@ -26,6 +26,7 @@ const formatBigNumberBoth = (num, separator = '', wrapFn = _ => _) => {
  * @param {string} [separator=''] - The string to use as a thousand separator.
  * @param {function(string): string} [wrapFn=_=>_] - Optional function to wrap each part of the number.
  * @returns {string} The formatted number.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGazAQzgIRAcwDkBXMAIwFMYEBfNGKMBAIgAF8BrYgYzBCoBeAemJwQAGwDOzANzBg6GFlwES5KnKA|▶ Try it live in Instacode}
  */
 export const formatBigNumber = formatBigNumberBoth;
 
@@ -36,6 +37,7 @@ export const formatBigNumber = formatBigNumberBoth;
  * @param {string} [separator=''] - The string to use as a thousand separator.
  * @param {function(string): string} [wrapFn=_=>_] - Optional function to wrap each part of the number.
  * @returns {string} The formatted number.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGazAQzgIRAcwDkBXMAIwFMYcBJBAXzRijAQCIABfAa2IGMwIKgC8A9MTggANgGc2AbmDB0MLLgIlyVWoqA|▶ Try it live in Instacode}
  */
 export const formatBigNumberBI = formatBigNumberBoth;
 

package/src/gcd.mjs

@@ -20,6 +20,7 @@ const getGCD = ZERO => {
  * @param {number} a - The first number.
  * @param {number} b - The second number.
  * @returns {number} The GCD of a and b.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYGMAmCC+CBmMUYCARAAKoDWArumCAKYwBeA9DXCADYDOpAbmDAMmIUA|▶ Try it live in Instacode}
  */
 export const gcd = getGCD(0);
 
@@ -28,5 +29,6 @@ export const gcd = getGCD(0);
  * @param {bigint} a - The first BigInt.
  * @param {bigint} b - The second BigInt.
  * @returns {bigint} The GCD of a and b.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYGMAmAhAkggXwQDMYowEAiAAVQGsBXdMEAUxgC8B6BuEAGwDOlANzBgGHLjFA|▶ Try it live in Instacode}
  */
 export const gcdBI = getGCD(0n);

package/src/get-type.mjs

@@ -4,6 +4,7 @@
  * More specific than the typeof operator (e.g., distinguishes 'array', 'null', 'date').
  * @param {*} val - The value to check.
  * @returns {string} The type of the value.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYFM4BUCeF0IC+CAZjFGAgEQACqA1gK4DGYI6MAXgPSNwgAbAM5UA3MGAZsedOKA|▶ Try it live in Instacode}
  */
 export const getType = val => {
   const str = Object.prototype.toString.call(val);

package/src/golden-ratio.mjs

@@ -3,6 +3,7 @@ import { squareRootBI } from './square-root.mjs';
 /**
  * The standard float approximation of the Golden Ratio (phi).
  * @constant {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOZQDYBMCmA7AJQEM4QoEBfBAMxijAQCIABVAawFcBjMEHGAF4B6DqQwBnRgG5gwdNnzFSUGUA|▶ Try it live in Instacode}
  */
 export const goldenRatio = ((5 ** 0.5) + 1) / 2;
 
@@ -14,6 +15,7 @@ export const goldenRatio = ((5 ** 0.5) + 1) / 2;
  * @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.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOZQDYBMCmA7AJQEM4QoAhASQQF8EAzGKMBAIgAFUBrAVwGMwIHDABeAeh6kMAZ1YBuYMHTZ8xUhUoKgA|▶ Try it live in Instacode}
  */
 export const goldenRatioBI = precision => {
   if (precision < 0) throw new Error('Precision cannot be negative');

package/src/gpn.mjs

@@ -17,6 +17,7 @@ const getGpn = (zero, one, two, three) => {
  * https://oeis.org/A001318
  * @param {number} n - The index of the sequence (0-based).
  * @returns {number} The n-th generalized pentagonal number.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYQHYIL4IGYxRgIBEAAqgNYCuAxmCAKYwBeA9NXCADYDOJAbmDB0GIUA|▶ Try it live in Instacode}
  */
 export const gpn = getGpn(0, 1, 2, 3);
 
@@ -24,5 +25,6 @@ export const gpn = getGpn(0, 1, 2, 3);
  * Generalized Pentagonal Numbers (GPN) - BigInt version.
  * @param {bigint} n - The index of the sequence (0-based).
  * @returns {bigint} The n-th generalized pentagonal number.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYQHYCECSCC+CAZjFGAgEQACqA1gK4DGYIApjAF4D09cIANgGcKAbmDB02HGKA|▶ Try it live in Instacode}
  */
 export const gpnBI = getGpn(0n, 1n, 2n, 3n);

package/src/gray-code.mjs

@@ -11,6 +11,7 @@ const convertBit = (p, v, i) => {
  * 
  * @param {Array<number|boolean>} bits Binary representation (MSB at index 0)
  * @returns {Array<number>} Array of Gray code bits
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IEYgHYCYDmMCGAnggL4IBmMUYCARAAI4DWArgMZggCmMAXgPQs4IADYBnWgG5gwdNjxFpQA|▶ Try it live in Instacode}
  */
 export const bin2gray = (bits) => {
   // Cloning array mathematically to prevent pure-function reference mutation
@@ -22,6 +23,7 @@ export const bin2gray = (bits) => {
  * 
  * @param {Array<number|boolean>} gray Gray Code representation
  * @returns {Array<number>} Decoded original binary bits
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IOYwIYE8BMAjEAOwQF8EAzGKMBAIgAFUBrAVwGMwQBTGALwHoWcEABsAzrQDcwYOmz4i0oA|▶ Try it live in Instacode}
  */
 export const gray2bin = (gray) => {
   return [...gray].reduce(convertBit, [...gray]);

package/src/heap.mjs

@@ -2,6 +2,7 @@
  * Creates a Min Heap data structure.
  * Implemented as a ES6 Class to fix prototyping documentation 
  * and properly encapsulate internal mechanics.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IBIFMCGEEF8EBmMUYCARAAIDmA1gK4DGYI6MAXgPR1wgA2AzmQDcwYBmwigA|▶ Try it live in Instacode}
  */
 export class Heap {
   #arr = [-1];
@@ -17,7 +18,7 @@ export class Heap {
 
   #up(idx) {
     while (idx > 1) {
-      const ni = idx / 2 | 0;
+      const ni = Math.trunc(idx / 2);
       if (this.#valFn(this.#arr[idx]) < this.#valFn(this.#arr[ni])) {
         [this.#arr[idx], this.#arr[ni]] = [this.#arr[ni], this.#arr[idx]];
       }

package/src/herons-formula.mjs

@@ -16,6 +16,7 @@ const getHeronsFormula = (four, sq) => (a, b, c) => {
  * @param {number} b - Length of side b.
  * @param {number} c - Length of side c.
  * @returns {number} The area of the triangle.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IBYFMZQHYGcBisYArgDYCGCAvggGZZgIBEAAgOYDWxAxmCJgC8A9MTghSuJgG5gwDFjyEYJCjKA|▶ Try it live in Instacode}
  */
 export const heronsFormula = getHeronsFormula(4, n => n ** 0.5);
 
@@ -26,5 +27,6 @@ export const heronsFormula = getHeronsFormula(4, n => n ** 0.5);
  * @param {bigint} b - Length of side b.
  * @param {bigint} c - Length of side c.
  * @returns {bigint} The area of the triangle.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IBYFMZQHYGcBisYArgDYCGAQgJIIC+CAZlmAgEQACA5gNbEDGYEJgBeAemJwQpXGwDcwYBix5CMEhRoKgA|▶ Try it live in Instacode}
  */
 export const heronsFormulaBI = getHeronsFormula(4n, squareRootBI);

package/src/langtons-ant.mjs

@@ -3,6 +3,7 @@
  * Ideal for sparse matrices or algorithms operating on an infinite plane (e.g., Langton's Ant, Game of Life).
  * 
  * @returns {Object} An object containing `get(x, y)` and `set(x, y, val)` methods.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMYwKYEM4YKoB2ANuCLgCYDiMI5CAvggGYxRgIBEAAgOYDWAV1RgQGGAC8A9ALggiAZw4BuYMHTZchEiIrVaKoA|▶ Try it live in Instacode}
  */
 export const createUnlimitedGrid = () => {
   const grid = new Map();
@@ -38,6 +39,7 @@ export const createUnlimitedGrid = () => {
  * @param {number} startY - The initial Y coordinate of the ant.
  * @param {number} [initialDir=-1] - The initial direction (0: TOP, 1: RIGHT, 2: BOTTOM, 3: LEFT). If -1, a random direction is chosen.
  * @returns {Object} An object containing a `step()` method which advances the simulation by one tick and returns `{x, y, state}` of the modified cell.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMYwKYEM4YDJYB2A5nFIQM4CChiAvggGYxRgIBEAAsQNYCuqMCAwwAXgHo+cEABsK7ANzBg6bLgIkylGnCVA|▶ Try it live in Instacode}
  */
 export const createLangtonsAnt = (grid, startX, startY, initialDir = -1) => {
   const [X, Y] = [0, 1];

package/src/lcm.mjs

@@ -15,6 +15,7 @@ const getLcm = gcd => {
  * @param {number} a - The first number.
  * @param {number} b - The second number.
  * @returns {number} The LCM of a and b.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IDYGMwIL4IGYxRYBEAAgOYDWArpiAKYwBeA9NXCKgM7EDcwwDGH5A|▶ Try it live in Instacode}
  */
 export const lcm = getLcm(gcd);
 
@@ -23,5 +24,6 @@ export const lcm = getLcm(gcd);
  * @param {bigint} a - The first BigInt.
  * @param {bigint} b - The second BigInt.
  * @returns {bigint} The LCM of a and b.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IDYGMwCECSCC+CAZjFGAgEQACA5gNYCumIApjAF4D0DcIqAzhQDcwYBmw4RQA|▶ Try it live in Instacode}
  */
 export const lcmBI = getLcm(gcdBI);

package/src/list-node.mjs

@@ -2,6 +2,7 @@
 
 /**
  * Represents a node in a singly linked list.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IDIgM5wHJQCYCmCAvggGYxRgIBEAAgOYDWArgMZggEwBeA9CzggANhhoBuYMHRZchSUA|▶ Try it live in Instacode}
  */
 export class ListNode {
   /**

package/src/lucas-lehmer.mjs

@@ -4,6 +4,7 @@
  * @param {number|bigint} exp - The exponent p of the Mersenne number M_p.
  * @param {boolean} [verbose=false] - If true, logs the calculation progress.
  * @returns {boolean} True if the Mersenne number is prime, false otherwise.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IDYFcDGBDAzgGQFMALMQmAIQEkEBfBAMxijAQCIABAcwGsswQ5AF4B6dHBCpcbANzBgGHARJlKVOUA|▶ Try it live in Instacode}
  */
 export const lucasLehmerBI = (exp, verbose = false) => {
   const steps = exp - 2;

package/src/math3d.mjs

@@ -1,5 +1,6 @@
 /**
  * Pure 3D Math Engine for Arcball/Trackball raw matrix transformations
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMYygZ0wBQwEwFdVEBfBAMwzAQCIABAcwGtiwQBTGALwHpC4IADaZaAbmDB0WXAWJwJQA|▶ Try it live in Instacode}
  */
 
 export const crossProduct = (u, v) => [

package/src/matrix.mjs

@@ -5,6 +5,7 @@
  * Allows accessing elements using a single index (row-major order).
  * @param {Array<Array<*>>} matrix - The 2D matrix to wrap.
  * @returns {Proxy} A proxy that behaves like a flat array.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LAQzjEAPAggZ1xhjQE8EBfBAMxijAQCIABAcwGsBXAYzBAFMYALwD0nOCAA2+RgG5gwdJhwEiJUvKA|▶ Try it live in Instacode}
  */
 export const matrixAsArray = matrix => {
   const [h, w] = [matrix.length, matrix[0].length];

package/src/measure-performance.mjs

@@ -2,10 +2,12 @@
  * 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).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LAUwIYGcCuM0AKaMAZrGBgHYDGaCAvgiTFGAgEQACA5gNY7UwIYgC8A9DjggANlnYBuYMHTY8hYmRgUaaRUA|▶ Try it live in Instacode}
  */
 export const measurePerformance = (fn, steps = 1e8, memo = 'noop') => {
   const t1 = Date.now();

package/src/memoize.mjs

@@ -5,6 +5,7 @@
  * Compares arguments by reference.
  * @param {Function} fn - The function to memoize.
  * @returns {Function} The memoized function.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LAUzFEAvNCC+CAZjFGAgEQACA5gNYCuAxmCGjNgPQNwgA2AZwoBuYMHSYcaUUA|▶ Try it live in Instacode}
  */
 export const memoize = fn => {
   const maps = [];

package/src/mod.mjs

@@ -14,6 +14,7 @@ const getMod = ZERO => {
  * @param {number} dividend - The dividend.
  * @param {number} divisor - The divisor.
  * @returns {number} The result of the modulo operation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LFAJggvggZjKMBAIgAEBzAawFcBjMEAUxgC8B6auEAGwGdiA3MGBp0QoA|▶ Try it live in Instacode}
  */
 export const mod = getMod(0);
 
@@ -22,5 +23,6 @@ export const mod = getMod(0);
  * @param {bigint} dividend - The dividend.
  * @param {bigint} divisor - The divisor.
  * @returns {bigint} The result of the modulo operation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LFAJgIQJIIL4IBmMUYCARAAIDmA1gK4DGYIApjAF4D09cIANgGdyAbmDA0WbGKA|▶ Try it live in Instacode}
  */
 export const modBI = getMod(0n);

package/src/n-choose-k.mjs

@@ -7,6 +7,7 @@
  * @param {number|bigint|string} n Total elements
  * @param {number|bigint|string} k Elements to pick
  * @returns {bigint} Total possible subset combinations
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYGEAWUoGcCmA0ggL4IBmMUYCARAAIDmA1gK4DGYI+MAXgPSs4IADa5aAbmDAM2PESlA|▶ Try it live in Instacode}
  */
 export const nChooseK = (n, k) => {
   const bigN = BigInt(n);

package/src/natural-search.mjs

@@ -5,6 +5,7 @@
  * @param {Function} cond - The condition evaluator function.
  * @param {Boolean} [retFirstTrue=true] - If true, returns the first match bounding condition true.
  * @returns {Number} The optimized integer step boundary that satisfies the condition structure.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYEM4FcboDYDKApujAMYAWCAvggGYxRgIBEAAgOYDWWZYIRGAC8A9Fjgg8AZxYBuYMAzZchEuQrygA|▶ Try it live in Instacode}
  */
 export const naturalSearch = (cond, retFirstTrue = true) => {
   let min = 1;

package/src/nelder-mead.mjs

@@ -6,6 +6,7 @@
  * @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}>}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IHYFMA2ATdMCy6AhtggL4IBmMUYCARAAIDmA1gK4DGYIeAXgHp2cEJgDO9ANzBgGHHkIlpQA|▶ Try it live in Instacode}
  */
 export const nelderMead = async (evaluate, bounds, options = {}) => {
   const steps = options.steps || 30;

package/src/particle-swarm.mjs

@@ -6,6 +6,7 @@
  * @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}>}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IgQ3iAxgGwKYDKA7hmAPIRzggBeaVUAdggL4IBmMUYCARAAIBzANYBXLGBB4YNAPSiqOAM68A3MGDpMuQiRjlK1Og0bqgA|▶ Try it live in Instacode}
  */
 export const particleSwarmOptimization = async (evaluate, bounds, options = {}) => {
   const numParticles = options.particles || 12;

package/src/permutations.mjs

@@ -3,6 +3,7 @@
  * 
  * @param {number|Array} sizeOrArr Integer size or an array of items
  * @yields {Array} Re-arranged array of items/indices
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IgUxmArnAhnEKAOwGcBJODfWBAXwQDMYowEAiAAQHMBrLAYzAgMALwD0OEABsSbANzBg6TDnyFSFKnFgKgA|▶ Try it live in Instacode}
  */
 export const permutationsIterator = function*(sizeOrArr) {
   const arr = Array.isArray(sizeOrArr) ? [...sizeOrArr] : new Array(sizeOrArr).fill(0).map((_, i) => i);
@@ -28,6 +29,7 @@ export const permutationsIterator = function*(sizeOrArr) {
  * 
  * @param {number|Array} sizeOrArr 
  * @returns {Array<Array>} Array of permutation sets
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IgUxmArnAhnEKAOwGcEBfBAMxijAQCIABAcwGssBjMEDALwD0OEABsSDANzBg6TDnyFSUoA|▶ Try it live in Instacode}
  */
 export const permutations = (sizeOrArr) => {
   return [...permutationsIterator(sizeOrArr)];

package/src/phi.mjs

@@ -37,6 +37,7 @@ const getPhiEuler = factors => {
  * Uses Euler's product formula based on prime factorization.
  * @param {number} n - The number to calculate phi for.
  * @returns {number} The value of phi(n).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IgCxAgvggZjKMBAIgAEBzAawFcBjMEAUxgC8B6auEAGwGdiA3MGDoQQoA|▶ Try it live in Instacode}
  */
 export const phi = getPhiEuler(factors);
 
@@ -44,6 +45,7 @@ export const phi = getPhiEuler(factors);
  * Euler's Totient Function (Phi) - BigInt version.
  * @param {bigint} n - The BigInt to calculate phi for.
  * @returns {bigint} The value of phi(n).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IgCxAIQJIIL4IBmMUYCARAAIDmA1gK4DGYIApjAF4D09cIANgGdyAbmDB0WbGKA|▶ Try it live in Instacode}
  */
 export const phiBI = getPhiEuler(factorsBI);
 

package/src/pow-mod.mjs

@@ -3,6 +3,7 @@
 
 const getPowMod = (ZERO, ONE, TWO, floor) => {
   return (base, exponent, modulus = null) => {
+    if (exponent < ZERO) throw new RangeError('Negative exponent is not supported');
     if (modulus === null) return base ** exponent;
     if (modulus === ONE) return ZERO;
     let result = ONE;
@@ -25,6 +26,7 @@ const getPowMod = (ZERO, ONE, TWO, floor) => {
  * @param {number} exponent - The exponent.
  * @param {number} [modulus] - The optional modulus.
  * @returns {number} The result of (base ** exponent) % modulus.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4OgdwLJQCYIL4IBmMUYCARAAIDmA1gK4DGYIApjAF4D09cIANgGdyAbmDB0WbGKA|▶ Try it live in Instacode}
  */
 export const powMod = getPowMod(0, 1, 2, n => Math.floor(n));
 
@@ -35,5 +37,6 @@ export const powMod = getPowMod(0, 1, 2, n => Math.floor(n));
  * @param {bigint} exponent - The exponent BigInt.
  * @param {bigint} [modulus] - The optional modulus BigInt.
  * @returns {bigint} The result of (base ** exponent) % modulus.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4OgdwLJQCYCECSCAvggGYxRgIBEAAgOYDWArgMZggCmMAXgPTM4IADYBnagG5gwdFjz4pQA|▶ Try it live in Instacode}
  */
 export const powModBI = getPowMod(0n, 1n, 2n, n => n);

package/src/rand-normal.mjs

@@ -4,6 +4,7 @@
  * @param {number} [mean=0] - The mean of the normal distribution.
  * @param {number} [sigma=1] - The standard deviation of the normal distribution.
  * @returns {number} A random number from the specified normal distribution.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JgQwHYBMBysxoA2CAvggGYxRgIBEAAgOYDWArgMZggCmMAXgHpWcEIQDOtANzBg6bHhgFC0oA|▶ Try it live in Instacode}
  */
 export const randNormal = (mean = 0, sigma = 1) => {
   const y1 = Math.random();

package/src/range-array.mjs

@@ -5,6 +5,7 @@
  * Converts a list of ranges into a flat array of numbers.
  * @param {Array<Array<number>>} ranges - An array of ranges, where each range is [min, max] or [min].
  * @returns {Array<number>} An array containing all numbers in the specified ranges.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JgQwHYHMCmAmNGdATwQF8EAzGKMBAIgAEsBrAVwGMwQcYAvAPRs4IADYBnegG5gwdNnyESMoA|▶ Try it live in Instacode}
  */
 export const range2array = ranges => {
   return ranges.reduce((arr, range) => {
@@ -22,6 +23,7 @@ export const range2array = ranges => {
  * Isolated numbers are represented as [num, num].
  * @param {Array<number>} arr - The sorted array of numbers.
  * @returns {Array<Array<number>>} An array of ranges.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIYxqgngJkwOwHMBTBAXwQDMYowEAiAAUIGsBXAYzBGJgC8A9GzggANgGd6AbmDB0mXARIygA|▶ Try it live in Instacode}
  */
 export const array2range = arr => {
   const ranges = [];

package/src/set-safe-interval.mjs

@@ -8,6 +8,7 @@
  * @param {boolean} [immediate=true] - Whether to fire the first execution immediately
  * @param {boolean} [nextTick=false] - If immediate is true, whether to yield to the event loop before the first execution
  * @returns {Function} A function to clear the interval
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM4FM4GUCGAzdASQDs50YA3HAGwQF8E8YowEAiAAQHMBrAVwDGYEOQBeAej5wQ1VGwDcwYBmz4ipclWqKgA|▶ Try it live in Instacode}
  */
 export const setSafeInterval = (cb, delay, immediate = true, nextTick = false) => {
   let isCleared = false;

package/src/simulated-annealing.mjs

@@ -6,6 +6,7 @@
  * @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}>}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM7gK4BsCGcCmAJgIIB2p+OWIpA5ggL4IBmMUYCARAAK0DWGAMZgQ+GAC8A9BjggsqTgG5gwdGGx4iZClRq1lQA|▶ Try it live in Instacode}
  */
 export const simulatedAnnealing = async (evaluate, bounds, options = {}) => {
   const steps = options.steps || 100;

package/src/square-root.mjs

@@ -4,6 +4,7 @@
  * Calculates the square root of a number.
  * @param {number} n - The number to calculate the square root of.
  * @returns {number} The square root of n.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM4EcCuBDGBTAJSikQF8EAzGKMBAIgAEBzAa0wGMwQ8YAvAekxwQAG1R0A3MGAYc+IiSlA|▶ Try it live in Instacode}
  */
 export const squareRoot = n => n ** 0.5;
 
@@ -11,8 +12,10 @@ export const squareRoot = n => n ** 0.5;
  * Calculates the integer square root of a BigInt using Newton's method.
  * @param {bigint} n - The BigInt to calculate the square root of.
  * @returns {bigint} The integer square root of n.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM4EcCuBDGBTAJSijgCEBJBAXwQDMYowEAiAAQHMBrTAYzBDwwAXgHpMcEABtUzANzBgGHPiIkK8oA|▶ Try it live in Instacode}
  */
 export const squareRootBI = n => {
+  if (n < 0n) throw new RangeError('Square root of negative numbers is not supported');
   if (n === 0n) return 0n;
   if (n < 4n) return 1n;
   if (n < 9n) return 2n;

package/src/tonelli-shanks.mjs

@@ -9,6 +9,7 @@ import {
  * @param {bigint} n - The number to find the square root of.
  * @param {bigint} p - The modulus (must be an odd prime).
  * @returns {bigint} The square root r such that r^2 = n (mod p), or 0n if no solution exists.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4LlAdgUwDbZAZQAsBDdAawGcAhASQQF8EAzGKMBAIgAEBzMgVwDGYEJhgAvAPT84IbBQ4BuYMDRZcBEuWo1lQA|▶ Try it live in Instacode}
  */
 export const tonelliShanksBI = (n, p) => {
   let s = 0n;