chronal 0.0.1-0

package/esm/core/dtf.d.ts

@@ -0,0 +1,2 @@
+export declare function getDTF(locale: string, tz: string): Intl.DateTimeFormat;
+//# sourceMappingURL=dtf.d.ts.map

package/esm/core/dtf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dtf.d.ts","sourceRoot":"","sources":["../../src/core/dtf.ts"],"names":[],"mappings":"AAEA,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,uBAiBhD"}

package/esm/core/dtf.js

@@ -0,0 +1,20 @@
+const dtfCache = new Map();
+export function getDTF(locale, tz) {
+    const key = `${locale}|${tz}`;
+    let dtf = dtfCache.get(key);
+    if (!dtf) {
+        dtf = new Intl.DateTimeFormat(locale, {
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12: false,
+            timeZone: tz,
+        });
+        dtfCache.set(key, dtf);
+    }
+    return dtf;
+}
+;

package/esm/lib/add.d.ts

@@ -0,0 +1,24 @@
+type AddOptions = {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+};
+/**
+ * Adds specified time units to the given date.
+ *
+ * @param date - The original date.
+ * @param opt - The time units to add.
+ * @returns A new Date object with the specified time units added.
+ * @example
+ * const date = new Date('2024-01-31T12:00:00Z');
+ * const newDate = add(date, { years: 1, months: 2, days: 3 });
+ * console.log(newDate.toISOString()); // '2025-04-03T12:00:00.000Z'
+ */
+export declare function add(date: Date, opt: AddOptions): Date;
+export {};
+//# sourceMappingURL=add.d.ts.map

package/esm/lib/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/lib/add.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;GAUG;AAEH,wBAAgB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CA8CrD"}

package/esm/lib/add.js

@@ -0,0 +1,47 @@
+/**
+ * Adds specified time units to the given date.
+ *
+ * @param date - The original date.
+ * @param opt - The time units to add.
+ * @returns A new Date object with the specified time units added.
+ * @example
+ * const date = new Date('2024-01-31T12:00:00Z');
+ * const newDate = add(date, { years: 1, months: 2, days: 3 });
+ * console.log(newDate.toISOString()); // '2025-04-03T12:00:00.000Z'
+ */
+export function add(date, opt) {
+    let d = new Date(date.getTime());
+    // ===== calendar-based (UTC-safe) =====
+    if (opt.years || opt.months) {
+        const years = opt.years ?? 0;
+        const months = opt.months ?? 0;
+        const year = d.getUTCFullYear();
+        const month = d.getUTCMonth(); // 0-based
+        const day = d.getUTCDate();
+        // target year/month (allow overflow, normalize manually)
+        let targetMonth = month + months;
+        const targetYear = year + years + Math.floor(targetMonth / 12);
+        targetMonth = ((targetMonth % 12) + 12) % 12;
+        // last valid day of target month
+        const lastDayOfTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate();
+        const safeDay = Math.min(day, lastDayOfTargetMonth);
+        d = new Date(Date.UTC(targetYear, targetMonth, safeDay, d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds()));
+    }
+    // ===== time-based =====
+    let delta = 0;
+    if (opt.milliseconds)
+        delta += opt.milliseconds;
+    if (opt.seconds)
+        delta += opt.seconds * 1_000;
+    if (opt.minutes)
+        delta += opt.minutes * 60_000;
+    if (opt.hours)
+        delta += opt.hours * 3_600_000;
+    if (opt.days)
+        delta += opt.days * 86_400_000;
+    if (opt.weeks)
+        delta += opt.weeks * 604_800_000;
+    if (delta)
+        d = new Date(d.getTime() + delta);
+    return d;
+}

package/esm/lib/difference.d.ts

@@ -0,0 +1,15 @@
+import type { PluralUnit } from "../types/unit.js";
+/**
+ * Calculates the difference between two dates in the specified unit.
+ *
+ * @param dateLeft - The first date.
+ * @param dateRight - The second date to subtract from the first.
+ * @param unit - The unit to express the difference in ('years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds').
+ * @returns The difference as a number (can be negative if dateLeft is before dateRight).
+ * @example
+ * const date1 = new Date('2024-01-20T12:00:00Z');
+ * const date2 = new Date('2024-01-15T12:00:00Z');
+ * console.log(difference(date1, date2, 'days')); // 5
+ */
+export declare function difference(dateLeft: Date, dateRight: Date, unit: PluralUnit): number;
+//# sourceMappingURL=difference.d.ts.map

