@tim-code/my-util 0.6.2 → 0.6.4

package/package.json

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

package/src/array.js

@@ -176,6 +176,80 @@ export function descending(transform) {
   }
 }
 
+function compareUndefinedNullEmpty(a, b) {
+  if (b === undefined || b === null || b === "") {
+    if (a === undefined || a === null || a === "") {
+      return 0
+    }
+    return -1
+  } else if (a === undefined || a === null || a === "") {
+    return 1
+  }
+  return undefined
+}
+
+function naturalCompare(a, b) {
+  if (a[0] === "-" && b[0] === "-") {
+    a = a.slice(1, a.length)
+    b = b.slice(1, b.length)
+    return b.localeCompare(a, undefined, { numeric: true })
+  }
+  return a.localeCompare(b, undefined, { numeric: true })
+}
+
+/**
+ * Returns an "ascending" comparator using natural string sort, to be used to sort an array of strings.
+ * Empty string or 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 compareUndefinedNullEmpty(a, b) ?? naturalCompare(a, b)
+    }
+  }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNullEmpty(a[transform], b[transform])
+      return invalid ?? naturalCompare(a[transform], b[transform])
+    }
+  }
+  return (a, b) => {
+    return compareUndefinedNullEmpty(a, b) ?? naturalCompare(a, b)
+  }
+}
+/**
+ * Returns a "descending" comparator using natural string sort, to be used to sort an array of strings.
+ * Empty string or 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 compareUndefinedNullEmpty(a, b) ?? naturalCompare(b, a)
+    }
+  }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNullEmpty(a[transform], b[transform])
+      return invalid ?? naturalCompare(b[transform], a[transform])
+    }
+  }
+  return (a, b) => {
+    return compareUndefinedNullEmpty(a, b) ?? naturalCompare(b, a)
+  }
+}
+
 /**
  * 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,102 @@ 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("defers empty string to the end along with undefined/null (default path)", () => {
+    const arr = ["b", "", "a", undefined, null, "c"]
+    arr.sort(naturalAsc())
+    expect(arr).toEqual(["a", "b", "c", "", null, undefined])
+  })
+
+  it("defers empty string to the end along with undefined/null (key path)", () => {
+    const arr = [{ v: "" }, { v: "a2" }, { v: undefined }, { v: "a1" }, { v: null }]
+    arr.sort(naturalAsc("v"))
+    expect(arr.map((o) => o.v)).toEqual(["a1", "a2", "", 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 naturally with undefined/null at end", () => {
+    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"])
+  })
+
+  it("handles negative number-like strings by comparing magnitudes (both negative)", () => {
+    const arr = ["-2", "-10", "-1"]
+    arr.sort(naturalAsc())
+    expect(arr).toEqual(["-10", "-2", "-1"])
+  })
+})
+
+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("defers empty string to the end along with undefined/null (default path)", () => {
+    const arr = ["b", "", "a", undefined, null, "c"]
+    arr.sort(naturalDesc())
+    expect(arr.slice(-3)).toEqual(["", null, undefined])
+    expect(arr.slice(0, 3)).toEqual(["c", "b", "a"])
+  })
+
+  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)
+  })
+
+  it("handles negative number-like strings by comparing magnitudes (both negative) in descending", () => {
+    const arr = ["-2", "-10", "-1"]
+    arr.sort(naturalDesc())
+    expect(arr).toEqual(["-1", "-2", "-10"])
+  })
+})
+
 describe("multilevel", () => {
   it("returns 0 if all comparators return 0", () => {
     const cmp = multilevel(