@zelgadis87/utils-core 4.3.4 → 4.4.0

package/src/utils/strings/StringParts.ts

@@ -0,0 +1,114 @@
+import { TReadableArray } from "../arrays.js";
+import { TMaybe } from "../nulls.js";
+import { capitalizeWord } from "../strings.js";
+
+export class StringParts {
+
+	private readonly _parts: string[];
+
+	private constructor( ...parts: string[] ) {
+		this._parts = parts;
+	}
+
+	public toUpperCase() {
+		return new StringParts( ...this.parts.map( part => part.toUpperCase() ) );
+	}
+
+	public toLowerCase() {
+		return new StringParts( ...this.parts.map( part => part.toLowerCase() ) );
+	}
+
+	public capitalizeFirst() {
+		if ( !this.length ) return this;
+		return new StringParts( capitalizeWord( this.first! ), ...this.tail.map( part => part.toLowerCase() ) );
+	}
+
+	public capitalizeEach() {
+		return new StringParts( ...this.parts.map( part => capitalizeWord( part ) ) );
+	}
+
+	public get parts() {
+		return this._parts;
+	}
+
+	public get tail() {
+		const [ _first, ...tail ] = this.parts;
+		return tail;
+	}
+
+	public get first(): TMaybe<string> {
+		return this._parts[ 0 ] ?? null;
+	}
+
+	public get last(): TMaybe<string> {
+		return this._parts[ this.length - 1 ] ?? null;
+	}
+
+	public get length() {
+		return this._parts.length;
+	}
+
+	public trim() {
+		return new StringParts( ...this.parts.map( part => part.trim() ) );
+	}
+
+	public toSnakeCase() {
+		return this.toLowerCase().join( '_' );
+	}
+
+	public toCamelCase() {
+		if ( !this.length ) return '';
+		return [ this.first!.toLowerCase(), ...this.tail.map( capitalizeWord ) ].join( '' );
+	}
+
+	public toKebabCase() {
+		return this.toLowerCase().join( '-' );
+	}
+
+	public toPascalCase() {
+		return this.capitalizeEach().join( '' );
+	}
+
+	public toHumanCase() {
+		return this.capitalizeFirst().join( ' ' );
+	}
+
+	public join( separator: string ) {
+		return this.parts.join( separator );
+	}
+
+	public mergeWith( { parts: otherParts }: { parts: TReadableArray<string>; } ) {
+		return new StringParts( ...this.parts, ...otherParts );
+	}
+
+	public slice( start: number, end?: number ) {
+		return new StringParts( ...this.parts.slice( start, end ) );
+	}
+
+	public splice( start: number, deleteCount: number, ...items: string[] ) {
+		return new StringParts( ...this.parts.splice( start, deleteCount, ...items ) );
+	}
+
+	public push( part: string ) {
+		return new StringParts( ...this.parts, part );
+	}
+
+	public shift( part: string ) {
+		return new StringParts( part, ...this.parts );
+	}
+
+	public reverse() {
+		return new StringParts( ...this.parts.reverse() );
+	}
+
+	public static fromString = ( s: string, separator: string | RegExp = /\s+/g ) => {
+		if ( s === null || separator === null )
+			throw new Error( 'Invalid arguments' );
+		return new StringParts( ...s.split( separator ) );
+	};
+
+	public static fromParts = ( ...parts: string[] ) => {
+		return new StringParts( ...parts );
+	};
+
+}

package/src/utils/strings.ts

@@ -0,0 +1,91 @@
+import { range } from "./arrays.js";
+import { ensureDefined, isNullOrUndefined } from "./nulls.js";
+
+export * from './strings/StringParts.js';
+
+// Semantic-only
+export type THtmlString = string;
+export type TUrl = string;
+export type TRelativeUrl = string;
+
+export function hashCode( str: string ): number {
+	let hash = 0
+	for ( let i = 0; i < str.length; ++i )
+		hash = Math.imul( 31, hash ) + str.charCodeAt( i )
+	return hash | 0
+}
+
+export function repeat( char: string, times: number ): string {
+	return times > 0 ? range( 0, times - 1 ).map( _ => char ).join( '' ) : '';
+}
+
+export function capitalizeWord( word: string ): string {
+	return word[ 0 ].toUpperCase() + word.substring( 1 ).toLowerCase();
+}
+
+export function splitWords( text: string, regEx: RegExp = /\s+/ ): string[] {
+	return text.split( regEx ).filter( t => t.length > 0 );
+}
+
+export function stringToNumber( s: string | null | undefined ): number | null {
+	if ( isNullOrUndefined( s ) )
+		return null;
+	return Number( s );
+}
+
+export 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' );
+}
+
+export function ellipsis( str: string, maxLength: number, padChar: string, padWhere: 'left' | 'right' = 'left' ): string {
+	if ( maxLength < 4 ) 
+		throw new Error( 'Invalid argument maxLength' );
+	if ( str.length <= maxLength ) {
+		return pad( str, maxLength, padChar, padWhere );
+	} else {
+		return str.substring( 0, maxLength - 3 ) + '...';
+	}
+}
+
+export 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;
+
+}
+
+export function wrapWithString( str: string, delimiter: string ): string {
+	return delimiter + str + delimiter;
+}
+
+/** @deprecated[2024-12-23]: Use {@link wrapWithString} instead. */
+export const wrap = wrapWithString;
+
+

