feat: add minBy method

src/index.ts

@@ -69,6 +69,7 @@ export * from "./mean-by.js";
 export * from "./mean-by-fn.js";
 export * from "./mean-by-property.js";
 export * from "./min.js";
+export * from "./min-by.js";
 export * from "./min-by-fn.js";
 export * from "./min-by-property.js";
 export * from "./multiply.js";

src/min-by-fn.ts

@@ -2,17 +2,15 @@
  * It will iterate through each of the provided `values` array,
  * by the provided `iteratee` function
  * and add the resulting numbers returned by the said `iteratee` function to produce the `minimum`,
- * @group Array
+ * @group Math
  * @since 1.0.0
  * @param values The array to iterate over.
  * @param iteratee The iteratee invoked per element.
  * @returns The minimum value.
  * @example
- * minByFn([1, 2, 3], number => number);
- * // => 1
+ * minByFn([1, 2, 3], number => number); // => 1
  * @example
- * minByFn([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a);
- * // => 1
+ * minByFn([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a); // => 1
  */
 export function minByFn<Value>(values: Value[], iteratee: (value: Value) => number): number {
   return values.reduce(

src/min-by-property.ts

@@ -5,7 +5,7 @@ import { property as propertyUtil } from "./property.js";
 
 /**
  * Computes the `minimum` of the values of the `property` for each element in the array.
- * @group Array
+ * @group Math
  * @since 1.0.0
  * @param values The array to iterate over.
  * @param property The property to get the value per element.

src/min-by.ts

@@ -0,0 +1,22 @@
+import { iteratee as iterateeUtil, type IterateeT } from "./iteratee.js";
+import { minByFn } from "./min-by-fn.js";
+
+/**
+ * It will iterate through each element of the provided `values` array
+ * and return the result of invoking `iteratee` function/property for each element to produce the desired `number`,
+ * to then be compared with other result `number`s to find the `minimum` value.
+ * @group Math
+ * @since 1.0.0
+ * @param values The array to iterate over.
+ * @param iteratee The function/property to get the value per element.
+ * @returns The minimum value.
+ * @example
+ * minBy([1, 2, 3], number => number); // => 1
+ * @example
+ * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a); // => 1
+ * @example
+ * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], "a"); // => 1
+ */
+export function minBy<Value>(values: Value[], iteratee: IterateeT<Value>): number {
+  return minByFn(values, iterateeUtil(iteratee, Infinity as never) as never);
+}

src/min.ts

@@ -3,7 +3,7 @@ import { minByFn } from "./min-by-fn.js";
 
 /**
  * Computes the `minimum` of the `numbers`.
- * @group Array
+ * @group Math
  * @since 1.0.0
  * @param numbers The array to iterate over.
  * @returns The minimum value.

tests/min-by.test.ts

@@ -0,0 +1,36 @@
+import { minBy } from "@extremejs/utils";
+
+describe("with property as iteratee", () => {
+  it("should return the minimum of the provided direct property", () => {
+    expect(minBy([{ a: 1 }, { a: 2 }, { a: 3 }], "a")).toBe(1);
+  });
+
+  it("should return the minimum of the provided nested property", () => {
+    expect(minBy([{ a: { b: 1 } }, { a: { b: 2 } }, { a: { b: 3 } }], "a.b"))
+      .toBe(1);
+  });
+
+  it("should return the minimum of the provided property while considering missing values as Infinity", () => {
+    expect(minBy([{ a: { b: 8 } }, { a: {} }, { }], "a.b"))
+      .toBe(8);
+  });
+});
+
+describe("with function as iteratee", () => {
+  it("should return the Infinity", () => {
+    expect(minBy<number>([], number => number)).toBe(Infinity);
+  });
+
+  it("should return the minimum of the elements", () => {
+    expect(minBy([1, 2, 3], number => number)).toBe(1);
+  });
+
+  it("should return the minimum of the provided direct property", () => {
+    expect(minBy([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a)).toBe(1);
+  });
+
+  it("should return the minimum of the provided nested property", () => {
+    expect(minBy([{ a: { b: 1 } }, { a: { b: 2 } }, { a: { b: 3 } }], ({ a }) => a.b))
+      .toBe(1);
+  });
+});