@yamato-daiwa/es-extensions
v1.9.1
Published
Helper functions and classes aimed to reduce the routine code. Build-in TypeScript type safety.
Readme
Yamato Daiwa E(CMA)S(cript) Extensions [YDEE]
Helper functions and classes aimed to reduce the routine code.
Build-in TypeScript type safety without any type.
Oriented to TypeScript users investing the time to quality including type-safety.
Installation
npm i @yamato-daiwa/es-extensions -EDocumentation
Getting Started
- Installation
- Information About Distribution Size
- Precautions for Non-Users of TypeScript
- Importing Functionality
AJAX
Arrays
Creating
As it is obvious from the function name, it creates an array of natural numbers. Elements’ count, ascending/descending and starting number can be specified.
(
compoudParameter: {
/** @description Must be the natural number. */
elementsCount: number;
/** @default false */
isDescendingOrder?: boolean;
/** @default 1 */
startingNumber?: number;
}
): Array<number>Retrieving of Elements
Returns the element of a specified array matching with the predicate if such an element is exactly one, otherwise error will be thrown or null will be returned depending on dedicated option's value.
/** @description [ 1st overload ] Returns null when element satisfying the predicate is not exatcly one. */
<ArrayElement>(
targetArray: Array<ArrayElement>,
predicate: (arrayElement: ArrayElement) => boolean
): ArrayElement | null
/** @description [ 2nd overload ] Throws a error when element satisfying the predicate is not exatcly one. */
<ArrayElement>(
targetArray: Array<ArrayElement>,
predicate: (arrayElement: ArrayElement) => boolean,
options: { mustThrowErrorIfElementNotFoundOrMatchesAreMultiple: true; }
): ArrayElementReturns the last element of an array if such the element exists, otherwise error will be thrown as default, or null will be returned if the dedicated option has been specified.
/** @description [ 1st overload ] Returns null when target array is empty. */
<ArrayElement>(targetArray: Array<ArrayElement>): ArrayElement | null;
/** @description [ 2nd overload ] Throws error when target array is empty. */
<ArrayElement>(
targetArray: Array<ArrayElement>,
options: { mustThrowErrorIfArrayIsEmpty: true; }
): ArrayElementRetrieving of Indexes
Obviously from the function name, returns the array of indexes of array elements which are satisfied to specified predicate function.
<ArrayElement>(
targetArray: Array<ArrayElement>,
predicate: (arrayElement: ArrayElement) => boolean
): Array<number>Returns the index of the array element satisfies the predicate if such element is exactly one, otherwise error will be thrown or null will be returned depending on dedicated option's value.
/** @description [ 1st overload ]
* Returns null when there is no matches with the predicate or such matches are more than one */
<ArrayElement>(
targetArray: Array<ArrayElement>,
predicate: (arrayElement: ArrayElement) => boolean
): number | null;
/** @description [ 2st overload ]
* Throws the error when there is no matches with the predicate or such matches are more than one */
<ArrayElement>(
targetArray: Array<ArrayElement>,
predicate: (arrayElement: ArrayElement) => boolean,
options: { mustThrowErrorIfElementNotFoundOrMatchesAreMultiple: true; }
): number;Retrieving of Subarrays
<ArrayElement>(
compoundParameter:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
(
(
{ fromStart: true; } &
(
{ startingElementNumber__numerationFrom0: number; } |
{ startingElementNumber__numerationFrom1: number; } |
{ fromFirstElement: true; }
) &
(
{ endingElementNumber__numerationFrom0__including: number; } |
{ endingElementNumber__numerationFrom1__including: number; } |
{ endingElementNumber__numerationFrom0__notIncluding: number; } |
{ endingElementNumber__numerationFrom1__notIncluding: number; } |
{ elementsCount: number; } |
{ untilLastElement: true; }
)
) |
(
{ fromEnd: true; } &
(
{ rightElementNumber__numerationFrom0_AndRight: number; } |
{ rightElementNumber__numerationFrom1_AndRight: number; } |
{ fromRightmostElement: true; }
) &
(
{ leftElementNumber__numerationFrom0_AndRight__including: number; } |
{ leftElementNumber__numerationFrom1_AndRight__including: number; } |
{ leftElementNumber__numerationFrom0_AndRight__notIncluding: number; } |
{ leftElementNumber__numerationFrom1_AndRight__notIncluding: number; } |
{ elementsCount: number; } |
{ untilLeftmostElement: true; }
)
)
) &
{ mustThrowErrorIfSpecifiedElementsNumbersAreOutOfRange: boolean; }
): Array<ArrayElement> Adding of Elements
Adds one or more elements to the start, end or specified position of the target array, herewith the adding can be mutable or not depending on dedicated property of the named parameters object.
<ArrayElement>(
compoundParameter:
{ newElements: ReadonlyArray<ArrayElement>; } &
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
(
{ toStart: true; } |
{ toEnd: true; } |
{ toPosition__numerationFrom0: number; } |
{ toPosition__numerationFrom1: number; }
)
): Array<ArrayElement>Replacing of Elements
Creates the swallow copy of the target array and replaces the elements by specified indexes.
<ArrayElement>(
sourceDataAndOptions:
{ targetArray: ReadonlyArray<ArrayElement>; } &
(
{
index: number;
newElement: ArrayElement;
} |
{
replacements: ReadonlyArray<{
index: number;
newElement: ArrayElement;
}>;
}
)
): Array<ArrayElement>Replaces array elements by one or more predicates, herewith the replacing can be mutable or no depending on dedicated option.
<ArrayElement>(
sourceDataAndOptions:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
(
Replacement<ArrayElement> |
{ replacements: Array<Replacement<ArrayElement>>; }
)
):
{
updatedArray: Array<ArrayElement>;
indexesOfReplacedElements: Array<number>;
}type Replacement<ArrayElement> = Readonly<
{ predicate: (arrayElement: ArrayElement) => boolean; } &
(
{ newValue: ArrayElement; } |
{ replacer: (currentValueOfElement: ArrayElement) => ArrayElement; }
)
>;Permutations of Elements
Moves specified by an index element to left or to right, herewith the ousted element will be placed to position of target one. Mutable and immutable swapping are available.
<ArrayElement>(
sourceDataAndOptions:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
(
{ targetElementNumber__numerationFrom0: number; } |
{ targetElementNumber__numerationFrom1: number; }
) &
{
toLeft: boolean;
errorMustBeThrownIf: {
elementsCountIsLessThan2: boolean;
targetElementNumberIsOutOfRange: boolean;
}
}
): Array<ArrayElement>Swaps two array elements, not obligatory the siblings. Each element can be specified by index, by number from 1 or via predicate. Mutable and immutable swapping are available
<ArrayElement>(
sourceDataAndOptions:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
{
oneElement:
{
position__numerationFrom0: number;
mustThrowErrorIfNotFound: boolean;
} |
{
position__numerationFrom1: number;
mustThrowErrorIfNotFound: boolean;
} |
{ isLastOne: true; } |
{
finder: (arrayElement: ArrayElement) => boolean;
mustThrowErrorIfElementNotFoundOrMatchesAreMultiple: boolean;
};
otherElement:
{
position__numerationFrom0: number;
mustThrowErrorIfNotFound: boolean;
} |
{
position__numerationFrom1: number;
mustThrowErrorIfNotFound: boolean;
} |
{ isLastOne: true; } |
{
finder: (arrayElement: ArrayElement) => boolean;
mustThrowErrorIfElementNotFoundOrMatchesAreMultiple: boolean;
}
} &
{
mustThrowErrorIfTargetArrayIsEmpty: boolean;
mustThrowErrorIfSpecifiedBothElementsRefersToSamePosition: boolean;
}
): Array<ArrayElement>Removing of Elements
Removes array elements by indexes, herewith the removing can be mutable or no depending on the dedicated option.
(
compoundParameter:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
{ indexes: number | ReadonlyArray<number>; }
):
{
updatedArray: Array<ArrayElement>;
removedElements: Array<ArrayElement>;
}Removes array elements by one or more predicates, herewith the removing can be mutable or not depending on the dedicated option.
<ArrayElement>(
compoundParameter:
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
) &
(
{ predicate: (arrayElement: ArrayElement) => boolean; } |
{ predicates: ReadonlyArray<(arrayElement: ArrayElement) => boolean>; }
)
):
{
updatedArray: Array<ArrayElement>;
removedElements: Array<ArrayElement>;
indexesOfRemovedElements: Array<number>;
} Restructuring
Converts a flat array to a 2-dimensional array with nested arrays of fixed elements count.
<ArrayElement>(
{
targetFlatArray,
elementsCountPerNestedArray
}:
{
targetFlatArray: Array<ArrayElement>;
elementsCountPerNestedArray: number;
}
):
Array<Array<ArrayElement>>Other
Obviously from the function name, adds elements to an array if they do not present otherwise remove them. For all types of elements except numbers, bigints, strings and booleans the element finding predicate must be specified. Mutable and immutable manipulations are available
/** @description [ 1st overload ] The array of primitive type elements */
<ArrayElement extends number | bigint | string | boolean>(
compoundParameter:
(
{ targetElement: ArrayElement; } |
{ targetElements: ReadonlyArray<ArrayElement>; }
) &
(
{ addingToStart: true; } |
{ addingToEnd: true; } |
{ addingToPosition__numerationFrom0: number; } |
{ addingToPosition__numerationFrom1: number; }
) &
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
)
): Array<ArrayElement>
/** @description [ 1st overload ] The array of non-primitive type elements */
<ArrayElement extends Exclude<unknown, number | bigint | string | boolean>>(
compoundParameter:
(
{
targetElement: ArrayElement;
targetElementFinder: (arrayElement: ArrayElement) => boolean;
} |
{
targetElements: ReadonlyArray<ArrayElement>;
targetElementsFinder: (arrayElement: ArrayElement) => boolean;
}
) &
(
{ addingToStart: true; } |
{ addingToEnd: true; } |
{ addingToPosition__numerationFrom0: number; } |
{ addingToPosition__numerationFrom1: number; }
) &
(
{
mutably: true;
targetArray: Array<ArrayElement>;
} |
{
mutably: false;
targetArray: ReadonlyArray<ArrayElement>;
}
)
): Array<ArrayElement>;From the viewpoint of TypeScript, allows to mutate the ReadonlyArray what basically not recommeded but in some particular cases almost inevitably. From the viewpoint of JavaScript, does nothing.
<ArrayElement>(targetArray: ReadonlyArray<ArrayElement>): Array<ArrayElement>Data Mocking
Date and Time
Default value Subsituters
Although the nullish coalescing operator makes the below functions redundant, they still could be used in the environments with old ECMAScript versions.
Errors
HTTPS
RawObjectDataProcessor
The tool for the validation and processing of unknown at advance external data (from HTTP requests/responses, files, etc.).
Pre-made pre-validation modifiers
Intended to be used when some property is expected to be the string but also expected to be a valid number if to parse it.
Numbers
Strings
All functions working with strings are supporting the surrogate pairs. If some function works incorrectly with surrogate pairs, it means the bug; please feel free to open issue in this case.
Objects
Sets
Maps
Types
Type guards
Value transformers
- emptyStringToNull
- nullToEmptyString
- nullToUndefined
- nullToZero
- undefinedToEmptyArray
- undefinedToEmptyString
- undefinedToNull