@usefultools/utils NPM

JavaScript / TypeScript Utilities

A collection of light-weight methods and helpers for defensive programming.

Prereqs & Install

Node >=9.10.0
npm >=6.1.0

Please note that the TypeScript target is ES6.

npm install @usefultools/utils

Usage

There are 6 main modules available:

Async

Available methods:

withTimeout
timeout
makeRecoverable

Examples

`withTimeout`

The below will resolve source after 750ms.

function findUserById(id: number) {
  const source = () => http.get(`/api/users/${id}`)
  return withTimeout(source, 750)
}

`timeout`

The below will reject if asyncOperation takes more than 0.5 seconds.

function work() {
  const source = asyncOperation() // can take 0-2 seconds
  return timeout(source, 500)
}

`makeRecoverable`

The below will retry 5 times.

function getUsers() {
  const source = () => http.get("/api/users")
  return makeRecoverable(source, 5)
}

The below will retry 3 times, each time with a delay of 250ms.

function getUsers() {
  const source = () => http.get("/api/users")
  return makeRecoverable(source, 3, 250)
}

The below will retry thrice if the error caught is a SyntaxError.

function initService() {
  const source = () => service.init()
  return makeRecoverable(source, 3, 0, SyntaxError)
}

Full test Docs here.

Conditionals

Available methods:

isNull
isUndefined
isMissing
isPresent
isBoolean
isArray
isObject
isString
isNumber
isInteger
isFunction
isNonEmptyString
isNonEmptyArray
isTrue
isFalse
isPositiveInteger
isNonNegativeInteger
hasOneItem
hasMultipleItems
isConstructable
hasOnlyKeys
isEqual

Examples

`isNull`

Find out whether value is null

isNull(null) // true

isNull(undefined) // false
isNull(0) // false
isNull(NaN) // false

`isUndefined`

Find out whether type of value is undefined

isUndefined(undefined) // true

isUndefined(null) // false
isUndefined(0) // false

`isMissing`

Find out whether value is null or undefined, therefore "missing"

isMissing(null) // true
isMissing(undefined) // true

isMissing(0) // false
isMissing(NaN) // false
isMissing("") // false

`isPresent`

Find out whether value is not null and not undefined, therefore "present"

isPresent(0) // true
isPresent(NaN) // true
isPresent("") // true

isPresent(null) // false
isPresent(undefined) // false

`isBoolean`

Find out whether value is of type Boolean

isBoolean(true) // true
isBoolean(false) // true

isBoolean(0) // false

`isArray`

Find out whether value is of type Array

isArray([]) // true
isArray([null, undefined]) // true

isArray({}) // false

`isObject`

Find out whether value is of type Object

isObject({}) // true

isObject(new Function()) // false
isObject([]) // false

`isString`

Find out whether value is of type String

isString("") // true

isString(new String()) // false

`isNumber`

Find out whether value is of type Number

isNumber(42) // true
isNumber(Math.PI) // true
isNumber(Infinity) // true

isNumber(NaN) // false

`isInteger`

Find out whether value is of type Number and is an Integer

isInteger(42) // true

isInteger(Math.PI) // false
isInteger(Infinity) // false
isInteger(NaN) // false

`isFunction`

Find out whether value is of type Function

isFunction(() => {}) // true
isFunction(ReferenceError) // true

isFunction(new ReferenceError()) // false

`isNonEmptyString`

Find out whether value is of type String, and has at least 1 character

isNonEmptyString("Hello, World!") // true

isNonEmptyString("") // false

`isNonEmptyArray`

Find out whether value is of type Array and has at least one element

isNonEmptyArray([null]) // true

isNonEmptyArray([]) // false

`isTrue`

Find out whether value is of type Boolean and is true

isTrue(true) // true

isTrue(1) // false
isTrue(false) // false

`isFalse`

Find out whether value is of type Boolean and is false

isFalse(false) // true

isFalse(0) // false
isFalse(true) // false

