@tim-code/my-util 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tim Sprowl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# my-util
+
+This library includes common util functions. It does not have any dependencies.
+
+This may include rewritten functionality from Lodash in the future (i.e. orderBy). groupBy should be available when using Node 22.
+
+## First Time Setup
+
+`npm install`

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tim-code/my-util",
+  "version": "0.0.1",
+  "description": "",
+  "type": "module",
+  "author": "",
+  "license": "MIT",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --no-warnings --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@tim-code"
+    ]
+  },
+  "devDependencies": {
+    "@tim-code/eslint-config": "^1.1.7",
+    "@jest/globals": "^29.7.0",
+    "@types/node": ">=20 <21",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "transform": {}
+  }
+}

package/src/array.js

@@ -0,0 +1,29 @@
+/**
+ * Converts an array into an array of arrays, where each subarray has a maximum size of chunkSize.
+ * Note the last subarray may have a length less than chunkSize.
+ * @param {Array} array
+ * @param {number=} chunkSize If not provided, defaults to the length of array, returning the input array as one chunk.
+ * @returns {Array}
+ */
+export function chunk(array, chunkSize = array.length) {
+  if (!array.length) {
+    return []
+  }
+  if (chunkSize <= 0 || chunkSize % 1 !== 0) {
+    throw new Error("chunkSize must be a positive integer")
+  }
+  const chunked = []
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunked.push(array.slice(i, i + chunkSize))
+  }
+  return chunked
+}
+
+/**
+ * Shorthand for returning all unique elements in an array.
+ * @param {Array} array
+ * @returns {Array}
+ */
+export function unique(array) {
+  return [...new Set(array)]
+}

package/src/array.test.js

@@ -0,0 +1,71 @@
+// src/array.test.js
+import { describe, expect, it } from "@jest/globals"
+
+const { chunk, unique } = await import("./array.js")
+
+describe("chunk", () => {
+  it("splits array into chunks of specified size", () => {
+    expect(chunk([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]])
+    expect(chunk([1, 2, 3, 4, 5, 6], 3)).toEqual([
+      [1, 2, 3],
+      [4, 5, 6],
+    ])
+  })
+
+  it("returns empty array when input is empty", () => {
+    expect(chunk([], 3)).toEqual([])
+  })
+
+  it("returns the entire array as one chunk if chunkSize >= array.length", () => {
+    expect(chunk([1, 2], 5)).toEqual([[1, 2]])
+    expect(chunk([1, 2], 2)).toEqual([[1, 2]])
+  })
+
+  it("returns the entire array as one chunk if chunkSize is omitted", () => {
+    expect(chunk([1, 2, 3])).toEqual([[1, 2, 3]])
+  })
+
+  it("throws if chunkSize is not a positive integer", () => {
+    expect(() => chunk([1, 2, 3], 0)).toThrow("chunkSize must be a positive integer")
+    expect(() => chunk([1, 2, 3], -1)).toThrow("chunkSize must be a positive integer")
+    expect(() => chunk([1, 2, 3], 1.5)).toThrow("chunkSize must be a positive integer")
+  })
+
+  it("handles chunkSize of 1 (each element in its own chunk)", () => {
+    expect(chunk([1, 2, 3], 1)).toEqual([[1], [2], [3]])
+  })
+
+  it("returns empty array when input is empty and chunkSize is omitted", () => {
+    expect(chunk([])).toEqual([])
+  })
+
+  it("returns one chunk if chunkSize is much larger than array length", () => {
+    expect(chunk([1, 2, 3], 100)).toEqual([[1, 2, 3]])
+  })
+})
+
+describe("unique", () => {
+  it("returns only unique elements, preserving order", () => {
+    expect(unique([1, 2, 2, 3, 1, 4])).toEqual([1, 2, 3, 4])
+    expect(unique(["a", "b", "a", "c"])).toEqual(["a", "b", "c"])
+  })
+
+  it("returns empty array when input is empty", () => {
+    expect(unique([])).toEqual([])
+  })
+
+  it("returns the same array if all elements are unique", () => {
+    expect(unique([1, 2, 3])).toEqual([1, 2, 3])
+  })
+
+  it("handles arrays with different types", () => {
+    expect(unique([1, "1", 1, "1"])).toEqual([1, "1"])
+    expect(unique([true, false, true])).toEqual([true, false])
+  })
+
+  it("handles arrays with objects (reference equality)", () => {
+    const a = {}
+    const b = {}
+    expect(unique([a, b, a])).toEqual([a, b])
+  })
+})

