@catbee/utils 2.0.0-next.1 → 2.0.0

package/date/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -209,6 +209,491 @@ declare function parseDuration(value: string | number): number;
  * ```
  */
 declare function getDateFromDuration(input: string): Date;
+/**
+ * Checks if a date is on a weekend (Saturday or Sunday).
+ *
+ * @param {Date | number} date - The date to check.
+ * @returns {boolean} True if weekend.
+ *
+ * @example
+ * isWeekend(new Date('2024-01-06')); // true (Saturday)
+ */
+declare function isWeekend(date: Date | number): boolean;
+/**
+ * Checks if a date is today.
+ *
+ * @param {Date | number} date - The date to check.
+ * @returns {boolean} True if today.
+ *
+ * @example
+ * isToday(new Date()); // true
+ */
+declare function isToday(date: Date | number): boolean;
+/**
+ * Checks if a date is in the future.
+ *
+ * @param {Date | number} date - The date to check.
+ * @returns {boolean} True if in the future.
+ *
+ * @example
+ * isFuture(new Date('2099-01-01')); // true
+ */
+declare function isFuture(date: Date | number): boolean;
+/**
+ * Checks if a date is in the past.
+ *
+ * @param {Date | number} date - The date to check.
+ * @returns {boolean} True if in the past.
+ *
+ * @example
+ * isPast(new Date('2020-01-01')); // true
+ */
+declare function isPast(date: Date | number): boolean;
+/**
+ * Adds days to a date.
+ *
+ * @param {Date | number} date - The base date.
+ * @param {number} days - Number of days to add (can be negative).
+ * @returns {Date} New date with days added.
+ *
+ * @example
+ * addDays(new Date('2024-01-15'), 7); // 2024-01-22
+ */
+declare function addDays(date: Date | number, days: number): Date;
+/**
+ * Adds months to a date.
+ *
+ * @param {Date | number} date - The base date.
+ * @param {number} months - Number of months to add (can be negative).
+ * @returns {Date} New date with months added.
+ *
+ * @example
+ * addMonths(new Date('2024-01-31'), 1); // 2024-02-29 (leap year)
+ */
+declare function addMonths(date: Date | number, months: number): Date;
+/**
+ * Adds years to a date.
+ *
+ * @param {Date | number} date - The base date.
+ * @param {number} years - Number of years to add (can be negative).
+ * @returns {Date} New date with years added.
+ *
+ * @example
+ * addYears(new Date('2024-01-15'), 5); // 2029-01-15
+ */
+declare function addYears(date: Date | number, years: number): Date;
+/**
+ * Gets the quarter of the year for a date (1-4).
+ *
+ * @param {Date | number} date - The date.
+ * @returns {1 | 2 | 3 | 4} Quarter number.
+ *
+ * @example
+ * quarterOf(new Date('2024-03-15')); // 1
+ * quarterOf(new Date('2024-07-15')); // 3
+ */
+declare function quarterOf(date: Date | number): 1 | 2 | 3 | 4;
+/**
+ * Gets the ISO week number of the year for a date.
+ *
+ * @param {Date | number} date - The date.
+ * @returns {number} Week number (1-53).
+ *
+ * @example
+ * weekOfYear(new Date('2024-01-15')); // 3
+ */
+declare function weekOfYear(date: Date | number): number;
+
+/**
+ * DateBuilder class for fluent date manipulation and building.
+ * Provides a chainable API similar to Java's date builders.
+ * All methods return a new instance, making it immutable.
+ *
+ * @example
+ * ```typescript
+ * // Create a date builder
+ * const date = new DateBuilder()
+ *   .year(2024)
+ *   .month(5)
+ *   .day(15)
+ *   .hour(14)
+ *   .minute(30)
+ *   .build();
+ *
+ * // Chain operations
+ * const nextWeek = new DateBuilder()
+ *   .addDays(7)
+ *   .startOfDay()
+ *   .build();
+ *
+ * // Use with existing date
+ * const modified = DateBuilder.from(new Date())
+ *   .addMonths(2)
+ *   .endOfMonth()
+ *   .format('yyyy-MM-dd');
+ * ```
+ */
+declare class DateBuilder {
+    private readonly date;
+    /**
+     * Creates a new DateBuilder instance.
+     * @param date - Initial date (default: current date/time)
+     */
+    constructor(date?: Date | number | string);
+    /**
+     * Create a DateBuilder from an existing date.
+     * @param date - Date to build from
+     */
+    static from(date: Date | number | string): DateBuilder;
+    /**
+     * Create a DateBuilder for the current moment.
+     */
+    static now(): DateBuilder;
+    /**
+     * Create a DateBuilder for a specific date.
+     * @param year - Year
+     * @param month - Month (1-12, not 0-11)
+     * @param day - Day of month
+     * @param hour - Hour (default: 0)
+     * @param minute - Minute (default: 0)
+     * @param second - Second (default: 0)
+     * @param millisecond - Millisecond (default: 0)
+     */
+    static of(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number): DateBuilder;
+    /**
+     * Parse a date string into a DateBuilder.
+     * @param dateString - Date string to parse
+     */
+    static parse(dateString: string): DateBuilder;
+    /**
+     * Create a DateBuilder from a duration string (e.g., "5m", "2h", "1d" from now).
+     * @param duration - Duration string
+     */
+    static fromDuration(duration: string): DateBuilder;
+    /**
+     * Clone this DateBuilder instance.
+     */
+    clone(): DateBuilder;
+    /**
+     * Set the year.
+     * @param year - Year to set
+     */
+    year(year: number): DateBuilder;
+    /**
+     * Set the month (1-12, not 0-11).
+     * @param month - Month to set (1-12)
+     */
+    month(month: number): DateBuilder;
+    /**
+     * Set the day of the month.
+     * @param day - Day to set
+     */
+    day(day: number): DateBuilder;
+    /**
+     * Set the hour.
+     * @param hour - Hour to set
+     */
+    hour(hour: number): DateBuilder;
+    /**
+     * Set the minute.
+     * @param minute - Minute to set
+     */
+    minute(minute: number): DateBuilder;
+    /**
+     * Set the second.
+     * @param second - Second to set
+     */
+    second(second: number): DateBuilder;
+    /**
+     * Set the millisecond.
+     * @param millisecond - Millisecond to set
+     */
+    millisecond(millisecond: number): DateBuilder;
+    /**
+     * Add years to the date.
+     * @param years - Number of years to add (can be negative)
+     */
+    addYears(years: number): DateBuilder;
+    /**
+     * Add months to the date.
+     * @param months - Number of months to add (can be negative)
+     */
+    addMonths(months: number): DateBuilder;
+    /**
+     * Add days to the date.
+     * @param days - Number of days to add (can be negative)
+     */
+    addDays(days: number): DateBuilder;
+    /**
+     * Add hours to the date.
+     * @param hours - Number of hours to add (can be negative)
+     */
+    addHours(hours: number): DateBuilder;
+    /**
+     * Add minutes to the date.
+     * @param minutes - Number of minutes to add (can be negative)
+     */
+    addMinutes(minutes: number): DateBuilder;
+    /**
+     * Add seconds to the date.
+     * @param seconds - Number of seconds to add (can be negative)
+     */
+    addSeconds(seconds: number): DateBuilder;
+    /**
+     * Add milliseconds to the date.
+     * @param milliseconds - Number of milliseconds to add (can be negative)
+     */
+    addMilliseconds(milliseconds: number): DateBuilder;
+    /**
+     * Subtract years from the date.
+     * @param years - Number of years to subtract
+     */
+    subtractYears(years: number): DateBuilder;
+    /**
+     * Subtract months from the date.
+     * @param months - Number of months to subtract
+     */
+    subtractMonths(months: number): DateBuilder;
+    /**
+     * Subtract days from the date.
+     * @param days - Number of days to subtract
+     */
+    subtractDays(days: number): DateBuilder;
+    /**
+     * Subtract hours from the date.
+     * @param hours - Number of hours to subtract
+     */
+    subtractHours(hours: number): DateBuilder;
+    /**
+     * Subtract minutes from the date.
+     * @param minutes - Number of minutes to subtract
+     */
+    subtractMinutes(minutes: number): DateBuilder;
+    /**
+     * Subtract seconds from the date.
+     * @param seconds - Number of seconds to subtract
+     */
+    subtractSeconds(seconds: number): DateBuilder;
+    /**
+     * Set to the start of the second.
+     */
+    startOfSecond(): DateBuilder;
+    /**
+     * Set to the start of the minute.
+     */
+    startOfMinute(): DateBuilder;
+    /**
+     * Set to the start of the hour.
+     */
+    startOfHour(): DateBuilder;
+    /**
+     * Set to the start of the day (midnight).
+     */
+    startOfDay(): DateBuilder;
+    /**
+     * Set to the start of the week (Sunday).
+     */
+    startOfWeek(): DateBuilder;
+    /**
+     * Set to the start of the month.
+     */
+    startOfMonth(): DateBuilder;
+    /**
+     * Set to the start of the quarter.
+     */
+    startOfQuarter(): DateBuilder;
+    /**
+     * Set to the start of the year.
+     */
+    startOfYear(): DateBuilder;
+    /**
+     * Set to the end of the second.
+     */
+    endOfSecond(): DateBuilder;
+    /**
+     * Set to the end of the minute.
+     */
+    endOfMinute(): DateBuilder;
+    /**
+     * Set to the end of the hour.
+     */
+    endOfHour(): DateBuilder;
+    /**
+     * Set to the end of the day (23:59:59.999).
+     */
+    endOfDay(): DateBuilder;
+    /**
+     * Set to the end of the week (Saturday).
+     */
+    endOfWeek(): DateBuilder;
+    /**
+     * Set to the end of the month.
+     */
+    endOfMonth(): DateBuilder;
+    /**
+     * Set to the end of the quarter.
+     */
+    endOfQuarter(): DateBuilder;
+    /**
+     * Set to the end of the year.
+     */
+    endOfYear(): DateBuilder;
+    /**
+     * Check if the date is before another date.
+     * @param other - Date to compare with
+     */
+    isBefore(other: Date | DateBuilder): boolean;
+    /**
+     * Check if the date is after another date.
+     * @param other - Date to compare with
+     */
+    isAfter(other: Date | DateBuilder): boolean;
+    /**
+     * Check if the date is the same as another date.
+     * @param other - Date to compare with
+     */
+    isSame(other: Date | DateBuilder): boolean;
+    /**
+     * Check if the date is between two dates.
+     * @param start - Start date
+     * @param end - End date
+     * @param inclusive - Whether to include boundaries
+     */
+    isBetween(start: Date | DateBuilder, end: Date | DateBuilder, inclusive?: boolean): boolean;
+    /**
+     * Check if the date is today.
+     */
+    isToday(): boolean;
+    /**
+     * Check if the date is in the future.
+     */
+    isFuture(): boolean;
+    /**
+     * Check if the date is in the past.
+     */
+    isPast(): boolean;
+    /**
+     * Check if the date is on a weekend.
+     */
+    isWeekend(): boolean;
+    /**
+     * Check if the year is a leap year.
+     */
+    isLeapYear(): boolean;
+    /**
+     * Get the year.
+     */
+    getYear(): number;
+    /**
+     * Get the month (1-12, not 0-11).
+     */
+    getMonth(): number;
+    /**
+     * Get the day of the month.
+     */
+    getDay(): number;
+    /**
+     * Get the day of the week (0-6, Sunday is 0).
+     */
+    getDayOfWeek(): number;
+    /**
+     * Get the hour.
+     */
+    getHour(): number;
+    /**
+     * Get the minute.
+     */
+    getMinute(): number;
+    /**
+     * Get the second.
+     */
+    getSecond(): number;
+    /**
+     * Get the millisecond.
+     */
+    getMillisecond(): number;
+    /**
+     * Get the quarter (1-4).
+     */
+    getQuarter(): 1 | 2 | 3 | 4;
+    /**
+     * Get the ISO week number.
+     */
+    getWeekOfYear(): number;
+    /**
+     * Get the number of days in the current month.
+     */
+    getDaysInMonth(): number;
+    /**
+     * Get the Unix timestamp in milliseconds.
+     */
+    getTime(): number;
+    /**
+     * Get the Unix timestamp in seconds.
+     */
+    getUnixTimestamp(): number;
+    /**
+     * Calculate the difference from another date.
+     * @param other - Date to compare with
+     * @param unit - Unit of time
+     */
+    diff(other: Date | DateBuilder, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
+    /**
+     * Get the difference from now.
+     * @param unit - Unit of time
+     */
+    diffFromNow(unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
+    /**
+     * Format the date.
+     * @param options - Formatting options
+     */
+    format(options?: DateFormatOptions | string): string;
+    /**
+     * Format as relative time (e.g., "5 minutes ago").
+     * @param locale - Locale for formatting
+     */
+    formatRelative(locale?: string | string[]): string;
+    /**
+     * Format as ISO 8601 string.
+     */
+    toISOString(): string;
+    /**
+     * Format as UTC string.
+     */
+    toUTCString(): string;
+    /**
+     * Format as date string.
+     */
+    toDateString(): string;
+    /**
+     * Format as time string.
+     */
+    toTimeString(): string;
+    /**
+     * Format as locale string.
+     */
+    toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Convert to JSON string.
+     */
+    toJSON(): string;
+    /**
+     * Build and return the Date object.
+     */
+    build(): Date;
+    /**
+     * Get the Date object (alias for build).
+     */
+    toDate(): Date;
+    /**
+     * Get the internal Date object value.
+     */
+    valueOf(): number;
+    /**
+     * Convert to string.
+     */
+    toString(): string;
+}
 
-export { addToDate, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, getDateFromDuration, isBetween, isLeapYear, parseDate, parseDuration, startOf };
+export { DateBuilder, addDays, addMonths, addToDate, addYears, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, getDateFromDuration, isBetween, isFuture, isLeapYear, isPast, isToday, isWeekend, parseDate, parseDuration, quarterOf, startOf, weekOfYear };
 export type { DateFormatOptions };