@zelgadis87/utils-core 5.0.2 → 5.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,
@@ -22,15 +22,15 @@
     "@stylistic/eslint-plugin-ts": "4.2.0",
     "@typescript-eslint/eslint-plugin": "8.26.1",
     "@typescript-eslint/parser": "8.26.1",
-    "@vitest/coverage-v8": "3.0.8",
-    "@vitest/ui": "3.0.8",
-    "esbuild": "0.19.2",
+    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/ui": "3.2.4",
+    "esbuild": "0.25.8",
     "eslint": "9.22.0",
-    "nx": "21.1.2",
+    "nx": "21.3.5",
     "rimraf": "6.0.1",
-    "typescript": "5.8.2",
+    "typescript": "5.8.3",
     "typescript-eslint": "8.26.1",
-    "vitest": "3.0.8"
+    "vitest": "3.2.4"
   },
   "dependencies": {
     "small-date": "^2.0.1"

package/src/Optional.ts

@@ -33,6 +33,13 @@ export class Optional<T> implements TOptional<T> {
 		this._present = true;
 	}
 
+	protected setNullable( t: T | null | undefined ) {
+		if ( isDefined( t ) ) {
+			return this.set( t );
+		}
+		return this;
+	}
+
 	public clear() {
 		this._value = undefined;
 		this._present = false;
@@ -61,32 +68,78 @@ export class Optional<T> implements TOptional<T> {
 		}
 	}
 
-	public orElse( newValue: T ) {
+	public orElseReturn( newValue: T ): T {
 		if ( this.isPresent() ) {
-			return this._value;
+			return this.get();
 		} else {
 			return newValue;
 		}
 	}
-	public orElseGet( newValueProducer: TProducer<T> ) {
+	public orElse = this.orElseReturn.bind( this );
+
+	public orElseProduce( newValueProducer: TProducer<T> ): T {
 		if ( this.isPresent() ) {
-			return this._value;
+			return this.get();
 		} else {
 			return newValueProducer();
 		}
 	}
+	public orElseGet = this.orElseProduce.bind( this );
+
+	public orElseReturnAndApply( newValue: T ): T {
+		if ( this.isPresent() ) {
+			return this.get();
+		} else {
+			this.set( newValue );
+			return newValue;
+		}
+	}
+
+	public orElseProduceAndApply( newValueProducer: TProducer<T> ): T {
+		if ( this.isPresent() ) {
+			return this.get();
+		} else {
+			const newValue = newValueProducer();
+			this.set( newValue );
+			return newValue;
+		}
+	}
+
+	public orElseReturnNullableAndApply( newValue: T | null | undefined ): TOptional<T> {
+		if ( this.isPresent() ) {
+			return this;
+		} else {
+			this.setNullable( newValue );
+			return this;
+		}
+	}
+
+	public orElseProduceNullableAndApply( newValueProducer: TProducer<T | null | undefined> ): TOptional<T> {
+		if ( this.isPresent() ) {
+			return this;
+		} else {
+			const newValue = newValueProducer();
+			this.setNullable( newValue );
+			return this;
+		}
+	}
 
-	public orElseNullable( newValue: T | null | undefined ) {
+	public orElseReturnNullable( newValue: T | null | undefined ) {
 		if ( this.isEmpty() ) return Optional.ofNullable( newValue );
 		return this as TPresentOptional<T>;
 	}
-	public orElseGetNullable( newValueProducer: TProducer<T | null | undefined> ) {
+	public orElseNullable = this.orElseReturnNullable.bind( this );
+
+
+	public orElseProduceNullable( newValueProducer: TProducer<T | null | undefined> ) {
 		if ( this.isEmpty() ) {
 			const newValue = newValueProducer();
 			return Optional.ofNullable( newValue );
 		}
 		return this as TPresentOptional<T>;
 	}
+	public orElseGetNullable = this.orElseProduceNullable.bind( this );
+
 
 	public orElseThrow( errorProducer: TProducer<Error> ) {
 		if ( this.isEmpty() )
@@ -127,24 +180,28 @@ export default Optional;
 export type TOptional<T> = {
 
 	/**
-		* @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} otherwise;
-		*/
+	 * @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} otherwise;
+	 */
 	get(): T;
+
 	/**
-		* @returns the currently stored value, if any; returns undefined otherwise;
-		*/
+	 * @returns the currently stored value, if any; returns undefined otherwise;
+	 */
 	getRawValue(): T | undefined;
+
 	/**
-		* @returns the currently stored value, if any; throws the error generated by errorProducer otherwise;
-		*/
+	 * @returns the currently stored value, if any; throws the error generated by errorProducer otherwise;
+	 */
 	getOrElseThrow: ( errorProducer: TProducer<Error> ) => T;
+
 	/**
-		* Places a new value inside this optional. Throws {@link ErrorSetEmptyOptional} if t is null or undefined.
-		*/
+	 * Places a new value inside this optional. Throws {@link ErrorSetEmptyOptional} if t is null or undefined.
+	 */
 	set( t: T ): void;
+
 	/**
-		* Clears the current value from this optional, if any.
-		*/
+	 * Clears the current value from this optional, if any.
+	 */
 	clear(): void;
 	isEmpty(): boolean;
 	isPresent(): boolean;
@@ -153,10 +210,25 @@ export type TOptional<T> = {
 	ifPresent: ( callback: TConsumer<T> ) => void;
 	apply( callbackIfPresent: TConsumer<T>, callbackIfEmpty: TVoidFunction ): void;
 
+	/** @deprecated[2025.07.25]: Replace with {@link orElseReturn} (drop-in replacement) */
 	orElse: ( newValue: T ) => T;
+	/** @deprecated[2025.07.25]: Replace with {@link orElseProduce} (drop-in replacement) */
 	orElseGet: ( newValueProducer: TProducer<T> ) => T;
+	/** @deprecated[2025.07.25]: Replace with {@link orElseReturnNullabe} (drop-in replacement) */
 	orElseNullable: ( newValue: T | null | undefined ) => TOptional<T>;
+	/** @deprecated[2025.07.25]: Replace with {@link orElseProduceNullable} (drop-in replacement) */
 	orElseGetNullable: ( newValueProducer: TProducer<T | null | undefined> ) => TOptional<T>;
+
+	orElseReturn: ( newValue: T ) => T;
+	orElseProduce: ( newValueProducer: TProducer<T> ) => T;
+	orElseReturnNullable: ( newValue: T | null | undefined ) => TOptional<T>;
+	orElseProduceNullable: ( newValueProducer: TProducer<T | null | undefined> ) => TOptional<T>;
+
+	orElseReturnAndApply: ( newValue: T ) => T;
+	orElseProduceAndApply: ( newValueProducer: TProducer<T> ) => T;
+	orElseReturnNullableAndApply: ( newValue: T | null | undefined ) => TOptional<T>;
+	orElseProduceNullableAndApply: ( newValueProducer: TProducer<T | null | undefined> ) => TOptional<T>;
+
 	orElseThrow: ( errorProducer: TProducer<Error> ) => TPresentOptional<T>;
 
 	mapTo<R>( mapper: TFunction<T, R> ): TOptional<R>;

package/src/time/RandomTimeDuration.ts

@@ -1,6 +1,6 @@
 import { randomNumberInInterval } from "../utils/random.js";
 import TimeDuration from "./TimeDuration.js";
-import TimeUnit from "./TimeUnit.js";
+import { TimeUnit } from "./TimeUnit.js";
 
 function randomize( unit: TimeUnit ) {
 	return ( a: number, b: number ) => {

package/src/time/TimeBase.ts

@@ -1,4 +1,12 @@
-import TimeUnit from "./TimeUnit";
+import { TimeUnit } from "./TimeUnit";
+
+export type TTimeInUnits = {
+	milliseconds: number;
+	seconds: number;
+	minutes: number;
+	hours: number;
+	days: number;
+}
 
 export default abstract class TimeBase<T> {
 
@@ -13,22 +21,37 @@ export default abstract class TimeBase<T> {
 
 	protected abstract create( value: number, unit: TimeUnit ): T;
 
+	/**
+	 * Total number of milliseconds, rounded down.
+	 */
 	public get ms(): number {
 		return Math.floor( this._ms / TimeUnit.MILLISECONDS.multiplier );
 	}
 
+	/**
+	 * Total number of seconds, rounded down.
+	 */
 	public get seconds(): number {
 		return Math.floor( this._ms / TimeUnit.SECONDS.multiplier );
 	}
 
+	/**
+	 * Total number of minutes, rounded down.
+	 */
 	public get minutes(): number {
 		return Math.floor( this._ms / TimeUnit.MINUTES.multiplier );
 	}
 
+	/**
+	 * Total number of hours, rounded down.
+	 */
 	public get hours(): number {
 		return Math.floor( this._ms / TimeUnit.HOURS.multiplier );
 	}
 
+	/**
+	 * Total number of days, rounded down.
+	 */
 	public get days(): number {
 		return Math.floor( this._ms / TimeUnit.DAYS.multiplier );
 	}
@@ -85,20 +108,21 @@ export default abstract class TimeBase<T> {
 		return this._ms / unit.multiplier;
 	}
 
-	protected toUnits(): { days: number, hours: number, minutes: number, seconds: number } {
+	protected toUnits(): TTimeInUnits {
 		return {
-			days: Math.floor( ( this._ms / TimeUnit.DAYS.multiplier ) ),
-			hours: Math.floor( ( this._ms / TimeUnit.HOURS.multiplier ) % 24 ),
-			minutes: Math.floor( ( this._ms / TimeUnit.MINUTES.multiplier ) % 60 ),
-			seconds: Math.floor( ( this._ms / TimeUnit.SECONDS.multiplier ) % 60 ),
+			milliseconds: this.ms % TimeUnit.SECONDS.multiplier,
+			seconds: Math.floor( this.seconds % 60 ),
+			minutes: Math.floor( this.minutes % 60 ),
+			hours: Math.floor( this.hours % 24 ),
+			days: Math.floor( this.days ),
 		};
 	}
 
-	protected static toMs( units: { days?: number, hours?: number, minutes?: number, seconds?: number, ms?: number } ): number {
+	protected static unitsToMs( units: Partial<TTimeInUnits> ): number {
 		if ( !units )
 			throw new Error( 'Invalid units given' );
 		let ms = 0
-		ms += units.ms ?? 0 * TimeUnit.MILLISECONDS.multiplier;
+		ms += ( units.milliseconds ?? 0 ) * TimeUnit.MILLISECONDS.multiplier;
 		ms += ( units.seconds ?? 0 ) * TimeUnit.SECONDS.multiplier;
 		ms += ( units.minutes ?? 0 ) * TimeUnit.MINUTES.multiplier;
 		ms += ( units.hours ?? 0 ) * TimeUnit.HOURS.multiplier;

package/src/time/TimeDuration.ts

@@ -1,9 +1,9 @@
 import Deferred, { DeferredCanceledError, ICancelable, ICancelablePromise } from "../async/Deferred.js";
 import { TComparisonResult } from "../sorting/_index.js";
 import { TIntervalHandle, TMaybe, TTimeoutHandle, ensureNonNegativeNumber, ensurePositiveNumber, pad } from "../utils/_index.js";
-import TimeBase from "./TimeBase";
+import TimeBase, { type TTimeInUnits } from "./TimeBase";
 import TimeInstant from "./TimeInstant";
-import TimeUnit from "./TimeUnit";
+import { TimeUnit } from "./TimeUnit";
 
 export class TimeDuration extends TimeBase<TimeDuration> {
 
@@ -183,6 +183,10 @@ export class TimeDuration extends TimeBase<TimeDuration> {
 		return this.ms > 0;
 	}
 
+	public override toUnits() {
+		return super.toUnits();
+	}
+
 	/**
 		* This method is used to provide a better DX when inspecting a TimeInstant object in DevTools.
 		*/
@@ -198,7 +202,7 @@ export class TimeDuration extends TimeBase<TimeDuration> {
 		const match = humanTime.trim().match( /^(?:([0-9]+)d|)\s*(?:([0-9]+)h|)\s*(?:([0-9]+)m|)\s*(?:([0-9]+)s|)$/ );
 		if ( match ) {
 			const [ _, days, hours, minutes, seconds ] = match;
-			return new TimeDuration( TimeBase.toMs( { days: Number( days ?? 0 ), hours: Number( hours ?? 0 ), minutes: Number( minutes ?? 0 ), seconds: Number( seconds ?? 0 ) } ), TimeUnit.MILLISECONDS );
+			return new TimeDuration( TimeBase.unitsToMs( { days: Number( days ?? 0 ), hours: Number( hours ?? 0 ), minutes: Number( minutes ?? 0 ), seconds: Number( seconds ?? 0 ) } ), TimeUnit.MILLISECONDS );
 		}
 		throw new Error( 'Failed to parse time: ' + humanTime );
 	}
@@ -263,6 +267,10 @@ export class TimeDuration extends TimeBase<TimeDuration> {
 		return TimeDuration.ms( ms );
 	}
 
+	public static fromUnits( parameters: Partial<TTimeInUnits> ): TimeDuration {
+		return TimeDuration.ms( TimeBase.unitsToMs( parameters ) );
+	}
+
 }
 
 export type TPredefinedTimeDuration = 0 | 50 | 100 | 150 | 200 | 250 | 300 | 500 | 1000 | 1500 | 2000 | 2500 | 5000;

package/src/time/TimeInstant.ts

@@ -4,7 +4,7 @@ import { TComparisonResult } from "../sorting/_index.js";
 import TimeBase from "./TimeBase";
 import TimeDuration from "./TimeDuration";
 import { TTimeInstantBuilder, TTimeInstantCreationParameters, createTimeInstantFromParameters, timeInstantBuilder } from "./TimeInstantBuilder.js";
-import TimeUnit from "./TimeUnit";
+import { TimeUnit } from "./TimeUnit";
 import { TDayOfMonth, TDayOfWeek, TIso8601DateString, TIso8601DateUtcString, TMonth, TWeekNumber } from "./types";
 
 export class TimeInstant extends TimeBase<TimeInstant> {

package/src/time/TimeUnit.ts

@@ -1,5 +1,5 @@
 
-export default class TimeUnit {
+export class TimeUnit {
 
 	private constructor(
 		public readonly multiplier: number
@@ -29,15 +29,10 @@ export default class TimeUnit {
 		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

@@ -1,9 +1,10 @@
 
 export { default as RandomTimeDuration } from './RandomTimeDuration.js';
-export { TPredefinedTimeDuration, TValidTimeDuration, TimeDuration, isAllowedTimeDuration } from './TimeDuration.js';
+export * from './TimeBase.js';
+export { isAllowedTimeDuration, TimeDuration, TPredefinedTimeDuration, TValidTimeDuration } from './TimeDuration.js';
 export { default as TimeFrequency } from './TimeFrequency.js';
 export * from './TimeInstant.js';
 export * from './TimeRange.js';
-export { default as TimeUnit } from './TimeUnit.js';
+export * from './TimeUnit.js';
 export * from './types.js';
 

package/src/utils/errors.ts

@@ -17,14 +17,14 @@ export function isError( e: unknown ): e is Error {
 	return e instanceof Error;
 }
 
-export function printErrorMessage( error: Error ): string {
-	const maybeCause = error.cause ? printErrorMessage( asError( error.cause ) ) : null;
+export function getMessageFromError( error: Error ): string {
+	const maybeCause = error.cause ? getMessageFromError( asError( error.cause ) ) : null;
 	const cause = maybeCause ? `\ncaused by: ${maybeCause}` : '';
 	return `${error.name}: ${error.message}${cause}`;
 }
 
-export function printErrorStack( error: Error ): string {
-	const maybeCause = error.cause ? printErrorStack( asError( error.cause ) ) : null;
+export function getStackFromError( error: Error ): string {
+	const maybeCause = error.cause ? getStackFromError( asError( error.cause ) ) : null;
 	const cause = maybeCause ? `\ncaused by: ${maybeCause}` : '';
 	const stack = error.stack && error.stack.includes( error.message ) ? error.stack : error.message + ' ' + ( error.stack ?? '' );
 	return `${error.name}: ${stack}${cause}`;