nevware21@nevware21/ts-utils
Common JavaScript/TypeScript helper functions for better minification
Description
This is a collection of general JavaScript functions (written in and for TypeScript) to aid with removing code duplication to assist with minification, the provided functions are expected to only rarely be included in their namespaced environment.
Support for standard JavaScript functions (ES5+) that are not support in all environments will be backed by internal polyfill implementations when not available.
Test Environments
- Node (16, 18, 20, 22)
- Browser (Chromium - headless)
- Web Worker (Chromium - headless)
All of the polyfill functions are tested against the standard native implementations for node, browser and web-worker to ensure compatibility.
Documentation and details
See the documentation generated from source code via typedoc for a full list and details of all of the available types, functions and interfaces.
See Browser Support for details.
Unless otherwise stated in the functions documentation polyfills are used to automatically backfill unsupported functions in older ES5 runtimes
Language ECMAScript Support
ES5
This library plans to maintain ES5 compatibility for all versions of v0.x and v1.x releases
ES(future [6 next, etc])
Future versions of this library starting at version 2.x are planned to lift and remove the internal polyfills to support the new targetted baseline once it is defined. ie. It may or may not be ES2020 depending on the runtime landscape and requests received.
When we release v2.x the supported browser matrix will also shift as required to match the defined language level supported at that time.
TypeScript Support
This library is built using TypeScript v4.9.5 and uses some keywords that where added in v2.8, so while it is recommended that you use at least v4.9.5, but the definitions will require at least v2.8 and therefore this will be the current minimum support version. If there are issues with any versions of TypeScript please open an issue and we will review whether its possible to work around any limitations with any specific features.
Quickstart
Install the npm packare: npm install @nevware21/ts-utils --save
It is suggested / recommended that you use the following definition in your
package.jsonso that you are compatible with any future releases as they become available we do not intend to make ANY known breaking changes moving forward until v2.x"@nevware21/ts-utils": ">= 0.12.2 < 2.x"
And then just import the helpers and use them.
Simple Example
These are simple representations of using some of the basic function vs the standard provided JavaScript versions. Examples are also being included in the source and generated typedoc documentation.
Using Helpers
import { isArray, arrForEach, objForEachKey, objHasOwnProperty } from "@nevware21/ts-utils";
export function simpleTest(theValue: any): string[] {
let result: any[] = [];
if (isArray(theValue)) {
arrForEach(theValue, (value, idx) => {
if (objHasOwnProperty(theValue, value)) {
result.push(idx + ":" + value);
}
});
} else {
objForEachKey(theValue, (key, value) => {
if (value) {
result.push(key + "=" + value);
}
});
}
return result;
}Or checking if a variable is a string
import { isString } from "@nevware21/ts-utils";
function checkString(value: any) {
let ug = 1;
return isString(value);
}Using standard JS functions
export function simpleTest2(theValue: any): string[] {
let result: any[] = [];
if (Array.isArray(theValue)) {
for (let idx = 0; idx < theValue.length; idx++) {
if (idx in theValue) {
let value = theValue[idx];
if (theValue.hasOwnProperty(value)) {
result.push(idx + ":" + value);
}
}
}
} else {
Object.keys(theValue).forEach((key) => {
let value = theValue[key];
if (value) {
result.push(key + "=" + value);
}
});
}
return result;
}Just from use the helpers you can visually see that the code you write is visually simpler and it removes the need for some standard biolerplate code that you should use when iterating over objects.
But if we have a look at what the minified version might look like the difference becomes even more obvious, as while the helper function names can be minified (because they are not global and they are not namespaced against any object) while the standard public classes and their any functions cannot (normally) be minified. (There are tricks you can do in your own code but it can become messy, this library actually uses those techniques internally to aid with minification).
Minified Using Helpers (~160 bytes) but not including the actual helpers
function simpleTest(t){var r=[];if (a(t)) {f(t,function(v, i){if (h(t,v)) {r.push(i+":"+v);}});}else{e(t,function(k,v){if(v){r.push(k+"="+v);}});}return r;}Minified Without helpers (~240 bytes)
function simpleTest2(t){var r=[];if(Array.isArray(t)){for(var i=0;i<t.length;i++){if(i in t){var v=t[i];if(t.hasOwnProperty(v)){r.push(i+":"+v);}}}}else{Object.keys(t).forEach(function(k){var v=t[k];if(v){r.push(k+"="+v);}});}return r;}While there are obvious savings here (~80 bytes), for this derrived simple case once you add the helper implementations back to the simpleTest instance (about 240 bytes the 4 used functions) then you would be better off just using the normal functions as you would still be using 160 bytes less.
For any real world code though you will find that the normal JS functions are repeated a lot and that is when the savings kick in. Lets just take these 2 sinple examples and assume some very simple duplication of the same code.
| Instances | Real functions Total = count * 240 bytes |
Using Helpers Total = (count * 160) + 240 bytes assuming 240 bytes are only required once as the helpers don't need to be duplicated |
Delta |
|---|---|---|---|
| 1 | 240 | 400 | -160 bytes |
| 2 | 480 | 560 | -80 bytes |
| 3 | 720 | 720 | 0 bytes (break even) |
| 4 | 960 | 880 | 80 bytes |
| 5 | 1200 | 1040 | 160 bytes |
| 10 | 2400 | 1840 | 560 bytes |
In practice the savings are not so easily calculated as it really does depend on which functions you are using, how many times and the "length" of the function name and how you call the function. For example in the above this calls theValue.hasOwnProperty(value) which assumes that the any value passed is always an object and therefore has this function available, while the helper actually always calls Object.prototype.hasOwnProperty.call(theValue,value), so it will always call the object instance and if you do this in your code suddenly you have 37 bytes of uncompressable code vs 15 (for just hasOwnProperty), while when you always use the helper each usage generally becomes a single byte h(theValue).
What does this mean? Generally, that you savings will vary, but you should find that by using these utility functions instead of the standard JavaScript versions (when available) you code will be smaller.
Could you do all of this yourself and create your own "helper" function -- Yes. In fact before publishing this set of utilities that is exactly what we did in every project, mostly just copying from the previous project. And whenever we "fixed" a bug or updated the functionality guess what happened... Update nightmare finding all of the instances in every project.
Import/Export Options
This library supports multiple module formats to accommodate different project setups:
ES Modules (ESM) - For modern applications using ES modules
import { isArray, objDeepCopy } from "@nevware21/ts-utils";CommonJS - For Node.js applications
const { isArray, objDeepCopy } = require("@nevware21/ts-utils");UMD (Universal Module Definition) - For environments that support neither ESM nor CommonJS
<script src="node_modules/@nevware21/ts-utils/bundle/ts-utils.min.js"></script> <script> // Access via global namespace const isArray = nevware21.tsUtils.isArray; </script>
Tree Shaking
The library is designed to be tree-shakable when used with bundlers that support it (like Webpack, Rollup, or esbuild). This means that only the functions you actually import and use will be included in your final bundle, helping to keep your application size small.
// Only these specific functions will be included in your bundle
import { isString, strTrim } from "@nevware21/ts-utils";
// The rest of the library's code will be excluded by tree shakingAdvanced Usage Examples
Custom Deep Copy Handlers
The deep copy functionality (objDeepCopy and objCopyProps) supports custom handlers to control how specific object types are copied. This is especially useful for handling complex objects like class instances or special native objects.
import {
objDeepCopy,
IObjDeepCopyHandlerDetails,
isDate,
isMap,
isSet
} from "@nevware21/ts-utils";
// Example class
class Person {
constructor(public name: string, public age: number) {}
greet() {
return `Hello, my name is ${this.name}`;
}
}
// Create custom handler
function customDeepCopyHandler(details: IObjDeepCopyHandlerDetails): boolean {
const value = details.value;
// Handle Person class instances
if (value instanceof Person) {
// Create a new instance with the same properties
details.result = new Person(value.name, value.age);
return true;
}
// Handle Map objects
if (isMap(value)) {
const newMap = new Map();
details.result = newMap;
// Deep copy each entry in the map
value.forEach((val, key) => {
// Use the details.copy method to handle recursive objects
newMap.set(details.copy(key), details.copy(val));
});
return true;
}
// Handle Set objects
if (isSet(value)) {
const newSet = new Set();
details.result = newSet;
value.forEach(val => {
newSet.add(details.copy(val));
});
return true;
}
// Let the library handle other types
return false;
}
// Use the custom handler
const original = {
person: new Person("Alice", 30),
dates: [new Date(), new Date(2020, 0, 1)],
preferences: new Map([
["theme", "dark"],
["fontSize", 16]
]),
tags: new Set(["typescript", "javascript", "utils"])
};
const copy = objDeepCopy(original, customDeepCopyHandler);
// The copy will have new instances of Person, Map and Set
console.log(copy.person.greet()); // "Hello, my name is Alice"
console.log(copy.person !== original.person); // true - different instances
console.log(copy.preferences !== original.preferences); // true
console.log(copy.tags !== original.tags); // trueThis example demonstrates how to handle:
- Custom class instances
- Built-in objects like Map and Set
- Maintaining object identity in recursive structures
Browser Support
General support is currently set to ES5 supported runtimes and higher.
Internal polyfills are used to backfill ES5 functionality which is not provided by older browsers.
 |
 |
 |
 |
 |
|
|---|---|---|---|---|---|
| Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ |
Internet Explorer support will be dropped in v2.x
Polyfills
All of the included polyfills are tested against the current native implementation running in node, browser and worker environments to ensure that they conform to the current specification, these polyfills are only internally used for ES5 compatibility and when running in an environment (mostly IE) that does not support the required function.
Some additional polyfills are provided for simple backward compatability to enable the utility functions in older environments (such as ES3 / IE8), however, you don't have to use or include these provided polyfils. If you need to use them you will need to import the pre-packaged "polyfill" bundle (bundle/ts-polyfills-utils.min.js) directly by hosting it on your own CDN or all of the non-internal polyfill implementations are exported so you could implement your own version of the polyfill initializer or more simply provide your own alternatives.
Notes:
- While some polyfills are provided to "somewhat" support ES3/IE8 this library does not intend to become a fully fledged polyfill library. And the polyfills provided (or contributed) are just the minimum set that have been required over time. And should be less necessary are time moves forward.
- Several functions use the Object.defineProperty and therefore support is limited to runtimes or good polyfills that can correctly implement this functionality. (eg. createIterator; createIterable)
Contributing
Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.