@tim-code/my-util 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",

package/src/time.js

@@ -1,24 +1,34 @@
 import { mod } from "./math.js"
 
+// `floorMinute` at first glance seems ugly and something like `floor: "minute"` seems better.
+// However, practically and realistically, it doesn't seem like we need other values for floor besides "second" and "minute".
+// So, then it seems more problematic to rely on an exact string to be passed... probably would need to throw on some other value.
+// We don't really ever want to disable flooring because we want timestamp, date, and time returned to represent the same thing.
 /**
  * Gets various ways of representing the current time in EDT. Floors to nearest second by default.
  * @param {Object} $1
- * @param {boolean=} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second.
- * @param {number=} $1.timestamp Unix timestamp to use instead of current time.
- * @param {string=} $1.timeZone Time zone to use instead of Eastern time. A falsy value corresponds to local time.
+ * @param {number=} $1.timestamp Unix timestamp to use instead of now (in seconds).
+ * @param {Date=} $1.dateInstance Alternative to specifying timestamp that is a Date instance.
+ *  This can be used to specify UTC: `getEasternTime({ dateInstance: new Date(utc) })`.
+ * @param {boolean=} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second (default).
+ * @param {string=} $1.timeZone Time zone to use instead of Eastern time. A falsy, not-undefined value corresponds to local time.
  * @returns {Object} { timestamp, date: YYYY-MM-DD, time: HH:mm:ss }
+ *  If invalid timestamp or dateInstance specified: { timestamp: NaN|Infinity, date: "Invalid date", time: undefined }
  */
 export function getEasternTime({
+  dateInstance = undefined,
+  timestamp = (dateInstance ?? new Date()).getTime() / 1000,
   floorMinute = false,
-  timestamp = undefined,
   timeZone = "America/New_York",
 } = {}) {
-  if (!timestamp) {
-    timestamp = new Date().getTime() / 1000
+  if (floorMinute) {
+    timestamp = Math.floor(timestamp / 60) * 60
+  } else {
+    timestamp = Math.floor(timestamp)
   }
-  timestamp = floorMinute ? Math.floor(timestamp / 60) * 60 : Math.floor(timestamp)
+  const flooredDateInstance = new Date(timestamp * 1000)
   // 'en-CA' (English - Canada) formats dates as YYYY-MM-DD and times in 24-hour format by default
-  const string = new Date(timestamp * 1000).toLocaleString("en-CA", {
+  const string = flooredDateInstance.toLocaleString("en-CA", {
     ...(timeZone ? { timeZone } : {}),
     hour12: false,
     year: "numeric",
@@ -35,13 +45,26 @@ export function getEasternTime({
 /**
  * Gets various ways of representing the current time in local timezone. Floors to nearest second by default.
  * @param {Object} $1
+ * @param {number=} $1.timestamp Unix timestamp to use instead of now (in seconds).
+ * @param {Date=} $1.dateInstance Alternative to specifying timestamp that is a Date instance.
+ *  This can be used to specify UTC: `getEasternTime({ dateInstance: new Date(utc) })`.
  * @param {boolean=} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second.
- * @param {number=} $1.timestamp Unix timestamp to use instead of current time.
- * @param {string=} $1.timeZone Time zone to use instead of local time. A falsy value (default) corresponds to local time.
- * @returns {Object} { timestamp, date, time, minute, datetime }
+ * @param {string=} $1.timeZone Time zone to use instead of local time. A falsy value corresponds to local time (default) .
+ * @returns {Object} { timestamp, date: YYYY-MM-DD, time: HH:mm:ss }
+ *  If invalid timestamp or dateInstance specified: { timestamp: NaN|Infinity, date: "Invalid date", time: undefined }
  */
-export function getTime({ floorMinute, timestamp, timeZone = false } = {}) {
-  return getEasternTime({ floorMinute, timestamp, timeZone })
+export function getTime({ timestamp, dateInstance, floorMinute, timeZone = false } = {}) {
+  return getEasternTime({ timestamp, dateInstance, floorMinute, timeZone })
+}
+
+/**
+ * Get Unix timestamp for a UTC date string.
+ * @param {string} utc UTC date time: "YYYY-MM-DDTHH:mm:ssZ" or with UTC offset
+ * @returns {number} Seconds since epoch
+ */
+export function getUnixTimestamp(utc) {
+  const timestamp = Math.floor(new Date(utc).getTime() / 1000)
+  return timestamp
 }
 
 /**
@@ -97,30 +120,41 @@ export function isDateString(string) {
 }
 
 /**
- * @deprecated Prefer isDateString()
+ * Checks if the string represents a valid HH:mm:ss time.
+ * This will return false for times like "24:00:00".
+ * Does not handle milliseconds.
  * @param {string} string
  * @returns {boolean}
  */
-export function isDate(string) {
-  return isDateString(string)
+export function isTimeString(string) {
+  return /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/u.test(string)
 }
 
 /**
- * Checks if the string represent a valid HH:mm:ss time.
+ * Checks if the string represents a valid date time string similar to YYYY-MM-DDTHH:mm:ss.
+ * Does not handle milliseconds.
  * @param {string} string
+ * @param {Object} $1
+ * @param {string=} $1.separator Can specify a different string separator between date and time. Defaults to "T".
  * @returns {boolean}
  */
-export function isTimeString(string) {
-  return /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/u.test(string)
+export function isDateTimeString(string, { separator = "T" } = {}) {
+  const [date, time] = string.split(separator)
+  return isDateString(date) && isTimeString(time)
 }
 
 /**
- * @deprecated Prefer isTimeString()
+ * Checks if the string represents a valid UTC date time similar to YYYY-MM-DDTHH:mm:ssZ.
+ * Does not handle milliseconds or UTC offsets.
  * @param {string} string
  * @returns {boolean}
  */
-export function isTime(string) {
-  return isTimeString(string)
+export function isUTCString(string) {
+  if (!string.endsWith("Z")) {
+    return false
+  }
+  const datetime = string.slice(0, string.length - 1)
+  return isDateTimeString(datetime)
 }
 
 /**

package/src/time.test.js

@@ -9,14 +9,20 @@ import {
   getStartOfWeek,
   getTime,
   getTimeRange,
-  isDate,
+  getUnixTimestamp,
   isDateString,
-  isTime,
+  isDateTimeString,
   isTimeString,
+  isUTCString,
   isUnixTimestamp,
   today,
 } from "./time.js"
 
+// Exported functions:
+// getEasternTime, getTime, getUnixTimestamp, today, getDayIndexInWeek, getMinute,
+// isDateString, isTimeString, isDateTimeString, isUTCString, isUnixTimestamp,
+// addTime, getTimeRange, addDays, getDateRange, getStartOfWeek
+
 describe("getEasternTime", () => {
   test("returns correct structure and types", () => {
     const result = getEasternTime()
@@ -47,6 +53,22 @@ describe("getEasternTime", () => {
     expect(floored.time.endsWith(":00")).toBe(true)
   })
 
+  test("accepts dateInstance and matches equivalent timestamp", () => {
+    const ts = 1717245296 // 2024-06-01T12:34:56Z
+    const di = new Date(ts * 1000)
+    const a = getEasternTime({ dateInstance: di, timeZone: "UTC" })
+    const b = getEasternTime({ timestamp: ts, timeZone: "UTC" })
+    expect(a).toEqual(b)
+  })
+
+  test("dateInstance path respects floorMinute", () => {
+    const ts = 1717245296 // ...:56
+    const di = new Date(ts * 1000)
+    const floored = getEasternTime({ dateInstance: di, floorMinute: true, timeZone: "UTC" })
+    expect(floored.timestamp % 60).toBe(0)
+    expect(floored.time).toBe("12:34:00")
+  })
+
   test("default parameters yield consistent output", () => {
     const def = getEasternTime()
     const explicit = getEasternTime({ floorMinute: false })
@@ -170,6 +192,14 @@ describe("getTime", () => {
     expect(pacific).toEqual(ref)
   })
 
+  test("accepts dateInstance and matches equivalent timestamp", () => {
+    const ts = 1717245296
+    const di = new Date(ts * 1000)
+    const a = getTime({ dateInstance: di, timeZone: "UTC" })
+    const b = getTime({ timestamp: ts, timeZone: "UTC" })
+    expect(a).toEqual(b)
+  })
+
   test("floors to minute if floorMinute is true", () => {
     const ts = 1717245296
     const floored = getTime({ timestamp: ts, floorMinute: true })
@@ -178,6 +208,26 @@ describe("getTime", () => {
   })
 })
 
+describe("getUnixTimestamp", () => {
+  test("parses Zulu (UTC) timestamp", () => {
+    expect(getUnixTimestamp("2024-06-01T12:34:56Z")).toBe(1717245296)
+  })
+
+  test("parses timestamp with positive offset", () => {
+    const expected = Date.UTC(2024, 5, 1, 10, 34, 56) / 1000 // 12:34:56+02:00 == 10:34:56Z
+    expect(getUnixTimestamp("2024-06-01T12:34:56+02:00")).toBe(expected)
+  })
+
+  test("floors fractional seconds", () => {
+    // 999ms floors down to the same second
+    expect(getUnixTimestamp("1970-01-01T00:00:00.999Z")).toBe(0)
+  })
+
+  test("returns NaN for invalid date string", () => {
+    expect(Number.isNaN(getUnixTimestamp("not-a-date"))).toBe(true)
+  })
+})
+
 describe("today", () => {
   test("returns today's date in YYYY-MM-DD format", () => {
     const expected = getTime().date
@@ -214,7 +264,6 @@ describe("getDayIndexInWeek", () => {
   })
 })
 
-// New tests for getMinute
 describe("getMinute", () => {
   test("extracts minute from HH:mm:ss", () => {
     expect(getMinute("12:34:56")).toBe(34)
@@ -247,67 +296,51 @@ describe("isDateString", () => {
   })
 })
 
-describe("isDate (deprecated wrapper)", () => {
-  test("returns true for valid YYYY-MM-DD dates", () => {
-    expect(isDate("2024-06-01")).toBe(true)
-    expect(isDate("1999-12-31")).toBe(true)
+describe("isTimeString", () => {
+  test("validates correct times", () => {
+    expect(isTimeString("00:00:00")).toBe(true)
+    expect(isTimeString("23:59:59")).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("rejects invalid times and formats", () => {
+    expect(isTimeString("24:00:00")).toBe(false)
+    expect(isTimeString("12:34")).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)
+describe("isDateTimeString", () => {
+  test("valid with default T separator", () => {
+    expect(isDateTimeString("2024-06-01T12:34:56")).toBe(true)
   })
 
-  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("rejects invalid combinations", () => {
+    expect(isDateTimeString("2024-06-01T12:34")).toBe(false) // missing seconds
+    expect(isDateTimeString("2024-06-01T24:00:00")).toBe(false) // invalid hour
+    expect(isDateTimeString("2024-02-31T12:00:00")).toBe(false) // invalid date
+    expect(isDateTimeString("2024-06-01 12:34:56")).toBe(false) // wrong separator
   })
 
-  test("returns true for leap day", () => {
-    expect(isDate("2024-02-29")).toBe(true)
-    expect(isDate("2023-02-29")).toBe(false)
+  test("supports custom separator", () => {
+    expect(isDateTimeString("2024-06-01 12:34:56", { separator: " " })).toBe(true)
+    expect(isDateTimeString("2024-06-01T12:34:56", { separator: " " })).toBe(false)
   })
 })
 
-describe("isTimeString", () => {
-  test("validates correct times", () => {
-    expect(isTimeString("00:00:00")).toBe(true)
-    expect(isTimeString("23:59:59")).toBe(true)
+describe("isUTCString", () => {
+  test("validates proper Zulu UTC format", () => {
+    expect(isUTCString("2024-06-01T12:34:56Z")).toBe(true)
   })
 
-  test("rejects invalid times and formats", () => {
-    expect(isTimeString("24:00:00")).toBe(false)
-    expect(isTimeString("12:34")).toBe(false)
+  test("rejects strings without trailing Z", () => {
+    expect(isUTCString("2024-06-01T12:34:56")).toBe(false)
   })
-})
 
-describe("isTime (deprecated wrapper)", () => {
-  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)
+  test("rejects invalid time/date and unsupported variants", () => {
+    expect(isUTCString("2024-06-01T24:00:00Z")).toBe(false) // invalid hour
+    expect(isUTCString("2024-02-31T12:00:00Z")).toBe(false) // invalid date
+    expect(isUTCString("2024-06-01T12:34:56+00:00")).toBe(false) // offset not supported
+    expect(isUTCString("2024-06-01T12:34:56.123Z")).toBe(false) // milliseconds not supported
+    expect(isUTCString("2024-06-01 12:34:56Z")).toBe(false) // wrong separator
   })
 })
 
@@ -428,6 +461,14 @@ describe("getTimeRange", () => {
   test("handles input with no seconds", () => {
     expect(getTimeRange("12:00", "12:02")).toEqual(["12:00:00", "12:01:00", "12:02:00"])
   })
+
+  // ISSUE: getTimeRange allows a zero step, which would otherwise loop forever; it's capped internally at 1440 iterations.
+  test("caps the number of results at MINUTES_IN_DAY when step is zero", () => {
+    const result = getTimeRange("12:00:00", "12:00:00", { hours: 0, minutes: 0 })
+    expect(result.length).toBe(24 * 60)
+    expect(result[0]).toBe("12:00:00")
+    expect(result[result.length - 1]).toBe("12:00:00")
+  })
 })
 
 describe("addDays", () => {
@@ -519,7 +560,6 @@ describe("getDateRange", () => {
   })
 })
 
-// Tests for getStartOfWeek (newly exported function)
 describe("getStartOfWeek", () => {
   test("returns same date if input is Sunday", () => {
     expect(getStartOfWeek("2024-06-02")).toBe("2024-06-02") // Sunday