`isPositiveInteger`

Find out whether value is an Integer and greater than 0

isPositiveInteger(42) // true

isPositiveInteger(0) // false
isPositiveInteger(-42) // false

`isNonNegativeInteger`

Find out whether value is an Integer and greater or equal to 0

isNonNegativeInteger(42) // true
isNonNegativeInteger(0) // true

isNonNegativeInteger(-42) // false

`hasOneItem`

Find out whether value is an Array and its length is 1

hasOneItem([null]) // true

hasOneItem([]) // false
hasOneItem([42, Math.PI]) // false

`hasMultipleItems`

Find out whether value is an Array and its length is more than 1

hasMultipleItems([42, Infinity]) // true

hasMultipleItems([]) // false
hasMultipleItems(["Hello, World"]) // false

`isConstructable`

Find out whether value is Constructable

isConstructable(new Function()) // true
isConstructable(function a() {}) // true
isConstructable(class {}) // true
isConstructable(class ClassName {}) // true

isConstructable(() => {}) // false

`hasOnlyKeys`

Find out whether value has only the keys provided

hasOnlyKeys({ a: "b", c: "d" }, ["a", "c"]) // true
hasOnlyKeys({ a: "b" }, ["a"]) // true
hasOnlyKeys({}, []) // true

hasOnlyKeys({ a: "b" }, ["c"]) // false
hasOnlyKeys({ a: "b", c: "d" }, ["a"]) // false

`isEqual`

Find out whether value 1 and value 2 are equal (shallow)

isEqual("Hello, World!", "Hello, World!") // true
isEqual(null, null) // true
isEqual(false, false) // true
isEqual(Math.PI, Math.PI) // true
isEqual(Infinity, Infinity) // true

isEqual([], []) // false
isEqual({}, {}) // false
isEqual(false, true) // false

Full test Docs here.

Env

Available methods:

getAsBool
getAsInt
getAsStr

NOTE: These methods are namespaced under env. The usage is therefore

import { env } from "@usefultools/utils"

env.getAsBool(...)
env.getAsInt(...)
env.getAsStr(...)

Examples

Assuming your process.env has loaded the following .env.

IS_PROD=true
ASYNC_MAX_TIMEOUT=2500
API_KEY=0351f02f-0be2-49d1-bfed-5c45275d4fd2

`env.getAsBool`

To retrieve the Boolean value of "IS_PROD" from process.env, you can use the following method.

env.getAsBool("IS_PROD") // true

If the raw value cannot be found, or the parsed value is not a Boolean, this function will throw a ReferenceError or a TypeError respectively.

`env.getAsInt`

To retrieve the Integer value of "ASYNC_MAX_TIMEOUT" from process.env, you can use the following method.

env.getAsInt("ASYNC_MAX_TIMEOUT") // 2500

If the raw value cannot be found, or the parsed value is not an Integer, this function will throw a ReferenceError or a TypeError respectively.

`env.getAsStr`

To retrieve the String value of "API_KEY" from process.env, you can use the following method.

env.getAsStr("API_KEY") // "0351f02f-0be2-49d1-bfed-5c45275d4fd2"

If the raw value cannot be found, this function will throw a ReferenceError.

In all of the above, you can also use your own env object like so:

// const env = { "IS_DEV": "false" }

env.getAsBool("IS_DEV", env) // false

Full test Docs here.

Helpers

Available methods:

noop
identity
getRandomIntInclusive
generateId
isValidId
generateUUID
isValidUUID
fill

Examples

`noop`

Sometimes you might want to provide a default callback parameter to some of your functions to prevent the application from crashing (on the off-chance someone or something accidentally calls them without any parameters). You can use the noop helper as shown below.

function doSomething(cb = noop) {
  let res: string

  try {
    await http.get("/api/healthcheck")
    res = "All works!"
  } catch (_err) {
    res = "There was an error!"
  }

  cb(res)
}

