@opentf/utils

 OPEN TECH FOUNDATION

Utils

A collection of JavaScript utility functions.

Playground | Documentation

Features

• Simple API
• Practical Default Options
• Includes Async Utils
• TypeScript Support
• ESM

Installation

npm install @opentf/utils

yarn add @opentf/utils

pnpm add @opentf/utils

bun add @opentf/utils

Usage

import {
  isNum,
  pascalCase,
  sort,
  clone,
  isEql,
  isEqlArr,
  sleep,
} from '@opentf/utils';

isNum(NaN); //=> false

pascalCase('pascal case'); //=> PascalCase

sort([1, 10, 21, 2], 'desc'); //=> [ 21, 10, 2, 1 ]

const obj = {
  a: 1,
  b: 'abc',
  c: new Map([['key', 'val']]),
};
clone(obj); // It returns deeply cloned value.

const mapA = new Map([
  ['a', 1],
  ['b', 2],
]);
const mapB = new Map([
  ['b', 2],
  ['a', 1],
]);
isEql(mapA, mapB); //=> false

isEqlArr([1, 2, 3], [2, 3, 1]); //=> true

await sleep(1000); // It suspends the exection for 1 second.

API

Array

• arrIns
• arrReplace
• arrRm
• bounds
• chunk
• compact
• countBy
• diff
• groupBy
• intersection
• max
• min
• move
• range
• sort
• sortBy
• symDiff
• union
• uniq

Async

• asyncFilter
• asyncForEach
• asyncMap

Maths

• percentage
• percentageOf

Number

• clamp
• isNegZero
• isZero
• toNum

Function

• sleep
• noop

Colors

• hexToRGB

Assert

• isEmpty
• isEql
• isEqlArr
• isNil
• isShallowEql

Object

• clone
• fromPath
• get
• has
• merge
• mergeAll
• omit
• pick
• set
• shallowMerge
• shallowMergeAll
• size
• toPath
• unset

String

• camelCase
• capitalize
• insertAt
• isEmail
• pascalCase
• replaceAt
• strReplace

Types

• isArr
• isArrBuf
• isBigInt
• isBlob
• isBool
• isDate
• isErr
• isFn
• isJSON
• isMap
• isNull
• isNum
• isObj
• isRegEx
• isSet
• isStr
• isSym
• isTypedArr
• isUndef
• isWkMap
• isWkRef
• isWkSet

Benchmarks

Some benchmark outputs are shown here for reference.

[!IMPORTANT]
Our priorities are reliability and accuracy rather than performance.

clone:
┌───┬──────────────────────────┬─────────┬────────────────────┬────────┬─────────┐
│   │ Task Name                │ ops/sec │ Average Time (ns)  │ Margin │ Samples │
├───┼──────────────────────────┼─────────┼────────────────────┼────────┼─────────┤
│ 0 │ structuredClone (Native) │ 246,358 │ 4059.129038804869  │ ±1.65% │ 24636   │
│ 1 │ _.cloneDeep (Lodash)     │ 169,432 │ 5902.043319168882  │ ±2.53% │ 16944   │
│ 2 │ R.clone (ramda)          │ 178,957 │ 5587.9189808343945 │ ±2.26% │ 17897   │
│ 3 │ R2.clone (remeda)        │ 314,247 │ 3182.204862216371  │ ±1.75% │ 31426   │
│ 4 │ clone                    │ 399,634 │ 2502.2859323385046 │ ±2.06% │ 39964   │
└───┴──────────────────────────┴─────────┴────────────────────┴────────┴─────────┘
*Note: Here the ramda & remeda does not support cloning Map & Set.

sortBy:
┌───┬────────────────────┬───────────┬───────────────────┬────────┬─────────┐
│   │ Task Name          │ ops/sec   │ Average Time (ns) │ Margin │ Samples │
├───┼────────────────────┼───────────┼───────────────────┼────────┼─────────┤
│ 0 │ _.orderBy (Lodash) │ 1,231,295 │ 812.1529684071648 │ ±3.09% │ 123130  │
│ 1 │ R.sortWith (Ramda) │ 1,279,200 │ 781.7380570822326 │ ±2.27% │ 127921  │
│ 2 │ R2.sortBy (Remeda) │ 1,419,707 │ 704.3703291518029 │ ±2.81% │ 141971  │
│ 3 │ sort (Moderndash)  │ 2,697,568 │ 370.7042634668106 │ ±1.82% │ 269757  │
│ 4 │ sortBy             │ 2,728,366 │ 366.5196435965459 │ ±2.19% │ 272837  │
└───┴────────────────────┴───────────┴───────────────────┴────────┴─────────┘

*Note: Here the Moderndash does not support passing object prop as string.

isEql:
┌───┬─────────────────────────────────────┬─────────┬───────────────────┬────────┬─────────┐
│   │ Task Name                           │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├───┼─────────────────────────────────────┼─────────┼───────────────────┼────────┼─────────┤
│ 0 │ deepStrictEqual (Native)            │ 927,921 │ 1077.676882954431 │ ±0.38% │ 92793   │
│ 1 │ fastDeepEqual (fast-deep-equal/es6) │ 638,108 │ 1567.132684562446 │ ±1.42% │ 63813   │
│ 2 │ _.isEqual (Lodash)                  │ 142,592 │ 7013.003366058248 │ ±2.13% │ 14260   │
│ 3 │ R.equals (Ramda)                    │ 50,346  │ 19862.42184707051 │ ±1.83% │ 5035    │
│ 4 │ isEql                               │ 109,127 │ 9163.615962614227 │ ±1.28% │ 10913   │
└───┴─────────────────────────────────────┴─────────┴───────────────────┴────────┴─────────┘

*Note:

- The native util `deepStrictEqual` not available in browsers, does not check `Map` ordering & returns false for same invalid dates.
- The `fast-deep-equal/es6` does not support cyclic refs, Map ordering check, invalid dates, symbols, objects values in Set & TypedArrays.
- The lodash `isEqual` does not check `Map` ordering & object values in `Set`.
- The ramda `equals` does not check `Map` ordering & symbols.

Running benchmarks

$ bun run build
$ bun benchmark.js

License

Copyright (c) Thanga Ganapathy (MIT License).