@tim-code/my-util 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "",
   "type": "module",
   "author": "",
@@ -23,5 +23,8 @@
   },
   "jest": {
     "transform": {}
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/array.js

@@ -27,3 +27,75 @@ export function chunk(array, chunkSize = array.length) {
 export function unique(array) {
   return [...new Set(array)]
 }
+
+/**
+ * Mutates the passed in object by calling callback on each of its values.
+ * @param {Object} object
+ * @param {Function} callback (value, key, object) => newValue // note if not changing value, should return value
+ * @returns {Object}
+ */
+export function mutateValues(object, callback) {
+  for (const key in object) {
+    object[key] = callback(object[key], key, object)
+  }
+  return object
+}
+
+// sorts undefined and null to the end if applicable
+function compareUndefinedNull(a, b) {
+  if (b === undefined || b === null) {
+    if (a === undefined || a === null) {
+      return 0
+    }
+    return -1
+  } else if (a === undefined || a === null) {
+    return 1
+  }
+  return undefined
+}
+
+/**
+ * Returns an "ascending" comparator, via "<", to be used to sort an array.
+ * Undefined or null values are always sorted to the end.
+ * @param {String=} key If sorting objects, can specify a key to use to compare.
+ * @returns {Function}
+ */
+export function ascending(key) {
+  if (!key) {
+    return (a, b) => {
+      return compareUndefinedNull(a, b) ?? (a < b ? -1 : b < a ? 1 : 0)
+    }
+  }
+  return (a, b) => {
+    return (
+      compareUndefinedNull(a[key], b[key]) ?? (a[key] < b[key] ? -1 : b[key] < a[key] ? 1 : 0)
+    )
+  }
+}
+
+/**
+ * Returns a "descending" comparator, via ">", to be used to sort an array.
+ * Undefined or null values are always sorted to the end.
+ * @param {String=} key If sorting objects, can specify a key to use to compare.
+ * @returns {Function}
+ */
+export function descending(key) {
+  if (!key) {
+    return (a, b) => {
+      return compareUndefinedNull(a, b) ?? (a > b ? -1 : b > a ? 1 : 0)
+    }
+  }
+  return (a, b) => {
+    return (
+      compareUndefinedNull(a[key], b[key]) ?? (a[key] > b[key] ? -1 : b[key] > a[key] ? 1 : 0)
+    )
+  }
+}
+
+// not sure how far we want to go down "key" rabbit hole:
+// export function sum(array, key) {}
+// or maybe
+// export function add(key) {
+//  if(!key) return (acc, value) => acc + value
+//  return (acc, obj) => acc + obj[key]
+// }

package/src/array.test.js

@@ -1,7 +1,7 @@
-// src/array.test.js
-import { describe, expect, it } from "@jest/globals"
+/* eslint-disable no-restricted-syntax */
+import { describe, expect, it, jest } from "@jest/globals"
 
-const { chunk, unique } = await import("./array.js")
+const { chunk, unique, mutateValues, ascending, descending } = await import("./array.js")
 
 describe("chunk", () => {
   it("splits array into chunks of specified size", () => {
@@ -69,3 +69,121 @@ describe("unique", () => {
     expect(unique([a, b, a])).toEqual([a, b])
   })
 })
+
+describe("mutateValues", () => {
+  it("mutates values in the object using the callback", () => {
+    const obj = { a: 1, b: 2 }
+    const result = mutateValues(obj, (v) => v * 2)
+    expect(result).toEqual({ a: 2, b: 4 })
+    expect(obj).toBe(result) // should mutate in place
+  })
+
+  it("callback receives value, key, and object", () => {
+    const obj = { x: 1 }
+    const cb = jest.fn((v) => v + 1)
+    mutateValues(obj, cb)
+    expect(cb).toHaveBeenCalledWith(1, "x", obj)
+  })
+
+  it("returns the same object reference", () => {
+    const obj = { foo: "bar" }
+    const returned = mutateValues(obj, (v) => v)
+    expect(returned).toBe(obj)
+  })
+
+  it("handles empty object", () => {
+    const obj = {}
+    expect(mutateValues(obj, (v) => v)).toEqual({})
+  })
+
+  it("mutates inherited enumerable properties", () => {
+    const proto = { inherited: 1 }
+    const obj = Object.create(proto)
+    obj.own = 2
+    const result = mutateValues(obj, (v) => v + 1)
+    expect(result.own).toBe(3)
+    expect(result.inherited).toBe(2)
+  })
+})
+
+describe("ascending", () => {
+  it("sorts primitives ascending, undefined/null at end", () => {
+    const arr = [undefined, null, 3, 1, 2]
+    arr.sort(ascending())
+    expect(arr).toEqual([1, 2, 3, null, undefined])
+  })
+
+  it("returns 0 for equal values", () => {
+    expect(ascending()(2, 2)).toBe(0)
+    expect(ascending()("a", "a")).toBe(0)
+  })
+
+  it("sorts objects by key ascending, undefined/null at end", () => {
+    const arr = [{ v: undefined }, { v: 3 }, { v: null }, { v: 1 }, { v: 2 }]
+    arr.sort(ascending("v"))
+    expect(arr.map((o) => o.v)).toEqual([1, 2, 3, undefined, null])
+  })
+
+  it("returns 0 for equal key values", () => {
+    expect(ascending("x")({ x: 5 }, { x: 5 })).toBe(0)
+  })
+
+  it("sorts negative numbers and zero correctly", () => {
+    const arr = [0, -2, -1, 2]
+    arr.sort(ascending())
+    expect(arr).toEqual([-2, -1, 0, 2])
+  })
+
+  it("sorts strings alphabetically", () => {
+    const arr = ["b", "a", "c"]
+    arr.sort(ascending())
+    expect(arr).toEqual(["a", "b", "c"])
+  })
+
+  it("handles objects missing the key", () => {
+    const arr = [{ v: 2 }, {}, { v: 1 }]
+    arr.sort(ascending("v"))
+    expect(arr.map((o) => o.v)).toEqual([1, 2, undefined])
+  })
+})
+
+describe("descending", () => {
+  it("sorts primitives descending, undefined/null at end", () => {
+    const arr = [undefined, 1, null, 3, 2]
+    arr.sort(descending())
+    expect(arr).toEqual([3, 2, 1, null, undefined])
+  })
+
+  it("returns 0 for equal values", () => {
+    expect(descending()(2, 2)).toBe(0)
+    expect(descending()("a", "a")).toBe(0)
+  })
+
+  it("sorts objects by key descending, undefined/null at end", () => {
+    const arr = [{ v: undefined }, { v: 1 }, { v: 3 }, { v: null }, { v: 2 }]
+    arr.sort(descending("v"))
+    expect(arr.map((o) => o.v)).toEqual([3, 2, 1, undefined, null])
+  })
+
+  it("returns 0 for equal key values", () => {
+    expect(descending("x")({ x: 5 }, { x: 5 })).toBe(0)
+  })
+
+  it("sorts negative numbers and zero correctly", () => {
+    const arr = [0, -2, -1, 2]
+    arr.sort(descending())
+    expect(arr).toEqual([2, 0, -1, -2])
+  })
+
+  it("sorts strings reverse alphabetically", () => {
+    const arr = ["b", "a", "c"]
+    arr.sort(descending())
+    expect(arr).toEqual(["c", "b", "a"])
+  })
+
+  it("handles objects missing the key", () => {
+    const arr = [{ v: 2 }, {}, { v: 3 }]
+    arr.sort(descending("v"))
+    expect(arr.map((o) => o.v)).toEqual([3, 2, undefined])
+  })
+})

package/src/fs.js

@@ -24,6 +24,9 @@ export async function getJSON(path) {
  * @returns {Object|Array}
  */
 export async function getCompressedJSON(path) {
+  if (!path.endsWith(".gz")) {
+    throw new Error("path does not suggest a compressed file")
+  }
   const buffer = await readFile(path)
   const uncompressed = await gunzip(buffer)
   return JSON.parse(uncompressed.toString())

package/src/fs.test.js

@@ -42,6 +42,9 @@ describe("getCompressedJSON", () => {
     expect(readFileMock).toHaveBeenCalledWith("bar.gz")
     expect(gunzipMock).toHaveBeenCalled()
   })
+  it("throws for bad filename", async () => {
+    await expect(getCompressedJSON("bar")).rejects.toThrow(/a compressed file/u)
+  })
 })
 
 describe("pathExists", () => {

package/src/time.js

@@ -30,3 +30,43 @@ export function getEasternTime({ days = 0, floorMinute = false } = {}) {
   const datetime = `${date} ${time}`
   return { timestamp, date, time, minute, datetime }
 }
+
+/**
+ * Checks if the string represents a valid YYYY-MM-DD date.
+ * This will return false for dates like "2024-02-31".
+ * @param {string} string
+ * @returns {boolean}
+ */
+export function isDate(string) {
+  const match = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/u.exec(string)
+  if (!match) {
+    return false
+  }
+  const [, year, month, day] = match.map(Number)
+  const date = new Date(`${string}T00:00:00Z`)
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() + 1 === month &&
+    date.getUTCDate() === day
+  )
+}
+
+/**
+ * Checks if the string represent a valid HH:mm:ss time.
+ * @param {string} string
+ * @returns {boolean}
+ */
+export function isTime(string) {
+  return /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/u.test(string)
+}
+
+/**
+ * Checks if a number is a Unix timestamp (i.e. in seconds).
+ * @param {number} ts
+ * @param {Object} $1
+ * @param {number} $1.max Maximum value for timestamp to allow - default is up to ~2286-11-20; this allows catching ms timestamps
+ * @returns {boolean}
+ */
+export function isUnixTimestamp(ts, { max = 9999999999 } = {}) {
+  return Number.isInteger(ts) && ts >= 0 && ts <= max
+}

package/src/time.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "@jest/globals"
-import { getEasternTime } from "./time.js"
+import { getEasternTime, isDate, isTime, isUnixTimestamp } from "./time.js"
 
 describe("getEasternTime", () => {
   test("returns correct structure and types", () => {
@@ -46,3 +46,77 @@ describe("getEasternTime", () => {
     expect(def.datetime).toEqual(explicit.datetime)
   })
 })
+
+describe("isDate", () => {
+  test("returns true for valid YYYY-MM-DD dates", () => {
+    expect(isDate("2024-06-01")).toBe(true)
+    expect(isDate("1999-12-31")).toBe(true)
+  })
+
+  test("returns false for invalid dates (e.g., 2024-02-31)", () => {
+    expect(isDate("2024-02-31")).toBe(false)
+    expect(isDate("2023-04-31")).toBe(false)
+  })
+
+  test("returns false for invalid formats", () => {
+    expect(isDate("2024/06/01")).toBe(false)
+    expect(isDate("06-01-2024")).toBe(false)
+    expect(isDate("2024-6-1")).toBe(false)
+    expect(isDate("20240601")).toBe(false)
+    expect(isDate("abcd-ef-gh")).toBe(false)
+  })
+
+  test("returns false for impossible months and days", () => {
+    expect(isDate("2024-00-10")).toBe(false)
+    expect(isDate("2024-13-10")).toBe(false)
+    expect(isDate("2024-01-00")).toBe(false)
+    expect(isDate("2024-01-32")).toBe(false)
+  })
+
+  test("returns true for leap day", () => {
+    expect(isDate("2024-02-29")).toBe(true)
+    expect(isDate("2023-02-29")).toBe(false)
+  })
+})
+
+describe("isTime", () => {
+  test("returns true for valid HH:mm:ss times", () => {
+    expect(isTime("00:00:00")).toBe(true)
+    expect(isTime("23:59:59")).toBe(true)
+    expect(isTime("12:34:56")).toBe(true)
+  })
+
+  test("returns false for invalid times", () => {
+    expect(isTime("24:00:00")).toBe(false)
+    expect(isTime("12:60:00")).toBe(false)
+    expect(isTime("12:00:60")).toBe(false)
+    expect(isTime("1:00:00")).toBe(false)
+    expect(isTime("12:0:00")).toBe(false)
+    expect(isTime("12:00:0")).toBe(false)
+    expect(isTime("12:00")).toBe(false)
+    expect(isTime("120000")).toBe(false)
+    expect(isTime("ab:cd:ef")).toBe(false)
+  })
+})
+
+describe("isUnixTimestamp", () => {
+  test("returns true for valid unix timestamps in seconds", () => {
+    expect(isUnixTimestamp(0)).toBe(true)
+    expect(isUnixTimestamp(1700000000)).toBe(true)
+    expect(isUnixTimestamp(9999999999)).toBe(true)
+  })
+
+  test("returns false for negative or non-integer or too large values", () => {
+    expect(isUnixTimestamp(-1)).toBe(false)
+    expect(isUnixTimestamp(1.5)).toBe(false)
+    expect(isUnixTimestamp(10000000000)).toBe(false)
+    expect(isUnixTimestamp(NaN)).toBe(false)
+    expect(isUnixTimestamp(Infinity)).toBe(false)
+  })
+
+  test("respects custom max option", () => {
+    expect(isUnixTimestamp(100, { max: 50 })).toBe(false)
+    expect(isUnixTimestamp(50, { max: 50 })).toBe(true)
+    expect(isUnixTimestamp(51, { max: 50 })).toBe(false)
+  })
+})