@zelgadis87/utils-core 4.0.0

package/src/upgrade/getTransitionsPath.ts

@@ -0,0 +1,89 @@
+
+import { TMaybe } from "../types";
+import { TTransition, TTransitionMatrix, TUpgradable } from "./types";
+
+const DEBUG_ENABLED = false;
+
+export default function getTransitionsPath<
+	XStar extends TUpgradable,
+	XFromNumber extends XStar[ "$version" ],
+	XToNumber extends XStar[ "$version" ]
+>(
+	matrix: TTransitionMatrix<XStar>,
+	from: XFromNumber,
+	to: XToNumber
+): TMaybe<TTransition<XStar, XFromNumber, XToNumber>[]> {
+	return internalGetTransitionsPath( matrix, from, to, 0, DEBUG_ENABLED );
+}
+
+function internalGetTransitionsPath<
+	XStar extends TUpgradable,
+	XFromNumber extends XStar[ "$version" ],
+	XToNumber extends XStar[ "$version" ]
+>(
+	matrix: TTransitionMatrix<XStar>,
+	from: XFromNumber,
+	to: XToNumber,
+	depth: number,
+	debug: boolean,
+): TMaybe<TTransition<XStar, any, any>[]> {
+
+	debugLog( debug, depth, from, to, 'Search started.' );
+
+	const transitionsTo = matrix[ to ];
+	if ( !transitionsTo ) {
+		debugLog( debug, depth, from, to, 'No transitions available to this version' );
+		return null;
+	}
+
+	// Check if there is a transition that goes directly from from to to.
+	const exactTransition = transitionsTo[ from ];
+	if ( exactTransition ) {
+		debugLog( debug, depth, from, to, 'Found exact transition.' );
+		return [ exactTransition ];
+	}
+
+	// Otherwise, recursively search for the min path.
+	const keys = Object.keys( transitionsTo );
+	return keys.reduce( ( curBestPath: TMaybe<TTransition<XStar, any, any>[]>, transitionKey: string ) => {
+		const transition = transitionsTo[ transitionKey as unknown as XStar[ "$version" ] ]!;
+		const path = internalGetTransitionsPath( matrix, from, transition.from, depth + 1, debug );
+		if ( path === null ) {
+			debugLog( debug, depth + 1, from, transition.from, 'No path found.' );
+			return curBestPath;
+		} else {
+			if ( curBestPath === null || curBestPath.length > path.length + 1 ) {
+				debugLog( debug, depth + 1, from, transition.from, 'New best path found: ' + printTransitions( path ) );
+				return [ ...path, transition ];
+			} else {
+				return curBestPath;
+			}
+		}
+	}, null as TMaybe<TTransition<XStar, any, any>[]> );
+
+}
+
+function debugLog(
+	enabled: boolean,
+	depth: number,
+	from: number,
+	to: number,
+	message: string
+) {
+	if ( !enabled )
+		return;
+	// istanbul ignore next
+	// eslint-disable-next-line no-restricted-globals
+	console.info(
+		'#'.repeat( depth + 1 ),
+		from + ' -> ' + to,
+		message
+	);
+}
+
+function printTransitions( transitions: TTransition<any, any, any>[] ): string {
+	return transitions.reduce( ( ret, cur ) => {
+		return ret + " -> " + cur.to;
+	}, "" + transitions[ 0 ].from );
+}
+

package/src/upgrade/index.ts

@@ -0,0 +1,4 @@
+
+export * from './DataUpgrader';
+export type { TUpgradable } from './types';
+

package/src/upgrade/types.ts

