date-time-kit

Lightweight date utilities with a small, explicit API.

Install

npm i @harshit/date-time-kit

Quick Start

import { formatDate } from "@harshit/date-time-kit";

formatDate("2026-04-04T14:30:00Z", "YYYY-MM-DD HH:mm:ss");
// Example output (local time): 2026-04-04 20:00:00

API

formatDate(input, format?, options?)

Formats a date using tokens.

formatDate("2026-04-04T14:30:00Z", "YYYY-MM-DD HH:mm:ss");
formatDate("04/05/2026", "DD/MM/YYYY", { dayFirst: true });
formatDate("2026-04-04T14:30:00Z", "YYYY-MM-DD HH:mm:ss", { utc: true });
formatDate("2026-03-25", "DD MMM YYYY");
formatDate("2026-03-25", "dddd, DD, YYYY");

Supported tokens:

YYYY YY MMMM MMM MM M DD D dddd ddd HH H hh h mm m ss s SSS A a

Options:

• utc: Format using UTC fields instead of local time.
• dayFirst: Interpret ambiguous numeric dates as DD/MM/YYYY (default is MM/DD/YYYY).
• warnOnUnknownFormat: Log a warning when the format includes unknown tokens.
• fallbackFormat: Use this format string if unknown tokens are detected.

parseDate(input, options?)

Parses supported inputs into a Date. Throws on invalid dates.

parseDate("2026-04-04");
parseDate("2026-4-5T07:08:09Z");
parseDate("04/05/2026", { dayFirst: true });
parseDate(1712235600); // epoch seconds

toUTC(input, options?)

toUTC("2026-04-04T14:30:00Z");

toLocal(input, options?)

toLocal("2026-04-04T14:30:00Z");

toEpochSeconds(input, options?)

toEpochSeconds("2026-04-04T14:30:00Z");

toEpochMillis(input, options?)

toEpochMillis("2026-04-04T14:30:00Z");

fromEpoch(epoch)

fromEpoch(1712235600); // seconds or milliseconds

timeAgo(input, options?)

timeAgo("2026-04-01T12:00:00Z");

Supported Input Formats

• ISO strings: YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss, with optional timezone offsets (e.g. +02:00, -05:00, Z)
• RFC 3339 (subset of ISO 8601): 2026-04-04T14:23:05Z, 2026-04-04T14:23:05+05:30
• RFC 2822 / 5322: Wed, 04 Apr 2026 14:23:05 +0000
• Numeric dates: MM/DD/YYYY, DD/MM/YYYY, MM-DD-YYYY, DD-MM-YYYY
• Compact dates: YYYYMMDD, MMDDYYYY, YYYYMMDDHHMMSS
• Ordinal dates: YYYY-DOY (day of year)
• Week dates: YYYY-Www-D
• Month names: Apr 4 2026, 4 Apr 2026, April 4, 2026, 04-Apr-2026
• Epoch seconds/milliseconds/microseconds (number or numeric string)
• TAI input: TAI:1712635385 (treated as POSIX seconds)

Invalid dates (like 2023-02-29) throw an error.

Notes

• Timezone names like Asia/Kolkata are not supported for formatting. Use utc: true to format in UTC.
• For ambiguous numeric formats (04/05/2026), use dayFirst: true if you mean DD/MM/YYYY.
• TAI parsing does not apply leap-second tables; it is treated as POSIX seconds.

Design Principles

• Small, single-purpose functions with explicit options.
• No global state; all behavior is controlled per call.
• Deterministic output for a given input and options.

Build

npm run build