@zelgadis87/utils-core 4.0.0

package/src/async/RateThrottler.ts

@@ -0,0 +1,46 @@
+import { TFunction, TimeInstant } from "..";
+import TimeFrequency from "../time/TimeFrequency";
+import Deferred from "./Deferred";
+
+type TPromiseFactory<T, R> = TFunction<T, Promise<R>>;
+
+export class RateThrottler {
+
+	private readonly _availableSlots: TimeInstant[];
+	private readonly _waitingRequests: Deferred<void>[];
+
+	constructor(
+		private readonly _frequency: TimeFrequency
+	) {
+		const initialOffset = this.cooldown.divideBy( _frequency.times );
+		this._availableSlots = new Array( _frequency.times ).fill( 0 ).map( ( _, i ) => TimeInstant.now().addMs( i * initialOffset.ms ) );
+		this._waitingRequests = [];
+	}
+
+	public get cooldown() {
+		return this._frequency.period;
+	}
+
+	public async execute<T>( fn: TPromiseFactory<void, T> ) {
+		const wrappedFn = async () => {
+			const slot = this._availableSlots.shift()!;
+			try {
+				return slot.promise().then( () => fn() );
+			} finally {
+				this._availableSlots.push( TimeInstant.now().addDuration( this.cooldown ) );
+				if ( this._waitingRequests.length > 0 ) this._waitingRequests.shift()!.resolve();
+			}
+		};
+		if ( this._availableSlots.length > 0 ) {
+			return wrappedFn();
+		} else {
+			// Semaphore implementation using promises.
+			const waitingRequest = new Deferred();
+			this._waitingRequests.push( waitingRequest );
+			return waitingRequest.then<T, T>( () => wrappedFn() );
+		}
+	}
+
+}
+
+export default RateThrottler;

package/src/async/Semaphore.ts

@@ -0,0 +1,45 @@
+import { TAsyncProducer, TProducer, TimeDuration } from "..";
+import Deferred from "./Deferred";
+
+export class Semaphore {
+
+	private readonly _waitingRequests: Deferred<void>[];
+
+	constructor(
+		private _availableSlots: number = 1
+	) {
+		this._waitingRequests = [];
+	}
+
+	private async _awaitSlot(): Promise<void> {
+		if ( this._availableSlots > 0 ) {
+			this._availableSlots -= 1;
+			return void 0;
+		} else {
+			// Semaphore implementation using promises.
+			const deferred = new Deferred();
+			this._waitingRequests.push( deferred );
+			return deferred.asPromise;
+		}
+	}
+
+	private _releaseSlot() {
+		const waitingSlotToResolve = this._waitingRequests.shift();
+		if ( waitingSlotToResolve ) {
+			waitingSlotToResolve.resolve();
+		} else {
+			this._availableSlots += 1;
+		}
+	}
+
+	public async execute<T>( fn: TAsyncProducer<T> | TProducer<T>, cooldown: TimeDuration = TimeDuration.ZERO ) {
+		return this._awaitSlot()
+			.then( () => fn() )
+			.finally( () => {
+				void cooldown.promise().then( () => this._releaseSlot() );
+			} );
+	}
+
+}
+
+export default Semaphore;

package/src/async/index.ts

@@ -0,0 +1,6 @@
+
+export * from './CancelableDeferred.ts';
+export * from './Deferred';
+export * from './RateThrottler';
+export * from './Semaphore';
+

package/src/index.ts

@@ -0,0 +1,13 @@
+
+export { default as Lazy } from './Lazy';
+export { default as LazyAsync } from './LazyAsync';
+export { default as Logger } from './Logger';
+export * from './Optional.js';
+export * from './async';
+export * from './random';
+export * from './sorting/index.js';
+export * from './time';
+export * from './types';
+export * from './upgrade';
+export * from './utils';
+

package/src/random/index.ts

@@ -0,0 +1,3 @@
+
+export { default as randomInterval } from './randomInterval';
+export { default as randomPercentage } from './randomPercentage';

package/src/random/randomInterval.ts

@@ -0,0 +1,4 @@
+
+export default function randomInterval( min: number, max: number ): number {
+	return Math.floor( Math.random() * ( max - min + 1 ) + min );
+}

package/src/random/randomPercentage.ts

@@ -0,0 +1,6 @@
+
+import randomInterval from "./randomInterval";
+
+export default function randomPercentage( min: number, max: number ): number {
+	return randomInterval( min, max ) / 100;
+}

package/src/sorting/ComparisonChain.ts

