@nevware21/ts-utils

Comprehensive TypeScript/JavaScript Utility Library

Overview

A comprehensive TypeScript/JavaScript utility library that provides:

• Cross-Environment Support: Works seamlessly in Node.js, browsers, and web workers
• Helper Functions: Extensive collection of utility functions for common operations
• Type Checking: Robust type checking utilities to improve code reliability
• Optimized for Minification: Function naming designed for better minification
• Zero Dependencies: Lightweight and self-contained
• ECMAScript Support: Supports modern JavaScript features across ES5 to ES2023, ensuring broad usability in various environments
• Polyfills: Uses built-in functions to support older environments, providing modern JavaScript features without sacrificing compatibility

If you find this library useful, please consider sponsoring @nevware21 to support ongoing development and maintenance.

Installation

1npm install @nevware21/ts-utils --save

Recommended Version Specification:

1"@nevware21/ts-utils": ">= 0.12.5 < 2.x"

Note: v0.x and v1.x maintain ES5 compatibility. Future v2.x releases will update the baseline to newer ECMAScript versions.

Key Features

Environment Utilities

• Global object detection and access
• Environment detection (Node.js, browser, web worker)
• Safe access to environment-specific APIs

Type Checking

• Comprehensive type checking for all JavaScript types
• Value validation helpers
• Advanced type checks for promises, iterables, and more

Array Helpers

• Safe array manipulation with polyfills for older environments
• Cross-environment array utilities
• Performance-optimized implementations

Object Utilities

• Property manipulation
• Deep copy/extend
• Object transformation helpers

String Manipulation

• Case conversion (camelCase, kebab-case, snake_case)
• String transformation utilities
• HTML and JSON encoding

Function Helpers

• Function binding and proxying utilities
• Argument manipulation
• Function creation helpers

Time and Performance

• Consistent timing APIs across environments
• Performance measurement utilities
• Scheduling helpers with automatic polyfills
• Customizable timeout handling via package-level and global overrides

For advanced timeout customization options, including global overrides, see our Timeout Overrides Guide.

And More

• Math utilities
• Symbol polyfills
• RegExp helpers
• Iterator utilities

Documentation & API Reference

Visit our documentation site for comprehensive guides and references.

• Full API documentation is available in the TypeDoc documentation.
• For practical examples and usage patterns, check out our Usage Guide.
• For detailed documentation on creating and using custom deep copy handlers, see the Advanced Deep Copy Handlers guide.

Documentation Quick Links

Category	Documentation
Getting Started	Usage Guide
Advanced Features	Timeout Overrides, Deep Copy
Performance	Bundle Size Optimization
API Reference	TypeDoc Documentation

Available Utilities

