Core API

/**
 * Creates a new Dayjs instance (basic overload)
 * @param date - Input date (string, number, Date, Dayjs, null, undefined)
 * @returns New Dayjs instance
 */
function dayjs(date?: ConfigType): Dayjs;

/**
 * Creates a new Dayjs instance with format (format overload)
 * @param date - Input date
 * @param format - Parse format string or format object
 * @param strict - Strict parsing mode
 * @returns New Dayjs instance
 */
function dayjs(date?: ConfigType, format?: OptionType, strict?: boolean): Dayjs;

/**
 * Creates a new Dayjs instance with format and locale (full overload)
 * @param date - Input date
 * @param format - Parse format string or format object
 * @param locale - Locale string
 * @param strict - Strict parsing mode
 * @returns New Dayjs instance
 */
function dayjs(date?: ConfigType, format?: OptionType, locale?: string, strict?: boolean): Dayjs;

type ConfigType = string | number | Date | Dayjs | null | undefined;
type OptionType = FormatObject | string | string[];

interface FormatObject {
  locale?: string;
  format?: string;
  utc?: boolean;
}

// Current time
const now = dayjs();

// From string
const date1 = dayjs('2018-04-04T16:00:00.000Z');
const date2 = dayjs('2018-04-13 19:18:17.040+02:00');
const date3 = dayjs('2018-04-13 19:18');

// From timestamp
const fromTimestamp = dayjs(1318781876406);

// From Date object
const fromDate = dayjs(new Date(2018, 8, 18));

// From another Dayjs (clone)
const cloned = dayjs(now);

// Invalid dates
const invalid = dayjs('invalid-date'); // Still creates instance
console.log(invalid.isValid()); // false

/**
 * Check if the Dayjs instance contains a valid date
 * @returns True if date is valid, false otherwise
 */
isValid(): boolean;

dayjs().isValid(); // true
dayjs('2018-01-01').isValid(); // true
dayjs('invalid').isValid(); // false
dayjs(null).isValid(); // false

/**
 * Get or set the year
 */
year(): number;
year(value: number): Dayjs;

/**
 * Get or set the month (0-indexed: January = 0)
 */
month(): number;
month(value: number): Dayjs;

/**
 * Get or set the day of the month (1-31)
 */
date(): number;
date(value: number): Dayjs;

/**
 * Get or set the day of the week (0-6: Sunday = 0)
 */
day(): 0 | 1 | 2 | 3 | 4 | 5 | 6;
day(value: number): Dayjs;

/**
 * Get or set the hour (0-23)
 */
hour(): number;
hour(value: number): Dayjs;

/**
 * Get or set the minute (0-59)
 */
minute(): number;
minute(value: number): Dayjs;

/**
 * Get or set the second (0-59)
 */
second(): number;
second(value: number): Dayjs;

/**
 * Get or set the millisecond (0-999)
 */
millisecond(): number;
millisecond(value: number): Dayjs;

/**
 * Generic getter for any unit
 * @param unit - Time unit to get
 * @returns Value for the specified unit
 */
get(unit: UnitType): number;

/**
 * Generic setter for any unit
 * @param unit - Time unit to set
 * @param value - Value to set
 * @returns New Dayjs instance with updated value
 */
set(unit: UnitType, value: number): Dayjs;

const date = dayjs('2018-04-04T16:00:00.000Z');

// Getters
console.log(date.year()); // 2018
console.log(date.month()); // 3 (April, 0-indexed)
console.log(date.date()); // 4
console.log(date.day()); // 3 (Wednesday)
console.log(date.hour()); // 16

// Setters (return new instances)
const newYear = date.year(2019);
const newMonth = date.month(0); // January
const newDate = date.date(1);

// Generic get/set
console.log(date.get('year')); // 2018
const updated = date.set('year', 2020);

/**
 * Add time to the current instance
 * @param value - Amount to add
 * @param unit - Time unit
 * @returns New Dayjs instance with added time
 */
add(value: number, unit?: ManipulateType): Dayjs;

/**
 * Subtract time from the current instance
 * @param value - Amount to subtract
 * @param unit - Time unit
 * @returns New Dayjs instance with subtracted time
 */
subtract(value: number, unit?: ManipulateType): Dayjs;

/**
 * Set to the start of a unit of time
 * @param unit - Time unit
 * @returns New Dayjs instance set to start of unit
 */
startOf(unit: OpUnitType): Dayjs;

/**
 * Set to the end of a unit of time
 * @param unit - Time unit
 * @returns New Dayjs instance set to end of unit
 */
endOf(unit: OpUnitType): Dayjs;

const date = dayjs('2018-04-04T16:00:00.000Z');

// Addition
const nextWeek = date.add(1, 'week');
const nextMonth = date.add(1, 'month');
const nextYear = date.add(1, 'year');
const later = date.add(30, 'minutes');

// Subtraction
const lastWeek = date.subtract(1, 'week');
const yesterday = date.subtract(1, 'day');

