universal-common
Version:
Library that provides useful missing base class library functionality.
407 lines (406 loc) • 15.7 kB
TypeScript
/**
* Represents a point in time, typically expressed as a date and time of day, relative to Coordinated Universal Time (UTC).
*
* DateTimeOffset consists of a DateTime and a TimeSpan offset from UTC. Unlike DateTime, it always represents
* an unambiguous point in time by including timezone offset information.
*
* @example
* // Create DateTimeOffset instances
* const now = DateTimeOffset.now;
* const utcNow = DateTimeOffset.utcNow;
* const specific = new DateTimeOffset(2024, 12, 25, 14, 30, 0, TimeSpan.fromHours(-5));
*
* // Convert between time zones
* const easternTime = utcNow.toOffset(TimeSpan.fromHours(-5));
* const pacificTime = easternTime.toOffset(TimeSpan.fromHours(-8));
*
* // Arithmetic operations preserve offset
* const tomorrow = now.addDays(1);
* const duration = tomorrow.subtract(now);
*/
export default class DateTimeOffset {
static "__#8@#MAX_OFFSET_MINUTES": number;
static "__#8@#MIN_OFFSET_MINUTES": number;
static "__#8@#UNIX_EPOCH_SECONDS": bigint;
static "__#8@#UNIX_EPOCH_MILLISECONDS": bigint;
static "__#8@#UNIX_MIN_SECONDS": number;
static "__#8@#UNIX_MAX_SECONDS": number;
static "__#8@#minValue": any;
static "__#8@#maxValue": any;
static "__#8@#unixEpoch": any;
/**
* Validates and converts TimeSpan offset to minutes.
*
* @private
* @param {TimeSpan} offset - The offset to validate
* @returns {number} Offset in minutes
* @throws {ArgumentError} If offset doesn't represent whole minutes
* @throws {RangeError} If offset is out of valid range
*/
private static "__#8@#validateOffset";
/**
* Validates that the DateTime and offset combination results in a valid UTC time.
*
* @private
* @param {DateTime} dateTime - The DateTime to validate
* @param {TimeSpan} offset - The offset
* @returns {DateTime} DateTime with Unspecified kind storing the UTC time
* @throws {RangeError} If the resulting UTC time is out of range
*/
private static "__#8@#validateDate";
/**
* Gets the current DateTimeOffset in the local time zone.
*
* @type {DateTimeOffset}
* @readonly
* @static
*/
static readonly get now(): DateTimeOffset;
/**
* Gets the current DateTimeOffset in UTC.
*
* @type {DateTimeOffset}
* @readonly
* @static
*/
static readonly get utcNow(): DateTimeOffset;
/**
* Gets the minimum DateTimeOffset value.
*
* @type {DateTimeOffset}
* @readonly
* @static
*/
static readonly get minValue(): DateTimeOffset;
/**
* Gets the maximum DateTimeOffset value.
*
* @type {DateTimeOffset}
* @readonly
* @static
*/
static readonly get maxValue(): DateTimeOffset;
/**
* Gets the Unix epoch as a DateTimeOffset (1970-01-01 00:00:00 +00:00).
*
* @type {DateTimeOffset}
* @readonly
* @static
*/
static readonly get unixEpoch(): DateTimeOffset;
/**
* Creates a DateTimeOffset from Unix time in seconds.
*
* @param {number} seconds - Seconds since Unix epoch
* @returns {DateTimeOffset} A DateTimeOffset representing the specified Unix time
* @throws {RangeError} If seconds is out of valid range
*
* @example
* const dto = DateTimeOffset.fromUnixTimeSeconds(1640458800); // 2021-12-25 17:00:00 UTC
*/
static fromUnixTimeSeconds(seconds: number): DateTimeOffset;
/**
* Creates a DateTimeOffset from Unix time in milliseconds.
*
* @param {number} milliseconds - Milliseconds since Unix epoch
* @returns {DateTimeOffset} A DateTimeOffset representing the specified Unix time
* @throws {RangeError} If milliseconds is out of valid range
*
* @example
* const dto = DateTimeOffset.fromUnixTimeMilliseconds(1640458800000); // 2021-12-25 17:00:00.000 UTC
*/
static fromUnixTimeMilliseconds(milliseconds: number): DateTimeOffset;
/**
* Creates a DateTimeOffset from a JavaScript Date.
*
* @param {Date} date - The JavaScript Date to convert
* @param {TimeSpan} [offset] - Optional offset (defaults to local offset)
* @returns {DateTimeOffset} A DateTimeOffset representing the Date
* @throws {TypeError} If date is not a Date instance
*
* @example
* const jsDate = new Date();
* const dto1 = DateTimeOffset.fromDate(jsDate); // Uses local offset
* const dto2 = DateTimeOffset.fromDate(jsDate, TimeSpan.zero); // UTC
*/
static fromDate(date: Date, offset?: TimeSpan): DateTimeOffset;
/**
* Compares two DateTimeOffset values.
*
* @param {DateTimeOffset} first - The first DateTimeOffset
* @param {DateTimeOffset} second - The second DateTimeOffset
* @returns {number} -1 if first < second, 0 if equal, 1 if first > second
*/
static compare(first: DateTimeOffset, second: DateTimeOffset): number;
/**
* Determines whether two DateTimeOffset values are equal.
*
* @param {DateTimeOffset} first - The first DateTimeOffset
* @param {DateTimeOffset} second - The second DateTimeOffset
* @returns {boolean} true if equal; otherwise, false
*/
static equals(first: DateTimeOffset, second: DateTimeOffset): boolean;
/**
* Parses a DateTimeOffset from its string representation.
*
* @param {string} input - The string to parse
* @returns {DateTimeOffset} A DateTimeOffset parsed from the string
* @throws {TypeError} If input is not a string
* @throws {ArgumentError} If string format is invalid
*
* @example
* const dto1 = DateTimeOffset.parse("2024-12-25T14:30:00-05:00");
* const dto2 = DateTimeOffset.parse("2024-12-25 14:30:00 -05:00");
*/
static parse(input: string): DateTimeOffset;
/**
* Attempts to parse a DateTimeOffset from its string representation.
*
* @param {string} input - The string to parse
* @returns {{success: boolean, value: DateTimeOffset|null}} Parse result
*
* @example
* const result = DateTimeOffset.tryParse("2024-12-25T14:30:00-05:00");
* if (result.success) {
* console.log(result.value.toString());
* }
*/
static tryParse(input: string): {
success: boolean;
value: DateTimeOffset | null;
};
/**
* Creates a new DateTimeOffset instance.
*
* @constructor
* @param {...*} args - Constructor arguments in various formats:
* - (ticks, offset) - Ticks since 1/1/0001 and TimeSpan offset
* - (dateTime) - DateTime instance (extracts local offset if Local/Unspecified, uses zero offset if UTC)
* - (dateTime, offset) - DateTime and TimeSpan offset
* - (date, time, offset) - DateOnly, TimeOnly, and TimeSpan offset
* - (year, month, day, hour, minute, second, offset) - Date/time components and offset
* - (year, month, day, hour, minute, second, millisecond, offset) - With milliseconds
* - (year, month, day, hour, minute, second, millisecond, microsecond, offset) - With microseconds
*
* @throws {ArgumentError} If invalid arguments provided
* @throws {RangeError} If date/time values or offset are out of range
*
* @example
* // From DateTime (uses local offset for Local/Unspecified, zero for UTC)
* const dto1 = new DateTimeOffset(DateTime.now);
*
* // From DateTime with explicit offset
* const dto2 = new DateTimeOffset(new DateTime(2024, 12, 25, 14, 30, 0), TimeSpan.fromHours(-5));
*
* // From date/time components with offset
* const dto3 = new DateTimeOffset(2024, 12, 25, 14, 30, 0, TimeSpan.fromHours(-8));
*/
constructor(...args: any[]);
/**
* Gets the DateTime component of this DateTimeOffset (the local/clock time).
*
* @type {DateTime}
* @readonly
*/
readonly get dateTime(): DateTime;
/**
* Gets the clock time (local time accounting for offset).
*
* @private
* @type {DateTime}
* @readonly
*/
private readonly get clockDateTime();
/**
* Gets the UTC DateTime represented by this DateTimeOffset.
*
* @type {DateTime}
* @readonly
*/
readonly get utcDateTime(): DateTime;
/**
* Gets the local DateTime equivalent of this DateTimeOffset.
*
* @type {DateTime}
* @readonly
*/
readonly get localDateTime(): DateTime;
/**
* Gets the time zone offset from UTC.
*
* @type {TimeSpan}
* @readonly
*/
readonly get offset(): TimeSpan;
/**
* Gets the total offset in minutes from UTC.
*
* @type {number}
* @readonly
*/
readonly get totalOffsetMinutes(): number;
/**
* Gets the number of ticks for the clock time.
*
* @type {bigint}
* @readonly
*/
readonly get ticks(): bigint;
/**
* Gets the number of ticks for the UTC time.
*
* @type {bigint}
* @readonly
*/
readonly get utcTicks(): bigint;
get year(): number;
get month(): number;
get day(): number;
get hour(): number;
get minute(): number;
get second(): number;
get millisecond(): number;
get microsecond(): number;
get nanosecond(): number;
get dayOfWeek(): number;
get dayOfYear(): number;
get date(): DateTime;
get timeOfDay(): TimeSpan;
/**
* Adjusts this DateTimeOffset to a different time zone offset.
*
* @param {TimeSpan} offset - The new offset from UTC
* @returns {DateTimeOffset} A new DateTimeOffset with the same UTC time but different offset
* @throws {ArgumentError} If offset is invalid
* @throws {RangeError} If offset is out of range
*
* @example
* const utc = DateTimeOffset.utcNow;
* const eastern = utc.toOffset(TimeSpan.fromHours(-5)); // UTC-5
* const pacific = utc.toOffset(TimeSpan.fromHours(-8)); // UTC-8
*/
toOffset(offset: TimeSpan): DateTimeOffset;
/**
* Adds a TimeSpan to this DateTimeOffset.
*
* @param {TimeSpan} timeSpan - The time interval to add
* @returns {DateTimeOffset} A new DateTimeOffset with the added time
* @throws {TypeError} If timeSpan is not a TimeSpan
* @throws {RangeError} If result is out of range
*
* @example
* const dto = DateTimeOffset.now;
* const later = dto.add(TimeSpan.fromHours(2));
*/
add(timeSpan: TimeSpan): DateTimeOffset;
addDays(days: any): DateTimeOffset;
addHours(hours: any): DateTimeOffset;
addMinutes(minutes: any): DateTimeOffset;
addSeconds(seconds: any): DateTimeOffset;
addMilliseconds(milliseconds: any): DateTimeOffset;
addMicroseconds(microseconds: any): DateTimeOffset;
addMonths(months: any): DateTimeOffset;
addYears(years: any): DateTimeOffset;
addTicks(ticks: any): DateTimeOffset;
/**
* Subtracts another DateTimeOffset or TimeSpan from this DateTimeOffset.
*
* @param {DateTimeOffset|TimeSpan} value - The value to subtract
* @returns {TimeSpan|DateTimeOffset} TimeSpan if subtracting DateTimeOffset, DateTimeOffset if subtracting TimeSpan
* @throws {TypeError} If value is not a DateTimeOffset or TimeSpan
*
* @example
* const dto1 = new DateTimeOffset(2024, 12, 25, 12, 0, 0, TimeSpan.fromHours(-5));
* const dto2 = new DateTimeOffset(2024, 12, 25, 10, 0, 0, TimeSpan.fromHours(-8));
* const difference = dto1.subtract(dto2); // TimeSpan representing the difference
*/
subtract(value: DateTimeOffset | TimeSpan): TimeSpan | DateTimeOffset;
/**
* Compares this DateTimeOffset with another DateTimeOffset.
* Comparison is based on UTC time.
*
* @param {DateTimeOffset} other - The DateTimeOffset to compare with
* @returns {number} -1 if this is earlier, 0 if equal, 1 if later
* @throws {TypeError} If other is not a DateTimeOffset
*
* @example
* const dto1 = new DateTimeOffset(2024, 12, 25, 12, 0, 0, TimeSpan.fromHours(-5));
* const dto2 = new DateTimeOffset(2024, 12, 25, 10, 0, 0, TimeSpan.fromHours(-8));
* console.log(dto1.compareTo(dto2)); // -1 (dto1 is 3 hours earlier in UTC)
*/
compareTo(other: DateTimeOffset): number;
/**
* Determines whether this DateTimeOffset is equal to another DateTimeOffset.
* Equality is based on UTC time only.
*
* @param {DateTimeOffset} other - The DateTimeOffset to compare with
* @returns {boolean} true if they represent the same UTC instant; otherwise, false
*
* @example
* const dto1 = new DateTimeOffset(2024, 12, 25, 17, 0, 0, TimeSpan.zero); // 17:00 UTC
* const dto2 = new DateTimeOffset(2024, 12, 25, 12, 0, 0, TimeSpan.fromHours(-5)); // 12:00 UTC-5 (17:00 UTC)
* console.log(dto1.equals(dto2)); // true (same UTC time)
*/
equals(other: DateTimeOffset): boolean;
/**
* Determines whether this DateTimeOffset is exactly equal to another (including offset).
*
* @param {DateTimeOffset} other - The DateTimeOffset to compare with
* @returns {boolean} true if both UTC time and offset are equal; otherwise, false
*
* @example
* const dto1 = new DateTimeOffset(2024, 12, 25, 17, 0, 0, TimeSpan.zero);
* const dto2 = new DateTimeOffset(2024, 12, 25, 12, 0, 0, TimeSpan.fromHours(-5));
* console.log(dto1.equalsExact(dto2)); // false (same UTC time but different offsets)
*/
equalsExact(other: DateTimeOffset): boolean;
/**
* Converts this DateTimeOffset to a JavaScript Date object.
*
* @returns {Date} A JavaScript Date representing the same instant
*/
toDate(): Date;
/**
* Converts this DateTimeOffset to local time.
*
* @returns {DateTimeOffset} A DateTimeOffset adjusted to the local time zone
*/
toLocalTime(): DateTimeOffset;
/**
* Converts this DateTimeOffset to UTC.
*
* @returns {DateTimeOffset} A DateTimeOffset with zero offset (UTC)
*/
toUniversalTime(): DateTimeOffset;
/**
* Gets the Unix timestamp in seconds.
*
* @type {number}
* @readonly
*/
readonly toUnixTimeSeconds(): number;
/**
* Gets the Unix timestamp in milliseconds.
*
* @type {number}
* @readonly
*/
readonly toUnixTimeMilliseconds(): number;
/**
* Converts the DateTimeOffset to its string representation.
*
* @param {string} [format] - A standard or custom date and time format string
* @returns {string} A string representation of the DateTimeOffset
*
* @example
* const dto = new DateTimeOffset(2024, 12, 25, 14, 30, 45, 123, TimeSpan.fromHours(-5));
* console.log(dto.toString()); // Default format with offset
* console.log(dto.toString('d')); // Short date format
* console.log(dto.toString('D')); // Long date format
* console.log(dto.toString('yyyy-MM-dd HH:mm:ss zzz')); // Custom format with offset
*/
toString(format?: string, ...args: any[]): string;
#private;
}
import DateTime from "./DateTime.js";
import TimeSpan from "./TimeSpan.js";