Начало работы
Установка
Процедура установки стандартная, с помощью пакетного менеджера npm.
npm i @yamato-daiwa/es-extensions -EОб объёме дистрибутива
На странице @yamato-daiwa/es-extensions официального сайта npm отображается объём пакета («Unpacked Size»). Например, для версии 1.5.8 это было 698 килобайт:
Основной объём дистрибутива занимают набор ECMAScript-модулей (оптимальны для браузерных приложений) и CommonJS-модулей (актуальные по умолчанию для Node.js-приложений). Таким образом, какой бы тип модулей из этих двух не использовался, значительная часть файлов будут проигнорирована.
Объём в несколько сотен килобайт для серверных и консольных Node.js-приложений незначителен в большинстве случаев. Что касается браузерных приложений, то здесь важно обеспечить устранение неиспользуемой функциональности из продакшен-сборки с помощью сборщика проектов.
В Webpack такая
функциональность называется
«Tree shaking».
Для её активации в режиме «продакшен» необходимо в
настройках TypeScript
указать тип модулей группы ES.
Второе условие срабатывания этой функциональности — наличие sideEffects: false в
package.json зависимости — со стороны
@yamato-daiwa/es-extensions выполнено.
Если Вы используете другой сборщик проектов, заявленный как конкурент
Webpack, то он обязан поддерживать функциональность, аналогичную
three shaking у Webpack.
Предупреждение об использовании без TypeScript
Библиотека разрабатывается в первую очередь для пользователей TypeScript.
Связано это прежде всего с отношением главного разработчика к JavaScript: он считает, что
данный язык непригоден для современной высококачественной
коммерческой разработки сайтов и приложений.
Однако к TypeScript отношение совершенно
другое — из-за полноценного
объектно-ориентированного программирования, крайне гибкой
типизации и возможности транспайлинга не только в
браузерный JavaScript, но и в Node.js.
При отсутствии ошибок проверки типов TypeScript-ом вероятность возникновения проблем с данной библиотекой низка. Тем не менее, ожидаются пользователи JavaScript, которые захотят использовать данную библиотеку.
Преобразуя исходный код в JavaScript, транспайлер TypeScript не добавляет никакой новой функциональности, в частности не добавляется валидация параметров функций/методов в соответствии с указанными в исходном TypeScript-коде типами. Поэтому, если бы была задача поддерживать JavaScript, то необходимо было провести тщательную валидацию всех параметров и подробно логировать все нарушения. На первый взгляд это может показаться незначительным увеличением кода, но на самом деле объём кода функций таким образом может вырасти в разы, это не преувеличение (конкретный пример).
После сбора информации было принято решение отказаться от реализации исчерпывающей валидации параметров. Основной причиной является резкое увеличение объёма библиотеки и транзитивных зависимостей большинства модулей в несколько раз, что критично для браузерных приложений, где каждый килобайт на счету. Это значит, что при использовании JavaScript и наличии в коде ошибок, связанных с неверными типами параметров возможно возникновение ошибок выполнения JavaScript, однако из сообщения об ошибке причина не будет очевидна, потому возникновение подобной ошибки может быть неверно диагностировано как баг библиотеки.
Импорт функциональности
После того, как npm-пакет установлен, становится возможным импорт любых
функций, классов и другой функциональности, упомянутой в данной документации.
Способ импорта — стандартный.
Для сборщиков проектов или рантаймов, поддерживающих
ключевое слово import это будет, например,
import { addElementsToArray, removeNthCharacter } from "@yamato-daiwa/es-extensions";