Added clamp and roundPrecision utility functions (#43)

Closes #27

Author: drebrez

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### dependabot: \#41 Bump micromatch from 4.0.5 to 4.0.8
 
 - added `parseBool` utility function
+- added `clamp` and `roundPrecision` utility functions
 
 ## [0.6.0] - 2024-06-26
 

src/index.ts

@@ -3,5 +3,6 @@ export * from "./lib/date";
 export * from "./lib/enum";
 export * from "./lib/guid";
 export * from "./lib/localStorage";
+export * from "./lib/number";
 export * from "./lib/object";
 export * from "./lib/string";

src/lib/number.spec.ts

@@ -0,0 +1,63 @@
+import { clamp, roundPrecision } from "./number";
+
+describe("number tests", () => {
+  test.each([
+    [null as unknown as number, null as unknown as number, null as unknown as number, 0],
+    [null as unknown as number, null as unknown as number, 2, 0],
+    [null as unknown as number, 1, 2, 1],
+    [undefined as unknown as number, undefined as unknown as number, undefined as unknown as number, Number.NaN],
+    [undefined as unknown as number, undefined as unknown as number, 2, Number.NaN],
+    [undefined as unknown as number, 1, 2, Number.NaN],
+    [1, undefined as unknown as number, undefined as unknown as number, Number.NaN],
+    [1, undefined as unknown as number, 2, Number.NaN],
+    [1, 1, undefined as unknown as number, Number.NaN],
+    ["test" as unknown as number, "test" as unknown as number, "test" as unknown as number, Number.NaN],
+    ["test" as unknown as number, 1, 2, Number.NaN],
+    [1, "test" as unknown as number, "test" as unknown as number, Number.NaN],
+    [-1, -1, 1, -1],
+    [0, -1, 1, 0],
+    [1, -1, 1, 1],
+    [-2, -1, 1, -1],
+    [2, -1, 1, 1],
+  ])("clamp", (value, min, max, expected) => {
+    expect(clamp(value, min, max)).toBe(expected);
+  });
+
+  test("clamp min greater than max", () => {
+    expect(() => {
+      clamp(0, 1, 0);
+    }).toThrow("'1' cannot be greater than '0'.");
+  });
+
+  test.each([
+    [null as unknown as number, null as unknown as number, 0],
+    [null as unknown as number, 2, 0],
+    [2, null as unknown as number, 2],
+    [undefined as unknown as number, undefined as unknown as number, Number.NaN],
+    [undefined as unknown as number, 2, Number.NaN],
+    [2, undefined as unknown as number, Number.NaN],
+    [0, 0, 0],
+    [0, 1, 0],
+    [0, 2, 0],
+    [0.4, 0, 0],
+    [0.4, 1, 0.4],
+    [0.4, 2, 0.4],
+    [0.5, 0, 1],
+    [0.5, 1, 0.5],
+    [0.5, 2, 0.5],
+    [0.44, 0, 0],
+    [0.44, 1, 0.4],
+    [0.44, 2, 0.44],
+    [0.45, 0, 0],
+    [0.45, 1, 0.5],
+    [0.45, 2, 0.45],
+    [0.454, 0, 0],
+    [0.454, 1, 0.5],
+    [0.454, 2, 0.45],
+    [0.455, 0, 0],
+    [0.455, 1, 0.5],
+    [0.455, 2, 0.46],
+  ])("roundPrecision", (value, precision, expected) => {
+    expect(roundPrecision(value, precision)).toBe(expected);
+  });
+});

src/lib/number.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns a number whose value is limited to the given range
+ * @param value The initial value
+ * @param min The lower boundary
+ * @param max The upper boundary
+ * @returns A number in the range (min, max)
+ */
+export function clamp(value: number, min: number, max: number): number {
+  if (min > max) {
+    throw new Error(`'${min}' cannot be greater than '${max}'.`);
+  }
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Round a number with the specified precision
+ * @param value The number to round
+ * @param precision The desired precision
+ * @returns The number rounded with the specified precision
+ */
+export function roundPrecision(value: number, precision: number): number {
+  const multiplier = Math.pow(10, precision);
+  return Math.round(value * multiplier) / multiplier;
+}