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)
• 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.

| Type | Functions / Helpers / Aliases / Polyfills |----------------------------|--------------------------------------------------- | Runtime Environment Checks | getCancelIdleCallback(); getDocument(); getGlobal(); getHistory(); getIdleCallback(); getInst(); getNavigator(); getPerformance(); getWindow(); hasDocument(); hasHistory(); hasNavigator(); hasPerformance(); hasWindow(); isNode(); isWebWorker(); hasIdleCallback(); lazySafeGetInst(); | Type Identity | isArray(); isArrayBuffer(); isBlob(); isBoolean(); isDate(); isError(); isFile(); isFormData(); isFunction(); isIterable(); isIterator(); isNullOrUndefined(); isNumber(); isObject(); isPlainObject(); isPrimitive(); isPrimitiveType(); isPromise(); isPromiseLike(); isThenable(); isRegExp(); isStrictNullOrUndefined(); isStrictUndefined(); isString(); isTypeof(); isUndefined(); | Value Check | hasValue(); isDefined(); isNotTruthy(); isNullOrUndefined(); isStrictNullOrUndefined(); isStrictUndefined(); isTruthy(); isUndefined(); | Value | getValueByKey(); setValueByKey(); getValueByIter(); setValueByIter(); encodeAsJson(); encodeAsHtml(); asString(); getIntValue(); normalizeJsName(); |   |   | Array | arrAppend(); arrContains(); arrEvery(); arrFilter(); arrFind(); arrFindIndex(); arrFindLast(); arrFindLastIndex(); arrForEach(); arrFrom(); arrIncludes(); arrIndexOf(); arrLastIndexOf(); arrMap(); arrReduce(); arrSlice(); arrSome(); getLength(); isArray();polyIsArray(); polyArrIncludes(); polyArrFind(); polyArrFindIndex(); polyArrFindLast(); polyArrFindLast(); polyArrFindLastIndex(); polyArrFrom(); | ArrayLike | arrContains(); arrEvery(); arrFilter(); arrFind(); arrFindIndex(); arrFindLast(); arrFindLastIndex(); arrForEach(); arrFrom(); arrIncludes(); arrIndexOf(); arrLastIndexOf(); arrMap(); arrReduce(); arrSlice(); arrSome(); getLength(); objEntries(); objValues(); | Enum | createEnum(); createEnumKeyMap(); createEnumValueMap(); createSimpleMap(); createTypeMap(); | Error | createCustomError(); isError(); throwError(); throwRangeError(); throwTypeError(); throwUnsupported(); | Function | fnApply(); fnBind(); fnCall(); createFnDeferredProxy(); createProxyFuncs(); readArgs(); | Idle | getCancelIdleCallback(); getIdleCallback(); hasIdleCallback(); | Iterator | createArrayIterator(); createIterator(); createIterable(); createRangeIterator(); iterForOf(); isIterable(); isIterator(); makeIterable(); arrAppend(); arrFrom(); | Math | mathCeil(); mathFloor(); mathMax(); mathMin(); mathToInt(); mathTrunc(); | Object | deepExtend(); isObject(); objAssign(); objCopyProps(); objCreate(); objDeepCopy(); objDeepFreeze(); objDefine(); objDefineAccessors(); objDefineGet(); objDefineProp(); objDefineProps(); objDefineProperties(); objEntries(); objExtend(); objForEachKey(); objFreeze(); objGetOwnPropertyDescriptor(); objHasOwn(); objHasOwnProperty(); objKeys(); objSeal(); objGetPrototypeOf(); objSetPrototypeOf(); objToString(); objValues();polyObjEntries(); polyObjKeys(); polyObjHasOwn(); polyObjValues(); | String | asString(); getLength(); isString(); strEndsWith(); strIndexOf(); strIsNullOrEmpty(); strIsNullOrWhiteSpace(); strLastIndexOf(); strLeft(); strPadEnd(); strPadStart(); strRepeat(); strRight(); strSlice(); strStartsWith(); strSubstr(); strSubstring(); strTrim(); strTrimEnd(); strTrimLeft(); strTrimRight(); strTrimStart(); strLetterCase(); strCamelCase(); strKebabCase(); strSnakeCase(); strUpper(); strLower(); strContains(); strIncludes(); polyStrSubstr(); polyStrTrim(); polyStrTrimEnd(); polyStrTrimStart(); polyStrIncludes(); | Symbol | WellKnownSymbols (const enum);getKnownSymbol(); getSymbol(); hasSymbol(); isSymbol(); newSymbol(); symbolFor(); symbolKeyFor();polyGetKnownSymbol(); polyNewSymbol(); polySymbolFor(); polySymbolKeyFor();Polyfills are used to automatically backfill runtimes that do not support Symbol, not all of the Symbol functionality is provided. | Timer | elapsedTime(); perfNow(); utcNow(); scheduleIdleCallback(); scheduleInterval(); scheduleTimeout(); scheduleTimeoutWith(); hasIdleCallback(); For runtimes that don't support requestIdleCallback normal setTimeout() is used with the values from setDefaultIdleTimeout() and setDefaultMaxExecutionTime(); polyUtcNow(); | Conversion | encodeAsJson(); encodeAsHtml(); asString(); getIntValue(); normalizeJsName(); strLetterCase(); strCamelCase(); strKebabCase(); strSnakeCase(); strUpper(); strLower(); | Cache | createCachedValue(); createDeferredCachedValue(); | Lazy | getLazy(); getWritableLazy(); lazySafeGetInst(); safeGetLazy(); | Safe | safe(); safeGetLazy(); safeGet(); lazySafeGetInst(); safeGetLazy(); | Diagnostic | dumpObj();

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 ES6 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.json so 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.11.5 < 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 functionsTotal = count * 240 bytes | Using HelpersTotal = (count * 160) + 240 bytesassuming 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.

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 ✔ | 9+ ✔ | Latest ✔ | Latest ✔ |

Note: 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.

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.

Note: 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.