package/esm/lib/difference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"difference.d.ts","sourceRoot":"","sources":["../../src/lib/difference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;GAWG;AAEH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAoDpF"}

package/esm/lib/difference.js

@@ -0,0 +1,47 @@
+/**
+ * Calculates the difference between two dates in the specified unit.
+ *
+ * @param dateLeft - The first date.
+ * @param dateRight - The second date to subtract from the first.
+ * @param unit - The unit to express the difference in ('years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds').
+ * @returns The difference as a number (can be negative if dateLeft is before dateRight).
+ * @example
+ * const date1 = new Date('2024-01-20T12:00:00Z');
+ * const date2 = new Date('2024-01-15T12:00:00Z');
+ * console.log(difference(date1, date2, 'days')); // 5
+ */
+export function difference(dateLeft, dateRight, unit) {
+    const delta = dateLeft.getTime() - dateRight.getTime();
+    switch (unit) {
+        case 'years': {
+            const yearDiff = dateLeft.getUTCFullYear() - dateRight.getUTCFullYear();
+            const adjustedDateRight = new Date(Date.UTC(dateRight.getUTCFullYear() + yearDiff, dateRight.getUTCMonth(), dateRight.getUTCDate(), dateRight.getUTCHours(), dateRight.getUTCMinutes(), dateRight.getUTCSeconds(), dateRight.getUTCMilliseconds()));
+            if (adjustedDateRight > dateLeft) {
+                return yearDiff - 1;
+            }
+            return yearDiff;
+        }
+        case 'months': {
+            const yearDiff = dateLeft.getUTCFullYear() - dateRight.getUTCFullYear();
+            const monthDiff = dateLeft.getUTCMonth() - dateRight.getUTCMonth();
+            let totalMonths = yearDiff * 12 + monthDiff;
+            const adjustedDateRight = new Date(Date.UTC(dateRight.getUTCFullYear() + Math.floor(totalMonths / 12), (dateRight.getUTCMonth() + (totalMonths % 12) + 12) % 12, dateRight.getUTCDate(), dateRight.getUTCHours(), dateRight.getUTCMinutes(), dateRight.getUTCSeconds(), dateRight.getUTCMilliseconds()));
+            if (adjustedDateRight > dateLeft) {
+                totalMonths -= 1;
+            }
+            return totalMonths;
+        }
+        case 'weeks':
+            return Math.floor(delta / 604800000); // 7 * 24 * 60 * 60 * 1000
+        case 'days':
+            return Math.floor(delta / 86400000); // 24 * 60 * 60 * 1000
+        case 'hours':
+            return Math.floor(delta / 3600000); // 60 * 60 * 1000
+        case 'minutes':
+            return Math.floor(delta / 60000); // 60 * 1000
+        case 'seconds':
+            return Math.floor(delta / 1000);
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}

package/esm/lib/end-of.d.ts

@@ -0,0 +1,14 @@
+import type { Unit } from "../types/unit.js";
+/**
+ * Returns the end of the specified time unit for the given date.
+ *
+ * @param date - The original date.
+ * @param unit - The time unit to get the end of ('year' | 'month' | 'day' | 'hour' | 'minute' | 'second').
+ * @returns A new Date object set to the end of the specified unit (last millisecond).
+ * @example
+ * const date = new Date('2024-06-15T14:35:22.500Z');
+ * const endOfDay = endOf(date, 'day');
+ * console.log(endOfDay.toISOString()); // '2024-06-15T23:59:59.999Z'
+ */
+export declare function endOf(date: Date, unit: Unit): Date;
+//# sourceMappingURL=end-of.d.ts.map

package/esm/lib/end-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-of.d.ts","sourceRoot":"","sources":["../../src/lib/end-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;;;;GAUG;AAEH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CA2ClD"}

package/esm/lib/end-of.js

@@ -0,0 +1,53 @@
+/**
+ * Returns the end of the specified time unit for the given date.
+ *
+ * @param date - The original date.
+ * @param unit - The time unit to get the end of ('year' | 'month' | 'day' | 'hour' | 'minute' | 'second').
+ * @returns A new Date object set to the end of the specified unit (last millisecond).
+ * @example
+ * const date = new Date('2024-06-15T14:35:22.500Z');
+ * const endOfDay = endOf(date, 'day');
+ * console.log(endOfDay.toISOString()); // '2024-06-15T23:59:59.999Z'
+ */
+export function endOf(date, unit) {
+    const time = new Date(date.getTime());
+    switch (unit) {
+        case 'year': {
+            time.setUTCMonth(11, 31);
+            time.setUTCHours(23, 59, 59, 999);
+            break;
+        }
+        case 'month': {
+            const year = time.getUTCFullYear();
+            const month = time.getUTCMonth();
+            const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+            time.setUTCDate(lastDay);
+            time.setUTCHours(23, 59, 59, 999);
+            break;
+        }
+        case 'week': {
+            const day = time.getUTCDay();
+            const diff = (day === 0 ? 0 : 7) - day; // Adjust when day is Sunday
+            time.setUTCDate(time.getUTCDate() + diff);
+            time.setUTCHours(23, 59, 59, 999);
+            break;
+        }
+        case 'day': {
+            time.setUTCHours(23, 59, 59, 999);
+            break;
+        }
+        case 'hour': {
+            time.setUTCMinutes(59, 59, 999);
+            break;
+        }
+        case 'minute': {
+            time.setUTCSeconds(59, 999);
+            break;
+        }
+        case 'second': {
+            time.setUTCMilliseconds(999);
+            break;
+        }
+    }
+    return time;
+}

package/esm/lib/format.d.ts

@@ -0,0 +1,21 @@
+type FormatOptions = {
+    tz?: string;
+    locale?: string;
+};
+/**
+ * Formats a date into a string using the specified format pattern.
+ *
+ * @param date - The date to format.
+ * @param fmt - The format string with tokens (YYYY, MM, DD, HH, mm, ss, etc.).
+ * @param options - Optional formatting options (locale and timezone).
+ * @returns The formatted date string.
+ * @example
+ * const date = new Date('2024-06-15T14:35:22Z');
+ * console.log(format(date, 'YYYY-MM-DD')); // '2024-06-15'
+ * console.log(format(date, 'YYYY-MM-DD HH:mm:ss')); // '2024-06-15 14:35:22'
+ * console.log(format(date, 'DD/MM/YYYY [at] HH:mm')); // '15/06/2024 at 14:35'
+ * console.log(format(date, 'MMMM D, YYYY', { locale: 'en-US' })); // 'June 15, 2024'
+ */
+export declare function format(date: Date, fmt: string, options?: FormatOptions): string;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/esm/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAGA,KAAK,aAAa,GAAG;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAkLF;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,MAAM,CACpB,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAqBR"}

package/esm/lib/format.js

@@ -0,0 +1,184 @@
+import { getDTF } from "../core/dtf.js";
+import { months } from "./months.js";
+// Pre-compute pad functions to avoid repeated padStart calls
+const pad2 = (n) => n < 10 ? '0' + n : String(n);
+const tokenMap = {
+    YYYY: p => String(p.year),
+    YY: p => String(p.year).slice(-2),
+    M: p => String(p.month),
+    MM: p => pad2(p.month),
+    MMM: (p, l) => months(l, 'short')[p.month - 1],
+    MMMM: (p, l) => months(l, 'long')[p.month - 1],
+    D: p => String(p.day),
+    DD: p => pad2(p.day),
+    H: p => String(p.hour),
+    HH: p => pad2(p.hour),
+    m: p => String(p.minute),
+    mm: p => pad2(p.minute),
+    s: p => String(p.second),
+    ss: p => pad2(p.second),
+};
+const tokenRegex = /YYYY|MMMM|MMM|YY|MM|M|DD|D|HH|H|mm|m|ss|s/g;
+const formatCache = new Map();
+function compileFormat(fmt) {
+    const cached = formatCache.get(fmt);
+    if (cached)
+        return cached;
+    const hasLiterals = fmt.includes('[');
+    const parts = [];
+    if (!hasLiterals) {
+        // Fast path: no literals, just parse tokens
+        let lastIndex = 0;
+        tokenRegex.lastIndex = 0;
+        let match;
+        while ((match = tokenRegex.exec(fmt)) !== null) {
+            if (match.index > lastIndex) {
+                parts.push({ type: 'literal', value: fmt.slice(lastIndex, match.index) });
+            }
+            parts.push({ type: 'token', value: match[0] });
+            lastIndex = match.index + match[0].length;
+        }
+        if (lastIndex < fmt.length) {
+            parts.push({ type: 'literal', value: fmt.slice(lastIndex) });
+        }
+    }
+    else {
+        // Slow path: handle escaped literals
+        let i = 0;
+        let currentLiteral = '';
+        let inBracket = false;
+        while (i < fmt.length) {
+            if (fmt[i] === '[' && !inBracket) {
+                if (currentLiteral) {
+                    // Process current literal for tokens
+                    let lastIndex = 0;
+                    tokenRegex.lastIndex = 0;
+                    let match;
+                    while ((match = tokenRegex.exec(currentLiteral)) !== null) {
+                        if (match.index > lastIndex) {
+                            parts.push({ type: 'literal', value: currentLiteral.slice(lastIndex, match.index) });
+                        }
+                        parts.push({ type: 'token', value: match[0] });
+                        lastIndex = match.index + match[0].length;
+                    }
+                    if (lastIndex < currentLiteral.length) {
+                        parts.push({ type: 'literal', value: currentLiteral.slice(lastIndex) });
+                    }
+                    currentLiteral = '';
+                }
+                inBracket = true;
+                i++;
+            }
+            else if (fmt[i] === ']' && inBracket) {
+                // Escaped literal content - add as-is
+                if (currentLiteral) {
+                    parts.push({ type: 'literal', value: currentLiteral });
+                    currentLiteral = '';
+                }
+                inBracket = false;
+                i++;
+            }
+            else {
+                currentLiteral += fmt[i];
+                i++;
+            }
+        }
+        if (currentLiteral) {
+            let lastIndex = 0;
+            tokenRegex.lastIndex = 0;
+            let match;
+            while ((match = tokenRegex.exec(currentLiteral)) !== null) {
+                if (match.index > lastIndex) {
+                    parts.push({ type: 'literal', value: currentLiteral.slice(lastIndex, match.index) });
+                }
+                parts.push({ type: 'token', value: match[0] });
+                lastIndex = match.index + match[0].length;
+            }
+            if (lastIndex < currentLiteral.length) {
+                parts.push({ type: 'literal', value: currentLiteral.slice(lastIndex) });
+            }
+        }
+    }
+    const compiled = { hasLiterals, parts };
+    formatCache.set(fmt, compiled);
+    return compiled;
+}
+// Fast UTC date parts extraction
+function getUTCParts(date) {
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+        hour: date.getUTCHours(),
+        minute: date.getUTCMinutes(),
+        second: date.getUTCSeconds(),
+    };
+}
+// Fallback for non-UTC timezones
+function getPartsWithTZ(date, locale, tz) {
+    const partsRaw = getDTF(locale, tz).formatToParts(date);
+    const p = {
+        year: 0,
+        month: 0,
+        day: 0,
+        hour: 0,
+        minute: 0,
+        second: 0,
+    };
+    for (const part of partsRaw) {
+        switch (part.type) {
+            case "year":
+                p.year = +part.value;
+                break;
+            case "month":
+                p.month = +part.value;
+                break;
+            case "day":
+                p.day = +part.value;
+                break;
+            case "hour":
+                p.hour = +part.value;
+                break;
+            case "minute":
+                p.minute = +part.value;
+                break;
+            case "second":
+                p.second = +part.value;
+                break;
+        }
+    }
+    return p;
+}
+/**
+ * Formats a date into a string using the specified format pattern.
+ *
+ * @param date - The date to format.
+ * @param fmt - The format string with tokens (YYYY, MM, DD, HH, mm, ss, etc.).
+ * @param options - Optional formatting options (locale and timezone).
+ * @returns The formatted date string.
+ * @example
+ * const date = new Date('2024-06-15T14:35:22Z');
+ * console.log(format(date, 'YYYY-MM-DD')); // '2024-06-15'
+ * console.log(format(date, 'YYYY-MM-DD HH:mm:ss')); // '2024-06-15 14:35:22'
+ * console.log(format(date, 'DD/MM/YYYY [at] HH:mm')); // '15/06/2024 at 14:35'
+ * console.log(format(date, 'MMMM D, YYYY', { locale: 'en-US' })); // 'June 15, 2024'
+ */
+export function format(date, fmt, options = {}) {
+    const locale = options.locale ?? "en-US";
+    const tz = options.tz ?? "UTC";
+    // Get compiled format (cached)
+    const compiled = compileFormat(fmt);
+    // Fast path for UTC
+    const p = tz === "UTC" ? getUTCParts(date) : getPartsWithTZ(date, locale, tz);
+    // Build result string from compiled parts
+    let result = '';
+    for (const part of compiled.parts) {
+        if (part.type === 'literal') {
+            result += part.value;
+        }
+        else {
+            result += tokenMap[part.value](p, locale);
+        }
+    }
+    return result;
+}

