@gkucmierz/utils 1.28.3 → 1.28.8

package/src/list-node.mjs

@@ -1,11 +1,25 @@
 
 
+/**
+ * Represents a node in a singly linked list.
+ */
 export class ListNode {
+  /**
+   * Creates a new ListNode.
+   * @param {*} [val=0] - The value of the node.
+   * @param {ListNode} [next=null] - The next node in the list.
+   */
   constructor(val = 0, next = null) {
     this.val = val;
     this.next = next;
   }
   
+  /**
+   * Converts the linked list to an array.
+   * Detects cycles and throws an error if one is found.
+   * @returns {Array} An array containing the values of the list nodes.
+   * @throws {Error} If a cyclic reference is detected.
+   */
   toArr() {
     const ret = [];
     let node = this;
@@ -19,6 +33,11 @@ export class ListNode {
     return ret;
   }
   
+  /**
+   * Creates a linked list from an iterable.
+   * @param {Iterable} iter - The iterable to create the list from.
+   * @returns {ListNode|null} The head of the created linked list, or null if empty.
+   */
   static fromArr(iter) {
     const head = new ListNode;
     let node = head;

package/src/matrix.mjs

@@ -1,8 +1,11 @@
 
 
-// represent matrix as array using Proxy
-// todo: iterator can be added
-
+/**
+ * Represents a 2D matrix as a flat 1D array using a Proxy.
+ * 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.
+ */
 export const matrixAsArray = matrix => {
   const [h, w] = [matrix.length, matrix[0].length];
   return new Proxy([], {

package/src/memoize.mjs

@@ -1,10 +1,10 @@
 
 /**
- * Memoize function, that builds tree structure for arguments
- * and compares arguments by reference
- * @method
- * @param {Function} Function to memoize
- * @return {Function} Memoized function
+ * Creates a memoized version of a function.
+ * Uses a tree structure to store results based on arguments.
+ * Compares arguments by reference.
+ * @param {Function} fn - The function to memoize.
+ * @returns {Function} The memoized function.
  */
 export const memoize = fn => {
   const maps = [];

package/src/mod.mjs

@@ -10,23 +10,17 @@ const getMod = ZERO => {
 };
 
 /**
- * Python like modulo implementation.
- * It behaves different than JavaScript %
- * with negative values
- * @method
- * @param {Number} Dividend
- * @param {Number} Divisor
- * @return {Number} Modulus
+ * Calculates the modulo of two numbers (Python-like behavior for negative numbers).
+ * @param {number} dividend - The dividend.
+ * @param {number} divisor - The divisor.
+ * @returns {number} The result of the modulo operation.
  */
 export const mod = getMod(0);
 
 /**
- * Python like modulo implementation.
- * It behaves different than JavaScript %
- * with negative values
- * @method
- * @param {BigInt} Dividend
- * @param {BigInt} Divisor
- * @return {BigInt} Modulus
+ * Calculates the modulo of two BigInts (Python-like behavior for negative numbers).
+ * @param {bigint} dividend - The dividend.
+ * @param {bigint} divisor - The divisor.
+ * @returns {bigint} The result of the modulo operation.
  */
 export const modBI = getMod(0n);

package/src/phi.mjs

@@ -31,7 +31,20 @@ const getPhiEuler = factors => {
   };
 };
 
+/**
+ * Euler's Totient Function (Phi).
+ * Counts the positive integers less than or equal to n that are relatively prime to n.
+ * 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).
+ */
 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).
+ */
 export const phiBI = getPhiEuler(factorsBI);
 
 // export const phi = getPhi(1, 2, gcd);

package/src/pow-mod.mjs

@@ -19,21 +19,21 @@ const getPowMod = (ZERO, ONE, TWO, floor) => {
 };
 
 /**
- * Power like python implementation with optional modulus
- * @method
- * @param {Number} Base
- * @param {Number} Exponent
- * @param [Number] Modulus
- * @return {Number} Power
+ * Calculates the power of a base to an exponent, optionally modulo a number.
+ * Similar to Python's pow(base, exponent, modulus).
+ * @param {number} base - The base number.
+ * @param {number} exponent - The exponent.
+ * @param {number} [modulus] - The optional modulus.
+ * @returns {number} The result of (base ** exponent) % modulus.
  */
 export const powMod = getPowMod(0, 1, 2, n => Math.floor(n));
 
 /**
- * Power like python implementation with optional modulus
- * @method
- * @param {BigInt} Base
- * @param {BigInt} Exponent
- * @param [BigInt] Modulus
- * @return {BigInt} Power
+ * Calculates the power of a base to an exponent, optionally modulo a BigInt.
+ * Similar to Python's pow(base, exponent, modulus).
+ * @param {bigint} base - The base BigInt.
+ * @param {bigint} exponent - The exponent BigInt.
+ * @param {bigint} [modulus] - The optional modulus BigInt.
+ * @returns {bigint} The result of (base ** exponent) % modulus.
  */
 export const powModBI = getPowMod(0n, 1n, 2n, n => n);

package/src/range-array.mjs

@@ -1,6 +1,11 @@
 
 // https://www.codewars.com/kata/57d83dfc950d842dcb00005b/train/javascript
 
+/**
+ * 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.
+ */
 export const range2array = ranges => {
   return ranges.reduce((arr, range) => {
     const min = range[0];
@@ -11,6 +16,13 @@ export const range2array = ranges => {
   }, []);
 };
 
+/**
+ * Converts a sorted array of numbers into a list of ranges.
+ * Consecutive numbers are grouped into a single range [min, max].
+ * Isolated numbers are represented as [num, num].
+ * @param {Array<number>} arr - The sorted array of numbers.
+ * @returns {Array<Array<number>>} An array of ranges.
+ */
 export const array2range = arr => {
   const ranges = [];
   let last = arr[0];

package/src/square-root.mjs

@@ -1,18 +1,16 @@
 
 
 /**
- * Native square root
- * @function
- * @param {Number} number - js double number
- * @return {Number} result
+ * 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.
  */
 export const squareRoot = n => n ** 0.5;
 
 /**
- * Calculate square root using Newton's formula
- * @function
- * @param {BigInt} number - big integer number
- * @return {BigInt} result
+ * 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.
  */
 export const squareRootBI = n => {
   if (n === 0n) return 0n;

package/src/tonelli-shanks.mjs

@@ -3,8 +3,13 @@ import {
   powModBI,
 } from './pow-mod.mjs';
 
-/* Takes as input an odd prime p and n < p and returns r
- * such that r * r = n [mod p]. */
+/**
+ * Computes the modular square root of n modulo p using the Tonelli-Shanks algorithm.
+ * Solves the congruence r^2 = n (mod p) where p is an odd prime.
+ * @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.
+ */
 export const tonelliShanksBI = (n, p) => {
   let s = 0n;
   let q = p - 1n;

package/.github/workflows/deploy-docs.yml

@@ -1,22 +0,0 @@
-name: Deploy docs
-on:
-  push:
-    branches:
-      - main # Change this to your default branch
-jobs:
-  build-and-deploy:
-    concurrency: ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
-
-      - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
-        run: |
-          npm i
-          npm run docs:build
-
-      - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          folder: docs # The folder the action should deploy.

package/.github/workflows/npm-publish.yml

@@ -1,25 +0,0 @@
-name: npm-publish
-on:
-  push:
-    branches:
-      - main # Change this to your default branch
-jobs:
-  npm-publish:
-    name: npm-publish
-    runs-on: ubuntu-latest
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2
-    - name: Publish if version has been updated
-      uses: pascalgn/npm-publish-action@1.3.9
-      with: # All of theses inputs are optional
-        tag_name: "v%s"
-        tag_message: "v%s"
-        create_tag: "true"
-        commit_pattern: "^Release (\\S+)"
-        workspace: "."
-        publish_command: "yarn"
-        publish_args: "--non-interactive --access public"
-      env: # More info about the environment variables in the README
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this as is, it's automatically generated
-        NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }} # You need to set this in your repo settings

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm test

package/jsdoc.json

@@ -1,10 +0,0 @@
-{
-  "source": {
-    "include": ["src"],
-    "includePattern": ".+\\.(js(doc|x)?|mjs)$"
-  },
-  "opts": {
-    "destination": "./docs/",
-    "template": "node_modules/docdash"
-  }
-}