@zelgadis87/utils-core 4.1.1 → 4.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "4.1.1",
+  "version": "4.2.1",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,
@@ -138,6 +138,9 @@
     "vitest": "^2.1.4",
     "wireit": "^0.14.9"
   },
+  "dependencies": {
+    "small-date": "^2.0.1"
+  },
   "scripts": {
     "clean": "rimraf .wireit dist esbuild coverage",
     "build": "wireit",

package/src/time/TimeDuration.ts

@@ -1,4 +1,4 @@
-import Deferred, { ICancelablePromise } from "../async/Deferred.js";
+import Deferred, { DeferredCanceledError, ICancelablePromise } from "../async/Deferred.js";
 import { randomInterval } from "../random";
 import { TComparisonResult } from "../sorting/index.js";
 import { TIntervalHandle, TMaybe, TTimeoutHandle, TVoidFunction, ensureNonNegativeNumber, ensurePositiveNumber } from "../types";
@@ -102,8 +102,10 @@ export class TimeDuration extends TimeBase<TimeDuration> {
 		const deferred = this.promise();
 		void deferred.then( () => {
 			cb();
-		}, _err => {
-			return; // Do nothing on cancelation ( err is always an instance of DeferredCanceledError )
+		}, err => {
+			if ( err instanceof DeferredCanceledError )
+				return; // Do nothing on cancelation
+			throw err;
 		} );
 		return { cancel: () => deferred.cancel() };
 	}

package/src/time/TimeInstant.ts

@@ -1,12 +1,12 @@
-import Deferred, { ICancelablePromise } from "../async/Deferred.js";
+import { format } from "small-date";
+import { ICancelablePromise } from "../async/Deferred.js";
 import { TComparisonResult } from "../sorting/index.js";
-import { TTimeoutHandle, TVoidFunction } from "../types";
-import { pad } from "../utils";
+import { TVoidFunction } from "../types";
 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";
+import { TDayOfMonth, TDayOfWeek, TIso8601DateString, TIso8601DateUtcString, TMonth, TWeekNumber } from "./types";
 
 export class TimeInstant extends TimeBase<TimeInstant> {
 
@@ -50,240 +50,116 @@ export class TimeInstant extends TimeBase<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;
+		this.ensureInTheFuture();
+		return this.distanceFromNow().promise()
 	}
 
 	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() };
+		this.ensureInTheFuture();
+		return this.distanceFromNow().delay( cb )
+	}
+
+	public ensureInTheFuture() {
+		if ( !this.isInTheFuture )
+			throw new Error( 'Instant is in the past' );
+	}
+
+	public ensureInThePast() {
+		if ( !this.isInThePast )
+			throw new Error( 'Instant is in the future' );
 	}
 
 	public isToday(): boolean {
 		return Math.floor( this.days ) === Math.floor( TimeInstant.now().days );
 	}
 
+	/**
+	 * @returns the time as HH:mm:ss
+	 * @deprecated [2024-12-11] this method is too ambigous and should be removed.
+	 */
 	public asTimeString(): string {
-		const date = this.asDate();
-		return `${this.doGetTwoDigitsHours( date )}:${this.doGetTwoDigitsMinutes( date )}:${this.doGetTwoDigitsSeconds( date )}`;
+		return this.format( 'HH:mm:ss' );
 	}
 
+	/**
+	 * @returns the date as dd/MM/yyyy
+	 * @deprecated [2024-12-11] this method is too ambigous and should be removed.
+	 */
 	public asDateString(): string {
-		const date = this.asDate();
-		return `${this.doGetTwoDigitsDays( date )}/${this.doGetTwoDigitsMonths( date )}/${this.doGetFourDigitsYears( date )}`;
+		return this.format( 'dd/MM/yyyy' );
 	}
 
