@tim-code/my-util 0.7.3 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.7.3",
+  "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,16 @@ 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 })
 }
 
 /**
@@ -107,7 +120,9 @@ export function isDateString(string) {
 }
 
 /**
- * Checks if the string represent a valid HH:mm:ss time.
+ * 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}
  */
@@ -115,6 +130,33 @@ export function isTimeString(string) {
   return /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/u.test(string)
 }
 
+/**
+ * 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 isDateTimeString(string, { separator = "T" } = {}) {
+  const [date, time] = string.split(separator)
+  return isDateString(date) && isTimeString(time)
+}
+
+/**
+ * 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 isUTCString(string) {
+  if (!string.endsWith("Z")) {
+    return false
+  }
+  const datetime = string.slice(0, string.length - 1)
+  return isDateTimeString(datetime)
+}
+
 /**
  * Checks if a number is a Unix timestamp (i.e. in seconds).
  * Would not validate timestamps set very far into the future.

package/src/time.test.js

@@ -11,11 +11,18 @@ import {
   getTimeRange,
   getUnixTimestamp,
   isDateString,
+  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()
@@ -46,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 })
@@ -169,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 })
@@ -233,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)
@@ -278,6 +308,42 @@ describe("isTimeString", () => {
   })
 })
 
+describe("isDateTimeString", () => {
+  test("valid with default T separator", () => {
+    expect(isDateTimeString("2024-06-01T12:34:56")).toBe(true)
+  })
+
+  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("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("isUTCString", () => {
+  test("validates proper Zulu UTC format", () => {
+    expect(isUTCString("2024-06-01T12:34:56Z")).toBe(true)
+  })
+
+  test("rejects strings without trailing Z", () => {
+    expect(isUTCString("2024-06-01T12:34:56")).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
+  })
+})
+
 describe("isUnixTimestamp", () => {
   test("returns true for valid unix timestamps in seconds", () => {
     expect(isUnixTimestamp(0)).toBe(true)
@@ -494,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