npm package: @sjabloons/timecraft
Description: A lightweight, dependency-free TypeScript utility libraru for \*\*human-friendly date and time handling
Latest version: 1.0.1

#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

```bash
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")

---

![npm](https://img.shields.io/npm/v/@sjabloons/timecraft)