@@ -0,0 +1,36 @@
+
+import { TFunction, TJsonObject, TPromisable } from "../types";
+
+export type TUpgradable = TJsonObject & { $version: number };
+
+export type TUpgradableAtVersion<XStar extends TUpgradable, N extends XStar[ "$version" ]> = Extract<XStar, { $version: N }>;
+
+export type TVersionMap<
+	XStar extends TUpgradable,
+> = {
+		[ XVersionNumber in XStar[ "$version" ] ]: TUpgradableAtVersion<XStar, XVersionNumber>;
+	}
+
+export type TPossibleVersion<XStar extends TUpgradable> = XStar[ "$version" ] & number;
+export type TPossibleFromVersion<XStar extends TUpgradable, XLatest extends XStar> = Exclude<TPossibleVersion<XStar>, XLatest[ "$version" ]>;
+export type TUpgradeFunction<
+	XStar extends TUpgradable,
+	XFrom extends XStar,
+	XTo extends XStar,
+> = TFunction<Readonly<TVersionMap<XStar>[ XFrom[ "$version" ] ]>, TPromisable<TVersionMap<XStar>[ XTo[ "$version" ] ]>>;
+export type TTransition<
+	XStar extends TUpgradable,
+	XFromNumber extends XStar[ "$version" ],
+	XToNumber extends XStar[ "$version" ],
+	XFrom extends Extract<XStar, { $version: XFromNumber }> = Extract<XStar, { $version: XFromNumber }>,
+	XTo extends Extract<XStar, { $version: XToNumber }> = Extract<XStar, { $version: XToNumber }>,
+> = {
+	from: XFromNumber;
+	to: XToNumber;
+	apply: TUpgradeFunction<XStar, XFrom, XTo>;
+};
+export type TTransitionMatrix<XStar extends TUpgradable> = Partial<{
+	[ XTo in XStar[ "$version" ] ]: Partial<{
+		[ XFrom in XStar[ "$version" ] ]: TTransition<XStar, XFrom, XTo>
+	}>
+}>;

package/src/utils/asError.ts

@@ -0,0 +1,12 @@
+
+export default function asError( e: unknown ): Error {
+	if ( e === undefined || e === null )
+		return new Error( 'Void message' );
+	if ( e instanceof Error )
+		return e;
+	if ( typeof e === 'string' )
+		return new Error( e );
+	if ( e instanceof String )
+		return new Error( e.toString() );
+	return new Error( JSON.stringify( e ) );
+}

package/src/utils/bindThis.ts

@@ -0,0 +1,4 @@
+
+export default function bindThis<F extends Function>( this: void, fn: F, _this: object ): F { // eslint-disable-line @typescript-eslint/no-unsafe-function-type
+	return fn.bind( _this );
+}

package/src/utils/constant.ts

@@ -0,0 +1,9 @@
+export function constant<T>( v: T ): () => T { return () => v; }
+export function identity<T>( t: T ) { return t; }
+export default constant;
+
+export const constantNull = constant( null );
+export const constantTrue = constant( true );
+export const constantFalse = constant( false );
+export const constantZero = constant( 0 );
+export const constantOne = constant( 1 );

package/src/utils/entries.ts

@@ -0,0 +1,13 @@
+import { TFunction } from "../types";
+
+export function dictToEntries<V, K extends string = string>( obj: Record<K, V> ): [K, V][] {
+	return Object.entries( obj ) as [K, V][];
+}
+
+export function entriesToDict<V, K extends string = string>( entries: [K, V][] ): Record<K, V> {
+	return Object.fromEntries( entries ) as Record<K, V>;
+}
+
+export function mapEntries<K1 extends string, V1, K2 extends string, V2>( dict: Record<K1, V1>, mapper: TFunction<[K1, V1], [K2, V2]> ): Record<K2, V2> {
+	return entriesToDict( dictToEntries( dict ).map( ( entry ) => mapper( entry ) ) );
+}

package/src/utils/groupBy.ts

