@zelgadis87/utils-core 4.5.0 → 4.6.1

package/src/time/TimeInstant.ts

@@ -33,6 +33,16 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return TimeDuration.fromMs( Math.abs( this.ms - Date.now() ) );
 	}
 
+	public timeLeftFrom( instant: TimeInstant ): TimeDuration {
+		const distance = this.ms - instant.ms;
+		return TimeDuration.fromMs( Math.max( distance, 0 ) );
+	}
+
+	public timeLeftFromNow(): TimeDuration {
+		const distance = this.ms - Date.now();
+		return TimeDuration.fromMs( Math.max( distance, 0 ) );
+	}
+
 	public distanceFromStartOfDay(): TimeDuration {
 		return this.distanceFrom( this.atStartOfDay() );
 	}
@@ -49,16 +59,20 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return this.atTime( { hours: 23, minutes: 59, seconds: 59, milliseconds: 999 } );
 	}
 
-	public promise(): ICancelablePromise<void> {
-		const ms = this.ms - Date.now();
-		const duration = TimeDuration.fromMs( Math.max( ms, 0 ) );
-		return duration.promise();
+	public promise(): Promise<void> {
+		return this.timeLeftFromNow().promise();
+	}
+
+	public cancelablePromise(): ICancelablePromise<void> {
+		return this.timeLeftFromNow().cancelablePromise();
 	}
 
-	public delay( cb: () => unknown ): ICancelable {
-		const ms = this.ms - Date.now();
-		const duration = TimeDuration.fromMs( Math.max( ms, 0 ) );
-		return duration.delay( cb );
+	public delay( cb: () => unknown ): void {
+		return this.timeLeftFromNow().delay( cb );
+	}
+
+	public cancelableDelay( cb: () => unknown ): ICancelable {
+		return this.timeLeftFromNow().cancelableDelay( cb );
 	}
 
 	public ensureInTheFuture() {
@@ -191,22 +205,25 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	/**
-		* @deprecated[04/07/2023]: Use distanceFromNow instead
-		*/
+	 * @deprecated: Use {@link distanceFromNow} instead
+	*/
+	// TODO[2023-07-04, Deprecated]: Remove this method in a future version
 	public fromNow(): TimeDuration {
 		return TimeDuration.ms( this.ms - Date.now() );
 	}
 
 	/**
-		* @deprecated[04/07/2023]: Use distanceFrom instead
-		*/
+	 * @deprecated: Use {@link distanceFrom} instead
+	*/
+	// TODO[2023-07-04, Deprecated]: Remove this method in a future version
 	public from( instant: TimeInstant ): TimeDuration {
 		return TimeDuration.ms( this.ms - instant.ms );
 	}
 
 	/**
-		* @deprecated[04/07/2023]: Use distanceFromUnixTimestamp instead
-		*/
+	 * @deprecated: Use {@link distanceFromUnixTimestamp} instead
+	*/
+	// TODO[2023-07-04, Deprecated]: Remove this method in a future version
 	public fromTimestamp( timestamp: number ): TimeDuration {
 		return TimeDuration.ms( this.ms - timestamp );
 	}
@@ -260,8 +277,8 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	/**
-		* @deprecated[19/07/2023] Use {@link fromParameters} instead.
-		*/
+	 * @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 ) )
@@ -334,15 +351,15 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	/**
-		* Returns the week number represented by this instant, according to the ISO 8601 standard.
+	 * 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.toDate();
 		const oneDay = 1000 * 60 * 60 * 24;
 		const thursdayOfThisWeek = new Date( date.getFullYear(), date.getMonth(), date.getDate() + 4 - ( date.getDay() || 7 ), 14, 0, 0 );
@@ -353,8 +370,8 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	/**
-		* This method is used to provide a better DX when inspecting a TimeInstant object in DevTools.
-		*/
+	 * This method is used to provide a better DX when inspecting a TimeInstant object in DevTools.
+	 */
 	protected get _time() {
 		return this.asHumanTimestamp();
 	}

package/src/utils/arrays/groupBy.ts

@@ -1,40 +1,40 @@
 
-import { TFunction, TKeysOfType } from "..";
+import { TFunction, TKeysOfType, TReadableArray } from "..";
 
-export function groupByString<V, K extends TKeysOfType<V, string>>( arr: V[], field: K ): Record<V[K] & string, V[]> {
+export function groupByString<V, K extends TKeysOfType<V, string>>( arr: TReadableArray<V>, field: K ): Record<V[ K ] & string, V[]> {
 	return groupByStringWith( arr, t => t[ field ] as string );
 }
 
-export function groupByNumber<V, K extends TKeysOfType<V, number>>( arr: V[], field: K ): Record<V[K] & number, V[]> {
+export function groupByNumber<V, K extends TKeysOfType<V, number>>( arr: TReadableArray<V>, field: K ): Record<V[ K ] & number, V[]> {
 	return groupByNumberWith( arr, t => t[ field ] as number );
 }
 
-export function groupByBoolean<V, K extends TKeysOfType<V, boolean>>( arr: V[], field: K ): Record<"true" | "false", V[]> {
+export function groupByBoolean<V, K extends TKeysOfType<V, boolean>>( arr: TReadableArray<V>, field: K ): Record<"true" | "false", V[]> {
 	return groupByBooleanWith( arr, t => t[ field ] as boolean );
 }
 
-export function groupBySymbol<V, K extends TKeysOfType<V, symbol>>( arr: V[], field: K ): Record<V[K] & symbol, V[]> {
+export function groupBySymbol<V, K extends TKeysOfType<V, symbol>>( arr: TReadableArray<V>, field: K ): Record<V[ K ] & symbol, V[]> {
 	return groupBySymbolWith( arr, t => t[ field ] as symbol );
 }
 
-export function groupByStringWith<V, K extends string>( arr: V[], getter: TFunction<V, K> ): Record<K, V[]> {
+export function groupByStringWith<V, K extends string>( arr: TReadableArray<V>, getter: TFunction<V, K> ): Record<K, V[]> {
 	return doGroupByWith<K, V>( arr, getter );
 }
 
-export function groupByNumberWith<V, K extends number>( arr: V[], getter: TFunction<V, K> ): Record<K, V[]> {
+export function groupByNumberWith<V, K extends number>( arr: TReadableArray<V>, getter: TFunction<V, K> ): Record<K, V[]> {
 	return doGroupByWith<K, V>( arr, getter );
 }
 
-export function groupByBooleanWith<V, K extends boolean>( arr: V[], getter: TFunction<V, K> ): Record<"true" | "false", V[]> {
+export function groupByBooleanWith<V, K extends boolean>( arr: TReadableArray<V>, getter: TFunction<V, K> ): Record<"true" | "false", V[]> {
 	return doGroupByWith<"true" | "false", V>( arr, item => getter( item ) ? "true" : "false" );
 }
 
-export function groupBySymbolWith<V, K extends symbol>( arr: V[], getter: TFunction<V, K> ): Record<K, V[]> {
+export function groupBySymbolWith<V, K extends symbol>( arr: TReadableArray<V>, getter: TFunction<V, K> ): Record<K, V[]> {
 	return doGroupByWith<K, V>( arr, getter );
 }
 
-function doGroupByWith<K extends string | number | symbol, V>( arr: V[], getter: TFunction<V, K> ): Record<K, V[]> {
-	return arr.reduce( ( dict, cur ) => {
+function doGroupByWith<K extends string | number | symbol, V>( arr: TReadableArray<V>, getter: TFunction<V, K> ): Record<K, V[]> { // TODO[2025-01-03, Native]: Migrate to native @ https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/#object.groupby-and-map.groupby
+	return [ ...arr ].reduce( ( dict, cur ) => {
 		const key = getter( cur );
 		if ( key !== null && key !== undefined ) {
 			const arr = dict[ key ] ?? [];

package/src/utils/random.ts

@@ -1,9 +1,15 @@
+import { TPositiveNumber } from "./numbers.ts";
 
+/** @deprecated[2025-01-14]: Use {@link randomNumberInInterval} instead. */
+export const randomInterval = ( min: number, max: number ): number => randomNumberInInterval( min, max );
 
-export function randomInterval( min: number, max: number ): number {
+/** @deprecated[2025-01-14]: Use {@link randomNumberInInterval} / 100 instead. */
+export const randomPercentage = ( min: number, max: number ): number => randomNumberInInterval( min, max ) / 100;
+
+export function randomNumberInInterval( min: number, max: number ): number {
 	return Math.floor( Math.random() * ( max - min + 1 ) + min );
 }
 
-export function randomPercentage( min: number, max: number ): number {
-	return randomInterval( min, max ) / 100;
+export const randomId = ( length: TPositiveNumber ): string => {
+	return Math.random().toString(36).substring(2, length + 2);
 }

package/src/utils/records.ts

@@ -26,3 +26,15 @@ export type TConditionalParameterOptions<T, R> = TConditionalParameter<TOptionsW
  * Given a type T, replaces all fields of type From to fields of type To.
  */
 export type TReplaceType<T, From, To> = { [ K in keyof T ]: T[ K ] extends From ? To : T[ K ]; };
+
+/**
+ * Given a type T, make field K required instead of optional.
+ */
+export type TWithRequiredProperty<T, K extends keyof T> = T & {
+	[ Property in K ]-?: T[ Property ];
+};
+
+/**
+ * Given a type T, make all fields required instead of optional.
+ */
+export type TWithRequiredProperties<T> = Required<T>;