@qntm-code/utils

A collection of useful utility functions with associated TypeScript types.

• @qntm-code/utils
  • Install
    • npm
    • yarn
  • Documentation
    • Generic Helpers
      • isNullOrUndefined
      • isEmpty
      • isNumber
      • isString
      • isEqual
        • EqualityType
        • IndividualEqualityType
      • randomNumberBetweenRange
    • Async helpers
      • asyncForEach
      • delay
    • Date helpers
      • convertTimeUnit
      • msToUnit
      • unitToMs
      • TimeUnit
      • getToday
      • getEndOfDay
      • getEndOfHour
      • getEndOfMinute
      • getEndOfMonth
      • getEndOfSecond
      • getEndOfWeek
      • getEndOfYear
      • getStartOfDay
      • getStartOfHour
      • getStartOfMinute
      • getStartOfMonth
      • getStartOfSecond
      • getStartOfWeek
      • getStartOfYear
      • setEndOfDay
      • setEndOfHour
      • setEndOfMinute
      • setEndOfMonth
      • setEndOfSecond
      • setEndOfWeek
      • setEndOfYear
      • setStartOfDay
      • setStartOfHour
      • setStartOfMinute
      • setStartOfMonth
      • setStartOfSecond
      • setStartOfWeek
      • setStartOfYear
    • DOM helpers
      • getAncestors
      • getNonInlineParent
      • getPositionedParent
      • getScrollParent
      • isDisplayInline
      • isVisible
    • Types
      • Dictionary

Install

You can install via npm or yarn.

npm

npm install --save @qntm-code/utils

yarn

yarn add @qntm-code/utils

Documentation

This documentation is written in TypeScript, however this library works fine in vanilla JavaScript too.

Generic Helpers

---

isNullOrUndefined

Detects whether a given value is null or undefined.

Method arguments:

Parameter	Type	Optional	Description
value	any	false	The value to check

Return type: boolean

Example

import { isNullOrUndefined } from '@qntm-code/utils';

const value = getTheValue();

if (isNullOrUndefined(value)) {
  // Do something
}

---

isEmpty

Checks if a given value is empty.

Method arguments:

Parameter	Type	Optional	Description
value	string, Array, object	false	The value to check

Return type: boolean

Example

import { isEmpty } from '@qntm-code/utils';

const value: string = getName();

if (isEmpty(value)) {
  // Do something
}

---

isNumber

Detects whether a given value is a number

Method arguments:

Parameter	Type	Optional	Description
value	any	false	The value to check

Return type: boolean

Example

import { isNumber } from '@qntm-code/utils';

const value = getTheValue();

if (isNumber(value)) {
  // Do something
}

---

isString

Detects whether a given value is a string

Method arguments:

Parameter	Type	Optional	Description
value	any	false	The value to check

Return type: boolean

Example

import { isString } from '@qntm-code/utils';

const value = getTheValue();

if (isString(value)) {
  // Do something
}

---

isEqual

Performs a deep comparison between two values to determine if they are equivalent.

Note: This method supports comparing nulls, undefineds, booleans, numbers, strings, Dates, objects, Functions, and Arrays.

Object objects are compared by their own, not inherited, enumerable properties.

Functions and DOM nodes are compared by strict equality, i.e. ===.

The order of the array items must be the same for the arrays to be equal.

Method arguments:

Parameter	Type	Optional	Description
a	EqualityType	false	The first value to compare
b	EqualityType	false	The second value to compare

Return type: boolean

Example

import { isEqual } from '@qntm-code/utils';

const a: Array<number> = getSensorAReadings();
const b: Array<number> = getSensorBReadings();

if (isEqual(a, b)) {
  // Do a thing
}

EqualityType

An EqualityType can be an IndividualEqualityType or an array of mixedIndividualEqualityTypes

IndividualEqualityType

The equality types allowed are:

• null
• undefined
• boolean
• number
• string
• Date
• object
• Function

---

randomNumberBetweenRange

Returns a random whole number between a given range

Method arguments:

Parameter	Type	Optional	Description
min	number	false	The minimum number the function can return
max	number	false	The maximum number the function can return

Return type: number

Example

import { randomNumberBetweenRange } from '@qntm-code/utils';

const random = randomNumberBetweenRange(2, 10);

---

Async helpers

---

asyncForEach

Allows you to iterate over an array asynchronously.

Method arguments:

Parameter	Type	Optional	Description
items	Array	false	The items to iterate over
callback	Function	false	A callback function to run for each item

Callback arguments:

Parameter	Type	Optional	Description
item	T	true	The current item from the loop
index	number	true	The index of the given in the array
array	Array	true	The array provided

Return type:

Promise<void>

Example

import { asyncForEach } from '@qntm-code/utils';

async function doAThing(): Promise<void> {
  // Array of items to iterate over
  const items: Array<string> = ['a', 'b', 'c'];

  await asyncForEach(items, async item => {
    const result = await someAsynchronousOperation(item);
  });

  functionToRunWhenAllItemsAreProcessed();
}