@@ -0,0 +1,39 @@
+
+import { TFunction, TKeysOfType } from "../types";
+
+export function groupByString<V, K extends TKeysOfType<V, string>>( arr: 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[]> {
+	return groupByNumberWith( arr, t => t[ field ] as number );
+}
+
+export function groupBySymbol<V, K extends TKeysOfType<V, symbol>>( arr: 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[]> {
+	return doGroupByWith<K, V>( arr, getter );
+}
+
+export function groupByNumberWith<V, K extends number>( arr: V[], getter: TFunction<V, K> ): Record<K, V[]> {
+	return doGroupByWith<K, V>( arr, getter );
+}
+
+export function groupBySymbolWith<V, K extends symbol>( arr: 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 ) => {
+		const key = getter( cur );
+		if ( key !== null && key !== undefined ) {
+			const arr = dict[ key ] ?? [];
+			arr.push( cur );
+			dict[ key ] = arr;
+		}
+		return dict;
+	}, {} as Record<K, V[]> );
+}
+

package/src/utils/iff.ts

@@ -0,0 +1,26 @@
+import { TPredicate } from "../types";
+
+type TBooleanOrPredicate = boolean | TPredicate<void>;
+type TIff<T> = {
+	elseIf<R>( pred: TBooleanOrPredicate, valueIfTrue: R ): TIff<T | R>;
+	otherwise<R>( valueIfElse: R ): T | R;
+}
+
+export default function iff<T>( firstPredicate: TBooleanOrPredicate, valueIfTrue: T ) {
+
+	if ( firstPredicate === true || ( firstPredicate instanceof Function && firstPredicate() === true ) ) {
+		const ret: TIff<T> = {
+			elseIf: () => ret,
+			otherwise: () => valueIfTrue
+		};
+		return ret;
+	} else {
+		const ret: TIff<T> = {
+			elseIf: <R>( elseIf: TBooleanOrPredicate, valueIfElseIfTrue: R ) => iff<R>( elseIf, valueIfElseIfTrue ),
+			otherwise: <R>( valueIfElse: R ) => valueIfElse
+		};
+		return ret;
+	}
+
+}
+

package/src/utils/index.ts

@@ -0,0 +1,24 @@
+
+export { default as asError } from './asError';
+export { default as bindThis } from './bindThis';
+export * from './constant.js';
+export * from './entries.js';
+export * from './groupBy.js';
+export { default as iff } from './iff';
+export * from './indexBy.js';
+export { default as jsonCloneDeep } from './jsonCloneDeep';
+export * from './math.js';
+export { default as noop } from './noop';
+export { default as omit } from './omit';
+export { default as pad } from './pad';
+export { default as pluralize } from './pluralize';
+export * from './round.js';
+export { default as sortBy } from './sortBy';
+export { default as throttle } from './throttle';
+export { default as uniq } from './uniq';
+export { default as uniqBy } from './uniqBy';
+export { default as uniqByKey } from './uniqByKey';
+export { default as withTryCatch } from './withTryCatch';
+export { default as withTryCatchAsync } from './withTryCatchAsync';
+export { default as wrap } from './wrap';
+

package/src/utils/indexBy.ts

@@ -0,0 +1,36 @@
+
+import { TFunction, TKeysOfType } from "../types";
+
+export function indexByString<V, K extends TKeysOfType<V, string>>( arr: V[], field: K ): Record<V[K] & string, V> {
+	return indexByStringWith( arr, t => t[ field ] as string );
+}
+
+export function indexByNumber<V, K extends TKeysOfType<V, number>>( arr: V[], field: K ): Record<V[K] & number, V> {
+	return indexByNumberWith( arr, t => t[ field ] as number );
+}
+
+export function indexBySymbol<V, K extends TKeysOfType<V, symbol>>( arr: V[], field: K ): Record<V[K] & symbol, V> {
+	return indexBySymbolWith( arr, t => t[ field ] as symbol );
+}
+
+export function indexByStringWith<V>( arr: V[], getter: TFunction<V, string> ): Record<string, V> {
+	return doIndexByWith<string, V>( arr, getter );
+}
+
+export function indexByNumberWith<V>( arr: V[], getter: TFunction<V, number> ): Record<number, V> {
+	return doIndexByWith<number, V>( arr, getter );
+}
+
+export function indexBySymbolWith<V>( arr: V[], getter: TFunction<V, symbol> ): Record<symbol, V> {
+	return doIndexByWith<symbol, V>( arr, getter );
+}
+
+function doIndexByWith<K extends string | number | symbol, V>( arr: V[], getter: TFunction<V, K> ): Record<K, V> {
+	return arr.reduce( ( dict, cur ) => {
+		const key = getter( cur );
+		if ( key !== null && key !== undefined )
+			dict[ key ] = cur;
+		return dict;
+	}, {} as Record<K, V> );
+}
+

