millis-js/dist/index.d.mts

A tiny and dependency-free datetime library with a chainable and immutable API

//#region src/types.d.ts

type AbsoluteDuration = {
  readonly millis?: number;
  readonly seconds?: number;
  readonly minutes?: number;
  readonly hours?: number;
  readonly days?: number;
};
type RelativeDuration = {
  readonly months?: number;
  readonly years?: number;
};
type DurationComponents = AbsoluteDuration & RelativeDuration;
type DurationLike = number | AbsoluteDuration | Duration | DurationComponents;
type OrdinalDate = {
  year: number;
  dayOfYear: number;
};
type CalendarDate = {
  year: number;
  month: number;
  dayOfMonth: number;
};
type TimeComponents = {
  hour: number;
  minute: number;
  second: number;
  millisecond: number;
};
type DateTimeFormat = 'YYYY' | 'YYYY-MM-DD' | 'YYYY-DDD' | 'HH:mm:ss';
type DateTimeComponents = (OrdinalDate & Partial<TimeComponents>) | (CalendarDate & Partial<TimeComponents>);
type DateLike = {
  getTime(): number;
};
type DateTimeLike = number | string | DateTime | DateLike | DateTimeComponents;
//#endregion
//#region src/duration.d.ts
/**
 * Duration options
 */
type DurationOptions = {
  /**
   * Round the duration to the nearest integer:
   * - `true` rounds up or down to the nearest integer
   * - `'up'` rounds up to the nearest integer
   * - `'down'` rounds down to the nearest integer
   */
  round?: 'up' | 'down' | true;
};
/**
 * A `Duration` represents a length of time.
 */
declare class Duration {
  private value;
  private constructor();
  /**
   * Creates a `Duration` object from an absolute duration.
   * @deprecated Use `Duration.from` instead.
   */
  static of(duration: AbsoluteDuration): Duration;
  /**
   * Creates a `Duration` object from an absolute duration.
   */
  static from(duration: DurationLike): Duration;
  /**
   * Creates a `Duration` object from the difference between two `DateTimeLike` objects.
   * @deprecated Use `Duration.between` instead.
   */
  static diff(start: DateTimeLike, end: DateTimeLike): Duration;
  /**
   * Creates a `Duration` object from the difference between two `DateTimeLike` objects.
   */
  static between(start: DateTimeLike, end: DateTimeLike): Duration;
  /**
   * Creates a `Duration` object from a number of days.
   */
  static days(days: number): Duration;
  /**
   * Creates a `Duration` object from a number of hours.
   */
  static hours(hours: number): Duration;
  /**
   * Creates a `Duration` object from a number of minutes.
   */
  static minutes(minutes: number): Duration;
  /**
   * Creates a `Duration` object from a number of seconds.
   */
  static seconds(seconds: number): Duration;
  /**
   * Creates a `Duration` object from a number of milliseconds.
   */
  static millis(millis: number): Duration;
  /**
   * Returns the number of milliseconds of the `Duration` object.
   */
  millis(): number;
  /**
   * Returns the number of seconds of the `Duration` object.
   */
  seconds(options?: DurationOptions): number;
  /**
   * Returns the number of minutes of the `Duration` object.
   */
  minutes(options?: DurationOptions): number;
  /**
   * Returns the number of hours of the `Duration` object.
   */
  hours(options?: DurationOptions): number;
  /**
   * Returns the number of days of the `Duration` object.
   */
  days(options?: DurationOptions): number;
  /**
   * Returns the ISO string representation of the `Duration` object.
   * Example: "P2DT4H12M30S"
   */
  iso(): string;
  /**
   * Returns a new `Duration` object by adding a duration to the current `Duration` object.
   */
  plus(duration: AbsoluteDuration): Duration;
  /**
   * Returns a new `Duration` object by subtracting a duration from the current `Duration` object.
   */
  minus(duration: AbsoluteDuration): Duration;
  /**
   * Returns a new `Duration` object with the absolute value of the current `Duration` object.
   */
  abs(): Duration;
  /**
   * Returns the ISO string representation of the `Duration` object.
   */
  toString(): string;
  /**
   * Returns the milliseconds of the `Duration` object when coercing to a number
   */
  valueOf(): number;
  private return;
}
//#endregion
//#region src/interval.d.ts
/**
 * An `Interval` represents a time span between two `DateTime` objects.
 */
