Nano-Date-Js

This project was generated using Angular CLI version 20.0.0.

Packed & UnPacked Size

• package size: 9.9 kB
• unpacked size: 45.3 kB

Documentation

# 📅 Nano Dates Js

A lightweight, developer-friendly date utility library built with **Angular 20**, inspired by Moment.js.  
It provides powerful date creation, manipulation, formatting, comparison, and duration handling in a clean and modular way.

---

## 🚀 Features

- ✅ Create dates from multiple sources (string, timestamp, Date, UTC, Unix)
- ✅ Easy getters (year, month, day, hours, etc.)
- ✅ Flexible date formatting
- ✅ Immutable-style manipulation (add, subtract, startOf, endOf)
- ✅ Rich comparison utilities
- ✅ Accurate date difference calculations
- ✅ Duration handling
- ✅ UTC & Local mode support
- ✅ Static utilities (min, max, now)
- ✅ Method chaining support

---

## 📦 Installation

```bash
npm install nano-date-js
```

📘 Usage

import { nanoDate } from "nano-date-js";

🧱 API Reference

1. Creating Dates

// Current date/time
const now = nanoDate();

// From string
const fromString = nanoDate("2024-01-15");

// From timestamp (milliseconds)
const fromTimestamp = nanoDate(1705315200000);

// From Date object
const fromDate = nanoDate(new Date(2024, 0, 15));

// Clone from another instance
const cloned = nanoDate(fromString);

// UTC mode
const utcNow = nanoDate.utc();

// Unix timestamp (seconds)
const unixTime = nanoDate.unix(1705315200);

// Invalid date
const invalid = nanoDate("invalid-date");
invalid.isValid(); // false

2. Getters

const date = nanoDate("2024-01-15 14:30:45");

date.year();
date.month(); // 0-11
date.date();
date.day(); // 0-6
date.hours();
date.minutes();
date.seconds();
date.quarter();

3. Formatting

const date = nanoDate("2024-01-15 14:30:45");

date.format("YYYY-MM-DD");
date.format("DD/MM/YYYY");
date.format("MMM DD, YYYY");
date.format("MMMM Do, YYYY");

date.format("HH:mm:ss");
date.format("hh:mm:ss A");
date.format("h:mm a");

date.format("dddd");
date.format("ddd");

date.format("Z");
date.format("ZZ");

date.format("dddd, MMMM Do YYYY, h:mm:ss a");

4. Manipulation

const date = nanoDate("2024-01-15");

// Add
date.add(1, "week");
date.add(1, "month");
date.add(1, "year");
date.add(5, "hours");

// Chain
date.add(1, "month").add(5, "days").add(3, "hours");

// Subtract
date.subtract(1, "week");
date.subtract(1, "month");

// Start of
date.startOf("year");
date.startOf("month");
date.startOf("week");
date.startOf("day");
date.startOf("hour");

// End of
date.endOf("year");
date.endOf("month");
date.endOf("week");
date.endOf("day");

5. Comparison

const d1 = nanoDate("2024-01-15");
const d2 = nanoDate("2024-02-20");

d1.isBefore(d2);
d2.isAfter(d1);
d1.isSame(d2);

d1.isSameOrBefore(d2);
d2.isSameOrAfter(d1);

const target = nanoDate("2024-02-01");
target.isBetween(d1, d2);
target.isBetween(d1, d2, "[]"); // inclusive

6. Difference

const start = nanoDate("2024-01-15");
const end = nanoDate("2024-02-20");

end.diff(start, "days");
end.diff(start, "weeks");
end.diff(start, "months");
end.diff(start, "years");

end.diff(start, "milliseconds");

// Floating result
end.diff(start, "months", true);

7. Duration

const d1 = nanoDate.duration(3600000);

const d2 = nanoDate.duration({
  hours: 2,
  minutes: 30,
  seconds: 15,
});

d2.asHours();
d2.asDays();

d2.hours();
d2.minutes();
d2.days();

// Use with nanoDate
nanoDate().add(d2.asHours(), "hours");

8. UTC & Local Mode

const local = nanoDate("2024-01-15T12:00:00");
const utc = nanoDate.utc("2024-01-15T12:00:00");

// Convert
local.utc();
utc.local();

// Check mode
local._isUTC;
utc._isUTC;

9. Static Methods

nanoDate.now();

const dates = [
  nanoDate("2024-01-15"),
  nanoDate("2024-02-20"),
  nanoDate("2024-01-01"),
];

nanoDate.max(...dates);
nanoDate.min(...dates);

nanoDate.unix(1705315200);

10. Chaining

nanoDate("2024-01-15")
  .add(1, "month")
  .add(5, "days")
  .startOf("week")
  .subtract(2, "hours")
  .utc()
  .format("dddd, MMMM Do YYYY, HH:mm [UTC]");

⚡ Why Nano Dates?

• Lightweight alternative to Moment.js
• Angular-first architecture
• Clean API with chaining support
• Easy to extend and customize

🛠 Built With

• Angular 20
• TypeScript

📄 License

MIT License