package/src/utils/jsonCloneDeep.ts

@@ -0,0 +1,31 @@
+import { TJsonObject, TJsonSerializable } from "../types";
+
+export default function jsonCloneDeep<A extends TJsonSerializable>( a: A ): A {
+
+	// Handle the 3 simple types, and null or undefined
+	if ( null === a || "object" !== typeof a ) return a;
+
+	if ( a instanceof Date ) {
+		// Handle Date
+		return new Date( a.getTime() ) as unknown as A;
+	} else if ( a instanceof Array ) {
+		// Handle Array
+		const copy = [] as unknown[];
+		for ( let i = 0, len = a.length; i < len; i++ ) {
+			copy[ i ] = jsonCloneDeep( a[ i ] );
+		}
+		return copy as A;
+	} else if ( a instanceof Object ) {
+		// Handle Object
+		const copy = {} as Record<string | number | symbol, unknown>;
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+		for ( let attr in ( a as TJsonObject ) ) {
+			if ( a.hasOwnProperty( attr ) )
+				copy[ attr ] = jsonCloneDeep( a[ attr ] );
+		}
+		return copy as A;
+	}
+
+	throw new Error( "Unable to copy obj! Its type isn't supported." );
+
+}

package/src/utils/math.ts

@@ -0,0 +1,44 @@
+import { TReadableArray } from "../types/arrays.js";
+
+export function clamp( n: number, min: number, max: number ): number {
+	if ( min === null || max === null || n === null || isNaN( min ) || isNaN( max ) || isNaN( n ) || min > max )
+		throw new Error();
+	if ( n > max ) {
+		return max;
+	} else if ( n < min ) {
+		return min;
+	} else {
+		return n;
+	}
+}
+
+export function average( arr: TReadableArray<number> ): number {
+	const f = 1 / arr.length;
+	return arr.reduce( ( tot, cur ) => tot + ( cur * f ), 0 );
+}
+
+export function sum( arr: TReadableArray<number> ): number {
+	return arr.reduce( ( tot, cur ) => tot + cur, 0 );
+}
+
+export function sumBy<T>( arr: TReadableArray<T>, getter: ( t: T ) => number ): number {
+	return sum( arr.map( getter ) );
+}
+
+export function min( arr: TReadableArray<number> ): number {
+	if ( arr.length === 0 ) throw new Error( 'Cannot calculate value on empty array' );
+	return arr.reduce( ( min, cur ) => cur < min ? cur : min );
+}
+
+export function minBy<T>( arr: TReadableArray<T>, getter: ( t: T ) => number ): number {
+	return min( arr.map( getter ) );
+}
+
+export function max( arr: TReadableArray<number> ): number {
+	if ( arr.length === 0 ) throw new Error( 'Cannot calculate value on empty array' );
+	return arr.reduce( ( max, cur ) => cur > max ? cur : max );
+}
+
+export function maxBy<T>( arr: TReadableArray<T>, getter: ( t: T ) => number ): number {
+	return max( arr.map( getter ) );
+}

package/src/utils/noop.ts

@@ -0,0 +1,2 @@
+export default function noop(): void { } // eslint-disable-line @typescript-eslint/no-empty-function
+

package/src/utils/omit.ts