---

delay

Delays an async function using await given an optionally provided duration.

Method arguments:

Parameter	Type	Optional	Description
duration	number	true	The number of milliseconds to delay by

Return type:

Promise<void>

Example

import { delay } from '@qntm-code/utils';

async function doAThing(): Promise<void> {
  const value = calculateAThing();

  await delay(200);

  operateOnCalculatedValue(value);
}

Date helpers

---

convertTimeUnit

Converts a value of a given TimeUnit into another TimeUnit.

Method arguments:

Parameter	Type	Optional	Description
value	number	false	The value to convert
sourceUnit	TimeUnit	false	The time unit the provided value is in
resultUnit	TimeUnit	false	The time unit you wish to convert your value to

Return type: number

Example

import { convertTimeUnit, TimeUnit } from '@qntm-code/utils';

const weeks: number = 24;
const minutes: number = convertTimeUnit(weeks, TimeUnit.Weeks, TimeUnit.Minutes);

Vanilla JS Example

import { convertTimeUnit } from '@qntm-code/utils';

const weeks = 24;
const minutes = convertTimeUnit(weeks, 'weeks', 'minutes');

---

msToUnit

Converts milliseconds into a TimeUnit.

Method arguments:

Parameter	Type	Optional	Description
value	number	false	The value in milliseconds
unit	TimeUnit	false	The time unit you wish to convert your value to

Return type: number

Example

import { msToUnit, TimeUnit } from '@qntm-code/utils';

const milliseconds: number = 4567876;
const hours: number = msToUnit(milliseconds, TimeUnit.Hours);

Example

import { msToUnit } from '@qntm-code/utils';

const milliseconds = 4567876;
const hours = msToUnit(milliseconds, 'hours');

---

unitToMs

Converts a TimeUnit into milliseconds.

Method arguments:

Parameter	Type	Optional	Description
value	number	false	The value to convert
unit	TimeUnit	false	The time unit of the value you provided

Return type: number

Example

import { unitToMs, TimeUnit } from '@qntm-code/utils';

const days: number = 10;
const milliseconds: number = unitToMs(days, TimeUnit.Days);

Example

import { unitToMs } from '@qntm-code/utils';

const days = 10;
const milliseconds = unitToMs(days, 'days');

---

TimeUnit

A TypeScript enum of available options to provide to time unit conversion functions. For vanilla JS just use the string values from the value column.

Enum Key	Value
Milliseconds	milliseconds
Seconds	seconds
Minutes	minutes
Hours	hours
Days	days
Weeks	weeks

---

getToday

Gets a Date for the start of the given day.

Return type: Date

Example

import { getToday } from '@qntm-code/utils';

const today: Date = getToday();

---

getEndOfDay

Takes an optional date and returns a new Date object set to the end of the given/current day.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfDay } from '@qntm-code/utils';

const endOfCurrentDay: Date = getEndOfDay();

---

getEndOfHour

Takes an optional date and returns a new Date object set to the end of the given/current hour.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfHour } from '@qntm-code/utils';

const endOfCurrentHour: Date = getEndOfHour();

---

getEndOfMinute

Takes an optional date and returns a new Date object set to the end of the given/current minute.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfMinute } from '@qntm-code/utils';

const endOfCurrentMinute: Date = getEndOfMinute();

---

getEndOfMonth

Takes an optional date and returns a new Date object set to the end of the given/current month.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfMonth } from '@qntm-code/utils';

const endOfCurrentMonth: Date = getEndOfMonth();

---

getEndOfSecond

Takes an optional date and returns a new Date object set to the end of the given/current second.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfSecond } from '@qntm-code/utils';

const endOfCurrentSecond: Date = getEndOfSecond();

---

getEndOfWeek

Takes an optional date and returns a new Date object set to the end of the given/current week.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfWeek } from '@qntm-code/utils';

const endOfCurrentWeek: Date = getEndOfWeek();

---

getEndOfYear

Takes an optional date and returns a new Date object set to the end of the given/current year.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getEndOfYear } from '@qntm-code/utils';

const endOfCurrentYear: Date = getEndOfYear();

---

getStartOfDay

Takes an optional date and returns a new Date object set to the start of the given/current day.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfDay } from '@qntm-code/utils';

const startOfCurrentDay: Date = getStartOfDay();

---

getStartOfHour

Takes an optional date and returns a new Date object set to the start of the given/current hour.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfHour } from '@qntm-code/utils';

const startOfCurrentHour: Date = getStartOfHour();

---

getStartOfMinute

Takes an optional date and returns a new Date object set to the start of the given/current minute.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfMinute } from '@qntm-code/utils';

const startOfCurrentMinute: Date = getStartOfMinute();

---

getStartOfMonth

Takes an optional date and returns a new Date object set to the start of the given/current month.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfMonth } from '@qntm-code/utils';

const startOfCurrentMonth: Date = getStartOfMonth();

