feat: clamp() overload without min

.changeset/two-baboons-shout.md

@@ -0,0 +1,5 @@
+---
+"@sv443-network/userutils": minor
+---
+
+Added overload to `clamp()` without `min` parameter

README.md

@@ -956,10 +956,12 @@ setInnerHtmlUnsafe(myXssElement, userModifiableVariable);
 ### clamp()
 Usage:  
 ```ts
+clamp(num: number, max: number): number
 clamp(num: number, min: number, max: number): number
 ```
   
 Clamps a number between a min and max boundary (inclusive).  
+If only two arguments are passed, the function will set the `min` boundary to 0.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -967,13 +969,14 @@ Clamps a number between a min and max boundary (inclusive).
 import { clamp } from "@sv443-network/userutils";
 
 clamp(7, 0, 10);     // 7
+clamp(7, 10);        // 7
 clamp(-1, 0, 10);    // 0
 clamp(5, -5, 0);     // 0
 clamp(99999, 0, 10); // 10
 
-// clamp without a min or max boundary:
-clamp(-99999, -Infinity, 0); // -99999
-clamp(99999, 0, Infinity);   // 99999
+// clamp without either a min or max boundary:
+clamp(Number.MAX_SAFE_INTEGER, Infinity);     // 9007199254740991
+clamp(Number.MIN_SAFE_INTEGER, -Infinity, 0); // -9007199254740991
 ```
 </details>
 

lib/math.ts

@@ -1,5 +1,13 @@
 /** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} */
-export function clamp(value: number, min: number, max: number): number {
+export function clamp(value: number, min: number, max: number): number
+/** Ensures the passed {@linkcode value} always stays between 0 and {@linkcode max} */
+export function clamp(value: number, max: number): number
+/** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} - if `max` isn't given, it defaults to `min` and `min` defaults to 0 */
+export function clamp(value: number, min: number, max?: number): number {
+  if(typeof max !== "number") {
+    max = min;
+    min = 0;
+  }
   return Math.max(Math.min(value, max), min);
 }
 
@@ -14,12 +22,10 @@ export function mapRange(value: number, range1min: number, range1max: number, ra
  */
 export function mapRange(value: number, range1max: number, range2max: number): number;
 export function mapRange(value: number, range1min: number, range1max: number, range2min?: number, range2max?: number): number {
-  // overload
-  if(typeof range2min === "undefined" || range2max === undefined) {
+  if(typeof range2min === "undefined" || typeof range2max === "undefined") {
     range2max = range1max;
-    range2min = 0;
     range1max = range1min;
-    range1min = 0;
+    range2min = range1min = 0;
   }
 
   if(Number(range1min) === 0.0 && Number(range2min) === 0.0)
@@ -54,7 +60,7 @@ export function randRange(...args: (number | boolean | undefined)[]): number {
     [ max ] = args;
   }
   else
-    throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+    throw new TypeError(`Wrong parameter(s) provided - expected (number, boolean|undefined) or (number, number, boolean|undefined) but got (${args.map(a => typeof a).join(", ")}) instead`);
 
   if(typeof args[2] === "boolean")
     enhancedEntropy = args[2];