@@ -0,0 +1,8 @@
+import { TJsonObject } from "../types";
+
+export default function omit<T extends TJsonObject, K extends keyof T>( o: T, ...keys: K[] ): Omit<T, K> {
+	return keys.reduce( ( obj, key ) => {
+		delete obj[ key ];
+		return obj;
+	}, { ...o } );
+}

package/src/utils/pad.ts

@@ -0,0 +1,20 @@
+import { ensureDefined } from "../types/nulls.js";
+import { repeat } from "../types/strings.js";
+
+export default function pad( str: string, n: number, char: string, where: 'left' | 'right' = 'left' ): string {
+	const length = ensureDefined( str ).length;
+	if ( length >= ensureDefined( n ) ) return str;
+
+	if ( ensureDefined( char ).length !== 1 )
+		throw new Error( 'Illegal pad character' );
+	const padding = repeat( char, n - length );
+	return ( where === 'left' ? padding : '' ) + str + ( where === 'right' ? padding : '' );
+}
+
+export function padLeft( str: string, n: number, char: string ): string {
+	return pad( str, n, char, 'left' );
+}
+
+export function padRight( str: string, n: number, char: string ): string {
+	return pad( str, n, char, 'right' );
+}

package/src/utils/pluralize.ts

@@ -0,0 +1,20 @@
+
+export default function pluralize( n: number, singular: string, plural?: string ): string {
+
+	if ( !singular || !singular.length )
+		throw new Error();
+	if ( n === 1 )
+		return singular;
+
+	plural = plural ?? singular + 's';
+
+	const firstUppercase = singular.charAt( 0 ) === singular.charAt( 0 ).toUpperCase();
+	if ( firstUppercase ) {
+		const PLURAL = plural.toUpperCase();
+		const isAllUppercase = plural === PLURAL;
+		plural = isAllUppercase ? PLURAL : plural.charAt( 0 ).toUpperCase() + plural.slice( 1 ).toLowerCase();
+	}
+
+	return plural;
+
+}

package/src/utils/round.ts

@@ -0,0 +1,24 @@
+
+type TRoundMode = 'toNearest' | 'toLower' | 'toUpper' | 'towardsZero' | 'awayFromZero';
+type TIntegerNumber = number;
+
+const roundModes: Record<TRoundMode, ( n: number ) => TIntegerNumber> = {
+	'toNearest': Math.round,
+	'toLower': Math.floor,
+	'toUpper': Math.ceil,
+	'towardsZero': n => n > 0 ? Math.floor( n ) : Math.ceil( n ),
+	'awayFromZero': n => n > 0 ? Math.ceil( n ) : Math.floor( n ),
+};
+
+export function round( n: number, precision: number = 0, mode: TRoundMode = 'toNearest' ) {
+	const base = 10;
+	const power = Math.pow( base, precision );
+	return roundModes[ mode ]( n * power ) / power;
+}
+export default round;
+export const roundToNearest = ( n: number, precision: number = 0 ) => round( n, precision, 'toNearest' );
+export const roundToLower = ( n: number, precision: number = 0 ) => round( n, precision, 'toLower' );
+export const roundToUpper = ( n: number, precision: number = 0 ) => round( n, precision, 'toUpper' );
+export const roundTowardsZero = ( n: number, precision: number = 0 ) => round( n, precision, 'towardsZero' );
+export const roundAwayFromZero = ( n: number, precision: number = 0 ) => round( n, precision, 'awayFromZero' );
+

package/src/utils/sortBy.ts

