@tim-code/my-util 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.6.1",
+  "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(

package/src/object.js

@@ -182,3 +182,20 @@ export function deepEqual(a, b) {
   }
   return true
 }
+
+/**
+ * Checks if the argument is a class.
+ * Example: `isClass(class {})`
+ * Returns: true
+ * In general, this will only work for third-party or user-defined classes, not built-ins.
+ * @param {any} thing
+ * @returns {boolean}
+ */
+export function isClass(thing) {
+  if (typeof thing !== "function") {
+    return false
+  }
+  const stringified = Function.prototype.toString.call(thing)
+  const result = /^class\s/u.test(stringified)
+  return result
+}

package/src/object.test.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-empty-function */
 import { jest } from "@jest/globals"
 import {
   deepCopy,
@@ -5,6 +6,7 @@ import {
   deepMerge,
   deepMergeCopy,
   deleteUndefinedValues,
+  isClass,
   isObject,
   like,
   mapValues,
@@ -38,7 +40,7 @@ describe("isObject", () => {
 
   it("returns false for functions", () => {
     expect(isObject(() => {})).toBe(false)
-    // eslint-disable-next-line func-names, prefer-arrow-callback, no-empty-function
+    // eslint-disable-next-line func-names, prefer-arrow-callback
     expect(isObject(function () {})).toBe(false)
   })
 })
@@ -592,3 +594,33 @@ describe("deepEqual", () => {
     expect(deepEqual({}, { a: undefined })).toBe(false)
   })
 })
+
+// --- isClass ---
+describe("isClass", () => {
+  it("returns true for class declarations and expressions", () => {
+    class A {}
+    const B = class {}
+    expect(isClass(A)).toBe(true)
+    expect(isClass(B)).toBe(true)
+  })
+
+  it("returns false for non-class functions", () => {
+    function f() {}
+    const g = () => {}
+    async function af() {}
+    function* gf() {}
+    expect(isClass(f)).toBe(false)
+    expect(isClass(g)).toBe(false)
+    expect(isClass(af)).toBe(false)
+    expect(isClass(gf)).toBe(false)
+  })
+
+  it("returns false for built-in constructors and non-functions", () => {
+    // Built-ins typically stringify as 'function X() { [native code] }'
+    expect(isClass(Date)).toBe(false)
+    expect(isClass(Map)).toBe(false)
+    expect(isClass(123)).toBe(false)
+    expect(isClass({})).toBe(false)
+    expect(isClass(null)).toBe(false)
+  })
+})