sortBy

import { sortBy } from "jsr:@ende/collections";

function

function sortBy<T>(iterator: Iterable<T>, selector: ((el: T, index: number) => number) | ((el: T, index: number) => string) | ((el: T, index: number) => bigint) | ((el: T, index: number) => Date), options?: SortByOptions): T[]

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. Ascending or descending order can be specified through the order option. By default, the elements are sorted in ascending order.

iterator: Iterable<T>: The iterator to sort.
selector: ((el: T, index: number) => number) | ((el: T, index: number) => string) | ((el: T, index: number) => bigint) | ((el: T, index: number) => Date): The selector function to get the value to sort by. The function receives the element and its index.
options?: SortByOptions: The options for sorting.

Returns

A new array containing all elements sorted by the selector.

Example: Usage with numbers

import { sortBy } from "@ende/collections/sort-by";
import { assertEquals } from "@ende/assert";

const people = [
  { name: "Anna", age: 34 },
  { name: "Kim", age: 42 },
  { name: "John", age: 23 },
];
const sortedByAge = sortBy(people, (person) => person.age);

assertEquals(sortedByAge, [
  { name: "John", age: 23 },
  { name: "Anna", age: 34 },
  { name: "Kim", age: 42 },
]);

const sortedByAgeDesc = sortBy(people, (person) => person.age, { order: "desc" });

assertEquals(sortedByAgeDesc, [
  { name: "Kim", age: 42 },
  { name: "Anna", age: 34 },
  { name: "John", age: 23 },
]);

Example: Usage with strings

import { sortBy } from "@ende/collections/sort-by";
import { assertEquals } from "@ende/assert";

const people = [
  { name: "Anna" },
  { name: "Kim" },
  { name: "John" },
];
const sortedByName = sortBy(people, (it) => it.name);

assertEquals(sortedByName, [
  { name: "Anna" },
  { name: "John" },
  { name: "Kim" },
]);

Example: Usage with bigints

import { sortBy } from "@ende/collections/sort-by";
import { assertEquals } from "@ende/assert";

const people = [
  { name: "Anna", age: 34n },
  { name: "Kim", age: 42n },
  { name: "John", age: 23n },
];

const sortedByAge = sortBy(people, (person) => person.age);

assertEquals(sortedByAge, [
  { name: "John", age: 23n },
  { name: "Anna", age: 34n },
  { name: "Kim", age: 42n },
]);

Example: Usage with Date objects

import { sortBy } from "@ende/collections/sort-by";
import { assertEquals } from "@ende/assert";

const people = [
  { name: "Anna", startedAt: new Date("2020-01-01") },
  { name: "Kim", startedAt: new Date("2020-03-01") },
  { name: "John", startedAt: new Date("2020-06-01") },
];

const sortedByStartedAt = sortBy(people, (people) => people.startedAt);

assertEquals(sortedByStartedAt, [
  { name: "Anna", startedAt: new Date("2020-01-01") },
  { name: "Kim", startedAt: new Date("2020-03-01") },
  { name: "John", startedAt: new Date("2020-06-01") },
]);

Example: Using the index parameter

import { sortBy } from "@ende/collections/sort-by";
import { assertEquals } from "@ende/assert";

const array = [2, 3, 1];
const result = sortBy(array, (_, index) => -index);

assertEquals(result, [1, 3, 2]);

Source