#TimeCraft

A lightweight, dependency-free TypeScript utility libraru for **human-friendly date and time handling

Built with:

• strict Typescript types
• ISO8601 correctnes
• full test coverage
• internationalization in mind

Perfect for dashboard, feeds, timelins and and any app that deals with dates

✨ Features

• 🗓️ Human-readable date formatting (humanizeDate)

• ⏱️ Human-readable durations (humanizeDuration)

• ⌛ Relative time formatting (timeAgo)

• 📆 ISO-8601 week helpers (isThisWeek, isNextWeek, isLastWeek)

• 📅 Day helpers (isToday, isTomorrow, isYesterday, isWeekday)

• 🌍 Season detection with north/south hemisphere support

• 🧠 Leap year detection (isLeapYear)

• 🗂️ Calendar utilities (getDay, getWeekOfYear, getCalendarDate)

• 🌐 International calendar support via Intl.DateTimeFormat

• 🧪 Fully tested with Vitest

• 🚫 Zero dependencies

📦 Installation

npm install @sjabloons/Timecraft

🚀 Quick Start

humanizeDate()

function humanizeDate(
    date: Date | string | number,
    options: HumanizeDateOptions
)

HumanizeDateOptions: | Key | Type | Default | Description | |------------------|-------------------|-----------|-------------| | locale | "en" \| "nl" | "en" | Language used for month and weekday names | | includeWeekday | boolean | false | Prepends the weekday to the date | | includeSeason | boolean | false | Appends the season to the date | | hemisphere | "north" \| "south" | "north" | Hemisphere used for season calculation |

humanizeDuration()

function humanizeDuration(
  totalSeconds: number,
  options?: HumanizeDurationOptions
): string

HumanizeDurationOptions: | Key | Type | Default | Description | |------------|----------------------|-------------|-------------| | locale | "en" \| "nl" | "en" | Language used for unit labels | | maxUnits | number | Infinity | Maximum number of units to display | | short | boolean | false | Use short format (1h 2m) | | round | boolean | false | Round values instead of flooring |

timeAgo()

function timeAgo(
    date: Date | string | number,
    options?: TimeAgoOptions
): string

TimeAgoOptions: | Key | Type | Default | Description | |----------------|------------------------|------------|-------------| | locale | "en" \| "nl" | "en" | Language used for output | | now | Date \| string \| number | new Date() | Reference date (useful for tests) | | includeSeconds | boolean | false | Show seconds for durations < 1 minute |

isToday(), isTommorow(), isYesterday(), isThisWeek(), isNextWeek(), isLastWeek()

function functionName(
    date: Date | string | number,
    options?: DateCompareOptions
):boolean

DateCompareOptions: | Key | Type | Default | Description | |--------------|-------------------------|---------|-------------| | now | Date \| string \| number | new Date() | Reference date | | weekStartsOn | 0 \| 1 | 1 | Week start (0 = Sunday, 1 = Monday / ISO) |

getSeason()

function getSeason(
  date: Date | string | number,
  options?: GetSeasonOptions
): Season

GetSeasonOptions: | Key | Type | Default | Description | |-------------|----------------------|-----------|-------------| | hemisphere | "north" \| "south" | "north" | Hemisphere used for season calculation |

getTimeDifference()

function getTimeDifference(
  from: Date | string | number,
  to: Date | string | number,
  options?: TimeDifferenceOptions
): TimeDifference

TimeDifferenceOptions: | Key | Type | Default | Description | |------------|-------------------|------------------------|-------------| | units | TimeUnit[] | all units | Units to include in the result | | round | boolean | false | Floor values to integers | | precision | number | undefined | Decimal precision | | absolute | boolean | true | Return absolute values |

isLeapYear()

function isLeapYear(year: number): boolean

getWeekOfYear()

function getWeekOfYear(
  date: Date | string | number
): number

getCalendarDate()

function getCalendarDate(
  date: Date | string | number,
  calendar: CalendarType,
  locale?: string
): string

calendar: | Parameter | Type | Description | |-----------|----------|-------------| | calendar | "gregorian" \| "islamic" \| "hebrew" \| "chinese" \| "indian" \| "japanese" | Calendar system to use | |locale | "en" \| "nl" | Locale used for formatting (default "en")

getDay()

function getDay(
  date: Date | string | number,
  options?: DayOptions
): string

DayOptions: | Parameter | Type | Description | |-----------|----------|-------------| | locale | "en" \| "nl" | Locale used for formatting (default "en")