xkernel

A lightweight TypeScript library providing utility functions for date manipulation, formatting, comparison, and more.

Features

• 🕐 Formatting — Flexible date formatting with token-based templates
• ➕ Calculation — Add/subtract time units (years, months, days, hours, etc.)
• 🔍 Comparison — Compare dates, check if same day/month/year, relative time checks
• 📏 Diff — Calculate differences between dates in various units
• 🌐 Relative Time — Human-readable relative time ("3 hours ago", "2 days later") with i18n
• 📅 Parse — Parse date strings and construct dates from parts
• 📆 Misc — Weekend checks, weekday names, leap year, day of year, timezone helpers

Installation

npm install xkernel
# or
pnpm add xkernel
# or
yarn add xkernel

Usage

import { formatDate, add, diff, fromNow, isWeekend, daysInMonth } from 'xkernel';

// Formatting
formatDate(new Date(2024, 0, 15), 'YYYY-MM-DD');       // '2024-01-15'
formatDate(new Date(2024, 0, 15, 9, 5), 'YYYY/MM/DD HH:mm'); // '2024/01/15 09:05'

// Calculation
add(new Date(2024, 0, 15), 1, 'day');   // 2024-01-16
add(new Date(2024, 0, 15), -1, 'month'); // 2023-12-15

// Diff
diff(new Date(2024, 0, 1), new Date(2024, 0, 10), 'day'); // 9

// Relative time
setRelativeTimeLocale('zh');
fromNow(new Date(2024, 0, 15), new Date(2024, 0, 14)); // '1天后'

// Misc
isWeekend(new Date(2024, 0, 6)); // true (Saturday)
daysInMonth(2024, 2); // 29 (leap year)
isLeapYear(2024); // true

API Reference

Format

• formatDate(date, format?) — Format a date to string with tokens (YYYY, MM, DD, HH, mm, ss, SSS, etc.)
• toISOString(date) — Convert to ISO 8601 string

Calculation

• add(date, amount, unit) — Add/subtract time by unit
• addDays(date, amount) / addMonths(date, amount) / addYears(date, amount)
• addHours(date, amount) / addMinutes(date, amount) / addSeconds(date, amount)

Comparison

• isValidDate(value) — Check if value is a valid Date
• isDateLike(value) — Check if value can be parsed as date
• compareDates(a, b) — Compare two dates (-1, 0, 1)
• isBefore(a, b) / isAfter(a, b) — Relative comparison
• isSameDay(a, b) / isSameMonth(a, b) / isSameYear(a, b)
• isToday(date) / isYesterday(date) / isTomorrow(date)
• isThisWeek(date, refDate?)

Diff

• diff(dateA, dateB, unit) — Difference in specified unit
• diffInDays(a, b) / diffInHours(a, b) / diffInMinutes(a, b) / diffInSeconds(a, b)
• startOfDay(date) / endOfDay(date)
• startOfWeek(date) / endOfWeek(date)
• startOfMonth(date) / endOfMonth(date)
• startOfYear(date) / endOfYear(date)

Relative Time

• fromNow(date, from?) — Human-readable relative time
• humanizeDuration(ms) — Convert milliseconds to readable duration
• setRelativeTimeLocale(locale) — Set locale ('en' | 'zh')

Parse

• parseDate(value) — Parse string/number to Date
• parseToTimestamp(value) — Parse to timestamp
• safeParseDate(value) — Parse, return null on failure
• fromDateParts(parts) — Construct date from components

Misc

• isWeekend(date) / isWeekday(date)
• countWeekdays(start, end) — Count weekdays in range
• getTimezoneOffset(date?) — Get timezone offset
• convertToTimezone(date, offsetMinutes) — Convert to target timezone
• getWeekdayName(date, locale?) — Get weekday name
• getISODay(date) — ISO weekday number (1=Mon, 7=Sun)
• daysInMonth(year, month) — Days in given month
• isLeapYear(year) — Check leap year
• dayOfYear(date) — Day number in year (1-366)
• now() — Current timestamp

License

MIT