package/dist/random/index.d.ts

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

package/dist/random/randomInterval.d.ts

@@ -1 +0,0 @@
-export default function randomInterval(min: number, max: number): number;

package/dist/random/randomPercentage.d.ts

@@ -1 +0,0 @@
-export default function randomPercentage(min: number, max: number): number;

package/dist/types/index.d.ts

@@ -1,14 +0,0 @@
-export type TTimeoutHandle = ReturnType<typeof setTimeout>;
-export type TIntervalHandle = ReturnType<typeof setInterval>;
-export type TPrimitive = string | number | boolean | null;
-export * from './arrays';
-export * from './booleans.ts';
-export * from './empties.ts';
-export * from './errors.ts';
-export * from './functions';
-export * from './json';
-export * from './nulls';
-export * from './numbers';
-export * from './promises';
-export * from './records';
-export * from './strings';

package/dist/types/json.d.ts

@@ -1,7 +0,0 @@
-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 declare function tryToParseJson<T extends TJsonSerializable>(jsonContent: string): [T, null] | [null, Error];

package/dist/utils/bindThis.d.ts

@@ -1 +0,0 @@
-export default function bindThis<F extends Function>(this: void, fn: F, _this: object): F;

package/dist/utils/jsonCloneDeep.d.ts

@@ -1,2 +0,0 @@
-import { TJsonSerializable } from "../types";
-export default function jsonCloneDeep<A extends TJsonSerializable>(a: A): A;

package/dist/utils/noop.d.ts

@@ -1 +0,0 @@
-export default function noop(): void;

package/dist/utils/omit.d.ts

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

package/dist/utils/sortBy.d.ts

@@ -1,7 +0,0 @@
-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', nulls?: 'FIRST' | 'LAST'): (a: T, b: T) => number;
-export {};

package/dist/utils/throttle.d.ts

@@ -1,3 +0,0 @@
-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>;

package/dist/utils/uniq.d.ts

@@ -1 +0,0 @@
-export default function uniq<T>(arr: T[]): T[];

package/dist/utils/uniqBy.d.ts

@@ -1,2 +0,0 @@
-import { TFunction } from "../types";
-export default function uniqBy<T, K>(arr: T[], getter: TFunction<T, K>): T[];

package/dist/utils/uniqByKey.d.ts

@@ -1 +0,0 @@
-export default function uniqByKey<T, K extends keyof T>(arr: T[], key: K): T[];

package/dist/utils/withTryCatch.d.ts

@@ -1,2 +0,0 @@
-import { TFunction } from "../types";
-export default function withTryCatch<R>(fn: TFunction<void, R>): R | Error;

package/dist/utils/withTryCatchAsync.d.ts

@@ -1,2 +0,0 @@
-import { TFunction } from "../types";
-export default function withTryCatchAsync<R>(fn: TFunction<void, Promise<R>>): Promise<R | Error>;

package/dist/utils/wrap.d.ts

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

package/src/random/index.ts

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

package/src/random/randomInterval.ts

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

package/src/random/randomPercentage.ts

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

package/src/types/index.ts

@@ -1,20 +0,0 @@
-
-// Semantic only
-
-export type TTimeoutHandle = ReturnType<typeof setTimeout>;
-export type TIntervalHandle = ReturnType<typeof setInterval>;
-
-export type TPrimitive = string | number | boolean | null;
-
-export * from './arrays';
-export * from './booleans.ts';
-export * from './empties.ts';
-export * from './errors.ts';
-export * from './functions';
-export * from './json';
-export * from './nulls';
-export * from './numbers';
-export * from './promises';
-export * from './records';
-export * from './strings';
-

package/src/types/json.ts

@@ -1,15 +0,0 @@
-import { asError } from "./errors.ts";
-
-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, null ] | [ null, Error ] {
-	try {
-		const data = JSON.parse( jsonContent );
-		return [ data as T, null ];
-	} catch ( err ) {
-		return [ null, asError( err ) ];
-	}
-}

package/src/types/strings.ts