`identity`

Let's assume that doSomething prints its result (String) into the console, but applies onSuccess for a Ok result, and onError for a Err result. You might want to uppercase the success result, but leave the error message in its original form. You can use the identity helper as shown below.

function onSuccess(res: string) {
   return res.toUpperCase()
}

doSomething(onSuccess, identity)

`getRandomIntInclusive`

To get a random integer within a specified range, you can use the following:

getRandomIntInclusive(10, 99) // Yields integers between 10 and 99

`generateId`

To get a random id (underlying is the shortid library) use:

generateId() // "HJ5fy5p3G"
generateId() // "Byij0Ka3z"

`isValidId`

To confirm whether a value is a valid id (underlying is the shortid library) use:

isValidId("HJ5fy5p3G") // true
isValidId("foo") // false

`generateUUID`

To get a random UUID v4 (underlying is the uuid library) use:

generateUUID() // "b98c5086-1dcc-4822-9fa4-8f343f18e8de"
generateUUID() // "7118f7d9-70b1-4cb2-97da-3fe272bed7e8"

`isValidId`

To confirm whether a value is a valid UUID v4 (underlying is the uuid library) use:

isValidUUID("1ad006bf-00c0-49de-bcf0-7c5eb2f83241") // true
isValidUUID("foo") // false

`fill`

To fill an array, use:

fill(4) // [0, 1, 2, 3]

Full test Docs here.

Match

Available methods:

match

Other exports:

_def

Examples

`match`

A basic pattern match:

const getMessage = (year: number): string => match(year)({
  [1984]: "The year is 1984.",
  [_def]: "Unfortunately, we cannot tell what year it is."
})

getMessage(1984) // "The year is 1984."
getMessage(1994) // "Unfortunately, we cannot tell what year it is."
getMessage(2024) // "Unfortunately, we cannot tell what year it is."

Advanced pattern matching, including assertions:

function isFutureYear(year) {
  return isPositiveInteger(year)
  && year > new Date().getFullYear()
}

function isCurrentYear(year) {
  return isPositiveInteger(year)
  && year === new Date().getFullYear()
}

const getMessage = (year: number): string => match(year)(
  [1984, "The year is 1984."],
  [isCurrentYear, x => `The year ${x} is up-to-date.`],
  [isFutureYear, x => `The year ${x} is in the future...`],
  [_def, "Unfortunately, we cannot tell what year it is."],
)

getMessage(1984) // "The year is 1984."
getMessage(2018) // "The year 2018 is up-to-date."
getMessage(2024) // "The year 2024 is in the future..."
getMessage(1333) // "Unfortunately, we cannot tell what year it is."

Full test Docs here.

ThrowIf

A collection of simple throwable assertions, all of which throw if the assertion fails.

Available methods:

throwIfMissing
throwIfPresent
throwIfNotBoolean
throwIfNotArray
throwIfNotObject
throwIfNotString
throwIfNotNumber
throwIfNotInteger
throwIfNotFunction
throwIfFalse
throwIfEmptyString
throwIfEmptyArray
throwIfNotPositiveInteger
throwIfNegativeInteger
throwIfNotConstructable

Examples

throwIfNotObject({}); // void
throwIfNotObject([]); // throws Error
throwIfNotObject(null); // throws Error
throwIfNotObject(undefined); // throws Error

You can also provide your own error messages, and errors.

throwIfMissing(someValue, '`someValue` missing!'); // throws Error('`someValue` missing!')
throwIfMissing(someValue, '`someValue` missing!', ReferenceError); // throws ReferenceError('`someValue` missing!')

Full test Docs here.

Development

1) Install dependencies:

npm install

2) Compile:

make compile

3) Test:

make test # watch mode
make test-ci # CI mode / single run

4) Format the codebase:

make format

Contributing

If you have comments, complaints, or ideas for improvements, feel free to open an issue or a pull request! See Contributing guide for details about project setup, testing, etc.