Версия 1.7 — Что нового

Основной пакет (@yamato-daiwa/es-extensions)

Новая функциональность

Работа с массивами

• addElementsToArrayIfTheyAreNotPresentOtherwiseRemove
• createArrayOfNaturalNumbers
• cropArray

Критические изменения

Работа с массивами

Изменение 3-его параметра в getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne и getIndexOfArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne

В 3-ем параметре типа «объект», свойство mustThrowErrorIfElementNotFoundOrMoreThan1 было переименовано в mustThrowErrorIfElementNotFoundOrMatchesAreMultiple.

Причина

Прежнее имя вводит в заблуждение: «or more than1» можно ошибочно интерпретировать как то, что в исходном массиве не должно быть более одного элемента. Теперь же «or matches are multiple» («... или совпадений несколько») однозначно передаёт, что элементов не должно быть более одного именно среди удовлетворяющих предикату.

Потребуются редактирование Вашего исходного кода, если

В Вашем коде при вызове функций getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne или getIndexOfArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne используется 3-ий параметр.

Миграция

Используя соответствующую функциональность редактора кода или интегрированной среды разработки, замените mustThrowErrorIfElementNotFoundOrMoreThan1 на mustThrowErrorIfElementNotFoundOrMatchesAreMultiple во всех файлах проекта.

Класс «RawObjectDataProcessor»

Переименование объекта локализации

В соответствии с обновлёнными соглашениями по именованию, объект локализации RawObjectDataProcessorLocalization__English был переименован в rawObjectDataProcessorLocalization__english. Аналогичные изменения были применены и к другим объектам локализациям.

Браузерный JavaScript (@yamato-daiwa/es-extensions-browserjs)

Критические изменения

Работа с DOM

Изменения параметров и условий бросания ошибок в функциях getExpectedToBeSingleDOM_Element и getExpectedToBeSingleChildOfTemplateElement

Прежде, единственный параметр типа «объект» имел полиморфное опциональное свойство context, которое, если было определено, должно было иметь тип Element, Document, или производный от одного из них. Теперь это свойство было заменено на contextElement, которое также полиморфное, но теперь имеет тип ParentNode | Readonly<{ selector: string; }>, благодаря чему стало возможно в качестве контекста указать не только контекстный элемент, но и его селектор. Однако, когда указан селектор контекстного элемента, ему должен соответствовать ровно один элемент, иначе будет брошена ошибка ( DOM_ElementRetrievingFailedError если контекстный элемент не найден или UnexpectedEventError, если найдено два или более элементов). Поскольку и Element, и Document унаследованы от ParentNode, то тип нового свойства совместим со старым.

Причина

Унификация API указания контекстного элемента — свойство contextElement типа ParentNode | Readonly<{ selector: string; }> теперь используется в параметрах нескольких функций и даже за пределами библиотеки YDEE (например, в библиотеке для фронтенд-разработки Yamato Daiwa Frontend.

Потребуются редактирование Вашего исходного кода, если

Вы пользовались свойством context параметра функций getExpectedToBeSingleDOM_Element или getExpectedToBeSingleChildOfTemplateElement.

Миграция

Переименуйте свойство context в contextElement во всех файлах проекта. Если Вам будет удобнее указать селектор контекстного элемента вместо самого контекстного элемента, то теперь Вы можете выполнить соответствующий рефакторинг с использованием нового API, при этом селектору контекстного элемента должен соответствовать ровно один элемент, в противном случае будет брошена ошибка.

Обработка событий

Изменение параметра функции addLeftClickEventHandler

Как и ранее, функция имеет единственный параметр типа «объект», однако его свойства изменились:

Удаление targetElementSelector

Удалено взамен на превращение свойства targetElement в полиморфное. Теперь селектор целевого элемента должен быть указан через строковое свойство selector объекта targetElement. При этом как и раньше, если целевой элемент указан с помощью селектора, то необходимо через одно из свойств mustApplyToAllMatchingsWithSelector, mustIgnoreSubsequentMatchingsWithSelector и mustExpectExactlyOneMatchingWithSelector указать, как функция должна себя вести в случае, когда указанному селектору соответствует более одного элемента.

Добавление contextElement

Если указано свойство targetElementSelector, то можно дополнительно через новое свойство contextElement указать контекстный элемент, внутри которого будет осуществляться поиск целевого элемента. Сделать это можно, как в случае с targetElementSelector, либо указав экземпляр элемента, либо селектор конкретного элемента, однако во втором случае селектор должен ссылаться на ровно один элемент, в противном случае будет брошена ошибка.

Замена mustInvokeBeforeChildren_sHandlers на eventPropagation

Благодаря новому полиморфному свойству eventPropagation можно не только указывать тип распространения события, но и вовсе прервать это распространение. Хотя элементы перечисления eventPropagation а именно EventPropagationTypes.capturing и eventPropagation: EventPropagationTypes.bubbling могут показаться менее понятными, «capturing» (движение вниз по DOM-древу) и «bubbling» (движение вверх по DOM-древу) являются каноническими терминами, а использование канонической терминологи не является признаком низкокачественного API.

Причины

• Частичная унификация API с другими функциями
• Потребность в возможности указывать селектор целевого элемента внутри конкретного родительского элемента
• Потребность в более гибком управлении распространением события

Потребуются редактирование Вашего исходного кода, если

Используется одно или более свойств единственного параметра среди нижеследующих:

• targetElementSelector
• mustInvokeBeforeChildren_sHandlers

Миграция

• Переименуйте свойство targetElementSelector в targetElement, а строковый литерал с селектором либо переменную с этим литералом поместите в дочерний объект со свойством selector. Например, targetElementSelector: ".Card-SavingButton" превратится в targetElement: { selector: ".Card-SavingButton"}.
• Если у Вас указано mustInvokeBeforeChildren_sHandlers: true, то замените это на eventPropagation: EventPropagationTypes.capturing.
• Если у Вас указано mustInvokeBeforeChildren_sHandlers: false, то замените это на eventPropagation: EventPropagationTypes.bubbling.