feat(format): add new format tokens and helper function 7️⃣

- Add Do format token for ordinal day
- Add tests for new format tokens
- Add toOrdinal helper function
- Add X format token for Unix timestamp in seconds
- Add x format token for Unix timestamp in milliseconds
- Add Z format token for timezone offset with colon
- Add ZZ format token for timezone offset without colon
- Improve single-character token handling in format

Author: NeaByteLab

src/helpers/Utilities.ts

@@ -7,3 +7,27 @@
 export function padNumber(num: number, length: number): string {
   return num.toString().padStart(length, '0')
 }
+
+/**
+ * Converts a number to its ordinal form (1st, 2nd, 3rd, etc.).
+ * @param num - The number to convert to ordinal
+ * @returns The ordinal string representation
+ */
+export function toOrdinal(num: number): string {
+  const numStr = num.toString()
+  const lastDigit = numStr[numStr.length - 1]
+  const lastTwoDigits = numStr.slice(-2)
+  if (lastTwoDigits === '11' || lastTwoDigits === '12' || lastTwoDigits === '13') {
+    return `${numStr}th`
+  }
+  if (lastDigit === '1') {
+    return `${numStr}st`
+  }
+  if (lastDigit === '2') {
+    return `${numStr}nd`
+  }
+  if (lastDigit === '3') {
+    return `${numStr}rd`
+  }
+  return `${numStr}th`
+}

src/utils/Format.ts

@@ -23,32 +23,55 @@ export function formatDate(date: Date, pattern: string, localeCode?: string): st
   const dayNameShort = locale.dayNamesShort[dayOfWeek] ?? 'Unknown'
   const monthName = locale.monthNames[month - 1] ?? 'Unknown'
   const monthNameShort = locale.monthNamesShort[month - 1] ?? 'Unknown'
+  const offsetMinutes = Helpers.getTimezoneOffset(date)
+  const offsetHours = Math.floor(Math.abs(offsetMinutes) / 60)
+  const offsetMins = Math.abs(offsetMinutes) % 60
+  const offsetSign = offsetMinutes >= 0 ? '+' : '-'
+  const offsetString = `${offsetSign}${Helpers.padNumber(offsetHours, 2)}${
+    Helpers.padNumber(
+      offsetMins,
+      2
+    )
+  }`
+  const offsetStringColon = `${offsetSign}${Helpers.padNumber(offsetHours, 2)}:${
+    Helpers.padNumber(
+      offsetMins,
+      2
+    )
+  }`
+  const unixSeconds = Math.floor(date.getTime() / 1000)
+  const unixMilliseconds = date.getTime()
   const tokens: Record<string, string> = {
-    YYYY: year.toString(),
-    YY: (year % 100).toString().padStart(2, '0'),
-    MM: Helpers.padNumber(month, 2),
-    M: month.toString(),
-    DD: Helpers.padNumber(day, 2),
+    A: hour >= 12 ? 'PM' : 'AM',
     D: day.toString(),
-    HH: Helpers.padNumber(hour, 2),
+    DD: Helpers.padNumber(day, 2),
+    Do: Helpers.toOrdinal(day),
     H: hour.toString(),
-    hh: Helpers.padNumber(hour % 12 || 12, 2),
+    HH: Helpers.padNumber(hour, 2),
+    M: month.toString(),
+    MM: Helpers.padNumber(month, 2),
+    MMM: monthNameShort,
+    MMMM: monthName,
+    S: Math.floor(millisecond / 100).toString(),
+    SS: Helpers.padNumber(Math.floor(millisecond / 10), 2),
+    SSS: Helpers.padNumber(millisecond, 3),
+    X: unixSeconds.toString(),
+    YY: (year % 100).toString().padStart(2, '0'),
+    YYYY: year.toString(),
+    Z: offsetStringColon,
+    ZZ: offsetString,
+    a: hour >= 12 ? 'pm' : 'am',
+    d: dayOfWeek.toString(),
+    dd: Helpers.padNumber(dayOfWeek, 2),
+    ddd: dayNameShort,
+    dddd: dayName,
     h: (hour % 12 || 12).toString(),
-    mm: Helpers.padNumber(minute, 2),
+    hh: Helpers.padNumber(hour % 12 || 12, 2),
     m: minute.toString(),
-    ss: Helpers.padNumber(second, 2),
+    mm: Helpers.padNumber(minute, 2),
     s: second.toString(),
-    SSS: Helpers.padNumber(millisecond, 3),
-    SS: Helpers.padNumber(Math.floor(millisecond / 10), 2),
-    S: Math.floor(millisecond / 100).toString(),
-    dddd: dayName,
-    ddd: dayNameShort,
-    dd: Helpers.padNumber(dayOfWeek, 2),
-    d: dayOfWeek.toString(),
-    MMMM: monthName,
-    MMM: monthNameShort,
-    A: hour >= 12 ? 'PM' : 'AM',
-    a: hour >= 12 ? 'pm' : 'am'
+    ss: Helpers.padNumber(second, 2),
+    x: unixMilliseconds.toString()
   }
   const placeholderStart = '\uE000'
   let result = pattern
@@ -60,10 +83,39 @@ export function formatDate(date: Date, pattern: string, localeCode?: string): st
       continue
     }
     const value = tokens[key]
-    if (value !== undefined && result.includes(key)) {
-      const placeholder = `${placeholderStart}${String.fromCharCode(0xe000 + i)}`
-      replacements.push({ placeholder, value })
-      result = result.replaceAll(key, placeholder)
+    if (value === undefined) {
+      continue
+    }
+    if (key.length === 1) {
+      const char = key[0]
+      if (char === undefined) {
+        continue
+      }
+      let searchStart = 0
+      while (true) {
+        const index = result.indexOf(char, searchStart)
+        if (index === -1) {
+          break
+        }
+        const prevChar = index > 0 ? result[index - 1] : ''
+        const nextChar = index < result.length - 1 ? result[index + 1] : ''
+        const isPrevAlpha = /[a-zA-Z]/.test(prevChar ?? '')
+        const isNextAlpha = /[a-zA-Z]/.test(nextChar ?? '')
+        if (!isPrevAlpha && !isNextAlpha) {
+          const placeholder = `${placeholderStart}${String.fromCharCode(0xe000 + i)}`
+          replacements.push({ placeholder, value })
+          result = result.substring(0, index) + placeholder + result.substring(index + 1)
+          searchStart = index + placeholder.length
+        } else {
+          searchStart = index + 1
+        }
+      }
+    } else {
+      if (result.includes(key)) {
+        const placeholder = `${placeholderStart}${String.fromCharCode(0xe000 + i)}`
+        replacements.push({ placeholder, value })
+        result = result.replaceAll(key, placeholder)
+      }
     }
   }
   for (const { placeholder, value } of replacements) {