@@ -1,191 +0,0 @@
-import { range, TReadableArray } from "./arrays.js";
-import { ensureDefined, isNullOrUndefined, TMaybe } from "./nulls.js";
-
-// Semantic-only
-export type THtmlString = string;
-export type TUrl = string;
-export type TRelativeUrl = string;
-
-export function hashCode( str: string ): number {
-	let hash = 0
-	for ( let i = 0; i < str.length; ++i )
-		hash = Math.imul( 31, hash ) + str.charCodeAt( i )
-	return hash | 0
-}
-
-export function repeat( char: string, times: number ): string {
-	return times > 0 ? range( 0, times - 1 ).map( _ => char ).join( '' ) : '';
-}
-
-export function capitalizeWord( word: string ): string {
-	return word[ 0 ].toUpperCase() + word.substring( 1 ).toLowerCase();
-}
-
-export function splitWords( text: string, regEx: RegExp = /\s+/ ): string[] {
-	return text.split( regEx ).filter( t => t.length > 0 );
-}
-
-export function stringToNumber( s: string | null | undefined ): number | null {
-	if ( isNullOrUndefined( s ) )
-		return null;
-	return Number( s );
-}
-
-export 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' );
-}
-
-export function ellipsis( str: string, maxLength: number, padChar: string, padWhere: 'left' | 'right' = 'left' ): string {
-	if ( maxLength < 4 ) 
-		throw new Error( 'Invalid argument maxLength' );
-	if ( str.length <= maxLength ) {
-		return pad( str, maxLength, padChar, padWhere );
-	} else {
-		return str.substring( 0, maxLength - 3 ) + '...';
-	}
-}
-
-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;
-
-}
-
-export class StringParts {
-
-	private readonly _parts: string[]
-
-	private constructor( ...parts: string[] ) {
-		this._parts = parts;
-	}
-
-	public toUpperCase() {
-		return new StringParts( ...this.parts.map( part => part.toUpperCase() ) );
-	}
-
-	public toLowerCase() {
-		return new StringParts( ...this.parts.map( part => part.toLowerCase() ) );
-	}
-
-	public capitalizeFirst() {
-		if ( !this.length ) return this;
-		return new StringParts( capitalizeWord( this.first! ), ...this.tail.map( part => part.toLowerCase() ) );
-	}
-
-	public capitalizeEach() {
-		return new StringParts( ...this.parts.map( part => capitalizeWord( part ) ) );
-	}
-
-	public get parts() {
-		return this._parts;
-	}
-
-	public get tail() {
-		const [ _first, ...tail ] = this.parts;
-		return tail;
-	}
-
-	public get first(): TMaybe<string> {
-		return this._parts[ 0 ] ?? null;
-	}
-
-	public get last(): TMaybe<string> {
-		return this._parts[ this.length - 1 ] ?? null;
-	}
-
-	public get length() {
-		return this._parts.length;
-	}
-
-	public trim() {
-		return new StringParts( ...this.parts.map( part => part.trim() ) )
-	}
-
-	public toSnakeCase() {
-		return this.toLowerCase().join( '_' );
-	}
-
-	public toCamelCase() {
-		if ( !this.length ) return '';
-		return [ this.first!.toLowerCase(), ...this.tail.map( capitalizeWord ) ].join( '' );
-	}
-
-	public toKebabCase() {
-		return this.toLowerCase().join( '-' );
-	}
-
-	public toPascalCase() {
-		return this.capitalizeEach().join( '' );
-	}
-
-	public toHumanCase() {
-		return this.capitalizeFirst().join( ' ' );
-	}
-
-	public join( separator: string ) {
-		return this.parts.join( separator );
-	}
-
-	public mergeWith( { parts: otherParts }: { parts: TReadableArray<string> } ) {
-		return new StringParts( ...this.parts, ...otherParts )
-	}
-
-	public slice( start: number, end?: number ) {
-		return new StringParts( ...this.parts.slice( start, end ) )
-	}
-
-	public splice( start: number, deleteCount: number, ...items: string[] ) {
-		return new StringParts( ...this.parts.splice( start, deleteCount, ...items ) )
-	}
-
-	public push( part: string ) {
-		return new StringParts( ...this.parts, part )
-	}
-
-	public shift( part: string ) {
-		return new StringParts( part, ...this.parts )
-	}
-
-	public reverse() {
-		return new StringParts( ...this.parts.reverse() )
-	}
-
-	public static fromString = ( s: string, separator: string | RegExp = /\s+/g ) => {
-		if ( s === null || separator === null )
-			throw new Error( 'Invalid arguments' );
-		return new StringParts( ...s.split( separator ) );
-	}
-
-	public static fromParts = ( ...parts: string[] ) => {
-		return new StringParts( ...parts );
-	}
-
-}

package/src/utils/bindThis.ts

@@ -1,4 +0,0 @@
-
-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/jsonCloneDeep.ts

@@ -1,31 +0,0 @@
-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/noop.ts

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

package/src/utils/omit.ts

@@ -1,8 +0,0 @@
-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/sortBy.ts

@@ -1,27 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

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