chronos-ts
Version:
A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.
461 lines (460 loc) • 13.9 kB
TypeScript
/**
* Chronos - The ultimate TypeScript date/time library
* @module Chronos
*/
import { DateInput, ChronosConfig, Duration, AnyTimeUnit, DayOfWeek, DateTimeSetter, DiffResult, HumanDiffOptions, ChronosLike, DateTimeComponents, ChronosJSON } from '../types';
/**
* Chronos - A comprehensive date/time manipulation library
*
* @example
* ```typescript
* // Create instances
* const now = Chronos.now();
* const date = Chronos.parse('2024-01-15');
* const birthday = Chronos.create(1990, 5, 15);
*
* // Manipulate
* const future = now.add(3, 'months').startOf('day');
* const past = now.subtract(1, 'year').endOf('month');
*
* // Compare
* const isAfter = date.isAfter(birthday);
* const diff = date.diff(birthday, 'years');
*
* // Format
* const formatted = now.format('YYYY-MM-DD HH:mm:ss');
* const relative = birthday.fromNow(); // "34 years ago"
* ```
*/
export declare class Chronos implements ChronosLike {
private readonly _date;
private _locale;
private _timezone?;
/**
* Create a new Chronos instance
*
* @param input - Date input (string, number, Date, or Chronos)
* @param timezone - Optional timezone
*/
private constructor();
/**
* Parse a date string
*/
private parseString;
/**
* Helper to create a date from components in a specific timezone
*/
private static dateFromComponents;
/**
* Create a Chronos instance from various inputs
*
* @example
* ```typescript
* Chronos.parse('2024-01-15')
* Chronos.parse(1705276800000)
* Chronos.parse(new Date())
* ```
*/
static parse(input?: DateInput, timezone?: string): Chronos;
/**
* Create a Chronos instance for the current moment
*
* @example
* ```typescript
* const now = Chronos.now();
* ```
*/
static now(timezone?: string): Chronos;
/**
* Create a Chronos instance for today at midnight
*/
static today(timezone?: string): Chronos;
/**
* Create a Chronos instance for tomorrow at midnight
*/
static tomorrow(timezone?: string): Chronos;
/**
* Create a Chronos instance for yesterday at midnight
*/
static yesterday(timezone?: string): Chronos;
/**
* Create a Chronos instance from individual components
* Month is 1-12 (like Carbon PHP)
*
* @example
* ```typescript
* Chronos.create(2024, 1, 15, 10, 30, 0) // Jan 15, 2024 10:30:00
* ```
*/
static create(year: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, millisecond?: number, timezone?: string): Chronos;
/**
* Create a Chronos instance from a Unix timestamp (seconds)
*/
static fromUnix(timestamp: number, timezone?: string): Chronos;
/**
* Create a Chronos instance from a Unix timestamp (milliseconds)
*/
static fromMillis(timestamp: number, timezone?: string): Chronos;
/**
* Create a Chronos instance from components object
* Month in components is 1-12 (like Carbon PHP)
*/
static fromObject(components: DateTimeComponents, timezone?: string): Chronos;
/**
* Create a Chronos instance from a format string
*
* @example
* ```typescript
* Chronos.fromFormat('15-01-2024', 'DD-MM-YYYY')
* ```
*/
static fromFormat(input: string, format: string, timezone?: string): Chronos;
/**
* Create the minimum possible date
*/
static min(): Chronos;
/**
* Create the maximum possible date
*/
static max(): Chronos;
/**
* Get the earliest of multiple dates
*/
static earliest(...dates: (DateInput | Chronos)[]): Chronos;
/**
* Get the latest of multiple dates
*/
static latest(...dates: (DateInput | Chronos)[]): Chronos;
/** Get the year */
get year(): number;
/** Get the month (1-12) */
get month(): number;
/** Get the day of month (1-31) */
get date(): number;
/** Alias for date */
get day(): number;
/** Get the day of week (0-6, Sunday = 0) */
get dayOfWeek(): DayOfWeek;
/** Get the hour (0-23) */
get hour(): number;
/** Get the minute (0-59) */
get minute(): number;
/** Get the second (0-59) */
get second(): number;
/** Get the millisecond (0-999) */
get millisecond(): number;
/** Get Unix timestamp (seconds) */
get unix(): number;
/** Get Unix timestamp (milliseconds) */
get timestamp(): number;
/** Get the quarter (1-4) */
get quarter(): number;
/** Get the day of year (1-366) */
get dayOfYear(): number;
/** Get the ISO week number (1-53) */
get week(): number;
/** Get the ISO week year */
get weekYear(): number;
/** Get the number of days in the current month */
get daysInMonth(): number;
/** Get the number of days in the current year */
get daysInYear(): number;
/** Get the number of weeks in the current year */
get weeksInYear(): number;
/** Check if the year is a leap year */
get isLeapYear(): boolean;
/** Get the timezone offset in minutes */
get offset(): number;
/** Get the timezone offset as string (+05:30) */
get offsetString(): string;
/**
* Set specific date/time components
* Returns a new Chronos instance
*/
/**
* Set multiple date/time values at once
* Month is 1-12 (like Carbon PHP)
*/
set(values: DateTimeSetter): Chronos;
/** Set the year */
setYear(year: number): Chronos;
/** Set the month (1-12) */
setMonth(month: number): Chronos;
/** Set the day of month (1-31) */
setDate(date: number): Chronos;
/** Set the hour (0-23) */
setHour(hour: number): Chronos;
/** Set the minute (0-59) */
setMinute(minute: number): Chronos;
/** Set the second (0-59) */
setSecond(second: number): Chronos;
/** Set the millisecond (0-999) */
setMillisecond(millisecond: number): Chronos;
/**
* Add time to the date
*
* @example
* ```typescript
* chronos.add(5, 'days')
* chronos.add(2, 'months')
* chronos.add({ years: 1, months: 2 })
* ```
*/
add(amount: number | Duration, unit?: AnyTimeUnit): Chronos;
/**
* Subtract time from the date
*/
subtract(amount: number | Duration, unit?: AnyTimeUnit): Chronos;
/**
* Get the start of a time unit
*
* @example
* ```typescript
* chronos.startOf('day') // 00:00:00.000
* chronos.startOf('month') // First day of month
* chronos.startOf('year') // January 1st
* ```
*/
startOf(unit: AnyTimeUnit): Chronos;
/**
* Get the end of a time unit
*
* @example
* ```typescript
* chronos.endOf('day') // 23:59:59.999
* chronos.endOf('month') // Last day of month
* chronos.endOf('year') // December 31st
* ```
*/
endOf(unit: AnyTimeUnit): Chronos;
addMilliseconds(amount: number): Chronos;
addSeconds(amount: number): Chronos;
addMinutes(amount: number): Chronos;
addHours(amount: number): Chronos;
addDays(amount: number): Chronos;
addWeeks(amount: number): Chronos;
addMonths(amount: number): Chronos;
addQuarters(amount: number): Chronos;
addYears(amount: number): Chronos;
subtractMilliseconds(amount: number): Chronos;
subtractSeconds(amount: number): Chronos;
subtractMinutes(amount: number): Chronos;
subtractHours(amount: number): Chronos;
subtractDays(amount: number): Chronos;
subtractWeeks(amount: number): Chronos;
subtractMonths(amount: number): Chronos;
subtractQuarters(amount: number): Chronos;
subtractYears(amount: number): Chronos;
/**
* Check if this date is before another
*/
isBefore(other: DateInput, unit?: AnyTimeUnit): boolean;
/**
* Check if this date is after another
*/
isAfter(other: DateInput, unit?: AnyTimeUnit): boolean;
/**
* Check if this date is the same as another
*/
isSame(other: DateInput, unit?: AnyTimeUnit): boolean;
/**
* Check if this date is same or before another
*/
isSameOrBefore(other: DateInput, unit?: AnyTimeUnit): boolean;
/**
* Check if this date is same or after another
*/
isSameOrAfter(other: DateInput, unit?: AnyTimeUnit): boolean;
/**
* Check if this date is between two others
*/
isBetween(start: DateInput, end: DateInput, unit?: AnyTimeUnit, inclusivity?: '()' | '[]' | '[)' | '(]'): boolean;
/** Check if this date is today */
isToday(): boolean;
/** Check if this date is tomorrow */
isTomorrow(): boolean;
/** Check if this date is yesterday */
isYesterday(): boolean;
/** Check if this date is in the past */
isPast(): boolean;
/** Check if this date is in the future */
isFuture(): boolean;
/** Check if this is a weekend (Saturday or Sunday) */
isWeekend(): boolean;
/** Check if this is a weekday (Monday-Friday) */
isWeekday(): boolean;
isSunday(): boolean;
isMonday(): boolean;
isTuesday(): boolean;
isWednesday(): boolean;
isThursday(): boolean;
isFriday(): boolean;
isSaturday(): boolean;
/**
* Get the difference between two dates in a specific unit
*/
diff(other: DateInput, unit?: AnyTimeUnit, precise?: boolean): number;
/**
* Get a detailed diff breakdown
*/
diffDetailed(other: DateInput): DiffResult;
/**
* Get a human-readable relative time string
*
* @example
* ```typescript
* date.fromNow() // "2 days ago"
* date.from(other) // "in 3 months"
* date.fromNow({ short: true }) // "2d ago"
* ```
*/
fromNow(options?: HumanDiffOptions): string;
/**
* Get relative time from another date
*/
from(other: DateInput, options?: HumanDiffOptions): string;
/**
* Get relative time to another date
*/
to(other: DateInput, options?: HumanDiffOptions): string;
/**
* Get relative time to now
*/
toNow(options?: HumanDiffOptions): string;
/**
* Format the date using a format string
*
* Supported tokens:
* - YYYY: 4-digit year
* - YY: 2-digit year
* - MMMM: Full month name
* - MMM: Short month name
* - MM: 2-digit month
* - M: 1-2 digit month
* - DD: 2-digit day
* - D: 1-2 digit day
* - dddd: Full weekday name
* - ddd: Short weekday name
* - dd: Min weekday name
* - d: Day of week number
* - HH: 2-digit hour (24h)
* - H: 1-2 digit hour (24h)
* - hh: 2-digit hour (12h)
* - h: 1-2 digit hour (12h)
* - mm: 2-digit minute
* - m: 1-2 digit minute
* - ss: 2-digit second
* - s: 1-2 digit second
* - SSS: 3-digit millisecond
* - A: AM/PM
* - a: am/pm
* - Z: Timezone offset (+05:00)
* - ZZ: Timezone offset (+0500)
*/
format(formatStr?: string): string;
/** Format as ISO 8601 */
toISOString(): string;
/** Format as ISO date (YYYY-MM-DD) */
toDateString(): string;
/** Format as time (HH:mm:ss) */
toTimeString(): string;
/** Format as datetime (YYYY-MM-DD HH:mm:ss) */
toDateTimeString(): string;
/** Format as RFC 2822 */
toRFC2822(): string;
/** Format as RFC 3339 */
toRFC3339(): string;
/** Format as ATOM */
toAtomString(): string;
/** Format as Cookie */
toCookieString(): string;
/** Format as RSS */
toRSSString(): string;
/** Format as W3C */
toW3CString(): string;
/**
* Convert to a specific timezone
*/
toTimezone(timezone: string): Chronos;
/** Convert to native Date object */
toDate(): Date;
/** Convert to array [year, month, day, hour, minute, second, millisecond] */
toArray(): number[];
/** Convert to object */
toObject(): DateTimeComponents;
/** Convert to JSON-serializable object */
toJSON(): ChronosJSON;
/** Get primitive value (timestamp) */
valueOf(): number;
/** Convert to string */
toString(): string;
/**
* Create a clone of this instance
*/
clone(): Chronos;
/**
* Set the locale for this instance
*/
locale(code: string): Chronos;
/**
* Get the current locale code
*/
getLocale(): string;
/**
* Get the next occurrence of a specific day
*/
next(day: DayOfWeek): Chronos;
/**
* Get the previous occurrence of a specific day
*/
previous(day: DayOfWeek): Chronos;
/**
* Get the closest date (either this or other)
*/
closest(date1: DateInput, date2: DateInput): Chronos;
/**
* Get the farthest date (either this or other)
*/
farthest(date1: DateInput, date2: DateInput): Chronos;
/**
* Set global configuration
*/
static configure(config: Partial<ChronosConfig>): void;
/**
* Get current global configuration
*/
static getConfig(): ChronosConfig;
/**
* Set test time (for testing purposes)
*/
static setTestNow(date?: DateInput): void;
/**
* Check if test mode is active
*/
static hasTestNow(): boolean;
/**
* Get the test time
*/
static getTestNow(): Chronos | null;
/**
* Check if the date is valid
*/
isValid(): boolean;
/**
* Check if this date is the same day as another (regardless of time)
*/
isSameDay(other: DateInput): boolean;
/**
* Check if this date is in the same month as another
*/
isSameMonth(other: DateInput): boolean;
/**
* Check if this date is in the same year as another
*/
isSameYear(other: DateInput): boolean;
/**
* Get calendar output for the current month
*/
calendar(referenceDate?: DateInput): string;
}
export default Chronos;