@zelgadis87/utils-core 4.3.5 → 4.4.1

package/package.json

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

package/src/Logger.ts

@@ -1,5 +1,5 @@
 import TimeInstant from "./time/TimeInstant";
-import noop from "./utils/noop";
+import { noop } from "./utils/index.js";
 
 const LEVELS = [ "log", "debug", "info", "warn", "error" ] as const;
 type TLogLevel = keyof Console & typeof LEVELS[ number ]

package/src/Optional.ts

@@ -1,5 +1,5 @@
-import { TConsumer, TFunction, TPredicate, TProducer, TVoidFunction } from "./types/functions.js";
-import { isDefined, isNullOrUndefined } from "./types/nulls.js";
+import { TConsumer, TFunction, TPredicate, TProducer, TVoidFunction } from "./utils/functions.js";
+import { isDefined, isNullOrUndefined } from "./utils/nulls.js";
 
 export class Optional<T> implements TOptional<T> {
 

package/src/async/Deferred.ts

@@ -1,4 +1,4 @@
-import { TFunction } from "../types/functions.js";
+import { TFunction } from "../utils/functions.js";
 
 type DeferredInternals<T> = {
 	promise: Promise<T>;

package/src/async/RateThrottler.ts

@@ -1,4 +1,4 @@
-import { TFunction, TimeInstant } from "..";
+import { TFunction, TimeInstant, TPromisable } from "..";
 import TimeFrequency from "../time/TimeFrequency";
 import Deferred from "./Deferred";
 
@@ -44,3 +44,10 @@ export class RateThrottler {
 }
 
 export default RateThrottler;
+
+export 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/async/index.ts

@@ -4,3 +4,4 @@ export * from './Deferred';
 export * from './RateThrottler';
 export * from './Semaphore';
 
+

package/src/index.ts

@@ -1,13 +1,10 @@
 
-export { default as Lazy } from './Lazy';
-export { default as LazyAsync } from './LazyAsync';
+export * from './async/index.js';
+export * from './lazy/index.js';
 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';
+export * from './time/index.js';
+export * from './upgrade/index.js';
+export * from './utils/index.js';
 

package/src/{Lazy.ts → lazy/Lazy.ts}

@@ -1,12 +1,12 @@
 
-import { ensureDefined } from "./types";
+import { ensureDefined } from "../utils";
 
 /**
  * Class that stores a value that is computationally/memory intensive to initialize.
  * The initialization of the value is done once and only if required (lazy initialization).
  * @author gtomberli
  */
-export default class Lazy<T> {
+export class Lazy<T> {
 
 	private _value: T | undefined = undefined;
 	private _initialized: boolean = false;
@@ -75,3 +75,5 @@ export default class Lazy<T> {
 	}
 
 }
+
+export default Lazy;

package/src/{LazyAsync.ts → lazy/LazyAsync.ts}

@@ -1,6 +1,6 @@
-import { ensureDefined } from "./types/nulls.js";
+import { ensureDefined } from "../utils/nulls.js";
 
-export default class LazyAsync<T> {
+export class LazyAsync<T> {
 
 	private _promise: Promise<T> | undefined = undefined;
 	private _pending: boolean = false;
@@ -98,3 +98,5 @@ export default class LazyAsync<T> {
 	}
 
 }
+
+export default LazyAsync;

package/src/lazy/index.ts

@@ -0,0 +1,3 @@
+
+export * from './Lazy.js';
+export * from './LazyAsync.js';

package/src/sorting/ComparisonChain.ts

@@ -1,5 +1,5 @@
-import { TFunction, TKeysOfType, TReadableArray, isDefined, isNullOrUndefined } from "../types";
-import { identity } from "../utils/constant.js";
+import { identity } from "../utils/functions/constant.js";
+import { TFunction, TKeysOfType, TReadableArray, isDefined, isNullOrUndefined } from "../utils/index.js";
 import { TComparisonDirection, TComparisonFunction, TComparisonResult } from "./types.js";
 
 type TCompareValueOptions = {

package/src/sorting/Sorter.ts

@@ -1,5 +1,5 @@
-import { TBiFunction, TConditionalParameterOptions, TFunction, TKeysOfType, TPositiveNumber, TReadableArray, isDefined, isNullOrUndefined } from "../types";
-import { identity } from "../utils/constant.js";
+import { identity } from "../utils/functions/constant.js";
+import { TBiFunction, TConditionalParameterOptions, TFunction, TKeysOfType, TPositiveNumber, TReadableArray, isDefined, isNullOrUndefined } from "../utils/index.js";
 import { TComparisonDirection, TComparisonFunction, TComparisonResult, TStrictComparisonResult } from "./types.js";
 
 type TCompareValuesOptions = {

package/src/sorting/types.ts

@@ -1,4 +1,4 @@
-import { TBiFunction } from "../types/functions.js";
+import { TBiFunction } from "../utils/functions.js";
 
 
 export type TComparisonResult = -1 | 0 | 1;

package/src/time/RandomTimeDuration.ts

@@ -1,4 +1,4 @@
-import randomInterval from "../random/randomInterval.js";
+import { randomInterval } from "../utils/random.js";
 import TimeDuration from "./TimeDuration.js";
 import TimeUnit from "./TimeUnit.js";
 

package/src/time/TimeDuration.ts

@@ -1,7 +1,6 @@
 import Deferred, { DeferredCanceledError, ICancelable, ICancelablePromise } from "../async/Deferred.js";
-import { randomInterval } from "../random";
 import { TComparisonResult } from "../sorting/index.js";
-import { TIntervalHandle, TMaybe, TTimeoutHandle, ensureNonNegativeNumber, ensurePositiveNumber, pad } from "../types";
+import { TIntervalHandle, TMaybe, TTimeoutHandle, ensureNonNegativeNumber, ensurePositiveNumber, pad, randomInterval } from "../utils/index.js";
 import TimeBase from "./TimeBase";
 import TimeInstant from "./TimeInstant";
 import TimeUnit from "./TimeUnit";

package/src/time/TimeFrequency.ts

@@ -1,4 +1,4 @@
-import { TPositiveNumber } from "../types";
+import { TPositiveNumber } from "../utils";
 import TimeDuration from "./TimeDuration";
 
 export default class TimeFrequency {

package/src/time/TimeInstantBuilder.ts

@@ -1,6 +1,6 @@
 
-import { TFunction } from "../types/functions.js";
-import { ensureDefined } from "../types/nulls.js";
+import { TFunction } from "../utils/functions.js";
+import { ensureDefined } from "../utils/nulls.js";
 import { TimeInstant, isTimeInstant } from "./TimeInstant.js";
 import { TDayOfMonth, THourOfDay, TMillisecondOfSecond, TMinuteOfHour, TMonth, TSecondOfMinute, TUpToTwoDigits } from "./types.js";
 

package/src/time/TimeRange.ts

@@ -1,5 +1,5 @@
-import { TimeDuration } from "./index.ts";
-import TimeInstant from "./TimeInstant.ts";
+import { TimeDuration } from "./index.js";
+import TimeInstant from "./TimeInstant.js";
 
 export class TimeRange {
 

package/src/time/types.ts

@@ -1,4 +1,4 @@
-import { TDigit, TDigit1_9, TNumber0_1000, TParseableInt } from "../types";
+import { TDigit, TDigit1_9, TNumber0_1000, TParseableInt } from "../utils";
 
 export type TOneDigit = `${TDigit}`;
 export type TTwoDigits = `${TDigit}${TDigit}`;

package/src/upgrade/DataUpgrader.ts

@@ -1,6 +1,6 @@
 
-import { isDefined, isNumber, isPositiveNumber, TJsonSerializable } from "../types/index.ts";
 import { jsonCloneDeep } from "../utils";
+import { isDefined, isNumber, isPositiveNumber, TJsonSerializable } from "../utils/index.js";
 import { EmptyUpgradeError, UnavailableUpgradeError } from "./errors";
 import getTransitionsPath from "./getTransitionsPath";
 import { TPossibleFromVersion, TPossibleVersion, TTransitionMatrix, TUpgradable, TUpgradeFunction, TVersionMap } from "./types";

package/src/upgrade/getTransitionsPath.ts

@@ -1,5 +1,5 @@
 
-import { TMaybe } from "../types";
+import { TMaybe } from "../utils";
 import { TTransition, TTransitionMatrix, TUpgradable } from "./types";
 
 const DEBUG_ENABLED = false;

package/src/upgrade/types.ts

@@ -1,5 +1,5 @@
 
-import { TFunction, TJsonObject, TPromisable } from "../types";
+import { TFunction, TJsonObject, TPromisable } from "../utils";
 
 export type TUpgradable = TJsonObject & { $version: number };
 

package/src/utils/{groupBy.ts → arrays/groupBy.ts}

@@ -1,5 +1,5 @@
 
-import { TFunction, TKeysOfType } from "../types";
+import { TFunction, TKeysOfType } from "..";
 
 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 );

package/src/utils/{indexBy.ts → arrays/indexBy.ts}

@@ -1,5 +1,5 @@
 
-import { TFunction, TKeysOfType } from "../types";
+import { TFunction, TKeysOfType } from "..";
 
 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 );

package/src/utils/{math.ts → arrays/statistics.ts}

@@ -1,16 +1,4 @@
-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;
-	}
-}
+import type { TReadableArray } from "../arrays.js";
 
 export function average( arr: TReadableArray<number> ): number {
 	const f = 1 / arr.length;

package/src/utils/arrays/uniqBy.ts

@@ -0,0 +1,24 @@
+
+import { TFunction, identity } from "../functions.js";
+
+export function uniq<T>( arr: T[] ): T[] {
+	return uniqBy( arr, identity );
+}
+
+export 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;
+}
+
+export function uniqByKey<T, K extends keyof T>( arr: T[], key: K ): T[] {
+	return uniqBy( arr, item => item[ key ] );
+}

package/src/{types → utils}/arrays.ts

@@ -1,6 +1,11 @@
-import { TComparisonFunction } from "../sorting/index.js";
-import { TBiPredicate } from "./functions.js";
-import { TMaybe } from "./nulls.js";
+import type { TComparisonFunction } from "../sorting/index.js";
+import type { TBiPredicate } from "./functions.js";
+import type { TMaybe } from "./nulls.js";
+
+export * from './arrays/groupBy.js';
+export * from './arrays/indexBy.js';
+export * from './arrays/statistics.js';
+export * from './arrays/uniqBy.js';
 
 export type TReadableArray<T> = Array<T> | ReadonlyArray<T>;
 export type TArrayable<T> = T | T[];
@@ -67,12 +72,16 @@ export function reverse<T>( arr: TReadableArray<T> ): Array<T> {
 	return [ ...arr ].reverse();
 }
 
-export function head<T>( arr: TReadableArray<T>, defaultValue: TMaybe<T> = null ): TMaybe<T> {
+export function first<T>( arr: TReadableArray<T>, defaultValue: TMaybe<T> = null ): TMaybe<T> {
 	return ( arr.length ? arr[ 0 ] : defaultValue );
 }
-
 export function last<T>( arr: TReadableArray<T>, defaultValue: TMaybe<T> = null ): TMaybe<T> {
-	return head( reverse( arr ), defaultValue );
+	return( arr.length ? arr[ arr.length - 1 ] : defaultValue );
+}
+
+export const head = first;
+export function tail<T>( arr: TReadableArray<T> ): T[] {
+	return( arr.length ? arr.slice( 1 ) : [] );
 }
 
 export function sortedArray<T>( arr: Array<T>, sortFn?: TComparisonFunction<T> | undefined ): Array<T>;

package/src/utils/errors/withTryCatch.ts

@@ -0,0 +1,15 @@
+
+import { asError } from "../errors.js";
+import type { TFunction } from "../functions.js";
+
+export function withTryCatch<R>( fn: TFunction<void, R> ): [ R, undefined ] | [ undefined, Error ] {
+	try {
+		return [ fn(), void 0 ] as const;
+	} catch ( e: unknown ) {
+		return [ void 0, asError( e ) ] as const;
+	}
+}
+
+export async function withTryCatchAsync<R>( fn: TFunction<void, Promise<R>> ): Promise<[ R, undefined ] | [ undefined, Error ]> {
+	return fn().then( ( value: R ) => [ value, void 0 ] as const, ( e: unknown ) => [ void 0, asError( e ) ] as const );
+}

package/src/{types → utils}/errors.ts

@@ -1,4 +1,6 @@
 
+export * from './errors/withTryCatch.js';
+
 export function asError( e: unknown ): Error {
 	if ( e === undefined || e === null )
 		return new Error( 'Void message' );

package/src/utils/functions/bindThis.ts

@@ -0,0 +1,4 @@
+
+export 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/{iff.ts → functions/iff.ts}

@@ -1,4 +1,4 @@
-import { TPredicate } from "../types";
+import { TPredicate } from "..";
 
 type TBooleanOrPredicate = boolean | TPredicate<void>;
 type TIff<T> = {
@@ -6,7 +6,7 @@ type TIff<T> = {
 	otherwise<R>( valueIfElse: R ): T | R;
 }
 
-export default function iff<T>( firstPredicate: TBooleanOrPredicate, valueIfTrue: T ) {
+export function iff<T>( firstPredicate: TBooleanOrPredicate, valueIfTrue: T ): TIff<T> {
 
 	if ( firstPredicate === true || ( firstPredicate instanceof Function && firstPredicate() === true ) ) {
 		const ret: TIff<T> = {
@@ -24,3 +24,5 @@ export default function iff<T>( firstPredicate: TBooleanOrPredicate, valueIfTrue
 
 }
 
+export default iff;
+

package/src/{types → utils}/functions.ts

@@ -1,4 +1,8 @@
 
+export * from './functions/bindThis.js';
+export * from './functions/constant.js';
+export * from './functions/iff.js';
+
 export type TFunction<A, R> = ( a: A ) => R;
 export type TVoidFunction = TFunction<void, void>
 export type TProducer<R> = TFunction<void, R>;
@@ -25,3 +29,5 @@ export type TAsyncAnyFunction<R> = ( ...args: unknown[] ) => Promise<R>;
 export function isFunction( t: unknown ): t is Function { // eslint-disable-line @typescript-eslint/no-unsafe-function-type
 	return typeof t === 'function';
 }
+
+export function noop(): void { } // eslint-disable-line @typescript-eslint/no-empty-function

package/src/utils/index.ts

@@ -1,21 +1,15 @@
 
-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 * 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';
+export * from './arrays.js';
+export * from './booleans.js';
+export * from './empties.js';
+export * from './errors.js';
+export * from './functions.js';
+export * from './json.js';
+export * from './nulls.js';
+export * from './numbers.js';
+export * from './primitives.js';
+export * from './promises.js';
+export * from './random.js';
+export * from './records.js';
+export * from './strings.js';
 

package/src/utils/json.ts

@@ -0,0 +1,49 @@
+import { withTryCatch } from "./errors.js";
+
+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, undefined ] | [ undefined, Error ] {
+	return withTryCatch( () => JSON.parse( jsonContent ) as T );
+}
+
+export 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." );
+
+}
+
+export function omitFromJsonObject<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 } );
+}
+/** @deprecated[2024-12-23]: Use {@link omitFromJsonObject} instead. */
+export const omit = omitFromJsonObject;

package/src/utils/{round.ts → numbers/round.ts}

@@ -15,6 +15,7 @@ export function round( n: number, precision: number = 0, mode: TRoundMode = 'toN
 	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' );

package/src/{types → utils}/numbers.ts

@@ -1,5 +1,7 @@
-import { TFunction } from "./functions.js";
 
+import type { TFunction } from "./functions.js";
+
+export * from './numbers/round.js';
 
 export type TNumericString = `${number}`;
 export type TNumericFloatingPointString = `${number}.${number}`;
@@ -78,3 +80,15 @@ export function isNegativeNumber( v: number ): v is TNegativeNumber {
 export function isZero( v: number ): v is TZero {
 	return v === 0;
 }
+
+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;
+	}
+}

package/src/utils/primitives.ts

@@ -0,0 +1,5 @@
+
+export type TTimeoutHandle = ReturnType<typeof setTimeout>;
+export type TIntervalHandle = ReturnType<typeof setInterval>;
+
+export type TPrimitive = string | number | boolean | null;

package/src/utils/random.ts

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

package/src/utils/{entries.ts → records/entries.ts}

@@ -1,4 +1,4 @@
-import { TFunction } from "../types";
+import { TFunction } from "..";
 
 export function dictToEntries<V, K extends string = string>( obj: Record<K, V> ): [K, V][] {
 	return Object.entries( obj ) as [K, V][];

package/src/{types → utils}/records.ts

@@ -1,4 +1,6 @@
 
+export * from './records/entries.js';
+
 export type TEmpty = Record<string, never>;
 export type TKeysOfType<T, V> = { [ K in keyof T ]-?: T[ K ] extends V ? K : never }[ keyof T ];