@@ -0,0 +1,27 @@
+import { TFunction, TKeysOfType } from "../types";
+
+type TKeyOrGetter<T> = T extends Record<string, unknown> ? TKeysOfType<T, number> & keyof T | TFunction<T, number | null> : TFunction<T, number | null>; 
+
+/**
+ * @deprecated[2023-11-01]: Use {@link Sorter} instead.
+ */
+export default function sortBy<T>( keyOrGetter: TKeyOrGetter<T>, direction: 'ASC' | 'DESC' = 'ASC', nulls: 'FIRST' | 'LAST' = 'LAST' ) {
+	const directionNum = direction === 'ASC' ? -1 : 1;
+	const nullsNum = nulls === 'LAST' ? -1 : 1;
+	const sortByNum = ( a: number | null | undefined, b: number | null | undefined ) => {
+		if ( a === b )
+			return -1;
+		const aDefined = !( a === null || a === undefined || isNaN( a ) );
+		const bDefined = !( b === null || b === undefined || isNaN( b ) );
+		if ( !aDefined && !bDefined )
+			return -1;
+		if ( aDefined !== bDefined )
+			return nullsNum * ( aDefined ? 1 : -1 );
+		return ( a! > b! ? -1 : 1 ) * directionNum;
+	}
+	if ( typeof keyOrGetter === "function" ) {
+		return ( a: T, b: T ) => sortByNum( keyOrGetter( a ), keyOrGetter( b ) );
+	} else {
+		return ( a: T, b: T ) => sortByNum( a[ keyOrGetter as keyof T ] as number, b[ keyOrGetter as keyof T ] as number );
+	}
+}

package/src/utils/throttle.ts

@@ -0,0 +1,10 @@
+import { RateThrottler } from "../async";
+import TimeFrequency from "../time/TimeFrequency";
+import { TPromisable } from "../types";
+
+export default function throttle<TParams extends unknown[], R>( fn: (...params: TParams) => TPromisable<R>, frequence: TimeFrequency ): (...params: TParams) => Promise<R> {
+	const semaphore = new RateThrottler( frequence );
+	return (...t: TParams): Promise<R> => {
+		return semaphore.execute<R>( async () => fn( ...t ) );
+	};
+}

package/src/utils/uniq.ts

@@ -0,0 +1,6 @@
+import { identity } from "./constant.js";
+import uniqBy from "./uniqBy";
+
+export default function uniq<T>( arr: T[] ): T[] {
+	return uniqBy( arr, identity );
+}

package/src/utils/uniqBy.ts

@@ -0,0 +1,15 @@
+import { TFunction } from "../types";
+
+export default function uniqBy<T, K>( arr: T[], getter: TFunction<T, K> ): T[] {
+	return arr.reduce( ( dict, cur ) => {
+		const key = getter( cur );
+		if ( dict.keys.includes( key ) ) {
+			return dict;
+		} else {
+			return {
+				keys: [ ...dict.keys, key ],
+				values: [ ...dict.values, cur ]
+			};
+		}
+	}, { keys: [], values: [] } as { keys: K[], values: T[] } ).values;
+}

package/src/utils/uniqByKey.ts

@@ -0,0 +1,5 @@
+import uniqBy from "./uniqBy";
+
+export default function uniqByKey<T, K extends keyof T>( arr: T[], key: K ): T[] {
+	return uniqBy( arr, item => item[ key ] );
+}

package/src/utils/upsert.ts

@@ -0,0 +1,2 @@
+
+

package/src/utils/withTryCatch.ts

@@ -0,0 +1,10 @@
+import { TFunction } from "../types";
+import asError from "./asError";
+
+export default function withTryCatch<R>( fn: TFunction<void, R> ): R | Error {
+	try {
+		return fn();
+	} catch ( e: unknown ) {
+		return asError( e );
+	}
+}

package/src/utils/withTryCatchAsync.ts

@@ -0,0 +1,6 @@
+import { TFunction } from "../types";
+import asError from "./asError";
+
+export default async function withTryCatchAsync<R>( fn: TFunction<void, Promise<R>> ): Promise<R | Error> {
+	return fn().catch( ( e: unknown ) => asError( e ) );
+}

package/src/utils/wrap.ts

@@ -0,0 +1,4 @@
+
+export default function wrap( str: string, delimiter: string ): string {
+	return delimiter + str + delimiter;
+}