package/esm/lib/is-after.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if the first date is after the second date.
+ *
+ * @param dateLeft - The date to compare.
+ * @param dateRight - The date to compare against.
+ * @returns True if dateLeft is after dateRight, false otherwise.
+ * @example
+ * const date1 = new Date('2024-01-20T12:00:00Z');
+ * const date2 = new Date('2024-01-15T12:00:00Z');
+ * console.log(isAfter(date1, date2)); // true
+ */
+export declare function isAfter(dateLeft: Date, dateRight: Date): boolean;
+//# sourceMappingURL=is-after.d.ts.map

package/esm/lib/is-after.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-after.d.ts","sourceRoot":"","sources":["../../src/lib/is-after.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO,CAEhE"}

package/esm/lib/is-after.js

@@ -0,0 +1,15 @@
+/**
+ * Checks if the first date is after the second date.
+ *
+ * @param dateLeft - The date to compare.
+ * @param dateRight - The date to compare against.
+ * @returns True if dateLeft is after dateRight, false otherwise.
+ * @example
+ * const date1 = new Date('2024-01-20T12:00:00Z');
+ * const date2 = new Date('2024-01-15T12:00:00Z');
+ * console.log(isAfter(date1, date2)); // true
+ */
+export function isAfter(dateLeft, dateRight) {
+    return dateLeft.getTime() > dateRight.getTime();
+}
+;

