push

pushy

Signed-off-by: Kenneth Obsequio <k80308392@gmail.com>

utils/datetime.util.js

@@ -0,0 +1,53 @@
+/***********************************************************************************************************************************************************************
+ * File Name: datetime.util.js
+ * Type of Program: Utility
+ * Description: Pure date/time formatting helpers for backend use (emails, crons, notifications).
+ *
+ * All functions accept an optional options object: { timezone, locale }
+ *   timezone — 'UTC' (default) | 'local'  (server's local timezone)
+ *   locale   — BCP 47 tag, defaults to 'en-US'
+ *
+ * UTC is the default because emails and cron output must be unambiguous regardless
+ * of where the server runs. Pass { timezone: 'local' } only when displaying times
+ * relative to the server's configured locale (e.g. admin dashboards, server logs).
+ ***********************************************************************************************************************************************************************/
+
+function tzOpt(timezone) {
+  return timezone === 'local' ? {} : { timeZone: 'UTC' };
+}
+
+function loc(locale) {
+  return locale ?? 'en-US';
+}
+
+/** "June 27, 2026" */
+function fmtDate(value, { timezone = 'UTC', locale } = {}) {
+  if (!value) return '—';
+  return new Date(value).toLocaleDateString(loc(locale), {
+    month: 'long', day: 'numeric', year: 'numeric',
+    ...tzOpt(timezone),
+  });
+}
+
+/** "June 27, 2026, 3:45 PM UTC" */
+function fmtDateTime(value, { timezone = 'UTC', locale } = {}) {
+  if (!value) return '—';
+  return new Date(value).toLocaleString(loc(locale), {
+    month: 'long', day: 'numeric', year: 'numeric',
+    hour: 'numeric', minute: '2-digit',
+    timeZoneName: 'short',
+    ...tzOpt(timezone),
+  });
+}
+
+/** "3:45 PM UTC" */
+function fmtTime(value, { timezone = 'UTC', locale } = {}) {
+  if (!value) return '—';
+  return new Date(value).toLocaleTimeString(loc(locale), {
+    hour: 'numeric', minute: '2-digit',
+    timeZoneName: 'short',
+    ...tzOpt(timezone),
+  });
+}
+
+module.exports = { fmtDate, fmtDateTime, fmtTime };