feat(collections/sort_by): descending order can be specified in options

collections/sort_by.ts

@@ -1,10 +1,18 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
+/** Order */
+export type Order = "asc" | "desc";
+
+/** Options for sortBy */
+export type SortByOptions = {
+  order: Order;
+};
+
 /**
  * Returns all elements in the given collection, sorted by their result using
  * the given selector. The selector function is called only once for each
- * element.
+ * element. Ascending or descending order can be specified.
  *
  * @example
  * ```ts
@@ -23,23 +31,35 @@
  *   { name: "Anna", age: 34 },
  *   { name: "Kim", age: 42 },
  * ]);
+ *
+ * const sortedByAgeDesc = sortBy(people, (it) => it.age, { order: "desc" });
+ *
+ * assertEquals(sortedByAgeDesc, [
+ *   { name: "Kim", age: 42 },
+ *   { name: "Anna", age: 34 },
+ *   { name: "John", age: 23 },
+ * ]);
  * ```
  */
 export function sortBy<T>(
   array: readonly T[],
   selector: (el: T) => number,
+  options?: SortByOptions,
 ): T[];
 export function sortBy<T>(
   array: readonly T[],
   selector: (el: T) => string,
+  options?: SortByOptions,
 ): T[];
 export function sortBy<T>(
   array: readonly T[],
   selector: (el: T) => bigint,
+  options?: SortByOptions,
 ): T[];
 export function sortBy<T>(
   array: readonly T[],
   selector: (el: T) => Date,
+  options?: SortByOptions,
 ): T[];
 export function sortBy<T>(
   array: readonly T[],
@@ -48,10 +68,12 @@ export function sortBy<T>(
     | ((el: T) => string)
     | ((el: T) => bigint)
     | ((el: T) => Date),
+  options?: SortByOptions,
 ): T[] {
   const len = array.length;
   const indexes = new Array<number>(len);
   const selectors = new Array<ReturnType<typeof selector> | null>(len);
+  const order = options?.order ?? "asc";
 
   for (let i = 0; i < len; i++) {
     indexes[i] = i;
@@ -60,8 +82,11 @@ export function sortBy<T>(
   }
 
   indexes.sort((ai, bi) => {
-    const a = selectors[ai];
-    const b = selectors[bi];
+    let a = selectors[ai];
+    let b = selectors[bi];
+    if (order === "desc") {
+      [a, b] = [b, a];
+    }
     if (a === null) return 1;
     if (b === null) return -1;
     return a > b ? 1 : a < b ? -1 : 0;

collections/sort_by_test.ts

@@ -197,3 +197,27 @@ Deno.test({
     );
   },
 });
+
+Deno.test({
+  name: "[collections/sortBy] desc ordering",
+  fn() {
+    assertEquals(
+      sortBy(
+        [
+          "January 27, 1995",
+          "November 26, 2020",
+          "June 17, 1952",
+          "July 15, 1993",
+        ],
+        (it) => new Date(it),
+        { order: "desc" },
+      ),
+      [
+        "November 26, 2020",
+        "January 27, 1995",
+        "July 15, 1993",
+        "June 17, 1952",
+      ],
+    );
+  },
+});