@zelgadis87/utils-core 5.0.3 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,

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/utils/arrays.ts

@@ -133,14 +133,32 @@ export function partition<T>( arr: T[], predicate: TPredicate<T> ): [ T[], T[] ]
  * @param mapFn - The mapping function.
  * @returns The first truthy value returned by the mapping function, or null if no truthy value is found.
  */
-export function mapFirstTruthy<T, R>(arr: T[], mapFn: TTransformer<T, R>): R | null {
-	for (let i = 0; i < arr.length; i++) {
-		const result = mapFn(arr[i]);
-		if (result) return result;
+export function mapFirstTruthy<T, R>( arr: T[], mapFn: TTransformer<T, R> ): R | null {
+	for ( let i = 0; i < arr.length; i++ ) {
+		const result = mapFn( arr[ i ] );
+		if ( result ) return result;
 	}
 	return null;
 }
 
-export function makeArrayEmpty( arr: unknown[] ): void {
-	arr.splice( 0, arr.length );
+export function listToDict<T, K extends string, V>( arr: T[], mapFn: TTransformer<T, [ K, V ]> ): Record<K, V> {
+	return arr.reduce( ( dict: Partial<Record<K, V>>, cur: T ) => {
+		const [ key, value ] = mapFn( cur );
+		return { ...dict, [ key ]: value };
+	}, {} satisfies Partial<Record<K, V>> );
+}
+
+export function countArrayBy<T, K extends string>( arr: T[], mapFn: TTransformer<T, K> ): Partial<Record<K, number>> {
+	return arr.reduce( ( dict: Partial<Record<K, number>>, cur: T ) => {
+		const value = mapFn( cur );
+		const count = ( dict[ value ] ?? 0 ) + 1;
+		return { ...dict, [ value ]: count };
+	}, {} satisfies Partial<Record<K, number>> );
+}
+
+export function sumArrayBy<T>( arr: T[], mapFn: TTransformer<T, number> ): number {
+	return arr.reduce( ( sum: number, cur: T ) => {
+		const value = mapFn( cur );
+		return sum + value;
+	}, 0 );
 }