npm package: @harshit7492/datetime-format-kit
Description: Simple and lightweight date utility library
Latest version: 1.0.0

# date-time-kit

Lightweight date utilities with a small, explicit API.

## Install

```bash
npm i @harshit/date-time-kit
```

## Quick Start

```ts
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.

```ts
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.

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

### `toUTC(input, options?)`

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

### `toLocal(input, options?)`

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

### `toEpochSeconds(input, options?)`

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

### `toEpochMillis(input, options?)`

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

### `fromEpoch(epoch)`

```ts
fromEpoch(1712235600); // seconds or milliseconds
```

### `timeAgo(input, options?)`

```ts
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

```bash
npm run build
```