Skip to main content

​
Overview

The date formatter utility provides timezone-aware date decomposition, breaking timestamps into comprehensive components including year, month, week numbers, and day-of-year calculations. Source: src/tools/dateFormatter.ts

​
decomposeTime

Decomposes a Unix timestamp into detailed date and time components with timezone support. 
function decomposeTime(ts: number, options?: Options): DateComponents

​
Parameters

​
ts
number
required
Unix timestamp in milliseconds to decompose
​
options
Options
Configuration options for timezone handling
​
timezone
string
default:"America/Bogota"
IANA timezone identifier (e.g., “America/Bogota”, “UTC”, “Europe/London”)

​
Returns

​
DateComponents
object
Object containing decomposed date and time information
​
year
number
Four-digit year
​
month
string
Two-digit month (01-12)
​
monthStr
string
Three-letter month abbreviation (JAN, FEB, MAR, etc.)
​
week
number
ISO week number of the year
​
dayOfWeek
number
Day of week as number (1-7, Monday=1)
​
dayOfWeekStr
string
Three-letter day abbreviation (MON, TUE, WED, THU, FRY, SAT, SUN)
​
dayOfYear
number
Day number within the year (1-366)
​
dayOfMonth
string
Two-digit day of month (01-31)
​
hourOfDay
string
Two-digit hour in 24-hour format (00-23)
​
minute
string
Two-digit minute (00-59)
​
second
string
Two-digit second (00-59)
​
milliseconds
string
Milliseconds portion of the timestamp

​
Examples

import { decomposeTime } from 'ubl-builder';

const timestamp = Date.now();
const components = decomposeTime(timestamp);

console.log(components.year);        // 2024
console.log(components.monthStr);    // "JAN"
console.log(components.dayOfWeekStr); // "MON"
This function uses Intl.DateTimeFormat for timezone-aware parsing and the weeknumber library for ISO week calculations. The default timezone is “America/Bogota” if not specified.

​
Use Cases

  • Generating UBL date/time fields with specific timezone requirements
  • Creating invoice timestamps with localized formatting
  • Extracting week numbers for period-based reporting
  • Converting timestamps for tax document compliance

Build docs developers (and LLMs) love

Get started for freeTalk to us