feat(arrays): add argSort()

packages/arrays/src/arg-sort.ts

@@ -0,0 +1,33 @@
+import { compare } from "@thi.ng/compare/compare";
+import { fillRange } from "./fill-range.js";
+import { sortByCachedKey } from "./sort-cached.js";
+
+/**
+ * Returns a new array of numeric indices in same order as sorted values of
+ * `src` using given (optional) comparator (default: thi.ng/compare). The `src`
+ * array will remain unmodified.
+ *
+ * @remarks
+ * Also see {@link swizzle} to read an array in custom order.
+ *
+ * @example
+ * ```ts
+ * const src = ["a", "c", "d", "b"];
+ *
+ * argSort(src)
+ * // [ 0, 3, 1, 2 ]
+ *
+ * // src[0] => "a"
+ * // src[3] => "b"
+ * // src[1] => "c"
+ * // src[2] => "d"
+ *
+ * swizzle(argSort(src))(src)
+ * // [ 'a', 'b', 'c', 'd' ]
+ * ```
+ *
+ * @param src -
+ * @param cmp -
+ */
+export const argSort = <T>(src: T[], cmp = compare) =>
+    sortByCachedKey(fillRange(new Array(src.length)), src.slice(), cmp);

packages/arrays/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./api.js";
+export * from "./arg-sort.js";
 export * from "./binary-search.js";
 export * from "./bisect.js";
 export * from "./ends-with.js";