Below is a categorized list of all available utilities with direct links to their documentation:

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(); isAsyncFunction(); isAsyncGenerator(); isBigInt(); isBlob(); isBoolean(); isDate(); isElement(); isElementLike(); isError(); isFile(); isFiniteNumber(); isFormData(); isFunction(); isGenerator(); isInteger(); isIterable(); isIterator(); isMap(); isMapLike(); isNullOrUndefined(); isNumber(); isObject(); isPlainObject(); isPrimitive(); isPrimitiveType(); isPromise(); isPromiseLike(); isRegExp(); isSet(); isSetLike(); isStrictNullOrUndefined(); isStrictUndefined(); isString(); isThenable(); isTypeof(); isUndefined(); isWeakMap(); isWeakSet();
Value Check	hasValue(); isDefined(); isEmpty(); 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(); polyArrFindLastIndex(); polyArrFindLast(); polyArrFindLastIndex(); polyArrFrom();
ArrayLike	arrContains(); arrEvery(); arrFilter(); arrFind(); arrFindIndex(); arrFindLast(); arrFindLastIndex(); arrForEach(); arrFrom(); arrIncludes(); arrIndexOf(); arrLastIndexOf(); arrMap(); arrReduce(); arrSlice(); arrSome(); getLength(); objEntries(); objValues();
DOM	isElement(); isElementLike();
Enum	createEnum(); createEnumKeyMap(); createEnumValueMap(); createSimpleMap(); createTypeMap();
Error	createCustomError(); isError(); throwError(); throwRangeError(); throwTypeError(); throwUnsupported();
Function	fnApply(); fnBind(); fnCall(); createFnDeferredProxy(); createProxyFuncs(); readArgs();
Idle	getCancelIdleCallback(); getIdleCallback(); hasIdleCallback(); setDefaultIdleTimeout(); setDefaultMaxExecutionTime();
Iterator	createArrayIterator(); createIterator(); createIterable(); createRangeIterator(); iterForOf(); isIterable(); isIterator(); makeIterable(); arrAppend(); arrFrom();
Number	getIntValue(); isInteger(); isFiniteNumber(); isNumber();
Math	mathAbs(); mathAcos(); mathAsin(); mathAtan(); mathAtan2(); mathCeil(); mathCos(); mathExp(); mathFloor(); mathLog(); mathMax(); mathMin(); mathPow(); mathRandom(); mathRound(); mathSin(); mathSqrt(); mathTan(); mathToInt(); mathTrunc();
Object	deepExtend(); isObject(); objAssign(); objCopyProps(); objCreate(); objDeepCopy(); objDeepFreeze(); objDefine(); objDefineAccessors(); objDefineGet(); objDefineProp(); objDefineProps(); objDefineProperties(); objEntries(); objExtend(); objForEachKey(); objFreeze(); objFromEntries(); objGetOwnPropertyDescriptor(); objGetOwnPropertyDescriptors(); objGetOwnPropertyNames(); objGetOwnPropertySymbols(); objHasOwn(); objHasOwnProperty(); objIs(); objIsExtensible(); objIsFrozen(); objIsSealed(); objKeys(); objPreventExtensions(); objPropertyIsEnumerable(); objSeal(); objGetPrototypeOf(); objSetPrototypeOf(); objToString(); objValues(); polyObjEntries(); polyObjIs(); polyObjKeys();
String	asString(); getLength(); isString(); strEndsWith(); strIndexOf(); strIsNullOrEmpty(); strIsNullOrWhiteSpace(); strLastIndexOf(); strLeft(); strPadEnd(); strPadStart(); strRepeat(); strRight(); strSlice(); strSplit(); strStartsWith(); strSubstr(); strSubstring(); strSymSplit(); 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	createTimeout(); createTimeoutWith(); elapsedTime(); perfNow(); setGlobalTimeoutOverrides(); setTimeoutOverrides(); 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(); getDeferred(); getWritableDeferred();
Lazy	getLazy(); getWritableLazy(); lazySafeGetInst(); safeGetLazy(); safeGetLazy(); setBypassLazyCache();
Safe	safe(); safeGetLazy(); safeGet(); safeGetDeferred(); safeGetWritableDeferred(); lazySafeGetInst(); safeGetWritableLazy();
Diagnostic	dumpObj();
RegEx	createFilenameRegex(); createWildcardRegex(); makeGlobRegex();

Unless otherwise stated in the functions documentation polyfills are used to automatically backfill unsupported functions in older ES5 runtimes

Why Use ts-utils?

1. Better Minification

Using ts-utils helper functions can significantly reduce your bundle size compared to standard JavaScript methods:

1// Standard JavaScript - Can't be minified effectively
2function stdCode(obj) {
3  if (Array.isArray(obj)) {
4    for (let i = 0; i < obj.length; i++) {
5      if (Object.prototype.hasOwnProperty.call(obj, i)) {
6        // Do something
7      }
8    }
9  }
10}
11
12// Using ts-utils - Allows better minification
13import { isArray, arrForEach, objHasOwnProperty } from "@nevware21/ts-utils";
14
15function optimizedCode(obj) {
16  if (isArray(obj)) {
17    arrForEach(obj, (value, idx) => {
18      if (objHasOwnProperty(obj, idx)) {
19        // Do something
20      }
21    });
22  }
23}

When minified, the ts-utils version is significantly smaller as function names can be reduced to single characters.

2. Cross-Environment Compatibility

Write code once that works across all environments without worrying about platform-specific APIs:

1import { getGlobal, isNode, isWebWorker } from "@nevware21/ts-utils";
2
3// Safely access the global object in any environment
4const globalObj = getGlobal();
5
6// Environment detection
7if (isNode()) {
8  // Node.js specific code
9} else if (isWebWorker()) {
10  // Web Worker specific code
11} else {
12  // Browser specific code
13}

3. Type Safety

Robust type checking utilities to make your code more reliable:

1import { 
2  isString, isNumber, isObject, isArray, 
3  isNullOrUndefined, isPromise 
4} from "@nevware21/ts-utils";
5
6function processValue(value: any) {
7  if (isString(value)) {
8    return value.toUpperCase();
9  } else if (isNumber(value)) {
10    return value * 2;
11  } else if (isArray(value)) {
12    return value.length;
13  } else if (isPromise(value)) {
14    return value.then(result => result);
15  } else if (isNullOrUndefined(value)) {
16    return "No value provided";
17  }
18  
19  return "Unknown type";
20}

4. Modern ECMAScript Features