package/esm/lib/is-before.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if the first date is before the second date.
+ *
+ * @param dateLeft - The date to compare.
+ * @param dateRight - The date to compare against.
+ * @returns True if dateLeft is before dateRight, false otherwise.
+ * @example
+ * const date1 = new Date('2024-01-15T12:00:00Z');
+ * const date2 = new Date('2024-01-20T12:00:00Z');
+ * console.log(isBefore(date1, date2)); // true
+ */
+export declare function isBefore(dateLeft: Date, dateRight: Date): boolean;
+//# sourceMappingURL=is-before.d.ts.map

package/esm/lib/is-before.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-before.d.ts","sourceRoot":"","sources":["../../src/lib/is-before.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO,CAEjE"}

package/esm/lib/is-before.js

@@ -0,0 +1,14 @@
+/**
+ * Checks if the first date is before the second date.
+ *
+ * @param dateLeft - The date to compare.
+ * @param dateRight - The date to compare against.
+ * @returns True if dateLeft is before dateRight, false otherwise.
+ * @example
+ * const date1 = new Date('2024-01-15T12:00:00Z');
+ * const date2 = new Date('2024-01-20T12:00:00Z');
+ * console.log(isBefore(date1, date2)); // true
+ */
+export function isBefore(dateLeft, dateRight) {
+    return dateLeft.getTime() < dateRight.getTime();
+}