package/src/fs.js

@@ -0,0 +1,67 @@
+import { readFile, stat } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { promisify } from "node:util"
+import { gunzip as _gunzip } from "node:zlib"
+
+const gunzip = promisify(_gunzip)
+
+// the integration tests for this file are the s3-fs integration tests in lambda-integrations
+// changes to this file should be tested against lambda-integrations' integration tests
+
+/**
+ * Get JSON from a path.
+ * @param {string} path
+ * @returns {Object|Array}
+ */
+export async function getJSON(path) {
+  const buffer = await readFile(path)
+  return JSON.parse(buffer.toString())
+}
+
+/**
+ * Get gzipped JSON from a path.
+ * @param {string} path
+ * @returns {Object|Array}
+ */
+export async function getCompressedJSON(path) {
+  const buffer = await readFile(path)
+  const uncompressed = await gunzip(buffer)
+  return JSON.parse(uncompressed.toString())
+}
+
+/**
+ * Checks if the path exists using stat(). Returns stat() result if so.
+ * @param {string} path
+ * @param {Object} $1
+ * @param {number=} $1.maxAge Max age to consider in milliseconds.
+ * @param {boolean=} $1.throws Whether the function should throw or not if not found
+ * @returns {Object|false}
+ */
+export async function pathExists(path, { maxAge = undefined, throws = false } = {}) {
+  try {
+    const stats = await stat(path)
+    if (typeof maxAge === "number") {
+      const age = Date.now() - stats.mtime.getTime()
+      if (age <= maxAge) {
+        return stats
+      }
+      return false
+    }
+    return stats
+  } catch (error) {
+    // if caller wants all errors or the error isn't related to the path not being found
+    if (throws || error.code !== "ENOENT") {
+      throw error
+    }
+  }
+  return false
+}
+
+/**
+ * Make a path to a temporary directory.
+ * @returns {string}
+ */
+export function makeTempDirectory() {
+  const path = tmpdir()
+  return path
+}

package/src/fs.test.js

