feat: added byRandom()

Author: webdeveric

src/sort/byRandom.ts

@@ -0,0 +1,4 @@
+/**
+ * Randomly return -1, 0, or 1. This is an easy way to shuffle an array.
+ */
+export const byRandom = (): number => (crypto.getRandomValues(new Uint8Array(1))[0]! % 3) - 1;

test/sort/byRandom.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { byRandom } from '../../src/sort/byRandom.js';
+
+describe('byRandom', () => {
+  it('should sort items randomly', () => {
+    expect(byRandom()).toBeOneOf([-1, 0, 1]);
+  });
+
+  it('can be used to shuffle an array', () => {
+    const data = [1, 2, 3, 4, 5];
+    const shuffledData = data.toSorted(byRandom);
+
+    expect(shuffledData).toHaveLength(data.length);
+    expect(shuffledData).toEqual(expect.arrayContaining(data));
+  });
+});