package/esm/lib/months.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns an array of month names for the specified locale and format.
+ *
+ * @param locale - The locale to use (default: 'en-US').
+ * @param format - The format of month names: 'long', 'short', or 'narrow' (default: 'long').
+ * @returns An array of 12 month names starting from January.
+ * @example
+ * console.log(months('en-US', 'long')); // ['January', 'February', 'March', ...]
+ * console.log(months('en-US', 'short')); // ['Jan', 'Feb', 'Mar', ...]
+ * console.log(months('pt-BR', 'long')); // ['janeiro', 'fevereiro', 'março', ...]
+ */
+export declare function months(locale?: string, format?: "long" | "short" | "narrow"): string[];
+//# sourceMappingURL=months.d.ts.map

package/esm/lib/months.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"months.d.ts","sourceRoot":"","sources":["../../src/lib/months.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,wBAAgB,MAAM,CACpB,MAAM,SAAU,EAChB,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,GAC3C,MAAM,EAAE,CAiBV"}

package/esm/lib/months.js

@@ -0,0 +1,25 @@
+const monthsCache = new Map();
+/**
+ * Returns an array of month names for the specified locale and format.
+ *
+ * @param locale - The locale to use (default: 'en-US').
+ * @param format - The format of month names: 'long', 'short', or 'narrow' (default: 'long').
+ * @returns An array of 12 month names starting from January.
+ * @example
+ * console.log(months('en-US', 'long')); // ['January', 'February', 'March', ...]
+ * console.log(months('en-US', 'short')); // ['Jan', 'Feb', 'Mar', ...]
+ * console.log(months('pt-BR', 'long')); // ['janeiro', 'fevereiro', 'março', ...]
+ */
+export function months(locale = "en-US", format = "long") {
+    const key = `${locale}|${format}`;
+    const cached = monthsCache.get(key);
+    if (cached)
+        return cached;
+    const fmt = new Intl.DateTimeFormat(locale, {
+        month: format,
+        timeZone: "UTC",
+    });
+    const result = Array.from({ length: 12 }, (_, i) => fmt.format(new Date(Date.UTC(2024, i, 1))));
+    monthsCache.set(key, result);
+    return result;
+}