@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals"
+
+const readFileMock = jest.fn()
+const statMock = jest.fn()
+const tmpdirMock = jest.fn()
+const gunzipMock = jest.fn()
+jest.unstable_mockModule("node:fs/promises", () => ({
+  readFile: readFileMock,
+  stat: statMock,
+}))
+jest.unstable_mockModule("node:os", () => ({
+  tmpdir: tmpdirMock,
+}))
+jest.unstable_mockModule("node:zlib", () => ({
+  gunzip: gunzipMock,
+}))
+jest.unstable_mockModule("node:util", () => ({
+  promisify: (mock) => mock,
+}))
+
+// Now import the module under test
+const mod = await import("./fs.js")
+const { getJSON, getCompressedJSON, pathExists, makeTempDirectory } = mod
+
+describe("getJSON", () => {
+  beforeEach(() => jest.clearAllMocks())
+  it("parses JSON from file", async () => {
+    readFileMock.mockResolvedValue(Buffer.from('{"a":1}'))
+    const result = await getJSON("foo.json")
+    expect(result).toEqual({ a: 1 })
+    expect(readFileMock).toHaveBeenCalledWith("foo.json")
+  })
+})
+
+describe("getCompressedJSON", () => {
+  beforeEach(() => jest.clearAllMocks())
+  it("reads, decompresses, and parses JSON", async () => {
+    readFileMock.mockResolvedValue(Buffer.from("gzipped"))
+    gunzipMock.mockResolvedValue(Buffer.from('{"b":2}'))
+    const result = await getCompressedJSON("bar.gz")
+    expect(result).toEqual({ b: 2 })
+    expect(readFileMock).toHaveBeenCalledWith("bar.gz")
+    expect(gunzipMock).toHaveBeenCalled()
+  })
+})
+
+describe("pathExists", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+  it("returns stats if file exists", async () => {
+    const stats = { mtime: new Date(Date.now() - 1000) }
+    statMock.mockResolvedValue(stats)
+    const result = await pathExists("file.txt")
+    expect(result).toBe(stats)
+    expect(statMock).toHaveBeenCalledWith("file.txt")
+  })
+  it("returns false if file is too old for maxAge", async () => {
+    const stats = { mtime: new Date(Date.now() - 2000) }
+    statMock.mockResolvedValue(stats)
+    const result = await pathExists("file.txt", { maxAge: 1000 })
+    expect(result).toBe(false)
+  })
+  it("returns stats if file is within maxAge", async () => {
+    const stats = { mtime: new Date(Date.now() - 500) }
+    statMock.mockResolvedValue(stats)
+    const result = await pathExists("file.txt", { maxAge: 1000 })
+    expect(result).toBe(stats)
+  })
+  it("returns false if file does not exist and throws=false", async () => {
+    const err = Object.assign(new Error("not found"), { code: "ENOENT" })
+    statMock.mockRejectedValue(err)
+    const result = await pathExists("nope.txt", { throws: false })
+    expect(result).toBe(false)
+  })
+  it("throws if file does not exist and throws=true", async () => {
+    const err = Object.assign(new Error("not found"), { code: "ENOENT" })
+    statMock.mockRejectedValue(err)
+    await expect(pathExists("nope.txt", { throws: true })).rejects.toThrow("not found")
+  })
+  it("throws if stat throws for other reasons", async () => {
+    const err = Object.assign(new Error("bad"), { code: "EACCES" })
+    statMock.mockRejectedValue(err)
+    await expect(pathExists("bad.txt")).rejects.toThrow("bad")
+  })
+  it("returns stats if maxAge is undefined", async () => {
+    const stats = { mtime: new Date(Date.now() - 999999) }
+    statMock.mockResolvedValue(stats)
+    const result = await pathExists("file.txt", {})
+    expect(result).toBe(stats)
+  })
+})
+
+describe("makeTempDirectory", () => {
+  it("returns the temp directory", () => {
+    tmpdirMock.mockReturnValue("/tmp")
+    expect(makeTempDirectory()).toBe("/tmp")
+    expect(tmpdirMock).toHaveBeenCalled()
+  })
+})

package/src/index.js

@@ -0,0 +1,5 @@
+export * from "./array.js"
+export * from "./fs.js"
+export * from "./promise.js"
+export * from "./run.js"
+export * from "./time.js"

package/src/promise.js

