@zelgadis87/utils-core 4.0.0

package/src/time/TimeInstant.ts

@@ -0,0 +1,488 @@
+import Deferred, { ICancelablePromise } from "../async/Deferred.js";
+import { TComparisonResult } from "../sorting/index.js";
+import { TTimeoutHandle, TVoidFunction } from "../types";
+import { pad } from "../utils";
+import TimeBase from "./TimeBase";
+import TimeDuration from "./TimeDuration";
+import { TTimeInstantBuilder, TTimeInstantCreationParameters, createTimeInstantFromParameters, timeInstantBuilder } from "./TimeInstantBuilder.js";
+import TimeUnit from "./TimeUnit";
+import { TDayOfMonth, TDayOfWeek, TFourDigitsMillisecond, TFourDigitsYear, TIso8601DateString, TIso8601DateUtcString, TMonth, TThreeDigitsMillisecond, TTwoDigitsDate, TTwoDigitsHour, TTwoDigitsMinute, TTwoDigitsMonth, TTwoDigitsSecond, TWeekNumber } from "./types";
+
+export class TimeInstant extends TimeBase<TimeInstant> {
+
+	protected constructor( number: number, unit: TimeUnit ) {
+		super( number, unit );
+	}
+
+	protected create( value: number, unit: TimeUnit ) {
+		return new TimeInstant( value, unit );
+	}
+
+	public addDuration( duration: TimeDuration ): TimeInstant {
+		return TimeInstant.fromUnixTimestamp( this.ms + duration.ms );
+	}
+
+	public removeDuration( duration: TimeDuration ): TimeInstant {
+		return TimeInstant.fromUnixTimestamp( this.ms - duration.ms );
+	}
+
+	public distanceFrom( instant: TimeInstant ): TimeDuration {
+		return TimeDuration.fromMs( Math.abs( this.ms - instant.ms ) );
+	}
+
+	public distanceFromNow(): TimeDuration {
+		return TimeDuration.fromMs( Math.abs( this.ms - Date.now() ) );
+	}
+
+	public distanceFromStartOfDay(): TimeDuration {
+		return this.distanceFrom( this.atStartOfDay() );
+	}
+
+	public atStartOfDay(): TimeInstant {
+		return this.atTime( { hours: 0, minutes: 0, seconds: 0, milliseconds: 0 } );
+	}
+
+	public distanceFromEndOfDay(): TimeDuration {
+		return this.distanceFrom( this.atEndOfDay() );
+	}
+
+	public atEndOfDay(): TimeInstant {
+		return this.atTime( { hours: 23, minutes: 59, seconds: 59, milliseconds: 999 } );
+	}
+
+	/** @deprecated[2024-10-24]: Use #promise() instead. */
+	public timeout( cb: () => unknown ): TTimeoutHandle {
+		if ( !this.isInTheFuture ) {
+			throw new Error( 'Instant is in the past' );
+		} else {
+			return this.distanceFromNow().timeout( () => cb() );
+		}
+	}
+
+	public promise(): ICancelablePromise<void> {
+		const deferred = new Deferred<void>;
+		if ( !this.isInTheFuture ) {
+			deferred.resolve();
+		} else {
+			this.distanceFromNow().timeout( () => deferred.resolve() );
+		}
+		return deferred.asCancelablePromise;
+	}
+
+	public delay( cb: () => unknown ): { cancel: TVoidFunction } {
+		const deferred = this.promise();
+		void deferred.then( () => {
+			cb();
+		}, _err => {
+			return; // Do nothing on cancelation ( err is always an instance of DeferredCanceledError )
+		} );
+		return { cancel: () => deferred.cancel() };
+	}
+
+	public isToday(): boolean {
+		return Math.floor( this.days ) === Math.floor( TimeInstant.now().days );
+	}
+
+	public asTimeString(): string {
+		const date = this.asDate();
+		return `${this.doGetTwoDigitsHours( date )}:${this.doGetTwoDigitsMinutes( date )}:${this.doGetTwoDigitsSeconds( date )}`;
+	}
+
+	public asDateString(): string {
+		const date = this.asDate();
+		return `${this.doGetTwoDigitsDays( date )}/${this.doGetTwoDigitsMonths( date )}/${this.doGetFourDigitsYears( date )}`;
+	}
+
+	public asIso8601(): TIso8601DateString {
+		const dash = '-', colon = '.', doublecolon = ':', T = 'T', date = this.asDate();
+		return (
+			this.doGetFourDigitsYears( date )
+			+ dash
+			+ this.doGetTwoDigitsMonths( date )
+			+ dash
+			+ this.doGetTwoDigitsDays( date )
+			+ T
+			+ this.doGetTwoDigitsHours( date )
+			+ doublecolon
+			+ this.doGetTwoDigitsMinutes( date )
+			+ doublecolon
+			+ this.doGetTwoDigitsSeconds( date )
+			+ colon
+			+ this.doGetThreeDigitsMilliseconds( date )
+			+ this.doGetFourDigitsTimezoneOffset( date )
+		) as TIso8601DateString;
+	}
+
+	public asIso8601UTC(): TIso8601DateUtcString {
+		const dash = '-', colon = '.', doublecolon = ':', T = 'T', utcDate = this.asDateUTC();
+		return (
+			this.doGetFourDigitsYears( utcDate )
+			+ dash
+			+ this.doGetTwoDigitsMonths( utcDate )
+			+ dash
+			+ this.doGetTwoDigitsDays( utcDate )
+			+ T
+			+ this.doGetTwoDigitsHours( utcDate )
+			+ doublecolon
+			+ this.doGetTwoDigitsMinutes( utcDate )
+			+ doublecolon
+			+ this.doGetTwoDigitsSeconds( utcDate )
+			+ colon
+			+ this.doGetThreeDigitsMilliseconds( utcDate )
+			+ 'Z'
+		) as TIso8601DateUtcString;
+	}
+
+	public asHumanTimestamp(): string {
+		const dash = '-', colon = '.', doublecolon = ':', T = 'T', date = this.asDate();
+		return (
+			this.doGetFourDigitsYears( date )
+			+ dash
+			+ this.doGetTwoDigitsMonths( date )
+			+ dash
+			+ this.doGetTwoDigitsDays( date )
+			+ T
+			+ this.doGetTwoDigitsHours( date )
+			+ doublecolon
+			+ this.doGetTwoDigitsMinutes( date )
+			+ doublecolon
+			+ this.doGetTwoDigitsSeconds( date )
+			+ colon
+			+ this.doGetThreeDigitsMilliseconds( date )
+		);
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsDays(): TTwoDigitsDate {
+		return this.doGetTwoDigitsDays( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsMonths(): TTwoDigitsMonth {
+		return this.doGetTwoDigitsMonths( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get fourDigitsYears(): TFourDigitsYear {
+		return this.doGetFourDigitsYears( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsHours(): TTwoDigitsHour {
+		return this.doGetTwoDigitsHours( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsMinutes(): TTwoDigitsMinute {
+		return this.doGetTwoDigitsMinutes( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsSeconds(): TTwoDigitsMinute {
+		return this.doGetTwoDigitsSeconds( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get threeDigitsMilliseconds(): TThreeDigitsMillisecond {
+		return this.doGetThreeDigitsMilliseconds( this.asDate() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsDaysUTC(): TTwoDigitsDate {
+		return this.doGetTwoDigitsDays( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsMonthsUTC(): TTwoDigitsMonth {
+		return this.doGetTwoDigitsMonths( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get fourDigitsYearsUTC(): TFourDigitsYear {
+		return this.doGetFourDigitsYears( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsHoursUTC(): TTwoDigitsHour {
+		return this.doGetTwoDigitsHours( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsMinutesUTC(): TTwoDigitsMinute {
+		return this.doGetTwoDigitsMinutes( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get twoDigitsSecondsUTC(): TTwoDigitsSecond {
+		return this.doGetTwoDigitsSeconds( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get threeDigitsMillisecondsUTC(): TThreeDigitsMillisecond {
+		return this.doGetThreeDigitsMilliseconds( this.asDateUTC() );
+	}
+
+	// Please do not use this method internally, as it is not optimized for continued usage.
+	public get fourDigitsTimezoneOffset(): TFourDigitsMillisecond {
+		const offset = this.asDate().getTimezoneOffset();
+		return ( ( offset >= 0 ? '+' : '-' )
+			+ pad( Math.floor( Math.abs( offset ) / 60 ).toString(), 2, '0' )
+			+ pad( ( Math.abs( offset ) % 60 ).toString(), 2, '0' )
+		) as TFourDigitsMillisecond;
+	}
+
+	protected doGetTwoDigitsDays( date: Date ): TTwoDigitsDate {
+		return pad( date.getDate().toString(), 2, '0' ) as TTwoDigitsDate;
+	}
+
+	protected doGetTwoDigitsMonths( date: Date ): TTwoDigitsMonth {
+		return pad( ( date.getMonth() + 1 ).toString(), 2, '0' ) as TTwoDigitsMonth;
+	}
+
+	protected doGetFourDigitsYears( date: Date ): TFourDigitsYear {
+		return pad( date.getFullYear().toString(), 4, '0' ) as TFourDigitsYear;
+	}
+
+	protected doGetTwoDigitsHours( date: Date ): TTwoDigitsHour {
+		return pad( date.getHours().toString(), 2, '0' ) as TTwoDigitsHour;
+	}
+
+	protected doGetTwoDigitsMinutes( date: Date ): TTwoDigitsMinute {
+		return pad( date.getMinutes().toString(), 2, '0' ) as TTwoDigitsMinute;
+	}
+
+	protected doGetTwoDigitsSeconds( date: Date ): TTwoDigitsMinute {
+		return pad( date.getSeconds().toString(), 2, '0' ) as TTwoDigitsMinute;
+	}
+
+	protected doGetThreeDigitsMilliseconds( date: Date ): TThreeDigitsMillisecond {
+		return pad( date.getMilliseconds().toString(), 3, '0' ) as TThreeDigitsMillisecond;
+	}
+
+	protected doGetFourDigitsTimezoneOffset( date: Date ): TFourDigitsMillisecond {
+		const offset = date.getTimezoneOffset();
+		return ( ( offset >= 0 ? '+' : '-' )
+			+ pad( Math.floor( Math.abs( offset ) / 60 ).toString(), 2, '0' )
+			+ pad( ( Math.abs( offset ) % 60 ).toString(), 2, '0' )
+		) as TFourDigitsMillisecond;
+	}
+
+	public asUnixTimestamp(): number {
+		// Syntatic sugar for this.ms;
+		return this.ms;
+	}
+
+	public asDate(): Date {
+		return new Date( this.ms );
+	}
+
+	public asDateUTC(): Date {
+		return new Date( this.ms + new Date().getTimezoneOffset() * 60 * 1000 );
+	}
+
+	public get isInThePast(): boolean {
+		return this.ms < Date.now();
+	}
+
+	public get isInTheFuture(): boolean {
+		return this.ms > Date.now();
+	}
+
+	public isAfter( other: TimeInstant ): boolean {
+		return this.ms > other.ms;
+	}
+
+	public isBefore( other: TimeInstant ): boolean {
+		return this.ms < other.ms;
+	}
+
+	public compareTo( other: TimeInstant ): TComparisonResult {
+		if ( this.ms === other.ms ) {
+			return 0;
+		} else if ( this.isBefore( other ) ) {
+			return -1;
+		} else {
+			return 1;
+		}
+	}
+
+	/**
+		* @deprecated[04/07/2023]: Use distanceFromNow instead
+		*/
+	public fromNow(): TimeDuration {
+		return TimeDuration.ms( this.ms - Date.now() );
+	}
+
+	/**
+		* @deprecated[04/07/2023]: Use distanceFrom instead
+		*/
+	public from( instant: TimeInstant ): TimeDuration {
+		return TimeDuration.ms( this.ms - instant.ms );
+	}
+
+	/**
+		* @deprecated[04/07/2023]: Use distanceFromUnixTimestamp instead
+		*/
+	public fromTimestamp( timestamp: number ): TimeDuration {
+		return TimeDuration.ms( this.ms - timestamp );
+	}
+
+	public distanceFromUnixTimestamp( timestamp: number ): TimeDuration {
+		return TimeDuration.ms( this.ms - timestamp );
+	}
+
+	public atTime( parameters: Partial<TTimeInstantCreationParameters & { year: never; month: never; date: never; }> ) {
+		return TimeInstant.fromParameters( parameters, this );
+	}
+
+	public atDate( parameters: Partial<TTimeInstantCreationParameters & { hours: never; minutes: never; seconds: never; milliseconds: never; }> ) {
+		return TimeInstant.fromParameters( parameters, this );
+	}
+
+	public at( parameters: Partial<TTimeInstantCreationParameters> ) {
+		return TimeInstant.fromParameters( parameters, this );
+	}
+
+	public isBetween( start: TimeInstant, end: TimeInstant ) {
+		return this.ms >= start.ms && this.ms <= end.ms;
+	}
+
+	public static fromDate( date: Date ): TimeInstant {
+		return this.fromUnixTimestamp( date.getTime() );
+	}
+
+	public static fromUnixTimestamp( unixTimestamp: number ): TimeInstant {
+		return new TimeInstant( unixTimestamp, TimeUnit.MILLISECONDS );
+	}
+
+	public static fromUnixSeconds( unixSeconds: number ): TimeInstant {
+		return new TimeInstant( unixSeconds, TimeUnit.SECONDS );
+	}
+
+	public static fromParameters( parameters: Partial<TTimeInstantCreationParameters>, referenceDate?: Date | TimeInstant ): TimeInstant {
+		return createTimeInstantFromParameters( parameters, referenceDate );
+	}
+
+	public static greatest( instant1: TimeInstant, instant2: TimeInstant ): TimeInstant {
+		return instant1.isAfter( instant2 ) ? instant1 : instant2;
+	}
+
+	public static lowest( instant1: TimeInstant, instant2: TimeInstant ): TimeInstant {
+		return instant1.isBefore( instant2 ) ? instant1 : instant2;
+	}
+
+	public static builder(): TTimeInstantBuilder {
+		return timeInstantBuilder();
+	}
+
+	/**
+		* @deprecated[19/07/2023] Use {@link fromParameters} instead.
+		*/
+	public static fromUnits( { date, month, year, hours, minutes, seconds }: { date: number, month: number, year: number, hours?: number, minutes?: number, seconds?: number } ): TimeInstant {
+		const dt = Date.UTC( year, month - 1, date, hours ?? 0, minutes ?? 0, seconds ?? 0 );
+		if ( isNaN( dt ) )
+			throw new Error( `Unparseable date: ${date}, ${month}, ${year}, ${hours ?? '-'}, ${minutes ?? '-'}, ${seconds ?? '-'}` )
+		return TimeInstant.fromUnixTimestamp( dt );
+	}
+
+	public static fromIso8601( str: TIso8601DateString ) {
+		return TimeInstant.fromUnixTimestamp( new Date( str ).getTime() );
+	}
+
+	public static now(): TimeInstant {
+		return TimeInstant.fromUnixTimestamp( Date.now() );
+	}
+
+	public static get currentTimeStamp(): number {
+		return Date.now();
+	}
+
+	public static compare( a: TimeInstant, b: TimeInstant ): TComparisonResult {
+		return a.compareTo( b );
+	}
+
+	public roundedToStartOf( unit: TimeUnit ) {
+		return TimeInstant.fromUnixTimestamp( this.ms - ( this.ms % unit.multiplier ) );
+	}
+
+	public roundedToEndOf( unit: TimeUnit ) {
+		return TimeInstant.fromUnixTimestamp( this.ms - ( this.ms % unit.multiplier ) + unit.toMs( 1 ) - 1 );
+	}
+
+	public roundedToNext( unit: TimeUnit, factor = 1 ) {
+		const unitMs = unit.toMs( factor );
+		const timestamp = Math.ceil( this.ms / unitMs ) * unitMs;
+		return TimeInstant.fromUnixTimestamp( timestamp );
+	}
+
+	public roundedToPrevious( unit: TimeUnit, factor = 1 ) {
+		const unitMs = unit.toMs( factor );
+		const timestamp = Math.floor( this.ms / unitMs ) * unitMs;
+		return TimeInstant.fromUnixTimestamp( timestamp );
+	}
+
+	public roundedTo( unit: TimeUnit, factor = 1 ) {
+		const unitMs = unit.toMs( factor );
+		const timestamp = Math.round( this.ms / unitMs ) * unitMs;
+		return TimeInstant.fromUnixTimestamp( timestamp );
+	}
+
+	public get dayOfMonth(): TDayOfMonth {
+		return this.asDate().getDate() as TDayOfMonth;
+	}
+
+	public get dayOfWeek(): TDayOfWeek {
+		return this.asDate().getDay() + 1 as TDayOfWeek;
+	}
+
+	public get month(): TMonth {
+		return this.asDate().getMonth() + 1 as TMonth;
+	}
+
+	public get year(): number {
+		return this.asDate().getFullYear();
+	}
+
+	/**
+		* Returns the week number represented by this instant, according to the ISO 8601 standard.
+		* Please note that the instant and the week number could be of two different years, eg the friday 1st january is actually part of week 52 of the previous year.
+		*/
+	public get weekNumber(): { weekNumber: TWeekNumber, year: number } {
+		/**
+			* According to the ISO 8601 Standard, week number 1 is defined as the week containing the 4th of january (or, equivalently, the week that contains the first Thursday of the year).
+			* As such, we basically have to count how many Thursdays there has been in this year.
+			* Please note that the thursdayOfThisWeek could be in the previous year.
+			*/
+		const date = this.asDate();
+		const oneDay = 1000 * 60 * 60 * 24;
+		const thursdayOfThisWeek = new Date( date.getFullYear(), date.getMonth(), date.getDate() + 4 - ( date.getDay() || 7 ), 14, 0, 0 );
+		const firstOfJanuary = new Date( thursdayOfThisWeek.getFullYear(), 0, 1, 14, 0, 0 );
+		const dayOfTheYear = Math.round( ( thursdayOfThisWeek.getTime() - firstOfJanuary.getTime() ) / oneDay );
+		const weekNumber = Math.floor( dayOfTheYear / 7 ) + 1;
+		return { weekNumber: weekNumber as TWeekNumber, year: thursdayOfThisWeek.getFullYear() };
+	}
+
+	/**
+		* This method is used to provide a better DX when inspecting a TimeInstant object in DevTools.
+		*/
+	protected get _time() {
+		return this.asHumanTimestamp();
+	}
+
+	public override toString() {
+		return `${this.constructor.name}[${this.asHumanTimestamp()}]`;
+	}
+
+	public static ZERO: TimeInstant = TimeInstant.fromUnixTimestamp( 0 );
+
+	public static fromJSON( ms: number ) {
+		return TimeInstant.fromUnixTimestamp( ms );
+	}
+
+}
+
+export function isTimeInstant( x: unknown ): x is TimeInstant {
+	return x !== null && x !== undefined && x instanceof TimeInstant;
+}
+
+export default TimeInstant;

package/src/time/TimeInstantBuilder.ts

@@ -0,0 +1,126 @@
+
+import { TFunction } from "../types/functions.js";
+import { ensureDefined } from "../types/nulls.js";
+import { TimeInstant, isTimeInstant } from "./TimeInstant.js";
+import { TDayOfMonth, THourOfDay, TMillisecondOfSecond, TMinuteOfHour, TMonth, TSecondOfMinute, TUpToTwoDigits } from "./types.js";
+
+type TRelativeSignum = '+' | '-';
+type TRelativeNumber = `${TRelativeSignum}${TUpToTwoDigits}`;
+const isRelativeNumber = ( x: string ): x is TRelativeNumber => x !== undefined && x.length > 0 && ( x[ 0 ] === '+' || x[ 0 ] === '-' );
+export type TTimeInstantCreationParameters = {
+	year: number | { absolute: number } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	month: TMonth | { absolute: TMonth } | keyof typeof monthNames | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	date: TDayOfMonth | { absolute: TDayOfMonth } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	hours: THourOfDay | { absolute: THourOfDay } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	minutes: TMinuteOfHour | { absolute: TMinuteOfHour } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	seconds: TSecondOfMinute | { absolute: TSecondOfMinute } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+	milliseconds: TMillisecondOfSecond | { absolute: TMillisecondOfSecond } | TRelativeNumber | { relative: number, relativeTo: 'now' | TimeInstant } | 'next' | 'last' | 'current' | undefined;
+}
+
+const defaultTimeInstantCreationParameters: TTimeInstantCreationParameters = {
+	year: { relative: 0, relativeTo: 'now' },
+	month: { relative: 0, relativeTo: 'now' },
+	date: { relative: 0, relativeTo: 'now' },
+	hours: { relative: 0, relativeTo: 'now' },
+	minutes: { relative: 0, relativeTo: 'now' },
+	seconds: { relative: 0, relativeTo: 'now' },
+	milliseconds: { relative: 0, relativeTo: 'now' },
+};
+const timeInstantCreationRelativeAliases = {
+	current: 0,
+	last: -1,
+	next: +1,
+} as const satisfies Record<string, number>;
+const monthNames = {
+	january: 1,
+	february: 2,
+	march: 3,
+	april: 4,
+	may: 5,
+	june: 6,
+	july: 7,
+	august: 8,
+	september: 9,
+	october: 10,
+	november: 11,
+	december: 12,
+} as const satisfies Record<string, number>;
+type TAllowedTimeInstantCreationAlias = keyof typeof timeInstantCreationRelativeAliases;
+type TAllowedTimeInstantCreationParameter = { absolute: number } | { relative: number, relativeTo?: TimeInstant | 'now' } | TAllowedTimeInstantCreationAlias | TRelativeNumber | keyof typeof monthNames | number | undefined;
+const timeInstantResolveValue = ( getFromDate: TFunction<Date, number>, referenceDate: Date, x: TAllowedTimeInstantCreationParameter ): number => {
+	if ( x === undefined ) {
+		return getFromDate( referenceDate );
+	} else if ( typeof x === 'number' ) {
+		return x;
+	} else if ( typeof x === 'string' ) {
+		if ( isRelativeNumber( x ) ) {
+			return getFromDate( referenceDate ) + parseInt( x );
+		} else if ( x in timeInstantCreationRelativeAliases ) {
+			return getFromDate( referenceDate ) + timeInstantCreationRelativeAliases[ x ];
+		} else if ( x in monthNames ) {
+			return monthNames[x];
+		} else {
+			throw new Error( 'Uparseable string detected: ' + x );
+		}
+	} else if ( "relative" in x ) {
+		const { relative, relativeTo } = x;
+		if ( relativeTo === undefined || relativeTo === 'now' ) {
+			return getFromDate( referenceDate ) + relative;
+		} else {
+			return getFromDate( relativeTo.asDateUTC() ) + relative;
+		}
+	} else if ( "absolute" in x ) {
+		return x.absolute
+	} else {
+		throw new Error( 'Uparseable value detected: ' + x );
+	}
+};
+const getFromDate = {
+	year: d => d.getFullYear(),
+	month: d => d.getMonth(),
+	date: d => d.getDate(),
+	hours: d => d.getHours(),
+	minutes: d => d.getMinutes(),
+	seconds: d => d.getSeconds(),
+	milliseconds: d => d.getMilliseconds(),
+} as const satisfies Record<string, TFunction<Date, number>>;
+const toReferenceDate = ( x: Date | TimeInstant ): Date => { 
+	ensureDefined( x );
+	if ( isTimeInstant( x ) ) return x.asDateUTC();
+	return x;
+}
+
+export function createTimeInstantFromParameters( aParameters: Partial<TTimeInstantCreationParameters>, aReferenceDate: TimeInstant | Date = TimeInstant.now() ): TimeInstant {
+	const { year, month, date, hours, minutes, seconds, milliseconds }: TTimeInstantCreationParameters = { ...defaultTimeInstantCreationParameters, ...aParameters };
+	const referenceDate = toReferenceDate( aReferenceDate );
+	const timestamp = Date.UTC(
+		timeInstantResolveValue( getFromDate.year, referenceDate, year ),
+		timeInstantResolveValue( getFromDate.month, referenceDate, month ),
+		timeInstantResolveValue( getFromDate.date, referenceDate, date ),
+		timeInstantResolveValue( getFromDate.hours, referenceDate, hours ),
+		timeInstantResolveValue( getFromDate.minutes, referenceDate, minutes ),
+		timeInstantResolveValue( getFromDate.seconds, referenceDate, seconds ),
+		timeInstantResolveValue( getFromDate.milliseconds, referenceDate, milliseconds )
+	);
+	if ( isNaN( timestamp ) )
+		throw new Error( `Unparseable date: ${JSON.stringify( aParameters )} }` );
+	return TimeInstant.fromUnixTimestamp( timestamp );
+}
+export function timeInstantBuilder() {
+	let referenceDate = TimeInstant.now().asDateUTC();
+	const value: TTimeInstantCreationParameters = { ...defaultTimeInstantCreationParameters };
+	const ret = {
+		year: ( x: TTimeInstantCreationParameters[ "year" ] ) => { value.year = x; return ret; },
+		month: ( x: TTimeInstantCreationParameters[ "month" ] ) => { value.month = x; return ret; },
+		date: ( x: TTimeInstantCreationParameters[ "date" ] ) => { value.date = x; return ret; },
+		hours: ( x: TTimeInstantCreationParameters[ "hours" ] ) => { value.hours = x; return ret; },
+		minutes: ( x: TTimeInstantCreationParameters[ "minutes" ] ) => { value.minutes = x; return ret; },
+		seconds: ( x: TTimeInstantCreationParameters[ "seconds" ] ) => { value.seconds = x; return ret; },
+		milliseconds: ( x: TTimeInstantCreationParameters[ "milliseconds" ] ) => { value.milliseconds = x; return ret; },
+		values: ( x: Partial<TTimeInstantCreationParameters> ) => { Object.keys( value ).forEach( key => value[key] = x[key] ?? value[key] ); return ret; },
+		relativeTo: ( x: TimeInstant | Date ) => { referenceDate = toReferenceDate( x ); return ret; },
+		build: () => createTimeInstantFromParameters( value, referenceDate ),
+	};
+	return ret;
+}
+export type TTimeInstantBuilder = ReturnType<typeof timeInstantBuilder>;

package/src/time/TimeUnit.ts

@@ -0,0 +1,43 @@
+
+export default class TimeUnit {
+
+	private constructor(
+		public readonly multiplier: number
+	) { }
+
+	public toUnit( value: number, unit: TimeUnit ): number {
+		return value * ( this.multiplier / unit.multiplier );
+	}
+
+	public toMs( value: number ): number {
+		return this.toUnit( value, TimeUnit.MILLISECONDS );
+	}
+
+	public toSeconds( value: number ): number {
+		return this.toUnit( value, TimeUnit.SECONDS );
+	}
+
+	public toMinutes( value: number ): number {
+		return this.toUnit( value, TimeUnit.MINUTES );
+	}
+
+	public toHours( value: number ): number {
+		return this.toUnit( value, TimeUnit.HOURS );
+	}
+
+	public toDays( value: number ): number {
+		return this.toUnit( value, TimeUnit.DAYS );
+	}
+
+	public toWeeks( value: number ): number {
+		return this.toUnit( value, TimeUnit.WEEKS );
+	}
+
+	public static readonly MILLISECONDS = new TimeUnit( 1 );
+	public static readonly SECONDS = new TimeUnit( 1000 * TimeUnit.MILLISECONDS.multiplier );
+	public static readonly MINUTES = new TimeUnit( 60 * TimeUnit.SECONDS.multiplier );
+	public static readonly HOURS = new TimeUnit( 60 * TimeUnit.MINUTES.multiplier );
+	public static readonly DAYS = new TimeUnit( 24 * TimeUnit.HOURS.multiplier );
+	public static readonly WEEKS = new TimeUnit( 7 * TimeUnit.DAYS.multiplier );
+
+}

package/src/time/index.ts

@@ -0,0 +1,8 @@
+
+export { default as RandomTimeDuration } from './RandomTimeDuration';
+export { TPredefinedTimeDuration, TValidTimeDuration, TimeDuration, isAllowedTimeDuration } from './TimeDuration';
+export { default as TimeFrequency } from './TimeFrequency';
+export * from './TimeInstant';
+export { default as TimeUnit } from './TimeUnit';
+export * from './types';
+