add findLastIndex and inRange utility functions to fast-web-utilities (…

…microsoft#5528)

* add findLastIndex function to fast-web-utilities

* add inRange function to fast-web-utilities

* Change files

* remove instance type check

* restore non-optional parameters

TS environments with strictNullChecks will throw errors if these parameters are optional.

change/@microsoft-fast-web-utilities-e9facd80-2d8e-4553-ae3d-8d06ad809738.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "add findLastIndex and inRange functions to fast-web-utilities",
+  "packageName": "@microsoft/fast-web-utilities",
+  "email": "john.kreitlow@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/utilities/fast-web-utilities/src/array.spec.ts

@@ -0,0 +1,30 @@
+import { expect } from "chai";
+import { findLastIndex } from "./array";
+
+describe("findLastIndex", (): void => {
+    it("should return -1 when array is empty", (): void => {
+        expect(findLastIndex([], () => true)).to.equal(-1);
+    });
+
+    it("should return the last valid item that matches the predicate", (): void => {
+        const array = [
+            { value: true },
+            { value: false },
+            { value: true },
+            { value: false },
+        ];
+
+        expect(findLastIndex(array, v => v.value)).to.equal(2);
+    });
+
+    it("should return -1 when no items match the predicate", (): void => {
+        const array = [
+            { value: false },
+            { value: false },
+            { value: false },
+            { value: false },
+        ];
+
+        expect(findLastIndex(array, v => v.value)).to.equal(-1);
+    });
+});

packages/utilities/fast-web-utilities/src/array.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns the index of the last element in the array where predicate is true, and -1 otherwise.
+ *
+ * @param array - the array to test
+ * @param predicate - find calls predicate once for each element of the array, in descending order, until it finds one where predicate returns true. If such an element is found, findLastIndex immediately returns that element index. Otherwise, findIndex returns -1.
+ */
+export function findLastIndex<T>(
+    array: Array<T>,
+    predicate: (value: T, index: number, obj: T[]) => unknown
+): number {
+    let k = array.length;
+    while (k--) {
+        if (predicate(array[k], k, array)) {
+            return k;
+        }
+    }
+
+    return -1;
+}

packages/utilities/fast-web-utilities/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./aria";
+export * from "./array";
 export * from "./class-names";
 export * from "./dom";
 export * from "./events";

packages/utilities/fast-web-utilities/src/numbers.spec.ts

@@ -1,5 +1,5 @@
 import { expect } from "chai";
-import { limit, wrapInBounds } from "./numbers";
+import { inRange, limit, wrapInBounds } from "./numbers";
 
 describe("wrapInBounds", () => {
     it("should not throw if any parameters are null", () => {
@@ -76,3 +76,45 @@ describe("limit", () => {
         expect(limit(0, 10, 5)).to.equal(5);
     });
 });
+
+describe("inRange", () => {
+    it("should not throw if any parameters are null", () => {
+        expect(() => {
+            inRange(null, null, null);
+        }).not.to.throw();
+        expect(() => {
+            inRange(0, null, null);
+        }).not.to.throw();
+        expect(() => {
+            inRange(0, null, 1);
+        }).not.to.throw();
+        expect(() => {
+            inRange(0, 10, null);
+        }).not.to.throw();
+    });
+
+    it("should return `true` if `value` is within range of `min` and `max`", () => {
+        expect(inRange(10, 0, 20)).to.be.true;
+        expect(inRange(10, 20)).to.be.true;
+    });
+
+    it("should return `false` when `value` is less than `min` and `max`", () => {
+        expect(inRange(10, 20, 30)).to.be.false;
+    });
+
+    it("should return `false` when `value` is greater than `min` and `max`", () => {
+        expect(inRange(10, 0, 5)).to.be.false;
+    });
+
+    it("should return `false` when `value` is equal to `max`", () => {
+        expect(inRange(10, 0, 10)).to.be.false;
+    });
+
+    it("should return `true` when `value` is less than `min` and `max` is omitted", () => {
+        expect(inRange(10, 20)).to.be.true;
+    });
+
+    it("should return `false` when `value` is less than 0 and `max` is omitted", () => {
+        expect(inRange(-10, 20)).to.be.false;
+    });
+});

packages/utilities/fast-web-utilities/src/numbers.ts

@@ -20,3 +20,15 @@ export function wrapInBounds(min: number, max: number, value: number): number {
 export function limit(min: number, max: number, value: number): number {
     return Math.min(Math.max(value, min), max);
 }
+
+/**
+ * Determines if a number value is within a specified range.
+ *
+ * @param value - the value to check
+ * @param min - the range start
+ * @param max - the range end
+ */
+export function inRange(value: number, min: number, max: number = 0): boolean {
+    [min, max] = [min, max].sort((a, b) => a - b);
+    return min <= value && value < max;
+}