@tim-code/my-util 0.7.3 → 0.8.1

package/package.json

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

package/src/array.js

@@ -194,6 +194,12 @@ function naturalCompare(a, b) {
     b = b.slice(1, b.length)
     return b.localeCompare(a, undefined, { numeric: true })
   }
+  if (a[0] === "+" && !Number.isNaN(Number(a))) {
+    a = a.slice(1, a.length)
+  }
+  if (b[0] === "+" && !Number.isNaN(Number(b))) {
+    b = b.slice(1, b.length)
+  }
   return a.localeCompare(b, undefined, { numeric: true })
 }
 

package/src/array.test.js

@@ -542,6 +542,18 @@ describe("naturalAsc", () => {
     arr.sort(naturalAsc())
     expect(arr).toEqual(["-10", "-2", "-1"])
   })
+
+  it("can sort negative to positive", () => {
+    const arr = ["-2", "+5", "0"]
+    arr.sort(naturalAsc())
+    expect(arr).toEqual(["-2", "0", "+5"])
+  })
+
+  it("handles leading plus signs on numeric-like strings", () => {
+    const arr = ["a", "+10", "+2", "+1"]
+    arr.sort(naturalAsc())
+    expect(arr).toEqual(["+1", "+2", "+10", "a"])
+  })
 })
 
 describe("naturalDesc", () => {
@@ -586,6 +598,18 @@ describe("naturalDesc", () => {
     arr.sort(naturalDesc())
     expect(arr).toEqual(["-1", "-2", "-10"])
   })
+
+  it("can sort positive to negative", () => {
+    const arr = ["+5", "-2", "0"]
+    arr.sort(naturalDesc())
+    expect(arr).toEqual(["+5", "0", "-2"])
+  })
+
+  it("handles leading plus signs on numeric-like strings (descending)", () => {
+    const arr = ["+1", "+2", "+10", "a"]
+    arr.sort(naturalDesc())
+    expect(arr).toEqual(["a", "+10", "+2", "+1"])
+  })
 })
 
 describe("multilevel", () => {

package/src/time.js

@@ -3,22 +3,28 @@ import { mod } from "./math.js"
 /**
  * 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 +41,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 })
 }
 
 /**
@@ -78,7 +87,7 @@ export function getDayIndexInWeek(string = today()) {
 
 /**
  * Get the minute from a time string.
- * @param {string} time HH:mm or HH:mm::ss
+ * @param {string} time HH:mm or HH:mm:ss
  * @returns {number} Between 0 and 59 inclusive
  */
 export function getMinute(time) {
@@ -107,7 +116,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 +126,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