declare class Interval {
  private start;
  private end;
  private constructor();
  /**
   * Creates a new Interval between two DateTimeLike values
   */
  static between(start: DateTimeLike, end: DateTimeLike): Interval;
  /**
   * Creates a new Interval starting from now and extending for the specified number of days
   */
  static days(days: number): Interval;
  /**
   * Returns the number of milliseconds between the start and end of the interval.
   */
  millis(): number;
  /**
   * Returns the duration between the start and end of the interval.
   */
  duration(): Duration;
  /**
   * Returns the start DateTime of the interval.
   */
  starts(): DateTime;
  /**
   * Returns the end DateTime of the interval.
   */
  ends(): DateTime;
  /**
   * Returns a new Interval with the start and end dates reversed.
   */
  reverse(): Interval;
  /**
   * Returns the ISO string representation of the interval.
   */
  iso(): string;
  toString(): string;
  /**
   * Returns an array of DateTime objects for each day in the interval, going from start to end.
   * The day of the end date is only included if it is not exactly at the start of a day.
   *
   * @example
   * - `2024-01-01T00:00:00.000Z` to `2024-01-02T00:00:00.000Z` will include only `2024-01-01`
   * - `2024-01-01T00:00:00.000Z` to `2024-01-02T23:59:59.999Z` will include both `2024-01-01` and `2024-01-02`
   */
  days(): Array<DateTime>;
  /**
   * Returns an array of DateTime objects for each year in the interval, going from start to end.
   * The year of the end date is only included if it is not exactly at the start of a year.
   *
   * @example
   * - `2024-01-01T00:00:00.000Z` to `2025-01-01T00:00:00.000Z` will include only `2024`
   * - `2024-01-01T00:00:00.000Z` to `2025-01-01T23:59:59.999Z` will include both `2024` and `2025`
   */
  years(): Array<DateTime>;
  /**
   * Returns true if the Interval contains the specified DateTime.
   */
  contains(dateTime: DateTimeLike): boolean;
  /**
   * Returns true if the Interval start date is before the Interval end date.
   */
  isPositive(): boolean;
  /**
   * Returns true if the Interval start date is after the Interval end date.
   */
  isNegative(): boolean;
}
//#endregion
//#region src/datetime.d.ts
type FormatLike = DateTimeFormat | Intl.DateTimeFormat;
/**
 * A `DateTime` represents a point in time.
 */