---

getStartOfSecond

Takes an optional date and returns a new Date object set to the start of the given/current second.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfSecond } from '@qntm-code/utils';

const startOfCurrentSecond: Date = getStartOfSecond();

---

getStartOfWeek

Takes an optional date and returns a new Date object set to the start of the given/current week.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfWeek } from '@qntm-code/utils';

const startOfCurrentWeek: Date = getStartOfWeek();

---

getStartOfYear

Takes an optional date and returns a new Date object set to the start of the given/current year.

Parameter	Type	Optional	Default value	Description
date	Date	true	new Date()	The date to modify

Return type: Date

Example

import { getStartOfYear } from '@qntm-code/utils';

const startOfCurrentYear: Date = getStartOfYear();

---

setEndOfDay

Takes a given date and mutates it to the end of the given day.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfDay } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentDay: Date = setEndOfDay(now);

---

setEndOfHour

Takes a given date and mutates it to the end of the given hour.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfHour } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentHour: Date = setEndOfHour(now);

---

setEndOfMinute

Takes a given date and mutates it to the end of the given minute.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfMinute } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentMinute: Date = setEndOfMinute(now);

---

setEndOfMonth

Takes a given date and mutates it to the end of the given month.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfMonth } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentMonth: Date = setEndOfMonth(now);

---

setEndOfSecond

Takes a given date and mutates it to the end of the given second.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfSecond } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentSecond: Date = setEndOfSecond(now);

---

setEndOfWeek

Takes a given date and mutates it to the end of the given week.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfWeek } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentWeek: Date = setEndOfWeek(now);

---

setEndOfYear

Takes a given date and mutates it to the end of the given year.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setEndOfYear } from '@qntm-code/utils';

const now: Date = new Date();
const endOfCurrentYear: Date = setEndOfYear(now);

---

setStartOfDay

Takes a given date and mutates it to the start of the given day.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfDay } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentDay: Date = setStartOfDay(now);

---

setStartOfHour

Takes a given date and mutates it to the start of the given hour.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfHour } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentHour: Date = setStartOfHour(now);

---

setStartOfMinute

Takes a given date and mutates it to the start of the given minute.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfMinute } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentMinute: Date = setStartOfMinute(now);

---

setStartOfMonth

Takes a given date and mutates it to the start of the given month.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfMonth } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentMonth: Date = setStartOfMonth(now);

---

setStartOfSecond

Takes a given date and mutates it to the start of the given second.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfSecond } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentSecond: Date = setStartOfSecond(now);

---

setStartOfWeek

Takes a given date and mutates it to the start of the given week.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfWeek } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentWeek: Date = setStartOfWeek(now);

---

setStartOfYear

Takes a given date and mutates it to the start of the given year.

Parameter	Type	Optional	Description
date	Date	false	The date to modify

Return type: Date

Example

import { setStartOfYear } from '@qntm-code/utils';

const now: Date = new Date();
const startOfCurrentYear: Date = setStartOfYear(now);

DOM helpers

---

getAncestors

Gets all the elements that a given element is nested within

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to find the ancestors for

Example

import { getAncestors } from '@qntm-code/utils';

const ancestors: HTMLElement[] = getAncestors(document.getElementById('my-element'));

getNonInlineParent

Gets the first parent of an element that isn't display: inline. Returns null if no matching element

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to non display: inline parent for

Example

import { getNonInlineParent } from '@qntm-code/utils';

const nonInlineParent: HTMLElement | null = getNonInlineParent(document.getElementById('my-element'));

getPositionedParent

Gets the first parent element with a relative or absolute position

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to find the ancestors for

Example

import { getPositionedParent } from '@qntm-code/utils';

const ancestors: HTMLElement = getPositionedParent(document.getElementById('my-element'));

getScrollParent

Gets the scrollable parent element of a given element

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to find the scroll parent for
x	boolean	true	true	Whether to check if the element can scroll on the x axis
y	boolean	true	true	Whether to check if the element can scroll on the y axis

Example

import { getScrollParent } from '@qntm-code/utils';

const scrollParent: HTMLElement | null = getScrollParent(document.getElementById('my-element'));

isDisplayInline

Return whether an element is display: inline

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to check for display: inline

Example

import { isDisplayInline } from '@qntm-code/utils';

const inline: boolean = isDisplayInline(document.getElementById('my-element'));

isVisible

Return whether an element is practically visible, considering things like dimensions of 0, opacity, visibility: hidden and overflow: hidden, and whether the item is scrolled off screen

Parameter	Type	Optional	Default value	Description
element	HTMLElement	false		The HTML element you want to check for visibility

Example

import { isVisible } from '@qntm-code/utils';

const visible: boolean = isVisible(document.getElementById('my-element'));

Types

---

Dictionary

Reusable dictionary type for typed maps

Example

import { Dictionary } from '@qntm-code/utils';

const dictionary: Dictionary<string> = {
  a: 'yes',
  b: 'no',
};