Implement sortArrayBy

.changeset/tough-clouds-applaud.md

@@ -0,0 +1,5 @@
+---
+"@giraugh/tools": minor
+---
+
+Implement `sortArrayBy`

.github/workflows/docs.yml

@@ -15,14 +15,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
       - name: Setup node & yarn
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v7
         with:
-          node-version: 18
+          node-version: 24
           cache: 'yarn'
 
       - name: Install dependencies

.github/workflows/release.yml

@@ -12,12 +12,12 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v7
       with:
-        node-version: 18
+        node-version: 24
         cache: 'yarn'
     - run: yarn install --immutable
     - uses: changesets/action@v1

.github/workflows/test.yml

@@ -12,21 +12,21 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions/setup-node@v3
+    - uses: actions/checkout@v7
+    - uses: actions/setup-node@v7
       with:
-        node-version: 18
+        node-version: 24
         cache: 'yarn'
     - run: yarn install --immutable
     - run: yarn test
 
   typecheck:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions/setup-node@v3
+    - uses: actions/checkout@v7
+    - uses: actions/setup-node@v7
       with:
-        node-version: 18
+        node-version: 24
         cache: 'yarn'
     - run: yarn install --immutable
     - run: yarn tsc

lib/arrays/index.ts

@@ -8,3 +8,4 @@ export * from './partitionArray'
 export * from './rotateArray'
 export * from './splitArray'
 export * from './splitArrayBy'
+export * from './sortArrayBy'

lib/arrays/sortArrayBy.ts

@@ -0,0 +1,41 @@
+/**
+ * Return a sorted array using a comparison function that returns a sorting key
+ * @param array the array to sort
+ * @param keyFn the key to sort by. The elements of the array will be sorted using standard `>` and `<` operations on this key.
+ * @param order - whether ascending or descending. 'asc' by default.
+ * @returns an object containing arrays with an entry for each group
+ * 
+ * @example
+ * const sorted = sortArrayBy(events, event => event.date.valueOf())
+ */
+export const sortArrayBy = <T, K extends number | string>(
+  array: T[],
+  keyFn: (element: T) => K,
+  order: 'asc' | 'desc' = 'asc',
+): T[] => {
+  const fw = order === 'asc' ? 1 : -1;
+  return array
+    .toSorted((a, b) => keyFn(a) > keyFn(b) ? fw : -fw)
+}
+
+// Tests
+if (import.meta.vitest) {
+  const { it, expect } = import.meta.vitest
+
+  it('works for example 1', () => {
+    const events = [
+      { message: 'Checked into hotel', date: new Date('2026-03-03 08:00') },
+      { message: 'Plane took off', date: new Date('2026-03-02 13:00') },
+      { message: 'Arrived at the airport', date: new Date('2026-03-02 10:00') },
+      { message: 'Arrived in Italy', date: new Date('2026-03-03 05:00') },
+    ]
+
+    const sorted = sortArrayBy(events, e => e.date.valueOf())
+    expect(sorted.map(s => s.message)).toEqual([
+      'Arrived at the airport',
+      'Plane took off',
+      'Arrived in Italy',
+      'Checked into hotel',
+    ])
+  })
+}

package.json

@@ -33,11 +33,14 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.1",
-    "typedoc": "^0.24.4",
-    "typescript": "^4.6.4",
+    "typedoc": "^0.28.20",
+    "typescript": "^5.2.2",
     "vercel": "^28.19.0",
     "vite": "^4.2.1",
-    "vite-plugin-dts": "^1.6.5",
+    "vite-plugin-dts": "^5.1.1",
     "vitest": "^0.30.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
   }
 }

tsconfig.json

@@ -3,7 +3,7 @@
     "target": "ESNext",
     "useDefineForClassFields": true,
     "module": "ESNext",
-    "lib": ["ESNext", "DOM"],
+    "lib": ["ESNext", "ES2023", "DOM", "DOM.Iterable"],
     "moduleResolution": "Node",
     "strict": true,
     "sourceMap": true,