@@ -0,0 +1,120 @@
+import { chunk } from "./array.js"
+
+/**
+ * Calls a function immediately and then every X milliseconds until the function does not return undefined, null or false.
+ * Note that other falsy values such as 0 or "" or NaN will resolve and be returned.
+ * This will never resolve if callback always returns undefined, null, or false. I may add a "max attempt" or "timeout" option at some point.
+ * @param {Function} callback
+ * @param {number} milliseconds
+ * @returns The result of the callback
+ */
+export function poll(callback, milliseconds) {
+  return new Promise((resolve, reject) => {
+    const resolver = async () => {
+      try {
+        const result = await callback()
+        if (result !== undefined && result !== null && result !== false) {
+          resolve(result)
+        } else {
+          setTimeout(resolver, milliseconds)
+        }
+      } catch (error) {
+        reject(error)
+      }
+    }
+    resolver()
+  })
+}
+
+/**
+ * Sleep for X milliseconds.
+ * @param {number} milliseconds
+ */
+export async function sleep(milliseconds) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, milliseconds)
+  })
+}
+
+/**
+ * Parallelize executions of a function using `Promise.allSettled()`.
+ * This is useful because usually you want to set a limit to the number of parallel requests possible at once.
+ * The output of this function contains the outcome of each call of the callback in a variety of formats.
+ *  - "results": Essentially the return value from Promise.allSettled().
+ *  - "values": The "value" property of each "result" object returned from allSettled(); this will be undefined if the associated promise rejects.
+ *  - "returned": The "value" property for each "result" object where the "status" property has a value of fulfilled.
+ *     This is arguably more useful than "values" unless you need to be able to index into the array based on the index of the promise.
+ *  - "errors": The "reason" property for each "result" object that did not have a status of "fulfilled".
+ * @param {Object} $1
+ * @param {Array} $1.array
+ * @param {number=} $1.limit If not provided, each call is done in parallel.
+ * @param {boolean=} $1.flatten Flattens values before returning; useful if promises return arrays
+ * @param {Function} callback
+ * @returns {Object} {results, values, returned, errors}
+ */
+export async function allSettled({ array, limit, flatten = false }, callback) {
+  const results = []
+  let returned = []
+  let values = []
+  const errors = []
+  const chunked = chunk(array, limit)
+  for (const elements of chunked) {
+    const promises = elements.map(callback)
+    const _results = await Promise.allSettled(promises)
+    for (const result of _results) {
+      const { value, status, reason } = result
+      results.push(result)
+      values.push(value)
+      if (status === "fulfilled") {
+        returned.push(value)
+      } else {
+        errors.push(reason)
+      }
+    }
+  }
+  if (flatten) {
+    values = values.flat()
+    returned = returned.flat()
+  }
+  return { values, returned, errors, results }
+}
+
+/**
+ * A convenience method to throw the result of allSettled().
+ * Useful in testing contexts when simply propagating the error is enough.
+ * @param {Object} result An object with an "errors" property i.e. awaited return value of allSettled()
+ * @returns {Object} result
+ */
+export function alert(result) {
+  const { errors } = result ?? {}
+  if (errors && errors.length) {
+    throw new Error(JSON.stringify(errors, undefined, 2))
+  }
+  return result
+}
+
+/**
+ * Parallelize executions of a function using `Promise.all()`.
+ * This is useful because usually you want to set a limit to the number of parallel requests possible at once.
+ * To maintain parity with allSettled(), this function provides both "values" and "returned" as output but they are the same array.
+ * Since this function throws on the first error (same behavior as Promise.all()), there isn't a situation where this function returns but an individual call errored.
+ * @param {Object} $1
+ * @param {Array} $1.array
+ * @param {number=} $1.limit If not provided, each call is done in parallel.
+ * @param {boolean=} $1.flatten Flattens values before returning; useful if promises return arrays
+ * @param {Function} callback
+ * @returns {Object} {values, returned}
+ */
+export async function throwFirstReject({ array, limit, flatten = false }, callback) {
+  let values = []
+  const chunked = chunk(array, limit)
+  for (const elements of chunked) {
+    const promises = elements.map(callback)
+    const _values = await Promise.all(promises)
+    values = values.concat(_values)
+  }
+  if (flatten) {
+    values = values.flat()
+  }
+  return { values, returned: values }
+}

package/src/promise.test.js

