@tim-code/my-util 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "",
   "type": "module",
   "author": "",

package/src/array.js

@@ -27,3 +27,84 @@ 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)
+    )
+  }
+}
+
+/**
+ * Parse an integer in base 10. Safe to use for array.map() since it only takes one argument and ignores the rest.
+ * @param {string} number
+ * @returns {number} Integer
+ */
+export function parseIntSafe(number) {
+  return parseInt(number, 10)
+}
+
+// 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/index.js

@@ -1,5 +1,6 @@
 export * from "./array.js"
 export * from "./fs.js"
+export * from "./math.js"
 export * from "./promise.js"
 export * from "./run.js"
 export * from "./time.js"

package/src/math.js

@@ -0,0 +1,9 @@
+/**
+ * Module safe for negative numbers i.e. mod(-1, 3) === 2 (not -1 as in -1 % 3).
+ * @param {number} n
+ * @param {number} m If 0, returns NaN as does n % m.
+ * @returns {number}
+ */
+export function mod(n, m) {
+  return ((n % m) + m) % m
+}

package/src/math.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "@jest/globals"
+const { mod } = await import("./math.js")
+
+describe("mod", () => {
+  it("returns n when n is less than m and n is non-negative", () => {
+    expect(mod(2, 3)).toBe(2)
+    expect(mod(0, 5)).toBe(0)
+  })
+
+  it("wraps negative n into the [0, m) range", () => {
+    expect(mod(-1, 3)).toBe(2)
+    expect(mod(-4, 3)).toBe(2)
+    expect(mod(-2, 5)).toBe(3)
+  })
+
+  it("returns 0 when n is a multiple of m", () => {
+    expect(mod(6, 3)).toBe(0)
+    expect(mod(-6, 3)).toBe(0)
+  })
+
+  it("handles n greater than m", () => {
+    expect(mod(7, 3)).toBe(1)
+    expect(mod(14, 5)).toBe(4)
+  })
+
+  it("handles m = 1 (should always return 0)", () => {
+    expect(mod(0, 1)).toBe(0)
+    expect(mod(5, 1)).toBe(0)
+    expect(mod(-3, 1)).toBe(0)
+  })
+
+  it("returns NaN when m is 0", () => {
+    expect(mod(5, 0)).toBeNaN()
+    expect(mod(0, 0)).toBeNaN()
+    expect(mod(-3, 0)).toBeNaN()
+  })
+})

package/src/time.js

@@ -1,3 +1,6 @@
+import { parseIntSafe } from "./array.js"
+import { mod } from "./math.js"
+
 /**
  * Gets various ways of representing the current time in EDT. Floors to nearest second by default.
  * @param {Object} $1
@@ -30,3 +33,70 @@ 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).
+ * Would not validate timestamps set very far into the future.
+ * @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
+}
+
+/**
+ * Add an amount of time to a time string.
+ * @param {string} timeString HH:mm:ss or HH:mm; parsable numbers separated by :
+ * @param {Object} $1
+ * @param {number} $1.hours Hours to add to time string
+ * @param {number} $1.minutes Minutes to add to time string
+ * @returns {string} HH:mm:ss
+ */
+export function addTime(timeString, { minutes = 0, hours = 0 }) {
+  let [hour, minute, second = 0] = timeString.split(":").map(parseIntSafe)
+  hour = mod(hour + hours, 24)
+  minute += minutes
+  while (minute >= 60) {
+    hour = mod(hour + 1, 24)
+    minute -= 60
+  }
+  while (minute < 0) {
+    hour = mod(hour - 1, 24)
+    minute += 60
+  }
+  const newTime = [hour, minute, second]
+    .map((number) => `${number}`.padStart(2, "0"))
+    .join(":")
+  return newTime
+}

package/src/time.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "@jest/globals"
-import { getEasternTime } from "./time.js"
+import { addTime, getEasternTime, isDate, isTime, isUnixTimestamp } from "./time.js"
 
 describe("getEasternTime", () => {
   test("returns correct structure and types", () => {
@@ -46,3 +46,136 @@ 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)
+  })
+})
+
+describe("addTime", () => {
+  test("adds minutes within the same hour", () => {
+    expect(addTime("12:30:00", { minutes: 15 })).toBe("12:45:00")
+    expect(addTime("12:30", { minutes: 15 })).toBe("12:45:00")
+  })
+
+  test("adds minutes with hour rollover", () => {
+    expect(addTime("12:50:00", { minutes: 15 })).toBe("13:05:00")
+    expect(addTime("23:50:00", { minutes: 15 })).toBe("00:05:00")
+  })
+
+  test("subtracts minutes with hour underflow", () => {
+    expect(addTime("12:10:00", { minutes: -15 })).toBe("11:55:00")
+    expect(addTime("00:10:00", { minutes: -15 })).toBe("23:55:00")
+  })
+
+  test("adds hours with 24-hour rollover", () => {
+    expect(addTime("22:15:00", { hours: 3 })).toBe("01:15:00")
+    expect(addTime("00:00:00", { hours: 24 })).toBe("00:00:00")
+    expect(addTime("23:59:59", { hours: 1 })).toBe("00:59:59")
+  })
+
+  test("subtracts hours with 24-hour underflow", () => {
+    expect(addTime("01:15:00", { hours: -3 })).toBe("22:15:00")
+    expect(addTime("00:00:00", { hours: -24 })).toBe("00:00:00")
+    expect(addTime("00:59:59", { hours: -1 })).toBe("23:59:59")
+  })
+
+  test("handles both hours and minutes together", () => {
+    expect(addTime("22:30:00", { hours: 2, minutes: 45 })).toBe("01:15:00")
+    expect(addTime("01:15:00", { hours: -2, minutes: -30 })).toBe("22:45:00")
+  })
+
+  test("pads single digit hours, minutes, seconds", () => {
+    expect(addTime("1:2:3", { hours: 0, minutes: 0 })).toBe("01:02:03")
+    expect(addTime("9:8", { hours: 0, minutes: 0 })).toBe("09:08:00")
+  })
+
+  // Edge case: negative minutes that require multiple hour underflows
+  test("handles large negative minutes", () => {
+    expect(addTime("05:10:00", { minutes: -130 })).toBe("03:00:00")
+  })
+
+  // Edge case: large positive minutes that require multiple hour rollovers
+  test("handles large positive minutes", () => {
+    expect(addTime("05:10:00", { minutes: 130 })).toBe("07:20:00")
+  })
+
+  // Edge case: input with seconds omitted
+  test("handles input with no seconds", () => {
+    expect(addTime("12:34", { minutes: 0 })).toBe("12:34:00")
+  })
+
+  // Edge case: input with all zeros
+  test("handles midnight", () => {
+    expect(addTime("00:00:00", { hours: 0, minutes: 0 })).toBe("00:00:00")
+  })
+})