feat: add sumBy method

README.md

@@ -54,13 +54,17 @@ yarn add @extremejs/utils
 ## Usage
 
 ```typescript
-import { sumByFn, sumByProperty } from "@extremejs/utils";
+import { sumByFn, sumByProperty, sumBy } from "@extremejs/utils";
 // or
-import { sumByFn, sumByProperty } from "@extremejs/utils/sum-by-fn";
+import { sumByFn, sumByProperty, sumBy } from "@extremejs/utils/sum-by-fn";
 
 const sum1 = sumByFn([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a); // => 6
 // or
 const sum2 = sumByProperty([{ a: 1 }, { a: 2 }, { a: 3 }], "a"); // => 6
+// or
+const sum3 = sumBy([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a); // => 6
+// or
+const sum4 = sumBy([{ a: 1 }, { a: 2 }, { a: 3 }], "a"); // => 6
 ```
 
 > API usage documents are available [here](https://extremejs.github.io/utils).

src/index.ts

@@ -83,6 +83,7 @@ export * from "./split.js";
 export * from "./starts-with.js";
 export * from "./subtract.js";
 export * from "./sum.js";
+export * from "./sum-by.js";
 export * from "./sum-by-fn.js";
 export * from "./sum-by-property.js";
 export * from "./tail.js";

src/sum-by-fn.ts

@@ -1,5 +1,5 @@
 /**
- * It will iterate through each of the provided `values` array,
+ * It will iterate through each element of the provided `values` array,
  * by the provided `iteratee` function
  * and add the resulting numbers returned by the said `iteratee` function to produce the desired `sum`.
  * @group Array

src/sum-by-property.ts

@@ -4,7 +4,7 @@ import { property as propertyUtil } from "./property.js";
 import { sumByFn } from "./sum-by-fn.js";
 
 /**
- * It will iterate through each of the provided `values` array
+ * It will iterate through each element of the provided `values` array
  * and add the value of each element's `property` to produce the desired `sum`.
  * @group Array
  * @since 1.0.0

src/sum-by.ts

@@ -0,0 +1,21 @@
+import { iteratee as iterateeUtil, type IterateeT } from "./iteratee.js";
+import { sumByFn } from "./sum-by-fn.js";
+
+/**
+ * It will iterate through each element of the provided `values` array
+ * and add the result of invoking `iteratee` function/property for each element to produce the desired `sum`.
+ * @group Array
+ * @since 1.0.0
+ * @param values The array to iterate over.
+ * @param iteratee The function/property to get the value per element.
+ * @returns The sum value.
+ * @example
+ * sumByFn([1, 2, 3], number => number); // => 6
+ * @example
+ * sumByFn([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a); // => 6
+ * @example
+ * sumBy([{ a: 1 }, { a: 2 }, { a: 3 }], "a"); // => 6
+ */
+export function sumBy<Value>(values: Value[], iteratee: IterateeT<Value>): number {
+  return sumByFn(values, iterateeUtil(iteratee, 0 as never) as never);
+}

tests/sum-by.test.ts

@@ -0,0 +1,27 @@
+import { sumBy } from "@extremejs/utils";
+
+describe("with property as iteratee", () => {
+  it("should return the sum of the provided direct property", () => {
+    expect(sumBy([{ a: 1 }, { a: 2 }, { a: 3 }], "a")).toBe(6);
+  });
+
+  it("should return the sum of the provided nested property", () => {
+    expect(sumBy([{ a: { b: 1 } }, { a: { b: 2 } }, { a: { b: 3 } }], "a.b"))
+      .toBe(6);
+  });
+});
+
+describe("with function as iteratee", () => {
+  it("should return the sum of the elements", () => {
+    expect(sumBy([1, 2, 3], number => number)).toBe(6);
+  });
+
+  it("should return the sum of the provided direct property", () => {
+    expect(sumBy([{ a: 1 }, { a: 2 }, { a: 3 }], ({ a }) => a)).toBe(6);
+  });
+
+  it("should return the sum of the provided nested property", () => {
+    expect(sumBy([{ a: { b: 1 } }, { a: { b: 2 } }, { a: { b: 3 } }], ({ a }) => a.b))
+      .toBe(6);
+  });
+});