@@ -0,0 +1,174 @@
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable prefer-promise-reject-errors */
+import { jest } from "@jest/globals"
+
+const { poll, sleep, allSettled, alert, throwFirstReject } = await import("./promise.js")
+
+describe("poll", () => {
+  it("resolves immediately if callback returns a non-undefined/null/false value", async () => {
+    const cb = jest.fn().mockReturnValue(42)
+    const promise = poll(cb, 1000)
+    await expect(promise).resolves.toBe(42)
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it("resolves after several attempts when callback returns undefined/null/false before a value", async () => {
+    const cb = jest
+      .fn()
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(null)
+      .mockReturnValueOnce(false)
+      .mockReturnValueOnce(0)
+    const promise = poll(cb, 500)
+    // Advance timers for 3 unsuccessful attempts (undefined, null, false)
+    const before = Date.now()
+    // The fourth call returns 0, which should resolve
+    await expect(promise).resolves.toBe(0)
+    const after = Date.now()
+    expect((after - before) / 1000).toBeCloseTo(1.5, 1)
+    expect(cb).toHaveBeenCalledTimes(4)
+  })
+
+  it('resolves if callback returns "" or NaN (should not treat as "keep polling")', async () => {
+    const cb = jest.fn().mockReturnValueOnce("").mockReturnValueOnce(NaN)
+    const promise1 = poll(cb, 100)
+    await expect(promise1).resolves.toBe("")
+    expect(cb).toHaveBeenCalledTimes(1)
+    cb.mockClear()
+    const promise2 = poll(cb, 100)
+    await expect(promise2).resolves.toBe(NaN)
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it("rejects if callback throws", async () => {
+    const error = new Error("fail")
+    const cb = jest.fn().mockImplementation(() => {
+      throw error
+    })
+    await expect(poll(cb, 100)).rejects.toBe(error)
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it("rejects if callback returns a rejected promise", async () => {
+    const error = new Error("async fail")
+    const cb = jest.fn().mockReturnValue(Promise.reject(error))
+    const promise = poll(cb, 100)
+    await expect(promise).rejects.toBe(error)
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe("sleep", () => {
+  it("resolves after the specified milliseconds", async () => {
+    const before = Date.now()
+    const promise = sleep(500)
+    await expect(promise).resolves.toBeUndefined()
+    const after = Date.now()
+    expect((after - before) / 1000).toBeCloseTo(0.5, 1)
+  })
+})
+
+describe("allSettled", () => {
+  it("returns correct structure for all fulfilled", async () => {
+    const arr = [1, 2, 3]
+    const cb = (x) => x * 2
+    const result = await allSettled({ array: arr }, cb)
+    expect(result.values).toEqual([2, 4, 6])
+    expect(result.returned).toEqual([2, 4, 6])
+    expect(result.errors).toEqual([])
+    expect(result.results.every((r) => r.status === "fulfilled")).toBe(true)
+  })
+
+  it("handles rejected promises and collects errors", async () => {
+    const arr = [1, 2, 3]
+    const cb = (x) => (x === 2 ? Promise.reject("fail") : x + 1)
+    const result = await allSettled({ array: arr }, cb)
+    expect(result.values.length).toBe(3)
+    expect(result.returned).toEqual([2, 4])
+    expect(result.errors).toEqual(["fail"])
+    expect(result.results[1].status).toBe("rejected")
+  })
+
+  it("respects limit and processes in chunks", async () => {
+    const arr = [1, 2, 3, 4]
+    const calls = []
+    const cb = (x) => {
+      calls.push(x)
+      return x
+    }
+    const result = await allSettled({ array: arr, limit: 2 }, cb)
+    expect(result.values).toEqual([1, 2, 3, 4])
+    expect(calls).toEqual([1, 2, 3, 4])
+  })
+
+  it("flattens values and returned if flatten=true", async () => {
+    const arr = [1, 2]
+    const cb = (x) => [x, x + 1]
+    const result = await allSettled({ array: arr, flatten: true }, cb)
+    expect(result.values).toEqual([1, 2, 2, 3])
+    expect(result.returned).toEqual([1, 2, 2, 3])
+  })
+
+  it("handles empty array", async () => {
+    const result = await allSettled({ array: [] }, () => 1)
+    expect(result.values).toEqual([])
+    expect(result.returned).toEqual([])
+    expect(result.errors).toEqual([])
+    expect(result.results).toEqual([])
+  })
+})
+
+describe("alert", () => {
+  it("returns result if errors is empty or missing", () => {
+    expect(alert({ errors: [] })).toEqual({ errors: [] })
+    expect(alert({})).toEqual({})
+    expect(alert(undefined)).toBeUndefined()
+  })
+
+  it("throws if errors is non-empty", () => {
+    const errors = ["fail", "bad"]
+    expect(() => alert({ errors })).toThrow(JSON.stringify(errors, undefined, 2))
+  })
+})
+
+describe("throwFirstReject", () => {
+  it("returns values and returned as same array for all fulfilled", async () => {
+    const arr = [1, 2, 3]
+    const cb = (x) => x * 3
+    const result = await throwFirstReject({ array: arr }, cb)
+    expect(result.values).toEqual([3, 6, 9])
+    expect(result.returned).toEqual([3, 6, 9])
+  })
+
+  it("throws on first rejection", async () => {
+    const arr = [1, 2, 3]
+    const cb = (x) => (x === 2 ? Promise.reject("fail") : x)
+    await expect(throwFirstReject({ array: arr }, cb)).rejects.toBe("fail")
+  })
+
+  it("respects limit and processes in chunks", async () => {
+    const arr = [1, 2, 3, 4]
+    const calls = []
+    const cb = (x) => {
+      calls.push(x)
+      return x
+    }
+    const result = await throwFirstReject({ array: arr, limit: 2 }, cb)
+    expect(result.values).toEqual([1, 2, 3, 4])
+    expect(calls).toEqual([1, 2, 3, 4])
+  })
+
+  it("flattens values if flatten=true", async () => {
+    const arr = [1, 2]
+    const cb = (x) => [x, x + 1]
+    const result = await throwFirstReject({ array: arr, flatten: true }, cb)
+    expect(result.values).toEqual([1, 2, 2, 3])
+    expect(result.returned).toEqual([1, 2, 2, 3])
+  })
+
+  it("handles empty array", async () => {
+    const result = await throwFirstReject({ array: [] }, (x) => x)
+    expect(result.values).toEqual([])
+    expect(result.returned).toEqual([])
+  })
+})

package/src/run.js

@@ -0,0 +1,24 @@
+import { pathToFileURL } from "url"
+
+/**
+ * Basically allows the file where this is called from to be run as a script.
+ * @param {string} importMetaUrl Intended to be literally `import.meta.url`
+ * @param {array} args Names for command line args that will be used to name keys in the object passed to callback
+ * @param {Function} callback A (wrapper) function to execute the file.
+ * @returns The result of the callback
+ */
+export function runnable(importMetaUrl, args, callback) {
+  if (importMetaUrl === pathToFileURL(process.argv[1]).href) {
+    // module was not imported but called directly
+    const parameter = {}
+    for (let i = 0; i < args.length; i++) {
+      parameter[args[i]] = process.argv[i + 2]
+    }
+    console.log("starting", parameter)
+    return callback(parameter).then((result) => {
+      const formatted = JSON.stringify(JSON.parse(result.body), undefined, 2)
+      console.log("complete", parameter, formatted)
+    })
+  }
+  return undefined
+}

package/src/time.js

@@ -0,0 +1,32 @@
+/**
+ * Gets various ways of representing the current time in EDT. Floors to nearest second by default.
+ * @param {Object} $1
+ * @param {number} $1.days An offset in days to the current time
+ * @param {boolean} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second.
+ * @returns {Object} { timestamp, date, time, minute, datetime }
+ */
+export function getEasternTime({ days = 0, floorMinute = false } = {}) {
+  const now = new Date()
+  if (days) {
+    now.setDate(now.getDate() + days)
+  }
+  const timestamp = floorMinute
+    ? Math.floor(now.getTime() / 1000 / 60) * 60
+    : Math.floor(now.getTime() / 1000)
+  const string = new Date(timestamp * 1000).toLocaleString("en-US", {
+    timeZone: "America/New_York",
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  })
+  const [americanDate, time] = string.split(", ")
+  const [month, day, year] = americanDate.split("/")
+  const date = [year, month, day].join("-")
+  const minute = parseInt(time.split(":")[1], 10)
+  const datetime = `${date} ${time}`
+  return { timestamp, date, time, minute, datetime }
+}

package/src/time.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "@jest/globals"
+import { getEasternTime } from "./time.js"
+
+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")
+    expect(typeof result.minute).toBe("number")
+    expect(typeof result.datetime).toBe("string")
+  })
+
+  test("floors to minute if floorMinute is true", () => {
+    const r1 = getEasternTime()
+    const r2 = getEasternTime({ floorMinute: true })
+    expect(r2.timestamp % 60).toBe(0)
+    expect(r2.timestamp).toBeLessThanOrEqual(r1.timestamp)
+  })
+
+  test("adds days offset", () => {
+    const today = getEasternTime()
+    const tomorrow = getEasternTime({ days: 1 })
+    const [y, m, d] = today.date.split("-").map(Number)
+    const [y2, m2, d2] = tomorrow.date.split("-").map(Number)
+    expect(new Date(y2, m2 - 1, d2).getTime() - new Date(y, m - 1, d).getTime()).toBeCloseTo(
+      24 * 60 * 60 * 1000,
+      -2
+    )
+  })
+
+  test("returns correct format for different days and floorMinute", () => {
+    const base = getEasternTime()
+    const plus2 = getEasternTime({ days: 2, floorMinute: true })
+    expect(plus2.date).not.toEqual(base.date)
+    expect(plus2.timestamp % 60).toBe(0)
+  })
+
+  // The following test ensures all code paths are covered, including when days=0 and floorMinute=false (the defaults).
+  test("default parameters yield consistent output", () => {
+    const def = getEasternTime()
+    const explicit = getEasternTime({ days: 0, floorMinute: false })
+    expect(def.date).toEqual(explicit.date)
+    expect(def.time).toEqual(explicit.time)
+    expect(def.timestamp).toEqual(explicit.timestamp)
+    expect(def.datetime).toEqual(explicit.datetime)
+  })
+})