@tim-code/my-util 0.2.4 → 0.2.6

package/package.json

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

package/src/object.js

@@ -55,3 +55,37 @@ export function like(template) {
     return true
   }
 }
+
+/**
+ * Deeply merges one or more source objects into a target object.
+ * If the property values are objects, they are merged recursively.
+ * Non-object properties (including arrays) are directly assigned to the target.
+ * @param {Object} target The target object that will receive the merged properties.
+ * @param {...Object} sources The source objects whose properties will be merged into the target.
+ * @returns {Object} The target object with the merged properties from all source objects.
+ */
+export function deepMerge(target, ...sources) {
+  for (const source of sources) {
+    const keys = Object.keys(source)
+    for (const key of keys) {
+      if (!Object.hasOwn(source, key)) {
+        continue
+      }
+      const targetValue = target[key]
+      const sourceValue = source[key]
+      if (Array.isArray(sourceValue)) {
+        target[key] = sourceValue
+      } else if (
+        targetValue &&
+        typeof targetValue === "object" &&
+        sourceValue &&
+        typeof sourceValue === "object"
+      ) {
+        deepMerge(targetValue, sourceValue)
+      } else {
+        target[key] = sourceValue
+      }
+    }
+  }
+  return target
+}

package/src/object.test.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-restricted-syntax */
 import { jest } from "@jest/globals"
