Starting Use

Installation

The normal installation method is to execute from the npm package manager.

Console command for installing the package

npm i @yamato-daiwa/es-extensions -E

Information About Distribution Size

On the npm official site @yamato-daiwa/es-extensions page, the uncompressed size (“Unpacked Size”) of the package is displayed. For example, version 1.5.8 is 698 kilobytes in size.

Example of distribution size listed on the official npm site. In the case of Yamato Daiwa ECMAScript extensions, please note that, following installation of the package, the size of the application will not increase by exactly the amount displayed on the official site of this package.

It is not the volume of the outputted JavaScript code, on which your output files will increase once you install @yamato-daiwa/es-extensions and build your project.

The majority of the volume is for the ECMAScript modules (optimized for browser applications) and CommonJS modules (default for Node.js applications). Regardless of which of the above modules you select, the majority of the files will be ignored.

In the case of a server/console Node.js application, this will increase the size by about several hundreds kilobytes, but this is commonly not a major　issue. However, in the case of a browser application, it is important to configure your project building tools such as to exclude functionality not used in the library from the production build.

In the case of Webpack, the functionality is called “tree shaking”. To enable this in the production build mode, you need to specify ES type modules in the TypeScript configuration . The second requirement, which is specifying sideEffects: false in package.json (the "package.json" file of the dependency), is satisfied by @yamato-daiwa/es-extensions. If you are using another project building tool that developers call a "competitor of Webpack", it must support the functionality similar to Webpack's tree shaking.

In order to exclude as many unneeded modules as possible, the majority of the functionality of @yamato-daiwa/es-extensions is implemented with functions and not classes (limited class functionality). Also, when one function uses other functions, those transitive dependencies are also included in the structure, but there is still substantial optimization. This is particularly true when only a small portion of the library is used.

Precautions for Non-Users of TypeScript

Our library was developed primarily for the goal of assisting users of TypeScript. This has to do with how main developer of @yamato-daiwa/es-extensions sees the JavaScript language. The reason is that the JavaScript language does not satisfy the requirements for modern high-quality development of practical commercial applications, websites, and the like. However, TypeScript is completely different. The support of complete object-oriented programming, extremely flexible typing, and whether the code is transpiled to either browser-specific JavaScript or to Node.js change the flow.

If there are no TypeScript type checking errors, you can probably use this library without any problems. This library wasn't originally designed for users of JavaScript, but it is expected that they will want to use it.

When source code is converted into JavaScript, the TypeScript transpiler does not add any new functionality. In particular, type-checking is performed for arguments of functions and methods specified in TypeScript source code, but this does not happen in JavaScript. Solving this issue in JavaScript required sufficient measures for checking the types of arguments of functions and methods with detailed logging of all violations if any. At first glance, you might think that implementing these checks does not increase the amount of code by a lot. However, in reality, it is no exaggeration to say that this increases the amount of code in functions and the like several hundred percent. (Reference: Specific Example).

As result of the collection and analysis of various types of information, we decided not to implement following validation of parameters. The primary reason is that the number of kilobytes needs to be decreased as much as possible due to concerns regarding a sudden increase in the total size of the library or in the transitive dependencies of a large number of functions and the like. This is an unavoidable problem for browser applications. If you are using JavaScript instead of TypeScript and there are mistakes related to the incorrect type of a parameter, a JavaScript runtime error could occur, but the cause will not be obvious from the error message. That is why it could be misinterpreted as a library bug.

Importing functionality

After installing this npm package, you can import the functions, classes, etc. described on the documentation site. For project building tools and runtimes that support the "import" keyword, you can import according to the example below.

Example of importing from ”@yamato-daiwa/es-extensions”

import { addElementsToArray, removeNthCharacter } from "@yamato-daiwa/es-extensions";