declare class DateTime {
  private value;
  private constructor();
  /**
   * Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).
   */
  static millis(): number;
  /**
   * Returns a new DateTime object representing the current date and time.
   */
  static now(): DateTime;
  /**
   * Returns a new DateTime object from a DateTimeLike value.
   */
  static from(dateTime: DateTimeLike): DateTime;
  /**
   * Creates an Interval from this DateTime to the specified end DateTime
   */
  until(end: DateTimeLike): Interval;
  /**
   * Formats the DateTime according to the specified format
   */
  format(format: FormatLike): string;
  /**
   * Returns the number of milliseconds of the DateTime object.
   */
  millis(): number;
  /**
   * Returns the ISO string representation of the DateTime object.
   */
  iso(): string;
  /**
   * Returns the number of seconds since the Unix Epoch. The value is floored to the nearest integer.
   */
  timestamp(): number;
  /**
   * Returns the JavaScript Date object representation of the DateTime object.
   */
  date(): Date;
  /**
   * Returns the year for the current DateTime object.
   */
  year(): number;
  /**
   * Returns the day of the year (1-365/366) for the current DateTime object.
   */
  dayOfYear(): number;
  /**
   * Returns the day of the month (1-31) for the current DateTime object.
   */
  dayOfMonth(): number;
  /**
   * Returns the month of the year (1-12) for the current DateTime object.
   */
  month(): number;
  /**
   * Returns the day of the week (1-7, Monday=1, Sunday=7) for the current DateTime object.
   */
  dayOfWeek(): number;
  /**
   * Returns the hour of the day (0-23) for the current DateTime object.
   */
  hour(): number;
  /**
   * Returns the minute of the hour (0-59) for the current DateTime object.
   */
  minute(): number;
  /**
   * Returns the second of the minute (0-59) for the current DateTime object.
   */
  second(): number;
  /**
   * Returns the millisecond of the second (0-999) for the current DateTime object.
   */
  millisecond(): number;
  /**
   * Returns a new DateTime object by adding a duration to the current DateTime object.
   */
  plus(duration: number | (AbsoluteDuration & RelativeDuration) | Duration): DateTime;
  /**
   * Returns a new DateTime object by subtracting a duration from the current DateTime object.
   */
  minus(duration: number | (AbsoluteDuration & RelativeDuration) | Duration): DateTime;
  /**
   * Returns the ISO string representation of the DateTime object.
   */
  toString(): string;
  /**
   * Returns the milliseconds value when coercing to a number
   */
  valueOf(): number;
  /**
   * Returns a new DateTime object set to the start of the second
   */
  startOfSecond(): DateTime;
  /**
   * Returns a new DateTime object set to the start of the minute
   */
  startOfMinute(): DateTime;
  /**
   * Returns a new DateTime object set to the start of the hour
   */
  startOfHour(): DateTime;
  /**
   * Returns a new DateTime object set to the start of the day
   */
  startOfDay(): DateTime;
  /**
   * Returns a new DateTime object set to the start of the month
   */
  startOfMonth(): DateTime;
  /**
   * Returns a new DateTime object set to the start of the year
   */
  startOfYear(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the second
   */
  endOfSecond(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the minute
   */
  endOfMinute(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the hour
   */
  endOfHour(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the day
   */
  endOfDay(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the month
   */
  endOfMonth(): DateTime;
  /**
   * Returns a new DateTime object set to the end of the year
   */
  endOfYear(): DateTime;
  /**
   * Checks if the current DateTime is at the start of the second
   */
  isStartOfSecond(): boolean;
  /**
   * Checks if the current DateTime is at the start of the minute
   */
  isStartOfMinute(): boolean;
  /**
   * Checks if the current DateTime is at the start of the hour
   */
  isStartOfHour(): boolean;
  /**
   * Checks if the current DateTime is at the start of the day
   */
  isStartOfDay(): boolean;
  /**
   * Checks if the current DateTime is at the start of the month
   */
  isStartOfMonth(): boolean;
  /**
   * Checks if the current DateTime is at the start of the year
   */
  isStartOfYear(): boolean;
  /**
   * Checks if the current DateTime is at the end of the second
   */
  isEndOfSecond(): boolean;
  /**
   * Checks if the current DateTime is at the end of the minute
   */
  isEndOfMinute(): boolean;
  /**
   * Checks if the current DateTime is at the end of the hour
   */
  isEndOfHour(): boolean;
  /**
   * Checks if the current DateTime is at the end of the day
   */
  isEndOfDay(): boolean;
  /**
   * Checks if the current DateTime is at the end of the month
   */
  isEndOfMonth(): boolean;
  /**
   * Checks if the current DateTime is at the end of the year
   */
  isEndOfYear(): boolean;
  /**
   * Checks if the current DateTime is in the same second as the given DateTime
   */
  isSameSecond(dateTime: DateTimeLike): boolean;
  /**
   * Checks if the current DateTime is in the same minute as the given DateTime
   */
  isSameMinute(dateTime: DateTimeLike): boolean;
  /**
   * Checks if the current DateTime is in the same hour as the given DateTime
   */
  isSameHour(dateTime: DateTimeLike): boolean;
  /**
   * Checks if the current DateTime is in the same day as the given DateTime
   */
  isSameDay(dateTime: DateTimeLike): boolean;
  /**
   * Checks if the current DateTime is in the same month as the given DateTime
   */
  isSameMonth(dateTime: DateTimeLike): boolean;
  /**
   * Checks if the current DateTime is in the same year as the given DateTime
   */
  isSameYear(dateTime: DateTimeLike): boolean;
  /**
   * Returns true if the current DateTime is before the specified DateTime.
   */
  isBefore(dateTime: DateTimeLike): boolean;
  /**
   * Returns true if the current DateTime is after the specified DateTime.
   */
  isAfter(dateTime: DateTimeLike): boolean;
  /**
   * Returns true if the current DateTime is between the specified DateTime.
   */
  isBetween(start: DateTimeLike, end: DateTimeLike): boolean;
  /**
   * Returns true if the current DateTime is equal to the specified DateTime.
   */
  equals(dateTime: DateTimeLike): boolean;
  /**
   * Returns a comparison value of the current DateTime object to the given DateTime object to be used in sorting.
   * The result is:
   * - negative (< 0) if the current DateTime object is before the given DateTime object (a < b)
   * - positive (> 0) if the current DateTime object is after the given DateTime object (a > b)
   * - zero (0) if the current DateTime object and the given DateTime object are the same (a === b)
   *
   * @example
   * const dates = [
   *   DateTime.from('2024-01-02T00:00:00.000Z'),
   *   DateTime.from('2024-01-01T00:00:00.000Z'),
   * ];
   *
   * dates.sort((a, b) => a.compare(b));
   */
  compare(dateTime: DateTimeLike): number;
  /**
   * Returns a new DateTime object set to the start of the specified unit
   */
  private startOf;
  /**
   * Returns a new DateTime object set to the end of the specified unit
   */
  private endOf;
  /**
   * Checks if the current DateTime is at the start of the specified unit
   */
  private isStartOf;
  /**
   * Checks if the current DateTime is at the end of the specified unit
   */
  private isEndOf;
  /**
   * Checks if the current DateTime is in the same time unit as the given DateTime
   */
  private isSame;
  /**
   * Calculates the absolute duration in milliseconds between the current DateTime and the absolute duration.
   */
  private absoluteDuration;
  /**
   * Calculates the duration in milliseconds between the current DateTime and the relative duration.
   * The minus parameter is used to determine the direction of the duration.
   * If minus is true, the duration is subtracted from the current DateTime.
   * If minus is false, the duration is added to the current DateTime.
   * In other words, are we going back in time or forward in time?
   */
  private relativeDuration;
}
//#endregion
export { AbsoluteDuration, CalendarDate, DateLike, DateTime, DateTimeComponents, DateTimeFormat, DateTimeLike, Duration, DurationComponents, DurationLike, Interval, OrdinalDate, RelativeDuration, TimeComponents };