universal-common
Version:
Library that provides useful missing base class library functionality.
584 lines (583 loc) • 21.4 kB
TypeScript
/**
* Represents a time interval with nanosecond precision.
*
* The TimeSpan class provides a way to represent and manipulate time durations.
* It stores time internally as 100-nanosecond intervals (ticks) using BigInt for full precision.
*
* @example
* // Create a TimeSpan of 1 day, 2 hours, 30 minutes
* const ts1 = new TimeSpan(1, 2, 30, 0);
*
* // Create a TimeSpan from hours
* const ts2 = TimeSpan.fromHours(25.5);
*
* // Add two TimeSpans
* const total = ts1.add(ts2);
*
* // Parse from string
* const ts3 = TimeSpan.parse("1.02:30:00");
*/
export default class TimeSpan {
/** @type {number} Number of nanoseconds in one tick (100ns) */
static NANOSECONDS_PER_TICK: number;
/** @type {number} Number of ticks in one microsecond */
static TICKS_PER_MICROSECOND: number;
/** @type {number} Number of ticks in one millisecond */
static TICKS_PER_MILLISECOND: number;
/** @type {number} Number of ticks in one second */
static TICKS_PER_SECOND: number;
/** @type {number} Number of ticks in one minute */
static TICKS_PER_MINUTE: number;
/** @type {number} Number of ticks in one hour */
static TICKS_PER_HOUR: number;
/** @type {number} Number of ticks in one day */
static TICKS_PER_DAY: number;
/** @type {number} Number of microseconds in one millisecond */
static MICROSECONDS_PER_MILLISECOND: number;
/** @type {number} Number of microseconds in one second */
static MICROSECONDS_PER_SECOND: number;
/** @type {number} Number of microseconds in one minute */
static MICROSECONDS_PER_MINUTE: number;
/** @type {number} Number of microseconds in one hour */
static MICROSECONDS_PER_HOUR: number;
/** @type {number} Number of microseconds in one day */
static MICROSECONDS_PER_DAY: number;
/** @type {number} Number of milliseconds in one second */
static MILLISECONDS_PER_SECOND: number;
/** @type {number} Number of milliseconds in one minute */
static MILLISECONDS_PER_MINUTE: number;
/** @type {number} Number of milliseconds in one hour */
static MILLISECONDS_PER_HOUR: number;
/** @type {number} Number of milliseconds in one day */
static MILLISECONDS_PER_DAY: number;
/** @type {number} Number of seconds in one minute */
static SECONDS_PER_MINUTE: number;
/** @type {number} Number of seconds in one hour */
static SECONDS_PER_HOUR: number;
/** @type {number} Number of seconds in one day */
static SECONDS_PER_DAY: number;
/** @type {number} Number of minutes in one hour */
static MINUTES_PER_HOUR: number;
/** @type {number} Number of minutes in one day */
static MINUTES_PER_DAY: number;
/** @type {number} Number of hours in one day */
static HOURS_PER_DAY: number;
/** @private @type {bigint} Minimum allowed ticks value */
private static "__#2@#MIN_TICKS";
/** @private @type {bigint} Maximum allowed ticks value */
private static "__#2@#MAX_TICKS";
/** @private @type {number} Minimum allowed milliseconds for safe conversion */
private static "__#2@#MIN_MILLISECONDS";
/** @private @type {number} Maximum allowed milliseconds for safe conversion */
private static "__#2@#MAX_MILLISECONDS";
/** @private @type {number} Minimum allowed seconds for safe conversion */
private static "__#2@#MIN_SECONDS";
/** @private @type {number} Maximum allowed seconds for safe conversion */
private static "__#2@#MAX_SECONDS";
/** @private @type {number} Minimum allowed minutes for safe conversion */
private static "__#2@#MIN_MINUTES";
/** @private @type {number} Maximum allowed minutes for safe conversion */
private static "__#2@#MAX_MINUTES";
/** @private @type {number} Minimum allowed hours for safe conversion */
private static "__#2@#MIN_HOURS";
/** @private @type {number} Maximum allowed hours for safe conversion */
private static "__#2@#MAX_HOURS";
/** @private @type {number} Minimum allowed days for safe conversion */
private static "__#2@#MIN_DAYS";
/** @private @type {number} Maximum allowed days for safe conversion */
private static "__#2@#MAX_DAYS";
/**
* Converts time components to ticks.
*
* @private
* @param {number} hour - Hours component
* @param {number} minute - Minutes component
* @param {number} second - Seconds component
* @returns {number} Total ticks
* @throws {RangeError} If resulting value exceeds allowed range
*/
private static "__#2@#timeToTicks";
/**
* Creates a TimeSpan that represents a specified number of days.
*
* @param {number} value - The number of days
* @returns {TimeSpan} A TimeSpan representing the specified days
* @throws {RangeError} If value exceeds allowed range
*
* @example
* const ts = TimeSpan.fromDays(1.5); // 1 day and 12 hours
*/
static fromDays(value: number): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of hours.
*
* @param {number} value - The number of hours
* @returns {TimeSpan} A TimeSpan representing the specified hours
* @throws {RangeError} If value exceeds allowed range
*
* @example
* const ts = TimeSpan.fromHours(2.5); // 2 hours and 30 minutes
*/
static fromHours(value: number, ...args: any[]): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of minutes.
*
* @param {number} value - The number of minutes
* @returns {TimeSpan} A TimeSpan representing the specified minutes
* @throws {RangeError} If value exceeds allowed range
*
* @example
* const ts = TimeSpan.fromMinutes(90); // 1 hour and 30 minutes
*/
static fromMinutes(value: number): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of seconds.
*
* @param {number} value - The number of seconds
* @returns {TimeSpan} A TimeSpan representing the specified seconds
* @throws {RangeError} If value exceeds allowed range
*
* @example
* const ts = TimeSpan.fromSeconds(90); // 1 minute and 30 seconds
*/
static fromSeconds(value: number): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of milliseconds.
*
* @param {number} value - The number of milliseconds
* @returns {TimeSpan} A TimeSpan representing the specified milliseconds
* @throws {RangeError} If value exceeds allowed range
*
* @example
* const ts = TimeSpan.fromMilliseconds(1500); // 1.5 seconds
*/
static fromMilliseconds(value: number): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of microseconds.
*
* @param {number} value - The number of microseconds
* @returns {TimeSpan} A TimeSpan representing the specified microseconds
*
* @example
* const ts = TimeSpan.fromMicroseconds(1500); // 1.5 milliseconds
*/
static fromMicroseconds(value: number): TimeSpan;
/**
* Creates a TimeSpan that represents a specified number of ticks.
*
* @param {number|bigint} value - The number of 100-nanosecond intervals
* @returns {TimeSpan} A TimeSpan representing the specified ticks
*
* @example
* const ts = TimeSpan.fromTicks(10000000); // 1 second
*/
static fromTicks(value: number | bigint): TimeSpan;
/**
* Creates a TimeSpan from a value and scale factor.
*
* @private
* @param {number} value - The value
* @param {number} scale - The scale factor (ticks per unit)
* @returns {TimeSpan} A new TimeSpan
* @throws {ArgumentError} If value is NaN
*/
private static "__#2@#interval";
/**
* Creates a TimeSpan from a floating-point ticks value.
*
* @private
* @param {number} ticks - The ticks as a floating-point number
* @returns {TimeSpan} A new TimeSpan
* @throws {RangeError} If ticks exceed allowed range
*/
private static "__#2@#intervalFromDoubleTicks";
/**
* Gets a TimeSpan that represents a zero time interval.
*
* @type {TimeSpan}
* @readonly
* @static
*
* @example
* const zero = TimeSpan.zero;
* console.log(zero.toString()); // "00:00:00"
*/
static readonly get zero(): TimeSpan;
/**
* Gets the maximum TimeSpan value.
*
* @type {TimeSpan}
* @readonly
* @static
*/
static readonly get maxValue(): TimeSpan;
/**
* Gets the minimum TimeSpan value.
*
* @type {TimeSpan}
* @readonly
* @static
*/
static readonly get minValue(): TimeSpan;
/**
* Compares two TimeSpan values and returns an indication of their relative values.
*
* @param {TimeSpan} t1 - The first TimeSpan
* @param {TimeSpan} t2 - The second TimeSpan
* @returns {number} -1 if t1 is less than t2, 0 if equal, 1 if greater
*
* @example
* const result = TimeSpan.compare(TimeSpan.fromHours(1), TimeSpan.fromHours(2)); // -1
*/
static compare(t1: TimeSpan, t2: TimeSpan): number;
/**
* Returns a value indicating whether two TimeSpan instances are equal.
*
* @param {TimeSpan} t1 - The first TimeSpan
* @param {TimeSpan} t2 - The second TimeSpan
* @returns {boolean} true if the values are equal; otherwise, false
*
* @example
* const equal = TimeSpan.equals(TimeSpan.fromHours(2), TimeSpan.fromMinutes(120)); // true
*/
static equals(t1: TimeSpan, t2: TimeSpan): boolean;
/**
* Parses a TimeSpan from its string representation.
*
* @param {string} s - The string to parse
* @returns {TimeSpan} A TimeSpan parsed from the string
* @throws {TypeError} If input is not a string
* @throws {ArgumentError} If string format is invalid
*
* @example
* const ts1 = TimeSpan.parse("1:30:45"); // 1 hour, 30 minutes, 45 seconds
* const ts2 = TimeSpan.parse("2.12:30:00"); // 2 days, 12 hours, 30 minutes
* const ts3 = TimeSpan.parse("-00:15:30.5"); // Negative 15 minutes, 30.5 seconds
*/
static parse(s: string): TimeSpan;
/**
* Tries to parse a TimeSpan from its string representation.
*
* @param {string} s - The string to parse
* @returns {{success: boolean, value: TimeSpan|null}} An object indicating success and the parsed value
*
* @example
* const result = TimeSpan.tryParse("1:30:45");
* if (result.success) {
* console.log(result.value.toString()); // "01:30:45"
* }
*/
static tryParse(s: string): {
success: boolean;
value: TimeSpan | null;
};
/**
* Creates a new TimeSpan instance.
*
* @constructor
* @param {...(number|bigint)} args - Constructor arguments in one of the following formats:
* - (ticks) - Single value representing 100-nanosecond intervals
* - (hours, minutes, seconds) - Time components
* - (days, hours, minutes, seconds) - Time components with days
* - (days, hours, minutes, seconds, milliseconds) - Time components with milliseconds
* - (days, hours, minutes, seconds, milliseconds, microseconds) - Full precision time components
*
* @throws {ArgumentError} If invalid number of arguments provided
* @throws {RangeError} If resulting TimeSpan exceeds allowed range
*
* @example
* // From ticks
* const ts1 = new TimeSpan(10000000); // 1 second
*
* // From hours, minutes, seconds
* const ts2 = new TimeSpan(1, 30, 45); // 1:30:45
*
* // From days, hours, minutes, seconds
* const ts3 = new TimeSpan(2, 12, 30, 0); // 2.12:30:00
*/
constructor(...args: (number | bigint)[]);
/**
* Gets the value of this TimeSpan expressed in whole and fractional ticks.
*
* @type {number}
* @readonly
* @warning May lose precision if value exceeds Number.MAX_SAFE_INTEGER
*/
readonly get ticks(): number;
/**
* Gets the days component of this TimeSpan.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(2, 12, 30, 0);
* console.log(ts.days); // 2
*/
readonly get days(): number;
/**
* Gets the hours component of this TimeSpan (0-23).
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(2, 12, 30, 0);
* console.log(ts.hours); // 12
*/
readonly get hours(): number;
/**
* Gets the minutes component of this TimeSpan (0-59).
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(2, 12, 30, 0);
* console.log(ts.minutes); // 30
*/
readonly get minutes(): number;
/**
* Gets the seconds component of this TimeSpan (0-59).
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 0, 0, 45);
* console.log(ts.seconds); // 45
*/
readonly get seconds(): number;
/**
* Gets the milliseconds component of this TimeSpan (0-999).
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 0, 0, 0, 500);
* console.log(ts.milliseconds); // 500
*/
readonly get milliseconds(): number;
/**
* Gets the microseconds component of this TimeSpan (0-999).
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 0, 0, 0, 0, 123);
* console.log(ts.microseconds); // 123
*/
readonly get microseconds(): number;
/**
* Gets the nanoseconds component of this TimeSpan (0-900).
* Note: Resolution is limited to 100-nanosecond intervals.
*
* @type {number}
* @readonly
*/
readonly get nanoseconds(): number;
/**
* Gets the total number of days represented by this TimeSpan.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(36, 0, 0, 0); // 36 hours
* console.log(ts.totalDays); // 1.5
*/
readonly get totalDays(): number;
/**
* Gets the total number of hours represented by this TimeSpan.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(1, 12, 0, 0);
* console.log(ts.totalHours); // 36
*/
readonly get totalHours(): number;
/**
* Gets the total number of minutes represented by this TimeSpan.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 1, 30, 0);
* console.log(ts.totalMinutes); // 90
*/
readonly get totalMinutes(): number;
/**
* Gets the total number of seconds represented by this TimeSpan.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 0, 2, 30);
* console.log(ts.totalSeconds); // 150
*/
readonly get totalSeconds(): number;
/**
* Gets the total number of milliseconds represented by this TimeSpan.
* Clamped to safe millisecond range.
*
* @type {number}
* @readonly
* @example
* const ts = new TimeSpan(0, 0, 0, 1, 500);
* console.log(ts.totalMilliseconds); // 1500
*/
readonly get totalMilliseconds(): number;
/**
* Gets the total number of microseconds represented by this TimeSpan.
*
* @type {number}
* @readonly
*/
readonly get totalMicroseconds(): number;
/**
* Gets the total number of nanoseconds represented by this TimeSpan.
*
* @type {number}
* @readonly
*/
readonly get totalNanoseconds(): number;
/**
* Internal getter for BigInt ticks (for internal operations).
*
* @private
* @type {bigint}
* @readonly
*/
private readonly get _ticksBigInt();
/**
* Returns a new TimeSpan that is the sum of this instance and the specified TimeSpan.
*
* @param {TimeSpan} ts - The TimeSpan to add
* @returns {TimeSpan} A new TimeSpan representing the sum
* @throws {TypeError} If argument is not a TimeSpan
* @throws {RangeError} If result exceeds allowed range
*
* @example
* const ts1 = TimeSpan.fromHours(2);
* const ts2 = TimeSpan.fromMinutes(30);
* const sum = ts1.add(ts2); // 2:30:00
*/
add(ts: TimeSpan): TimeSpan;
/**
* Returns a new TimeSpan that is the difference between this instance and the specified TimeSpan.
*
* @param {TimeSpan} ts - The TimeSpan to subtract
* @returns {TimeSpan} A new TimeSpan representing the difference
* @throws {TypeError} If argument is not a TimeSpan
* @throws {RangeError} If result exceeds allowed range
*
* @example
* const ts1 = TimeSpan.fromHours(3);
* const ts2 = TimeSpan.fromHours(1);
* const diff = ts1.subtract(ts2); // 2:00:00
*/
subtract(ts: TimeSpan): TimeSpan;
/**
* Returns a new TimeSpan whose value is the negated value of this instance.
*
* @returns {TimeSpan} A new TimeSpan with negated value
* @throws {RangeError} If this instance equals MinValue
*
* @example
* const ts = TimeSpan.fromHours(2);
* const negated = ts.negate(); // -2:00:00
*/
negate(): TimeSpan;
/**
* Returns a new TimeSpan whose value is the absolute value of this instance.
*
* @returns {TimeSpan} A new TimeSpan with absolute value
* @throws {RangeError} If this instance equals MinValue
*
* @example
* const ts = TimeSpan.fromHours(-2);
* const abs = ts.duration(); // 2:00:00
*/
duration(): TimeSpan;
/**
* Returns a new TimeSpan that is multiplied by the specified factor.
*
* @param {number} factor - The multiplication factor
* @returns {TimeSpan} A new TimeSpan multiplied by factor
* @throws {ArgumentError} If factor is NaN
* @throws {RangeError} If result exceeds allowed range
*
* @example
* const ts = TimeSpan.fromHours(2);
* const doubled = ts.multiply(2); // 4:00:00
*/
multiply(factor: number): TimeSpan;
/**
* Returns a new TimeSpan that is divided by the specified divisor.
*
* @param {number} divisor - The divisor
* @returns {TimeSpan} A new TimeSpan divided by divisor
* @throws {ArgumentError} If divisor is NaN
* @throws {RangeError} If result exceeds allowed range
*
* @example
* const ts = TimeSpan.fromHours(4);
* const halved = ts.divide(2); // 2:00:00
*/
divide(divisor: number): TimeSpan;
/**
* Returns the ratio of this TimeSpan to the specified TimeSpan.
*
* @param {TimeSpan} ts - The divisor TimeSpan
* @returns {number} The ratio of the two TimeSpans
* @throws {TypeError} If argument is not a TimeSpan
*
* @example
* const ts1 = TimeSpan.fromHours(6);
* const ts2 = TimeSpan.fromHours(2);
* const ratio = ts1.divideBy(ts2); // 3
*/
divideBy(ts: TimeSpan): number;
/**
* Determines whether this instance is equal to a specified TimeSpan.
*
* @param {TimeSpan} other - The TimeSpan to compare with
* @returns {boolean} true if the values are equal; otherwise, false
*
* @example
* const ts1 = TimeSpan.fromHours(2);
* const ts2 = TimeSpan.fromMinutes(120);
* console.log(ts1.equals(ts2)); // true
*/
equals(other: TimeSpan): boolean;
/**
* Compares this instance to a specified TimeSpan and returns an indication of their relative values.
*
* @param {TimeSpan} other - The TimeSpan to compare with
* @returns {number} -1 if this instance is less than other, 0 if equal, 1 if greater
* @throws {TypeError} If argument is not a TimeSpan
*
* @example
* const ts1 = TimeSpan.fromHours(1);
* const ts2 = TimeSpan.fromHours(2);
* console.log(ts1.compareTo(ts2)); // -1
*/
compareTo(other: TimeSpan): number;
/**
* Converts the value of this TimeSpan to its string representation.
*
* @param {string} [format="c"] - The format string (currently only "c" is supported)
* @returns {string} String representation of the TimeSpan
* @throws {ArgumentError} If unsupported format is specified
*
* @example
* const ts = new TimeSpan(1, 12, 30, 45, 123);
* console.log(ts.toString()); // "1.12:30:45.123"
*/
toString(format?: string): string;
/**
* Returns the primitive value of this TimeSpan.
* Used by JavaScript when converting to primitive types.
*
* @returns {number} The ticks value as a number
* @warning May lose precision if value exceeds Number.MAX_SAFE_INTEGER
*/
valueOf(): number;
#private;
}