package/esm/lib/start-of.d.ts

@@ -0,0 +1,14 @@
+import type { Unit } from "../types/unit.js";
+/**
+ * Returns the start of the specified time unit for the given date.
+ *
+ * @param date - The original date.
+ * @param unit - The time unit to get the start of ('year' | 'month' | 'day' | 'hour' | 'minute' | 'second').
+ * @returns A new Date object set to the start of the specified unit.
+ * @example
+ * const date = new Date('2024-06-15T14:35:22.500Z');
+ * const startOfDay = startOf(date, 'day');
+ * console.log(startOfDay.toISOString()); // '2024-06-15T00:00:00.000Z'
+ */
+export declare function startOf(date: Date, unit: Unit): Date;
+//# sourceMappingURL=start-of.d.ts.map

package/esm/lib/start-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-of.d.ts","sourceRoot":"","sources":["../../src/lib/start-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;;;;GAUG;AAEH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAwCpD"}

package/esm/lib/start-of.js

@@ -0,0 +1,50 @@
+/**
+ * Returns the start of the specified time unit for the given date.
+ *
+ * @param date - The original date.
+ * @param unit - The time unit to get the start of ('year' | 'month' | 'day' | 'hour' | 'minute' | 'second').
+ * @returns A new Date object set to the start of the specified unit.
+ * @example
+ * const date = new Date('2024-06-15T14:35:22.500Z');
+ * const startOfDay = startOf(date, 'day');
+ * console.log(startOfDay.toISOString()); // '2024-06-15T00:00:00.000Z'
+ */
+export function startOf(date, unit) {
+    const time = new Date(date.getTime());
+    switch (unit) {
+        case 'year': {
+            time.setUTCMonth(0, 1);
+            time.setUTCHours(0, 0, 0, 0);
+            break;
+        }
+        case 'month': {
+            time.setUTCDate(1);
+            time.setUTCHours(0, 0, 0, 0);
+            break;
+        }
+        case 'week': {
+            const day = time.getUTCDay();
+            const diff = (day === 0 ? -6 : 1) - day; // Adjust when day is Sunday
+            time.setUTCDate(time.getUTCDate() + diff);
+            time.setUTCHours(0, 0, 0, 0);
+            break;
+        }
+        case 'day': {
+            time.setUTCHours(0, 0, 0, 0);
+            break;
+        }
+        case 'hour': {
+            time.setUTCMinutes(0, 0, 0);
+            break;
+        }
+        case 'minute': {
+            time.setUTCSeconds(0, 0);
+            break;
+        }
+        case 'second': {
+            time.setUTCMilliseconds(0);
+            break;
+        }
+    }
+    return time;
+}

package/esm/lib/sub.d.ts

@@ -0,0 +1,24 @@
+type SubOptions = {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+};
+/**
+ * Subtracts specified time units from the given date.
+ *
+ * @param date - The original date.
+ * @param opt - The time units to subtract.
+ * @returns A new Date object with the specified time units subtracted.
+ * @example
+ * const date = new Date('2024-03-31T12:00:00Z');
+ * const newDate = sub(date, { years: 1, months: 1 });
+ * console.log(newDate.toISOString()); // '2023-02-28T12:00:00.000Z'
+ */
+export declare function sub(date: Date, opt: SubOptions): Date;
+export {};
+//# sourceMappingURL=sub.d.ts.map