@tim-code/my-util 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",

package/src/array.js

@@ -176,6 +176,59 @@ export function descending(transform) {
   }
 }
 
+/**
+ * Returns an "ascending" comparator using natural string sort, to be used to sort an array of strings.
+ * Undefined or null values are always sorted to the end.
+ * @param {string|number|Function=} transform
+ *  If a function, calls the provided function on an element to get the value to sort on.
+ *  If a string or number, treats transform as a key and sorts on each element's value at key.
+ * @returns {Function}
+ */
+export function naturalAsc(transform) {
+  if (typeof transform === "function") {
+    return (a, b) => {
+      a = transform(a)
+      b = transform(b)
+      return compareUndefinedNull(a, b) ?? a.localeCompare(b, undefined, { numeric: true })
+    }
+  }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNull(a[transform], b[transform])
+      return invalid ?? a[transform].localeCompare(b[transform], undefined, { numeric: true })
+    }
+  }
+  return (a, b) => {
+    return compareUndefinedNull(a, b) ?? a.localeCompare(b, undefined, { numeric: true })
+  }
+}
+/**
+ * Returns a "descending" comparator using natural string sort, to be used to sort an array of strings.
+ * Undefined or null values are always sorted to the end.
+ * @param {string|number|Function=} transform
+ *  If a function, calls the provided function on an element to get the value to sort on.
+ *  If a string or number, treats transform as a key and sorts on each element's value at key.
+ * @returns {Function}
+ */
+export function naturalDesc(transform) {
+  if (typeof transform === "function") {
+    return (a, b) => {
+      b = transform(b)
+      a = transform(a)
+      return compareUndefinedNull(a, b) ?? b.localeCompare(a, undefined, { numeric: true })
+    }
+  }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNull(a[transform], b[transform])
+      return invalid ?? b[transform].localeCompare(a[transform], undefined, { numeric: true })
+    }
+  }
+  return (a, b) => {
+    return compareUndefinedNull(a, b) ?? b.localeCompare(a, undefined, { numeric: true })
+  }
+}
+
 /**
  * Combines multiple ascending and descending comparators.
  * @param  {...Function} comparators

package/src/array.test.js

@@ -1,8 +1,16 @@
 import { describe, expect, it, jest } from "@jest/globals"
 
-const { chunk, unique, duplicates, ascending, descending, multilevel, sortN } = await import(
-  "./array.js"
-)
+const {
+  chunk,
+  unique,
+  duplicates,
+  ascending,
+  descending,
+  naturalAsc,
+  naturalDesc,
+  multilevel,
+  sortN,
+} = await import("./array.js")
 
 describe("chunk", () => {
   it("splits array into chunks of specified size", () => {
@@ -484,6 +492,71 @@ describe("descending", () => {
   })
 })
 
+describe("naturalAsc", () => {
+  it("sorts strings using natural order when transform is a function", () => {
+    const arr = ["a10", "a2", "a1"]
+    arr.sort(naturalAsc((s) => s))
+    expect(arr).toEqual(["a1", "a2", "a10"])
+  })
+
+  it("sorts by key using natural order and defers undefined/null to the end", () => {
+    const arr = [
+      { v: "file10" },
+      { v: undefined },
+      { v: "file2" },
+      { v: null },
+      { v: "file1" },
+    ]
+    arr.sort(naturalAsc("v"))
+    expect(arr.map((o) => o.v)).toEqual(["file1", "file2", "file10", undefined, null])
+  })
+
+  it("returns 0 for equal values (function and key paths)", () => {
+    expect(naturalAsc((x) => x)("a", "a")).toBe(0)
+    expect(naturalAsc("v")({ v: "x" }, { v: "x" })).toBe(0)
+  })
+
+  it("default comparator sorts with undefined/null at end but uses non-natural, descending semantics", () => {
+    const arr = [undefined, "b", null, "a", "c"]
+    arr.sort(naturalAsc())
+    expect(arr).toEqual(["a", "b", "c", null, undefined])
+    const numericLike = ["a10", "a2", "a1"]
+    numericLike.sort(naturalAsc())
+    expect(numericLike).toEqual(["a1", "a2", "a10"])
+  })
+})
+
+describe("naturalDesc", () => {
+  it("sorts strings using natural order descending (default path)", () => {
+    const arr = [undefined, "a", null, "c", "b"]
+    arr.sort(naturalDesc())
+    expect(arr).toEqual(["c", "b", "a", null, undefined])
+  })
+
+  it("sorts using transform function in natural descending order", () => {
+    const arr = ["a1", "a10", "a2"]
+    arr.sort(naturalDesc((s) => s))
+    expect(arr).toEqual(["a10", "a2", "a1"])
+  })
+
+  it("sorts by key using natural descending order and defers undefined/null to the end", () => {
+    const arr = [
+      { v: "file1" },
+      { v: "file10" },
+      { v: undefined },
+      { v: "file2" },
+      { v: null },
+    ]
+    arr.sort(naturalDesc("v"))
+    expect(arr.map((o) => o.v)).toEqual(["file10", "file2", "file1", undefined, null])
+  })
+
+  it("returns 0 for equal values (function and key paths)", () => {
+    expect(naturalDesc((x) => x)("a", "a")).toBe(0)
+    expect(naturalDesc("v")({ v: "x" }, { v: "x" })).toBe(0)
+  })
+})
+
 describe("multilevel", () => {
   it("returns 0 if all comparators return 0", () => {
     const cmp = multilevel(