@@ -0,0 +1,209 @@
+import { TFunction, TKeysOfType, TReadableArray, isDefined, isNullOrUndefined } from "../types";
+import { identity } from "../utils/constant.js";
+import { TComparisonDirection, TComparisonFunction, TComparisonResult } from "./types.js";
+
+type TCompareValueOptions = {
+	nullsFirst: boolean;
+	direction: TComparisonDirection;
+}
+const defaultCompareValueOptions: TCompareValueOptions = {
+	nullsFirst: false,
+	direction: 'ASC',
+}
+
+type TLooseCompareValueOptions = Partial<TCompareValueOptions> | TComparisonDirection;
+
+function looseOptionsToStrict( x: TLooseCompareValueOptions | undefined ): TCompareValueOptions {
+	return { ...defaultCompareValueOptions, ...( typeof x === 'string' ? { direction: x } : x ) };
+}
+
+function compareValues<V>( a: V, b: V, options: Omit<TCompareValueOptions, "direction"> ): TComparisonResult {
+	if ( a === b )
+		return 0;
+
+	const nullA = ( a === null || a === undefined );
+	const nullB = ( b === null || b === undefined );
+	if ( nullA && nullB )
+		return 0;
+	if ( nullA !== nullB )
+		return ( nullA === options.nullsFirst ) ? -1 : 1;
+
+	// A & B are defined and are different.
+	return ( a < b ? -1 : 1 );
+}
+
+function compareFunction<T, V>( fn: TFunction<T, V>, options: TCompareValueOptions ): TComparisonFunction<T> {
+	return ( a: T, b: T ) => applyDirection( compareValues<V>( fn( a ), fn( b ), options ), options.direction );
+}
+
+function applyDirection( res: TComparisonResult, direction: TComparisonDirection ): TComparisonResult {
+	return res * ( direction === 'ASC' ? 1 : -1 ) as TComparisonResult
+}
+
+function compareUsingGetter<T>( getter: TFunction<T, string>, options?: TLooseCompareValueOptions ): TComparisonFunction<T>;
+function compareUsingGetter<T>( getter: TFunction<T, number>, options?: TLooseCompareValueOptions ): TComparisonFunction<T>;
+function compareUsingGetter<T>( getter: TFunction<T, Date>, options?: TLooseCompareValueOptions ): TComparisonFunction<T>;
+function compareUsingGetter<T>( getter: TFunction<T, string | number | Date>, options?: TLooseCompareValueOptions ): TComparisonFunction<T> {
+	return compareFunction( getter, looseOptionsToStrict( options ) )
+}
+
+function compareUsingField<T>( field: keyof T & TKeysOfType<T, string | number | Date>, options?: TLooseCompareValueOptions ): TComparisonFunction<T> {
+	return compareFunction( t => t[ field ], looseOptionsToStrict( options ) );
+}
+
+function compareUsingNaturalOrder<T>( options?: TLooseCompareValueOptions ): TComparisonFunction<T> {
+	return compareFunction( identity, looseOptionsToStrict( options ) );
+}
+
+function compareStrings( options?: TLooseCompareValueOptions & { ignoreCase?: boolean } ): TComparisonFunction<string> {
+	return compareFunction<string, string>( t => options?.ignoreCase === true ? t.toLowerCase() : t, looseOptionsToStrict( options ) );
+}
+
+function compareBooleans( options: Partial<TCompareValueOptions> & { truesFirst: boolean } ): TComparisonFunction<boolean> {
+	const opts = { ...defaultCompareValueOptions, ...options };
+	const fn: TComparisonFunction<boolean> = ( a: boolean, b: boolean ) => {
+		if ( a === b )
+			return 0 as const;
+		if ( isNullOrUndefined( a ) ) return opts.nullsFirst ? -1 : 1;
+		if ( isNullOrUndefined( b ) ) return opts.nullsFirst ? 1 : -1;
+		return ( ( a === true && opts.truesFirst ) || ( a === false && !opts.truesFirst ) ) ? -1 : 1;
+	}
+	return ( a, b ) => applyDirection( fn( a, b ), opts.direction );
+}
+
+function compareUsingFunction<T>( fn: TComparisonFunction<T> ): TComparisonFunction<T> {
+	return fn;
+}
+
+function compareUsingSet<T>( arr: Array<T> ): TComparisonFunction<T> {
+	const fn: TComparisonFunction<T> = ( a: T, b: T ) => {
+		if ( a === b )
+			return 0 as const;
+		const aIncluded = isDefined( a ) && arr.includes( a );
+		const bIncluded = isDefined( b ) && arr.includes( b );
+		if ( aIncluded === bIncluded ) {
+			return 0 as const;
+		} else {
+			return ( aIncluded ? -1 as const : 1 as const );
+		}
+	}
+	return fn;
+}
+
+function compareUsingArray<T>( arr: Array<T> ): TComparisonFunction<T> {
+	const fn: TComparisonFunction<T> = ( a: T, b: T ) => {
+		if ( a === b )
+			return 0 as const;
+		const aIncluded = isDefined( a ) && arr.includes( a );
+		const bIncluded = isDefined( b ) && arr.includes( b );
+		if ( !aIncluded && !bIncluded ) {
+			return 0 as const;
+		} else if ( aIncluded && bIncluded ) {
+			return ( arr.indexOf( a ) < arr.indexOf( b ) ? -1 as const : 1 as const );
+		} else {
+			return ( aIncluded ? -1 as const : 1 as const );
+		}
+	}
+	return fn;
+}
+
+function reverse<T>( fn: TComparisonFunction<T> ): TComparisonFunction<T> {
+	return ( a: T, b: T ) => fn( a, b ) * -1 as TComparisonResult;
+}
+
+/** 
+ * Creates a ComparisonChain V1.
+ * Usage: ComparisonChain.createWith<number>( c => c.compareUsingNumbers() ).sort( [ 100, 1, 10, 5 ] );
+ * @deprecated[2023-10-22]: Use createSorterFor instead.
+ **/
+export class ComparisonChain<T> {
+
+	private constructor(
+		private readonly _fns: TComparisonFunction<T>[],
+		private readonly _reversed: boolean = false
+	) {}
+
+	public compare = ( a: T, b: T ): TComparisonResult => {
+		return this.doCompare( a, b ) * ( this._reversed ? -1 : 1 ) as TComparisonResult;
+	}
+
+	public sort = <A extends TReadableArray<T>>( arr: A ): A extends Array<T> ? Array<T> : ReadonlyArray<T> => {
+		return [ ...arr ].sort( this.compare );
+	}
+
+	public then( getFn: ( compare: TChain<T> ) => TComparisonFunction<T> ): ComparisonChain<T> {
+		const cmp = getFn( createCompare<T>() );
+		return this.thenBy( cmp );
+	}
+
+	public thenBy( cmp: ComparisonChain<T> | TComparisonFunction<T> ): ComparisonChain<T> {
+		return new ComparisonChain<T>( [ ...this._fns, getComparisonFunction( cmp ) ] );
+	}
+
+	public thenChain<R>( transform: TFunction<T, R>, getFn: ( compare: TChain<R> ) => TComparisonFunction<R> ): ComparisonChain<T> {
+		const cmp = getFn( createCompare<R>() );
+		return this.thenChainBy( transform, cmp );
+	}
+
+	public thenChainBy<R>( transform: TFunction<T, R>, cmp: ComparisonChain<R> | TComparisonFunction<R> ): ComparisonChain<T> {
+		return new ComparisonChain<T>( [ ...this._fns, applyTransformationBeforeComparison( transform, getComparisonFunction( cmp ) ) ] );
+	}
+
+	public reversed(): ComparisonChain<T> {
+		return new ComparisonChain<T>( [ ...this._fns ], !this._reversed );
+	}
+
+	private doCompare( this: ComparisonChain<T>, a: T, b: T ): TComparisonResult {
+		return this._fns.reduce( ( ret: TComparisonResult, fn: TComparisonFunction<T> ) => {
+			return ret !== 0 ? ret : fn( a, b );
+		}, 0 );
+	}
+
+	public static create<T>() {
+		return {
+			using: ( getFn: ( chainable: TChain<T> ) => TComparisonFunction<T> ) => {
+				return new ComparisonChain<T>( [] ).then( getFn );
+			},
+			usingTransformation: <R>( transform: TFunction<T, R>, getFn: ( chainable: TChain<R> ) => TComparisonFunction<R> ) => {
+				return new ComparisonChain<T>( [] ).thenChain( transform, getFn );
+			},
+		}
+	}
+
+	public static createWith<T>( getFn: ( chainable: TChain<T> ) => TComparisonFunction<T> ) {
+		return this.create<T>().using( getFn );
+	}
+	
+	public static createWithTransformation<T, R>( transform: TFunction<T, R>, getFn: ( chainable: TChain<R> ) => TComparisonFunction<R> ) {
+		return this.create<T>().usingTransformation( transform, getFn );
+	}
+
+}
+export default ComparisonChain;
+
+function createCompare<T>() {
+	return {
+		compareUsingGetter: compareUsingGetter<T>,
+		compareUsingField: compareUsingField<T>,
+		compareUsingStrings: compareStrings,
+		compareUsingStringsIgnoringCase: ( options?: TLooseCompareValueOptions ) => compareStrings( { ...looseOptionsToStrict( options ), ignoreCase: true } ),
+		compareUsingBooleans: compareBooleans,
+		compareUsingNumbers: compareUsingNaturalOrder<number>,
+		compareUsingDates: compareUsingNaturalOrder<Date>,
+		compareUsingFunction: compareUsingFunction<T>,
+		placeFirst: ( arr: Array<T> ) => compareUsingSet( arr ),
+		placeFirstInOrder: ( arr: Array<T> ) => compareUsingArray( arr ),
+		placeLast: ( arr: Array<T> ) => reverse( compareUsingSet( arr ) ),
+		placeLastInOrder: ( arr: Array<T> ) => reverse( compareUsingArray( [ ...arr ].reverse() ) ),
+	} satisfies Record<string, ( ...args: any[] ) => TComparisonFunction<any>>;
+}
+
+function applyTransformationBeforeComparison<T, R>( transform: TFunction<T, R>, fn: TComparisonFunction<R> ): TComparisonFunction<T> {
+	return ( a: T, b: T ) => fn( transform( a ), transform( b ) );
+}
+
+function getComparisonFunction<T>( arg: ComparisonChain<T> | TComparisonFunction<T> ): TComparisonFunction<T> {
+	return ( arg instanceof ComparisonChain ) ? arg.compare : arg;
+}
+
+type TChain<T> = ReturnType<typeof createCompare<T>>