✨ Add Date (#37)

Author: NatoBoram

.env

@@ -26,3 +26,7 @@ EXAMPLE_NO_URL=
 EXAMPLE_UUID=eb4cd2db-7250-40b2-948f-436b628ee8e2
 EXAMPLE_INVALID_UUID=EXAMPLE_INVALID_UUID
 EXAMPLE_NO_UUID=
+
+EXAMPLE_DATE=2025-05-28T00:50:58.816Z
+EXAMPLE_INVALID_DATE=EXAMPLE_INVALID_DATE
+EXAMPLE_NO_DATE=

src/env.test.ts

@@ -1,13 +1,15 @@
 import { beforeAll, describe, test } from "vitest"
 import {
 	envBool,
+	envDate,
 	envFloat,
 	envInt,
 	envString,
 	envStrings,
 	envUrl,
 	envUuid,
 	maybeEnvBool,
+	maybeEnvDate,
 	maybeEnvFloat,
 	maybeEnvInt,
 	maybeEnvString,
@@ -200,6 +202,34 @@ describe("envUuid", () => {
 	})
 })
 
+describe("envDate", () => {
+	const date = new Date("2025-05-28T00:50:58.816Z")
+
+	test("valid", ({ expect }) => {
+		const actual = envDate("EXAMPLE_DATE")
+		expect(actual).toBeInstanceOf(Date)
+		expect(actual.toISOString()).toBe(date.toISOString())
+	})
+
+	test("fallback", ({ expect }) => {
+		const actual = envDate("EXAMPLE_NO_DATE", date)
+		expect(actual).toBeInstanceOf(Date)
+		expect(actual.toISOString()).toBe(date.toISOString())
+	})
+
+	test("invalid", ({ expect }) => {
+		expect(() => envDate("EXAMPLE_INVALID_DATE")).toThrow(
+			"$EXAMPLE_INVALID_DATE is not a valid Date: EXAMPLE_INVALID_DATE",
+		)
+	})
+
+	test("empty", ({ expect }) => {
+		expect(() => envDate("EXAMPLE_NO_DATE")).toThrow(
+			"$EXAMPLE_NO_DATE is missing",
+		)
+	})
+})
+
 describe("maybeEnvBool", () => {
 	test("valid", ({ expect }) => {
 		const actual = maybeEnvBool("EXAMPLE_BOOL")
@@ -326,3 +356,24 @@ describe("maybeEnvUuid", () => {
 		)
 	})
 })
+
+describe("maybeEnvDate", () => {
+	const date = new Date("2025-05-28T00:50:58.816Z")
+
+	test("valid", ({ expect }) => {
+		const actual = maybeEnvDate("EXAMPLE_DATE")
+		expect(actual).toBeInstanceOf(Date)
+		expect(actual?.toISOString()).toBe(date.toISOString())
+	})
+
+	test("empty", ({ expect }) => {
+		const actual = maybeEnvDate("EXAMPLE_NO_DATE")
+		expect(actual).toBe(undefined)
+	})
+
+	test("invalid", ({ expect }) => {
+		expect(() => maybeEnvDate("EXAMPLE_INVALID_DATE")).toThrow(
+			"$EXAMPLE_INVALID_DATE is not a valid Date: EXAMPLE_INVALID_DATE",
+		)
+	})
+})

src/env.ts

@@ -111,6 +111,24 @@ export function envUuid(key: string, fallback?: UUID): UUID {
 	return str
 }
 
+/**
+ * Obtains an environment variable as a Date.
+ *
+ * @example
+ *
+ * export const START_DATE = envDate("START_DATE")
+ */
+export function envDate(key: string, fallback?: Date): Date {
+	const str = process.env[key]?.trim() || fallback?.toISOString().trim()
+	if (str === undefined) throw new Error(`$${key} is missing`)
+
+	const date = new Date(str)
+	if (isNaN(date.getTime()))
+		throw new Error(`$${key} is not a valid Date: ${str}`)
+
+	return date
+}
+
 /**
  * Obtains an optional environment variable as a boolean.
  *
@@ -218,3 +236,21 @@ export function maybeEnvUuid(key: string): UUID | undefined {
 	if (!isUuid(str)) throw new Error(`$${key} is not a UUID: ${str}`)
 	return str
 }
+
+/**
+ * Obtains an optional environment variable as a Date.
+ *
+ * @example
+ *
+ * export const END_DATE = maybeEnvDate("END_DATE")
+ */
+export function maybeEnvDate(key: string): Date | undefined {
+	const str = process.env[key]?.trim()
+	if (!str) return undefined
+
+	const date = new Date(str)
+	if (isNaN(date.getTime()))
+		throw new Error(`$${key} is not a valid Date: ${str}`)
+
+	return date
+}