universal-common
Version:
Library that provides useful missing base class library functionality.
398 lines (397 loc) • 13.3 kB
TypeScript
/**
* Represents an instant in time, typically expressed as a date and time of day.
*
* DateTime values are stored internally as 100-nanosecond intervals (ticks) since
* January 1, 0001 12:00:00 midnight, with additional flags for DateTimeKind.
*
* @example
* // Create DateTime instances
* const now = DateTime.now;
* const specificDate = new DateTime(2024, 12, 25, 10, 30, 0);
* const fromTicks = new DateTime(638000000000000000n);
*
* // Arithmetic operations
* const tomorrow = now.addDays(1);
* const duration = tomorrow.subtract(now);
*/
export default class DateTime {
static "__#5@#DAYS_PER_YEAR": number;
static "__#5@#DAYS_PER_4_YEARS": number;
static "__#5@#DAYS_PER_100_YEARS": number;
static "__#5@#DAYS_PER_400_YEARS": number;
static "__#5@#DAYS_TO_1601": number;
static "__#5@#DAYS_TO_1970": number;
static "__#5@#DAYS_TO_10000": number;
static "__#5@#MIN_TICKS": bigint;
static "__#5@#MAX_TICKS": bigint;
static "__#5@#TICKS_MASK": bigint;
static "__#5@#FLAGS_MASK": bigint;
static "__#5@#KIND_SHIFT": bigint;
static "__#5@#KIND_UNSPECIFIED": bigint;
static "__#5@#KIND_UTC": bigint;
static "__#5@#KIND_LOCAL": bigint;
static "__#5@#KIND_LOCAL_AMBIGUOUS_DST": bigint;
static "__#5@#DAYS_TO_MONTH_365": number[];
static "__#5@#DAYS_TO_MONTH_366": number[];
static "__#5@#minValue": any;
static "__#5@#maxValue": any;
static "__#5@#unixEpoch": any;
/**
* Converts date components to ticks.
*
* @private
* @param {number} year - Year (1-9999)
* @param {number} month - Month (1-12)
* @param {number} day - Day (1-31)
* @returns {bigint} Ticks representing the date
* @throws {RangeError} If date components are invalid
*/
private static "__#5@#dateToTicks";
/**
* Converts time components to ticks.
*
* @private
* @param {number} hour - Hour (0-23)
* @param {number} minute - Minute (0-59)
* @param {number} second - Second (0-59)
* @returns {bigint} Ticks representing the time
* @throws {RangeError} If time components are invalid
*/
private static "__#5@#timeToTicks";
/**
* Calculates the number of days from 1/1/0001 to the beginning of the specified year.
*
* @private
* @param {number} year - The year
* @returns {number} Number of days
*/
private static "__#5@#daysToYear";
/**
* Determines if the specified year is a leap year.
*
* @param {number} year - The year to check
* @returns {boolean} true if the year is a leap year; otherwise, false
* @throws {RangeError} If year is out of range
*/
static isLeapYear(year: number): boolean;
/**
* Returns the number of days in the specified month and year.
*
* @param {number} year - The year
* @param {number} month - The month (1-12)
* @returns {number} The number of days in the month
* @throws {RangeError} If year or month is out of range
*/
static daysInMonth(year: number, month: number): number;
/**
* Creates a DateTime from a JavaScript Date instance.
*
* @param {Date} jsDate - The JavaScript Date to convert
* @param {number} [kind=DateTimeKind.UNSPECIFIED] - The DateTimeKind for the result
* @param {boolean} [useUtc=false] - Whether to use UTC components from the Date
* @returns {DateTime} A new DateTime representing the same instant
* @throws {TypeError} If jsDate is not a Date instance
* @throws {ArgumentError} If kind is invalid
*/
static fromDate(jsDate: Date, kind?: number, useUtc?: boolean): DateTime;
/**
* Gets a DateTime representing the current date and time.
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get now(): DateTime;
/**
* Gets a DateTime representing the current UTC date and time.
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get utcNow(): DateTime;
/**
* Gets a DateTime representing the current date with time set to midnight.
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get today(): DateTime;
/**
* Gets the minimum DateTime value.
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get minValue(): DateTime;
/**
* Gets the maximum DateTime value.
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get maxValue(): DateTime;
/**
* Gets the Unix epoch (1970-01-01 00:00:00 UTC).
*
* @type {DateTime}
* @readonly
* @static
*/
static readonly get unixEpoch(): DateTime;
/**
* Compares two DateTime values.
*
* @param {DateTime} t1 - The first DateTime
* @param {DateTime} t2 - The second DateTime
* @returns {number} -1 if t1 < t2, 0 if equal, 1 if t1 > t2
*/
static compare(t1: DateTime, t2: DateTime): number;
/**
* Determines whether two DateTime values are equal.
*
* @param {DateTime} t1 - The first DateTime
* @param {DateTime} t2 - The second DateTime
* @returns {boolean} true if equal; otherwise, false
*/
static equals(t1: DateTime, t2: DateTime): boolean;
/**
* Creates a new DateTime instance.
*
* @constructor
* @param {...(number|bigint)} args - Constructor arguments in various formats:
* - (ticks) - 100-nanosecond intervals since 1/1/0001
* - (ticks, kind) - Ticks with DateTimeKind
* - (year, month, day) - Date components
* - (year, month, day, hour, minute, second) - Date and time components
* - (year, month, day, hour, minute, second, millisecond) - With milliseconds
* - (year, month, day, hour, minute, second, millisecond, kind) - With kind
*
* @throws {ArgumentError} If invalid arguments provided
* @throws {RangeError} If date/time values are out of range
*/
constructor(...args: (number | bigint)[]);
/**
* Gets the ticks value of this DateTime (without kind flags).
*
* @type {bigint}
* @readonly
*/
readonly get ticks(): bigint;
/**
* Gets the DateTimeKind of this DateTime.
*
* @type {number}
* @readonly
*/
readonly get kind(): number;
/**
* Gets the year component of this DateTime.
*
* @type {number}
* @readonly
*/
readonly get year(): number;
/**
* Gets the month component of this DateTime (1-12).
*
* @type {number}
* @readonly
*/
readonly get month(): number;
/**
* Gets the day component of this DateTime (1-31).
*
* @type {number}
* @readonly
*/
readonly get day(): number;
/**
* Gets the hour component of this DateTime (0-23).
*
* @type {number}
* @readonly
*/
readonly get hour(): number;
/**
* Gets the minute component of this DateTime (0-59).
*
* @type {number}
* @readonly
*/
readonly get minute(): number;
/**
* Gets the second component of this DateTime (0-59).
*
* @type {number}
* @readonly
*/
readonly get second(): number;
/**
* Gets the millisecond component of this DateTime (0-999).
*
* @type {number}
* @readonly
*/
readonly get millisecond(): number;
/**
* Gets the microsecond component of this DateTime (0-999).
*
* @type {number}
* @readonly
*/
readonly get microsecond(): number;
/**
* Gets the nanosecond component of this DateTime (0-900).
*
* @type {number}
* @readonly
*/
readonly get nanosecond(): number;
/**
* Gets the day of the week for this DateTime.
*
* @type {number}
* @readonly
*/
readonly get dayOfWeek(): number;
/**
* Gets the day of the year for this DateTime (1-366).
*
* @type {number}
* @readonly
*/
readonly get dayOfYear(): number;
/**
* Gets the date part of this DateTime.
*
* @type {DateTime}
* @readonly
*/
readonly get date(): DateTime;
/**
* Gets the time of day for this DateTime.
*
* @type {TimeSpan}
* @readonly
*/
readonly get timeOfDay(): TimeSpan;
/**
* Adds the specified TimeSpan to this DateTime.
*
* @param {TimeSpan} value - The TimeSpan to add
* @returns {DateTime} A new DateTime with the added time
* @throws {TypeError} If value is not a TimeSpan
* @throws {RangeError} If result is out of range
*/
add(value: TimeSpan): DateTime;
/**
* Adds the specified number of ticks to this DateTime.
*
* @param {number} value - The number of ticks to add
* @returns {DateTime} A new DateTime with the added ticks
* @throws {RangeError} If result is out of range
*/
addTicks(value: number): DateTime;
/**
* Adds the specified number of days to this DateTime.
*
* @param {number} value - The number of days to add
* @returns {DateTime} A new DateTime with the added days
*/
addDays(value: number): DateTime;
/**
* Adds the specified number of hours to this DateTime.
*
* @param {number} value - The number of hours to add
* @returns {DateTime} A new DateTime with the added hours
*/
addHours(value: number): DateTime;
/**
* Adds the specified number of minutes to this DateTime.
*
* @param {number} value - The number of minutes to add
* @returns {DateTime} A new DateTime with the added minutes
*/
addMinutes(value: number): DateTime;
/**
* Adds the specified number of seconds to this DateTime.
*
* @param {number} value - The number of seconds to add
* @returns {DateTime} A new DateTime with the added seconds
*/
addSeconds(value: number): DateTime;
/**
* Adds the specified number of milliseconds to this DateTime.
*
* @param {number} value - The number of milliseconds to add
* @returns {DateTime} A new DateTime with the added milliseconds
*/
addMilliseconds(value: number): DateTime;
/**
* Adds the specified number of months to this DateTime.
*
* @param {number} months - The number of months to add
* @returns {DateTime} A new DateTime with the added months
* @throws {RangeError} If months is out of range or result is invalid
*/
addMonths(months: number): DateTime;
/**
* Adds the specified number of years to this DateTime.
*
* @param {number} years - The number of years to add
* @returns {DateTime} A new DateTime with the added years
* @throws {RangeError} If years is out of range or result is invalid
*/
addYears(years: number): DateTime;
/**
* Subtracts the specified DateTime from this DateTime.
*
* @param {DateTime} value - The DateTime to subtract
* @returns {TimeSpan} A TimeSpan representing the difference
* @throws {TypeError} If value is not a DateTime
*/
subtract(value: DateTime): TimeSpan;
/**
* Compares this DateTime to another DateTime.
*
* @param {DateTime} other - The DateTime to compare to
* @returns {number} -1 if this is less than other, 0 if equal, 1 if greater
* @throws {TypeError} If other is not a DateTime
*/
compareTo(other: DateTime): number;
/**
* Determines whether this DateTime is equal to another DateTime.
*
* @param {DateTime} other - The DateTime to compare to
* @returns {boolean} true if equal; otherwise, false
*/
equals(other: DateTime): boolean;
/**
* Converts this DateTime to a JavaScript Date object.
* For UTC DateTimes, creates a Date representing the same UTC instant.
* For Local/Unspecified DateTimes, creates a Date treating the components as local time.
*
* @returns {Date} A JavaScript Date representing the same instant
*/
toDate(): Date;
/**
* Converts the value of the current DateTime object to its equivalent string representation.
*
* @param {string} [format] - A standard or custom date and time format string
* @returns {string} A string representation of the DateTime
*
* @example
* const dt = new DateTime(2024, 12, 25, 14, 30, 45, 123);
* console.log(dt.toString()); // Default format
* console.log(dt.toString('d')); // "12/25/2024" (short date)
* console.log(dt.toString('D')); // "Wednesday, December 25, 2024" (long date)
* console.log(dt.toString('yyyy-MM-dd')); // "2024-12-25" (custom format)
*/
toString(format?: string, ...args: any[]): string;
#private;
}
import TimeSpan from "./TimeSpan.js";