@gambar/date-utils

A lightweight, immutable date utility library with zero dependencies. Every operation returns a new instance — no surprises, no mutation.

Installation

npm install @gambar/date-utils
# or
bun add @gambar/date-utils

import { DateHelper } from "@gambar/date-utils";

Basic Usage

const d = new DateHelper("15.03.2024");

d.format("YYYY-MM-DD");   // "2024-03-15"
d.format("DD.MM");        // "15.03"
d.addMonths(2).format();  // "15.05.2024"
d.isBefore("2025-01-01"); // true

DateHelper.now()
    .startOf("month")
    .addMonths(3)
    .format("YYYY-MM-DD");

Auto-detected input formats

new DateHelper(str) and DateHelper.from(str) recognise:

| Pattern | Example | | ------- | ------- | | YYYY-MM-DD | "2024-03-15" | | ISO datetime | "2024-03-15T10:30:00.000Z" | | DD.MM.YYYY | "15.03.2024" | | DD.MM.YY | "15.03.24" | | DD.MM | "15.03" (uses current year) |

Quick reference

Formatting

d.format()              // "15.03.2024"  (default)
d.format("YYYY-MM-DD")  // "2024-03-15"
d.format("DD.MM")       // "15.03"
d.format("ISO")         // full ISO string
d.format("TIMESTAMP")   // epoch ms as string
d.format("DD/MM/YY")    // custom pattern

Arithmetic

d.add("days", 10)    .addDays(10)
d.sub("months", 2)   .subMonths(2)
d.addYears(1)        d.addWeeks(2)
d.addHours(6)        d.addMinutes(30)

Month/year addition clamps to the last valid day of the target month:

new DateHelper("2024-01-31").addMonths(1).format() // "29.02.2024"

Boundaries

d.startOf("month")  // first moment of the month
d.endOf("year")     // last millisecond of the year
// units: year · month · week · day · hour · minute · second

Comparison

d.isBefore(other)       d.isAfter(other)
d.lessThan(other)       d.greaterThan(other)
d.lessOrEqual(other)    d.greaterOrEqual(other)
d.equals(other)         d.equals(other, "month")
d.isToday()   d.isPast()   d.isFuture()

Difference

a.diff(b)              // { years, months, days, milliseconds }
a.diff(b, "days")      // number (signed, fractional)
a.diff(b, "months")    // calendar-accurate
a.convertTo("days", b) // shorthand for diff with unit

License

MIT