-		/**
-	 * @returns this instant, in ISO 8601 format (eg, 2024-11-01T15:49:22.024+0200). The format is meant to always be realiable.
+	/**
+	 * Formats this instant using the given pattern. The pattern can contain the following tokens:
+	 * 
+	 * | Token | Description                     | Example                       |
+	 * |:------|:--------------------------------|:------------------------------|
+	 * | D     | Weekday, 1 letter               | W                             |
+	 * | DD    | Weekday, 3 letters              | Wed                           |
+	 * | DDD   | Weekday, long                   | Wednesday                     |
+	 * | d     | Day of the month, no padding    | 3                             |
+	 * | dd    | Day of the month, padded to 2   | 03                            |
+	 * | M     | Month, numeric                  | 3                             |
+	 * | MM    | Month, 2 digits                 | 03                            |
+	 * | MMM   | Month, 3 letters                | Mar                           |
+	 * | MMMM  | Month, long                     | March                         |
+	 * | y     | Year, numeric                   | 2021                          |
+	 * | yy    | Year, 2 digits                  | 21                            |
+	 * | yyyy  | Year, numeric                   | 2021                          |
+	 * | h     | Hours, no padding               | 6                             |
+	 * | hh    | Hours, padded to 2              | 06                            |
+	 * | H     | Hours in 24-format, no padding  | 18                            |
+	 * | HH    | Hours in 24-format, padded to 2 | 18                            |
+	 * | m     | Minutes, no padding             | 7                             |
+	 * | m     | Minutes, padded to 2            | 07                            |
+	 * | s     | Seconds, no padding             | 8                             |
+	 * | ss    | Seconds, padded to 2            | 08                            |
+	 * | S     | Milliseconds, no padding        | 9                             |
+	 * | SS    | Milliseconds, padded to 2       | 09                            |
+	 * | SSS   | Milliseconds, padded to 3       | 009                           |
+	 * | G     | Era, narrow                     | A                             |
+	 * | GG    | Era, short                      | AD                            |
+	 * | GGG   | Era, long                       | Anno Domino                   |
+	 * | Z     | Time zone, short                | GMT+1                         |
+	 * | ZZ    | Time short, long	C              | entral European Standard Time |
+	 * | P     | Period of the day, narrow       | in the morning                |
+	 * | PP    | Period of the day, short        | in the morning                |
+	 * | PPP   | Period of the day, long         | in the morning                |
+	 * | a     | Meridiem                        | pm                            |
+	 * @param pattern The pattern to use. Refer to the token table above for details.
+	 * @param config An optional locale and timeZone definition to use during the format.
+	 * @returns a string, formatted using the given pattern, at the given timeZone with the given locale.
 	 */
