Version 1.7 — Realize Notes

Core Package (@yamato-daiwa/es-extensions)

New Functionality

Working With Arrays

• addElementsToArrayIfTheyAreNotPresentOtherwiseRemove
• createArrayOfNaturalNumbers
• cropArray

Breaking Changes

Working with Arrays

Renaming of the Third Parameter in getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne and getIndexOfArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne

In the 3rd parameter of the object type the mustThrowErrorIfElementNotFoundOrMoreThan1 property has been renamed to mustThrowErrorIfElementNotFoundOrMatchesAreMultiple.

Reason

The previous name is confusing because "or more than1" could be misinterpreted as like there must not be more than one element in the source array. Now, «or matches are multiple» clearly declares that it must not be more than one element namely among ones which satisfying the predicate.

Changes in your code will required if

In your code, during the calling of getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne function, 3rd parameter is being used.

Migration

Using the appropriate functionality of your code editor or IDE, replace mustThrowErrorIfElementNotFoundOrMoreThan1 occurrences with mustThrowErrorIfElementNotFoundOrMatchesAreMultiple in all files of the project.

"RawObjectDataProcessor" class

Renaming of Localization Object

According the updated naming conventions, the localization object RawObjectDataProcessorLocalization__English has been renamed to rawObjectDataProcessorLocalization__english. Similar changes has been applied to other localization objects.

BrowserJS JavaScript (@yamato-daiwa/es-extensions-browserjs)

Braking changes

Working with DOM

The Changes in Parameters and Conditions of Error Throwing at Functions getExpectedToBeSingleDOM_Element and getExpectedToBeSingleChildOfTemplateElement

Previously, the sole object-type parameter had optional polymorphic property context which, if defined, must have type Element, Document or the one derived from the one of them. Now, this property has been replaced with contextElement, which also polymorphic, but now has ParentNode | Readonly<{ selector: string; }> type, due to what besides the specifying of the context element itself it has become possible to specify its selector. However, if the selector of context element specified, exactly one element must correspond to it, otherwise error will be thrown ( DOM_ElementRetrievingFailedError if element not found, or UnexpectedEventError, if two or more elements found). Because both Element and Document are inherited from ParentNode, the new type of the new property is compatible with the old one.

Reason

The unification of API for specifying of the context element: the contextElement property of ParentNode | Readonly<{ selector: string; }> type now being used in parameters of multiple functions and even outside of YDEE library (for example, in Yamato Daiwa Frontend library for the frontend development).

Changes in your code will required if

You have use the context property of getExpectedToBeSingleDOM_Element or getExpectedToBeSingleChildOfTemplateElement functions.

Migration

Rename context property to contextElement in all files of your project. If it will be good for you to specify the selector of the context element instead of context element itself, you may refactor the occurrences of the calling of this function using the newest API, herewith exactly one element must correspond to specified selector of the context element, otherwise the error will be thrown.

Events Handling

Changes of addLeftClickEventHandler Parameter

As previously, this function has single parameter of the «object» type, but its properties has changed:

Removing of targetElementSelector

Deleted in exchange to the turing of targetElement property to polymorphic. Now the selector of target element must be specified via string property selector of the targetElement object. Herewith as previously, if target element is been specified via selector, it is required to specify via one of mustApplyToAllMatchingsWithSelector, mustIgnoreSubsequentMatchingsWithSelector or mustExpectExactlyOneMatchingWithSelector properties how the function must to behave when more than one element detected for specified selector.

Adding of contextElement

If targetElementSelector property has been specified then it is possible to specify additionally the context element inside which target element will be searched via new contextElement property. As in the targetElementSelector case, it is possible to specify either the instance of element or the selector, however in the second scenario the selector must refer to exactly one element, otherwise the error will be thrown.

Replacing of mustInvokeBeforeChildren_sHandlers with eventPropagation

Thanks to the new polymorphic property eventPropagation it is possible to specify not only the type of the event propagation, but also prevent this event propagation. Although the elements of eventPropagation enumeration namely EventPropagationTypes.capturing and eventPropagation: EventPropagationTypes.bubbling seems to be less understandable, the capturing (moving down of the DOM tree) and bubbling (moving up of the DOM tree) are the canonical terms, and the usage of canonical terminology does not indicate the low quality of API.

Reasons

• Partial unification with the API of another functions
• The demand in specifying of the selector of target element inside the specific parent element.
• The demand in more flexible control on event propagation

Changes in your code will required if

One ore more of the following properties of the single parameter are being used:

• targetElementSelector
• mustInvokeBeforeChildren_sHandlers

Migration

• Rename the targetElementSelector property to targetElement, then place the string literal with the selector or the variable containing this literal to the child object with selector property. For example, targetElementSelector: ".Card-SavingButton" will become to targetElement: { selector: ".Card-SavingButton"}.
• If mustInvokeBeforeChildren_sHandlers: true has been specified in your code, then replace it with eventPropagation: EventPropagationTypes.capturing.
• If mustInvokeBeforeChildren_sHandlers: true has been specified in your code, then то замените это на eventPropagation: EventPropagationTypes.bubbling.