Support for newer ECMAScript features with backward compatibility:

1import {
2  arrFindLast, arrFindLastIndex, // ES2023
3  objGetOwnPropertyDescriptors, // ES2017
4  strPadStart, strPadEnd, // ES2017
5  isBigInt, // ES2020
6  isWeakMap, isWeakSet // ES2015+
7} from "@nevware21/ts-utils";
8
9// Using ES2023 array methods with backward compatibility
10const numbers = [5, 12, 8, 130, 44];
11const lastBigNumber = arrFindLast(numbers, num => num > 10); // 44
12const lastBigNumberIndex = arrFindLastIndex(numbers, num => num > 10); // 4
13
14// Safe property descriptor access (ES2017)
15const descriptors = objGetOwnPropertyDescriptors(myObject);
16
17// String padding (ES2017)
18const paddedString = strPadStart("123", 5, "0"); // "00123"
19const paddedEnd = strPadEnd("hello", 10, "."); // "hello....."
20
21// Safe type checks for modern types
22if (isBigInt(someValue)) {
23  // Handle BigInt (ES2020) safely
24}

Test Environments

This library is thoroughly tested in:

• Node.js (16, 18, 20, 22)
• Modern browsers (via Chromium headless)
• Web Workers (via Chromium headless)

All polyfill functions are tested against native implementations to ensure full compatibility.

Module Support

The library supports multiple module formats to accommodate different project setups:

• ES Modules (ESM)
• CommonJS (CJS)
• Universal Module Definition (UMD)

Language Support

ES5 Compatibility

This library maintains ES5 compatibility for all v0.x and v1.x releases, ensuring support for any runtime that supports ES5 or higher.

Internal polyfills are used to backfill ES5 functionality which is not provided by older runtimes / browsers.

Future ECMAScript Support

Starting with v2.x, the library plans to update its baseline to target newer ECMAScript versions, reducing the need for polyfills as browser and runtime support evolves.

Browser Support

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	9+ ✔

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 compatibility to enable the utility functions in older environments, 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 older environments 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)

TypeScript Support

Built with TypeScript v5.2.2, with minimal requirements of TypeScript v2.8+ for the type definitions.

Size Analysis and Bundle Optimization

Bundle Size Impact

The ts-utils library is designed with size optimization as a primary goal. Each function is independently importable and has been optimized for tree-shaking in modern bundlers like Webpack and Rollup. This allows you to include only what you need in your final bundle.

Here's a comparison of bundle sizes when using ts-utils versus standard JavaScript approaches:

Scenario	Standard JS	With ts-utils	Size Reduction
Basic type checking	~1.2KB	~0.3KB	~75%
Array operations	~0.9KB	~0.4KB	~55%
String utilities	~1.5KB	~0.6KB	~60%
Object helpers	~2.1KB	~0.8KB	~62%

For detailed byte-level measurements and concrete size optimization strategies, check out our Bundle Size Optimization Guide.

Note: Actual size savings depend on your specific usage patterns, minification settings, and bundler configuration.

When to Use ts-utils for Repeated Functions

You should consider using ts-utils helper functions when:

1. Your code uses the same operations repeatedly: If you're frequently checking types, manipulating arrays/objects, or working with strings, using ts-utils can reduce repetition and improve minification.

2. Bundle size is a concern: For applications where download size matters (e.g., mobile web apps, SPAs), ts-utils can significantly reduce your bundle size through better minification.

3. Cross-environment compatibility is needed: When your code needs to run across Node.js, browsers, and web workers without environment-specific code paths.

4. You want better tree-shaking: The library is designed to allow bundlers to eliminate unused code effectively.

5. Consistent API access is important: ts-utils provides a unified API for accessing functionality that might be implemented differently across environments.

For example, instead of repeating this pattern across your codebase:

1// Before: Multiple instances of this pattern across your code
2if (typeof value === 'object' && value !== null && Array.isArray(value)) {
3  for (let i = 0; i < value.length; i++) {
4    if (Object.prototype.hasOwnProperty.call(value, i)) {
5      // Do something with value[i]
6    }
7  }
8}

Use ts-utils to make it more concise and minification-friendly:

1// After: More concise, better minification
2import { isArray, arrForEach, objHasOwnProperty } from "@nevware21/ts-utils";
3
4if (isArray(value)) {
5  arrForEach(value, (item, idx) => {
6    if (objHasOwnProperty(value, idx)) {
7      // Do something with item
8    }
9  });
10}

For more information on performance and minification benefits, see our Usage Guide.

For detailed documentation on all available utilities, refer to the main documentation site.

License

MIT