@tim-code/my-util 0.0.3 → 0.0.4

package/package.json

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

package/src/array.js

@@ -92,6 +92,15 @@ export function descending(key) {
   }
 }
 
+/**
+ * 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

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
@@ -62,6 +65,7 @@ export function isTime(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
@@ -70,3 +74,29 @@ export function isTime(string) {
 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, isDate, isTime, isUnixTimestamp } from "./time.js"
+import { addTime, getEasternTime, isDate, isTime, isUnixTimestamp } from "./time.js"
 
 describe("getEasternTime", () => {
   test("returns correct structure and types", () => {
@@ -119,4 +119,63 @@ describe("isUnixTimestamp", () => {
     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")
+  })
+})