// Start/End of periods
const startOfDay = date.startOf('day'); // 2018-04-04T00:00:00.000Z
const endOfDay = date.endOf('day'); // 2018-04-04T23:59:59.999Z
const startOfMonth = date.startOf('month'); // 2018-04-01T00:00:00.000Z
const startOfYear = date.startOf('year'); // 2018-01-01T00:00:00.000Z

// Chaining operations
const result = dayjs()
  .add(1, 'day')
  .subtract(2, 'hours')
  .startOf('hour');

/**
 * Check if this date is before another date
 * @param date - Date to compare against
 * @param unit - Unit for comparison granularity
 * @returns True if this date is before the other
 */
isBefore(date?: ConfigType, unit?: OpUnitType): boolean;

/**
 * Check if this date is the same as another date
 * @param date - Date to compare against
 * @param unit - Unit for comparison granularity
 * @returns True if dates are the same
 */
isSame(date?: ConfigType, unit?: OpUnitType): boolean;

/**
 * Check if this date is after another date
 * @param date - Date to compare against
 * @param unit - Unit for comparison granularity
 * @returns True if this date is after the other
 */
isAfter(date?: ConfigType, unit?: OpUnitType): boolean;

/**
 * Get the difference between this and another date
 * @param date - Date to compare against (defaults to now)
 * @param unit - Unit for the difference (defaults to milliseconds)
 * @param float - Return floating point result
 * @returns Difference in specified unit
 */
diff(date?: ConfigType, unit?: QUnitType | OpUnitType, float?: boolean): number;

const date1 = dayjs('2018-01-01');
const date2 = dayjs('2018-01-02');

// Basic comparisons
console.log(date1.isBefore(date2)); // true
console.log(date1.isAfter(date2)); // false
console.log(date1.isSame(date1)); // true

// Comparisons with unit granularity
const time1 = dayjs('2018-01-01 10:30:00');
const time2 = dayjs('2018-01-01 15:45:00');

console.log(time1.isSame(time2, 'day')); // true (same day)
console.log(time1.isSame(time2, 'hour')); // false (different hours)

// Differences
const diff1 = date2.diff(date1); // milliseconds
const diff2 = date2.diff(date1, 'day'); // 1
const diff3 = date2.diff(date1, 'hour'); // 24
const diff4 = dayjs().diff(date1, 'year', true); // floating point years

/**
 * Format the date according to the string of tokens
 * @param template - Format template string
 * @returns Formatted date string
 */
format(template?: string): string;

/**
 * Get the number of milliseconds since Unix Epoch
 * @returns Milliseconds since epoch
 */
valueOf(): number;

/**
 * Get the Unix timestamp (seconds since epoch)
 * @returns Seconds since epoch (floored)
 */
unix(): number;

/**
 * Get the number of days in the current month
 * @returns Number of days in month
 */
daysInMonth(): number;

/**
 * Get a copy of the native Date object
 * @returns Native JavaScript Date
 */
toDate(): Date;

/**
 * Serialize as ISO 8601 string
 * @returns ISO 8601 formatted string
 */
toJSON(): string;

/**
 * Format as ISO 8601 string
 * @returns ISO 8601 formatted string
 */
toISOString(): string;

/**
 * Return string representation
 * @returns UTC string representation
 */
toString(): string;

/**
 * Get the UTC offset in minutes
 * @returns UTC offset in minutes
 */
utcOffset(): number;

const date = dayjs('2018-04-04T16:00:00.000Z');

// Default format (ISO 8601)
console.log(date.format()); // 2018-04-04T16:00:00Z

// Custom formats
console.log(date.format('YYYY-MM-DD')); // 2018-04-04
console.log(date.format('DD/MM/YYYY')); // 04/04/2018
console.log(date.format('MMM D, YYYY')); // Apr 4, 2018
console.log(date.format('dddd, MMMM Do YYYY, h:mm:ss a')); // Wednesday, April 4th 2018, 4:00:00 pm

// Escaped text
console.log(date.format('[Today is] dddd [the] Do [of] MMMM')); // Today is Wednesday the 4th of April

// Timestamps
console.log(date.valueOf()); // 1522857600000
console.log(date.unix()); // 1522857600

// Other representations
console.log(date.daysInMonth()); // 30
console.log(date.toDate()); // Native Date object
console.log(date.toJSON()); // 2018-04-04T16:00:00.000Z
console.log(date.toISOString()); // 2018-04-04T16:00:00.000Z
console.log(date.toString()); // Wed, 04 Apr 2018 16:00:00 GMT

/**
 * Clone the current instance
 * @returns New identical Dayjs instance
 */
clone(): Dayjs;

/**
 * Get or set the locale for this instance
 * @param preset - Locale name or locale object
 * @param object - Locale definition
 * @returns Current locale name or new instance with locale
 */
locale(): string;
locale(preset: string | ILocale, object?: Partial<ILocale>): Dayjs;

const original = dayjs('2018-04-04');

// Clone
const copy = original.clone();
console.log(copy.isSame(original)); // true
console.log(copy === original); // false (different instances)

// Locale operations
console.log(dayjs().locale()); // 'en' (current locale)
const spanish = dayjs().locale('es'); // Spanish locale for this instance
console.log(spanish.format('MMMM')); // Spanish month name