-	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 format( pattern: string, config: { locale?: string, timeZone?: string } = {} ) {
+		return format( this.toDate(), pattern, config );
 	}
 
 	/**
-	 * @returns this instant, in ISO 8601 format and UTC time zone (eg, 2024-11-01T15:49:22.024Z). The format is meant to always be realiable.
-	 */
-	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;
+ * @returns this instant, in ISO 8601 format (eg, 2024-11-01T15:49:22.024Z). The format is meant to always be realiable.
+ */
+	public asIso8601(): TIso8601DateUtcString {
+		return this.format( 'yyyy-MM-dd"T"HH:mm:ss.SSS"Z"', { timeZone: 'UTC' } ) as TIso8601DateUtcString;
 	}
 
 	/**
 	 * @returns this instant, in a human readable format. The format COULD change in the future, do NOT use this method for consistent outputs.
+	 * @deprecated [2024-12-11] this method is too broad and ambigous and should be removed.
 	 */
 	public asHumanTimestamp(): string {
-		const dash = '-', doublecolon = ':', space = ' ', T = 'T', date = this.asDate();
-		return (
-			this.doGetFourDigitsYears( date )
-			+ dash
-			+ this.doGetTwoDigitsMonths( date )
-			+ dash
-			+ this.doGetTwoDigitsDays( date )
-			+ space
-			+ this.doGetTwoDigitsHours( date )
-			+ doublecolon
-			+ this.doGetTwoDigitsMinutes( date )
-			+ doublecolon
-			+ this.doGetTwoDigitsSeconds( 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;
+		return this.format( 'yyyy-MM-dd HH:mm:ss' )
 	}
 
-	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 {
+	public toUnixTimestamp(): number {
 		// Syntatic sugar for this.ms;
 		return this.ms;
 	}
 
-	public asDate(): Date {
+	public toDate(): Date {
 		return new Date( this.ms );
 	}
 
-	public asDateUTC(): Date {
+	public toDateUTC(): Date {
 		return new Date( this.ms + new Date().getTimezoneOffset() * 60 * 1000 );
 	}
 
@@ -396,6 +272,12 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return TimeInstant.fromUnixTimestamp( new Date( str ).getTime() );
 	}
 
+	public static tryFromIso8601( str: string ) {
+		if ( !str.match( /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(Z|([+-]\d{2}:\d{2})))?$/ ) )
+			throw new Error( 'Invalid date given: ' + str );
+		return TimeInstant.fromUnixTimestamp( new Date( str ).getTime() );
+	}
+
 	public static now(): TimeInstant {
 		return TimeInstant.fromUnixTimestamp( Date.now() );
 	}
@@ -435,19 +317,19 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public get dayOfMonth(): TDayOfMonth {
-		return this.asDate().getDate() as TDayOfMonth;
+		return this.toDate().getDate() as TDayOfMonth;
 	}
 
 	public get dayOfWeek(): TDayOfWeek {
-		return this.asDate().getDay() + 1 as TDayOfWeek;
+		return this.toDate().getDay() + 1 as TDayOfWeek;
 	}
 
 	public get month(): TMonth {
-		return this.asDate().getMonth() + 1 as TMonth;
+		return this.toDate().getMonth() + 1 as TMonth;
 	}
 
 	public get year(): number {
-		return this.asDate().getFullYear();
+		return this.toDate().getFullYear();
 	}
 
 	/**
@@ -460,7 +342,7 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 			* 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 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 );
 		const firstOfJanuary = new Date( thursdayOfThisWeek.getFullYear(), 0, 1, 14, 0, 0 );

package/src/time/TimeInstantBuilder.ts

@@ -67,7 +67,7 @@ const timeInstantResolveValue = ( getFromDate: TFunction<Date, number>, referenc
 		if ( relativeTo === undefined || relativeTo === 'now' ) {
 			return getFromDate( referenceDate ) + relative;
 		} else {
-			return getFromDate( relativeTo.asDateUTC() ) + relative;
+			return getFromDate( relativeTo.toDate() ) + relative;
 		}
 	} else if ( "absolute" in x ) {
 		return x.absolute
@@ -86,7 +86,7 @@ const getFromDate = {
 } as const satisfies Record<string, TFunction<Date, number>>;
 const toReferenceDate = ( x: Date | TimeInstant ): Date => { 
 	ensureDefined( x );
-	if ( isTimeInstant( x ) ) return x.asDateUTC();
+	if ( isTimeInstant( x ) ) return x.toDate();
 	return x;
 }
 
@@ -107,7 +107,7 @@ export function createTimeInstantFromParameters( aParameters: Partial<TTimeInsta
 	return TimeInstant.fromUnixTimestamp( timestamp );
 }
 export function timeInstantBuilder() {
-	let referenceDate = TimeInstant.now().asDateUTC();
+	let referenceDate = TimeInstant.now().toDate();
 	const value: TTimeInstantCreationParameters = { ...defaultTimeInstantCreationParameters };
 	const ret = {
 		year: ( x: TTimeInstantCreationParameters[ "year" ] ) => { value.year = x; return ret; },

package/src/types/json.ts

@@ -1,5 +1,15 @@
+import { asError } from "./errors.ts";
 
 export type TJsonPrimitive = string | number | boolean | null | undefined;
 export type TJsonArray = Array<TJsonSerializable> | ReadonlyArray<TJsonSerializable>;
 export type TJsonObject = { [ key: string ]: TJsonSerializable }
 export type TJsonSerializable = TJsonPrimitive | TJsonArray | TJsonObject;
+
+export function tryToParseJson<T extends TJsonSerializable>( jsonContent: string ): [ T, null ] | [ null, Error ] {
+	try {
+		const data = JSON.parse( jsonContent );
+		return [ data as T, null ];
+	} catch ( err ) {
+		return [ null, asError( err ) ];
+	}
+}

package/src/types/records.ts

@@ -14,8 +14,13 @@ export function pick<T extends object, K extends keyof T>( o: T, keys: K[] ): Pi
 }
 
 export type TOptionsWithoutDefaults<T, R> = Partial<T> & Required<Omit<T, keyof R>>;
-export type TOptionalKeysForType<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? K : never }[keyof T];
+export type TOptionalKeysForType<T> = { [ K in keyof T ]-?: {} extends Pick<T, K> ? K : never }[ keyof T ];
 export type TRequiredKeysForType<T> = Exclude<keyof T, TOptionalKeysForType<T>>;
 export type TAllKeysOptional<T> = TRequiredKeysForType<T> extends never ? true : false;
 export type TConditionalParameter<T> = TAllKeysOptional<T> extends true ? T | undefined : T;
 export type TConditionalParameterOptions<T, R> = TConditionalParameter<TOptionsWithoutDefaults<T, R>>;
+
+/**
+ * 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 ]; };