WLS Utils

A collection of common utility functions frequently reused across projects.

JSDoc documentation can be found in the docs directory.

Installation

npm install wls-utils

Usage

import * as Utils from 'wls-utils'
Utils.uuid()

or

import { uuid } from 'wls-utils'
uuid()

Available Objects and Functions

Devices

/**
* Check if the browser supports storage types
* @param {string} storageType - The type of storage to check: 'localStorage', 'sessionStorage'
* @returns {boolean} - True if the browser supports the requested storage type
*/
storageAvailable(storageType)


/**
* Detect the version of Internet Explorer
* @param {string} [userAgent] - Optional: The userAgent string, default value uses navigator.userAgent
* @returns {number} - The version number of Internet Explorer
*/
getInternetExplorerVersion([userAgent])


/**
* Detect if client is on a mobile or tablet device
* @returns {boolean} - True if device matches certain vendor and userAgent checks
*/
isMobileOrTablet()


/**
* Detect if client is on an iOS device
* @returns {boolean} - True if device userAgent contains iPhone, iPad, or iPod
*/
isIos()


/**
* Detect if browser is Safari
* @returns {boolean} - True if browser is determined to be Safari
*/
isSafari()

DOMActions

/**
* Disable all scrolling functionality
*/
disableScroll()


/**
* Enable all scrolling functionality
*/
enableScroll()


/**
* Internet Explorer 11 polyfill for querySelectorAll, converts NodeList to Array
* @param {string} selector - DOM element selector to query
* @param {Element} [parent] - DOM parent element, default is document
* @returns {Array} - The converted NodeList as an Array
*/
selectAll(selector, [parent])

Objects

/**
* Deep copy keys and values from one object to a new object
* @param {object} obj - Object to copy
* @returns {object} - A new object with the same keys and values of obj
*/
deepCopy(obj)


/**
* Shuffle an array using the Durstenfeld/Fisher–Yates algorithm
* @param {Array} arr - Array to shuffle
* @returns {Array} - A shuffled array
*/
shuffleArray(arr)

Numbers

/**
* Generate a random float between a range of exclusive numbers
* @param {number} min - Minimum value of range, exclusive
* @param {number} max - Maximum value of range, exclusive
* @returns {number} - A random number between min and max
*/
randomFloatRange(min, max)


/**
* Generate a random integer between a range of exclusive numbers
* @param {number} min - Minimum value of range, exclusive
* @param {number} max - Maximum value of range, exclusive
* @returns {number} - A random integer between min and max
*/
randomIntRange(min, max)


/**
* Find the nearest power of two
* @param {number} num
* @returns {number} - The power of two nearest to num
*/
nearestPow2(num)

Strings

/**
* Prefix a number with zeros
* @param {number} num - The number that should appear after the zeros
* @param {number} [maxZeros] - The optional number of zeros to prefix num, default is 1
* @returns {string} - Num prefixed by 0 one or more times as defined by maxZeros
*/
leadZeros(num, [maxZeros])


/**
* Generate a random v4 UUID of the form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx,
* where each x is replaced with a random hexadecimal digit from 0 to f,
* and y is replaced with a random hexadecimal digit from 8 to b.
* credit: https://gist.github.com/jed/982883
*
* @param {string} [a] - An optional placeholder
* @returns {string} - The placeholder if supplied, otherwise a UUID of the form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
*/
uuid([a])


/**
* Find the indefinite article of the given phrase
* @param {string} phrase - The phrase in which to determine the indefinite article
* @returns {string} - Lowercase 'a' or 'an' depending on the phrase
*/
indefiniteArticle(phrase)

Colors

/**
* Convert red, green, and blue values to its hexadecimal color string equivalent
* @param {number} r - The red value in the 0-255 range
* @param {number} g - The green value in the 0-255 range
* @param {number} b - The blue value in the 0-255 range
* @returns {string} - A hexadecimal string in the format '#RRGGBB'
*/
rgbToHex(r, g, b)


/**
* Determine if a color is considered dark by calculating its luminance value
* @param {string} color - A hexadecimal color string in the format '#RRGGBB'
* @returns {boolean} - True if the color's calculated luminance is less than 0.5
*/
isDark(hex)


/**
* Shade, blend or convert a web color
* credit: https://github.com/PimpTrizkit/PJs/wiki/12.-Shade,-Blend-and-Convert-a-Web-Color-(pSBC.js)
* 
* @param {number} p - A percentage in the range 0-1
* @param {string} from - A valid color string: 'rgb(r,g,b)', 'rgba(r,g,b,a)', '#RRGGBB', '#RRGGBBAA', '#RGB', '#RGBA'
* @param {string} [to] - An optional valid color string
*                        Omitting a to value will only shade the from value by percentage p
*                        If present, blend from and to by percentage p and return in the same format as to
*                        To only convert formats, pass p as 0 and to as 'c'
* @returns {(string|object|null)} - A color string, or an object containing separate color channel values, or null
*/
shadeBlendConvert(p, from, [to])
shadeBlendConvert(0, '#F3A', 'c') // Only convert hex to rgb(a) format
shadeBlendConvert(0.42, 'rgb(20, 60, 200)') // Shade 42% lighter and maintain rgb format
shadeBlendConvert(-0.4, '#F3A') // Shade 40% darker and maintain hex format
shadeBlendConvert(0.36, 'rgba(20, 60, 200, 0.6)', 'c') // Shade 36% lighter and convert to hex format
shadeBlendConvert(0.25, 'rgb(20, 60, 200)', '#67DAF0') // Blend from color with to color 25% and convert to hex format
shadeBlendConvert(0.75, '#67DAF0', 'rgb(20, 60, 200)') // Blend from color with to color 75% and convert to rgb format
shadeBlendConvert('#67DAF0') // Rip hex color to rgb(a) format, returns {'0': r, '1': g, '2': b, '3': a}
shadeBlendConvert(0.42, {r:20, g:60, b:200}) // returns null, colors must be strings