-import { deleteUndefinedValues, like, mutateValues, via } from "./object.js"
+import { deepMerge, deleteUndefinedValues, like, mutateValues, via } from "./object.js"
 
 describe("mutateValues", () => {
   it("mutates values in the object using the callback", () => {
@@ -159,3 +159,101 @@ describe("contains", () => {
     expect(fn(obj)).toBe(false)
   })
 })
+
+describe("deepMerge", () => {
+  it("merges flat objects", () => {
+    const target = { a: 1, b: 2 }
+    const source = { b: 3, c: 4 }
+    expect(deepMerge(target, source)).toEqual({ a: 1, b: 3, c: 4 })
+    expect(target).toEqual({ a: 1, b: 3, c: 4 })
+  })
+
+  it("deeply merges nested objects", () => {
+    const target = { a: { x: 1, y: 2 }, b: 2 }
+    const source = { a: { y: 3, z: 4 }, b: 5 }
+    expect(deepMerge(target, source)).toEqual({ a: { x: 1, y: 3, z: 4 }, b: 5 })
+    expect(target).toEqual({ a: { x: 1, y: 3, z: 4 }, b: 5 })
+  })
+
+  it("overwrites arrays instead of merging them", () => {
+    const target = { arr: [1, 2], a: 1 }
+    const source = { arr: [3, 4] }
+    expect(deepMerge(target, source)).toEqual({ arr: [3, 4], a: 1 })
+  })
+
+  it("merges multiple sources left-to-right", () => {
+    const target = { a: 1 }
+    const s1 = { b: 2 }
+    const s2 = { a: 3, c: 4 }
+    expect(deepMerge(target, s1, s2)).toEqual({ a: 3, b: 2, c: 4 })
+  })
+
+  it("does not merge non-object values, just assigns", () => {
+    const target = { a: { x: 1 } }
+    const source = { a: 2 }
+    expect(deepMerge(target, source)).toEqual({ a: 2 })
+  })
+
+  it("handles empty sources", () => {
+    const target = { a: 1 }
+    expect(deepMerge(target)).toEqual({ a: 1 })
+    expect(deepMerge(target, {})).toEqual({ a: 1 })
+  })
+
+  it("handles empty target", () => {
+    const target = {}
+    const source = { a: 1 }
+    expect(deepMerge(target, source)).toEqual({ a: 1 })
+  })
+
+  it("does not merge inherited properties from sources", () => {
+    const proto = { x: 1 }
+    const source = Object.create(proto)
+    source.a = 2
+    const target = {}
+    expect(deepMerge(target, source)).toEqual({ a: 2 })
+    expect("x" in target).toBe(false)
+  })
+
+  it("merges deeply with multiple sources", () => {
+    const target = { a: { x: 1 } }
+    const s1 = { a: { y: 2 } }
+    const s2 = { a: { z: 3 } }
+    expect(deepMerge(target, s1, s2)).toEqual({ a: { x: 1, y: 2, z: 3 } })
+  })
+
+  it("does not merge if source value is null", () => {
+    const target = { a: { x: 1 } }
+    const source = { a: null }
+    expect(deepMerge(target, source)).toEqual({ a: null })
+  })
+
+  it("does not merge if target value is null", () => {
+    const target = { a: null }
+    const source = { a: { x: 1 } }
+    expect(deepMerge(target, source)).toEqual({ a: { x: 1 } })
+  })
+
+  it("does not merge arrays deeply", () => {
+    const target = { a: [1, 2, 3] }
+    const source = { a: [4, 5] }
+    expect(deepMerge(target, source)).toEqual({ a: [4, 5] })
+  })
+
+  it("does not merge non-enumerable properties from source", () => {
+    const target = {}
+    const source = {}
+    Object.defineProperty(source, "hidden", {
+      value: 123,
+      enumerable: false,
+    })
+    expect(deepMerge(target, source)).toEqual({})
+    expect("hidden" in target).toBe(false)
+  })
+
+  it("returns the target object", () => {
+    const target = { a: 1 }
+    const result = deepMerge(target, { b: 2 })
+    expect(result).toBe(target)
+  })
+})

package/src/time.js

@@ -53,19 +53,27 @@ export function today() {
 }
 
 /**
- * Get the day of the week from a YYYY-MM-DD string.
+ * Get the day of the week index from a YYYY-MM-DD string.
  * @param {string=} string YYYY-MM-DD
- * @returns {string} "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"
+ * @returns {string} 0, 1, 2, 3, 4, 5, 6; 0 is Sunday and, 1 is Monday, ... 6 is Saturday
  */
-export function getDayOfWeek(string = today()) {
+export function getDayIndexInWeek(string = today()) {
   const [year, month, day] = string.split("-").map(Number)
-  const dayOfWeek = new Date(year, month - 1, day)
-    .toLocaleDateString("en-US", { weekday: "long" })
-    .toLowerCase()
-  if (dayOfWeek === "invalid date") {
-    throw new Error(`invalid date passed: ${string}`)
+  const index = new Date(year, month - 1, day).getDay()
+  if (isNaN(index)) {
+    throw new Error(`invalid date: ${string}`)
   }
-  return dayOfWeek
+  return index
+}
+
+/**
+ * Get the minute from a time string.
+ * @param {string} time HH:mm or HH:mm::ss
+ * @returns {number} Between 0 and 59 inclusive
+ */
+export function getMinute(time) {
+  const minute = Number(time.split(":")[1])
+  return minute
 }
 
 /**

package/src/time.test.js

@@ -3,8 +3,10 @@ import {
   addDays,
   addTime,
   getDateRange,
-  getDayOfWeek,
+  getDayIndexInWeek,
+  // getDayOfWeek, // removed, replaced by getDayIndexInWeek
   getEasternTime,
+  getMinute,
   getTime,
   getTimeRange,
   isDate,
@@ -13,14 +15,12 @@ import {
   today,
 } from "./time.js"
 
-// getEasternTime changed: now accepts a "timezone" param and no longer returns "minute" or "datetime"
 describe("getEasternTime", () => {
   test("returns correct structure and types", () => {
     const result = getEasternTime()
     expect(typeof result.timestamp).toBe("number")
     expect(typeof result.date).toBe("string")
     expect(typeof result.time).toBe("string")
-    // minute and datetime are no longer returned
     expect(result).not.toHaveProperty("minute")
     expect(result).not.toHaveProperty("datetime")
   })
@@ -53,7 +53,6 @@ describe("getEasternTime", () => {
     expect(def.timestamp).toEqual(explicit.timestamp)
   })
 
-  // New: test timezone override
   test("respects timezone parameter", () => {
     // 2024-06-01T12:34:56Z (UTC)
     const ts = 1717245296
@@ -66,7 +65,6 @@ describe("getEasternTime", () => {
     expect(eastern.time).not.toBe(pacific.time)
     expect(eastern.time).not.toBe(utc.time)
     expect(pacific.time).not.toBe(utc.time)
-    // Should match expected hour offset
     expect(eastern.time.startsWith("08:34")).toBe(true) // EDT
     expect(pacific.time.startsWith("05:34")).toBe(true) // PDT
     expect(utc.time.startsWith("12:34")).toBe(true) // UTC
@@ -93,7 +91,6 @@ describe("getEasternTime", () => {
     expect(local.time).toBe(time)
   })
 
-  // DST boundary tests
   test("handles DST start (spring forward) correctly", () => {
     // In 2024, DST starts in US/Eastern at 2024-03-10 02:00:00 local time (clocks jump to 03:00:00)
     // 2024-03-10T06:59:59Z = 1:59:59 EST (should be 01:59:59)
@@ -133,7 +130,6 @@ describe("getEasternTime", () => {
   })
 })
 
-// New tests for getTime (newly exported function)
 describe("getTime", () => {
   test("returns same structure as getEasternTime", () => {
     const result = getTime({})
@@ -188,30 +184,52 @@ describe("today", () => {
   })
 })
 
-describe("getDayOfWeek", () => {
-  test("returns correct day of week for known dates", () => {
-    expect(getDayOfWeek("2024-06-01")).toBe("saturday")
-    expect(getDayOfWeek("2024-06-02")).toBe("sunday")
-    expect(getDayOfWeek("2024-06-03")).toBe("monday")
-    expect(getDayOfWeek("2024-06-04")).toBe("tuesday")
-    expect(getDayOfWeek("2024-06-05")).toBe("wednesday")
-    expect(getDayOfWeek("2024-06-06")).toBe("thursday")
-    expect(getDayOfWeek("2024-06-07")).toBe("friday")
+describe("getDayIndexInWeek", () => {
+  test("returns correct index for known dates", () => {
+    expect(getDayIndexInWeek("2024-06-02")).toBe(0)
+    expect(getDayIndexInWeek("2024-06-03")).toBe(1)
+    expect(getDayIndexInWeek("2024-06-04")).toBe(2)
+    expect(getDayIndexInWeek("2024-06-05")).toBe(3)
+    expect(getDayIndexInWeek("2024-06-06")).toBe(4)
+    expect(getDayIndexInWeek("2024-06-07")).toBe(5)
+    expect(getDayIndexInWeek("2024-06-08")).toBe(6)
   })
 
-  test("returns correct day for leap day", () => {
-    expect(getDayOfWeek("2024-02-29")).toBe("thursday")
+  test("returns correct index for leap day", () => {
+    // 2024-02-29 is Thursday (4)
+    expect(getDayIndexInWeek("2024-02-29")).toBe(4)
   })
 
   test("defaults to today() if no argument is given", () => {
-    // Should match today()'s day of week
     const todayDate = today()
-    expect(getDayOfWeek()).toBe(getDayOfWeek(todayDate))
+    expect(getDayIndexInWeek()).toBe(getDayIndexInWeek(todayDate))
   })
 
-  test("handles invalid date strings (returns 'invalid date')", () => {
-    expect(() => getDayOfWeek("not-a-date")).toThrow(/invalid date/u)
-    expect(getDayOfWeek("2024-02-31")).toBe("saturday")
+  test("throws on invalid date strings", () => {
+    expect(() => getDayIndexInWeek("not-a-date")).toThrow(/invalid date/u)
+    // don't worry about bad dates like the following; can be caught with isDate()
+    expect(getDayIndexInWeek("2024-02-31")).toBe(6)
+  })
+})
+
+// New tests for getMinute
+describe("getMinute", () => {
+  test("extracts minute from HH:mm:ss", () => {
+    expect(getMinute("12:34:56")).toBe(34)
+    expect(getMinute("00:01:00")).toBe(1)
+    expect(getMinute("23:59:59")).toBe(59)
+  })
+
+  test("extracts minute from HH:mm", () => {
+    expect(getMinute("12:34")).toBe(34)
+    expect(getMinute("00:01")).toBe(1)
+    expect(getMinute("23:59")).toBe(59)
+  })
+
+  test("handles single-digit minutes", () => {
+    expect(getMinute("12:07:00")).toBe(7)
+    expect(getMinute("12:7:00")).toBe(7)
+    expect(getMinute("12:7")).toBe(7)
   })
 })
 
@@ -327,27 +345,22 @@ describe("addTime", () => {
     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")
   })
 
-  // New: test default parameters (no options argument)
   test("handles missing options argument (all defaults)", () => {
     expect(addTime("12:34:56")).toBe("12:34:56")
     expect(addTime("05:10")).toBe("05:10:00")
@@ -419,14 +432,12 @@ describe("addDays", () => {
     expect(addDays("2024-01-01", { days: -1 })).toBe("2023-12-31")
   })
 
-  // DST boundary: adding days across US DST start (spring forward)
   test("adds days across DST start (spring forward) (object param)", () => {
     expect(addDays("2024-03-09", { days: 1 })).toBe("2024-03-10")
     expect(addDays("2024-03-09", { days: 2 })).toBe("2024-03-11")
     expect(addDays("2024-03-10", { days: -1 })).toBe("2024-03-09")
   })
 
-  // DST boundary: adding days across US DST end (fall back)
   test("adds days across DST end (fall back) (object param)", () => {
     expect(addDays("2024-11-02", { days: 1 })).toBe("2024-11-03")
     expect(addDays("2024-11-02", { days: 2 })).toBe("2024-11-04")