js-helpers

JavaScript helper functions for various operations, used across my projects.

Table of Contents

• Compatibility
• Installation
• Functions
  • createEl
  • createEls
  • cssTimeToMs
  • fetchWithTimeout
  • getAverage
  • getCssUnit
  • getElPropValue
  • isMotionAllowed
  • wait
• Migrating from @codebundlesbyvik/js-*-operations
  • Renamed functions
• License

Compatibility

The distributables are compiled with the following browserslist:

"> 0.1% and fully supports object-entries"

Practically speaking, all popular browser versions released after H2 2016 are supported.

Installation

Usage within the Node.js ecosystem

Install the package with npm.

npm install @codebundlesbyvik/js-helpers

Import the helpers you need...

import { getElPropValue, isMotionAllowed } from "@codebundlesbyvik/js-helpers";

...or import the bundle in its entirety.

import * as helpers from "@codebundlesbyvik/js-helpers";

Standalone usage

Download the latest release from GitHub.

Then you can either:

• Use the UMD bundle, or
• Import the helpers you need from the index file, or
• Import the helpers you need seperately.

The UMD bundle has the required core-js polyfills inlined. If you use the module files then you'll need to include the required core-js polyfills yourself. These are loaded from a subdirectory corejs/modules, whose location should be relative to the directory where the js-helpers files are stored.

Functions

• createEl
• createEls
• cssTimeToMs
• fetchWithTimeout
• getAverage
• getCssUnit
• getElPropValue
• isMotionAllowed
• wait

• Required parameters are indicated with *.
• Default values for required parameters are listed first in the array of accepted parameter value types.

createEl(tagName, attrs)

Create and return an HTMLElement.

Parameters

• * tagName (String): The HTMLElement's tag name.
• attrs (Object): Individual attribute - value pairs to set on the HTMLElement.

Special case is the text attribute. Use it to set the HTMLElement's textContent.

Example

const ATTRS = {
    class: "example-div",
    id: "example-div-1",
    ariaHidden: "true",
    text: "This is an example."
};

createEl("div", ATTRS);

// <div class="example-div" id="example-div-1" aria-hidden="true">
//     This is an example
// </div>

createEls(elSkeletons)

Create and return an object of HTMLElements.

Parameters

• * elSkeletons (Object): An object that consists of multiple createEl tagName / attrs entries.

Example

const SKELETONS = {
    fieldset: {
        el: "fieldset",
    },
    field: {
        el: "div",
        attrs: {
            class: "field",
        },
    },
    label: {
        el: "label",
        attrs: {
            for: "example-input"
        }
    },
    input: {
        el: "input",
        attrs: {
            id: "example-input",
            name: "example-input",
            placeholder: "Example input",
        }
    }
};

createEls(SKELETONS);

// {
//     fieldset: <fieldset></fieldset>,
//     field: <div class="field"></div>,
//     label: <label for="example-input"></label>,
//     input: <input id="example-input" name="example-input" placeholder="Example input" />
// }

cssTimeToMs(time)

Convert a 'CSS-style time' to a Number of milliseconds.

If the given value is unitless, it'll be returned as-is. If it has an unrecognized unit, the returned value will be null.

Parameters

• time (String): 'CSS-style' time duration.

Supported units

• ms: Milliseconds
• s: Seconds
• h: Hours
• d: Days
• w: Weeks
• y: Years - assumes 1 year = 365 days

Example

cssTimeToMs("2s");
// 2000

cssTimeToMs("0.25d");
// 21600000

cssTimeToMs("-1w");
// -604800000

cssTimeToMs("1asdf");
// null

cssTimeToMs("20");
// 20

fetchWithTimeout(resource, fetchOptions, timeout)

Make a fetch() call that's aborted by an AbortController after a given amount of time.

Parameters

• * resource (RequestInfo | URL): Location of the resource.
• fetchOptions ({} | RequestInit): Options accepted by fetch().
• timeout (8000 | Number): Time in milliseconds after which AbortController.abort() is called and the fetch() is aborted.

Example

// Make a GET request that's aborted if no response is returned within 10 seconds.
await fetchWithTimeout("target-resource-url", { method: "GET" }, 10000);

getAverage(array, round)

Get the average of an array of Numbers.

Parameters

• * array (Number[]): Array to check.
• round (false | "floor" | "ceil"): Rounding method to apply to the average.

Example

getAverage([1, 2, 3]);
// 2

getAverage([3, 8, 41, 88, 1024]);
// 232.8

getAverage([3, 8, 41, 88, 1024], "floor");
// 232

getAverage([0.1, 0.33, 0.82, 1], "ceil");
// 1

getCssUnit(value)

Get the unit of a quantitative 'CSS-style' value.

If the given value has no unit, the returned value will be null.

Parameters

• value (String): 'CSS-style' value to get the unit from.

Example

getCssUnit("2px");
// "px"

getCssUnit(".5ms");
// "ms"

getCssUnit("100");
// null

getElPropValue(el, prop)

Get an Element's CSS property value.

If the given property is not set, the returned value will be null.

Parameters

• * el (Element): The target.
• * prop (String): Element property to retrieve.

Example

const el = document.querySelector("#example-div-1");
// Has the following properties set:
// margin-bottom: 0.75rem;
// background-color: black;

getElPropValue(el, "margin-bottom");
// "0.75rem"

getElPropValue(el, "background-color");
// "black"

getElPropValue(el, "non-existent");
// null

getPseudoRandomIntBelow(max, includeMax)

Generate and return a pseudo-random integer below a given integer.

⚠️ Makes use of Math.random(), which ISN'T cryptographically secure. You WILL BE FIRED if you misuse this function in an attempt to generate secure, random integers. ⚠️

Parameters

• * max (Number): Depending on includeMax, the returned integer will be either equal to or below this number.
• includeMax (false | Boolean): Whether or not to include max when generating the integer.

Example

getPseudoRandomIntBelow(10);
// 7

getPseudoRandomIntBelow(10, true);
// 10

isMotionAllowed()

Check if prefers-reduced-motion is set to something other than 'reduce'. Returns a Boolean.

Parameters

• None

Example

// 'prefers-reduced-motion' is set to 'reduce'.
isMotionAllowed();
// false

// 'prefers-reduced-motion' is set to 'no-preference'.
isMotionAllowed();
// true

// 'prefers-reduced-motion' is unsupported.
isMotionAllowed();
// true

wait(ms)

Wait for a certain amount of time before continuing script execution.

Parameters

• * ms (Number): Duration after which script execution will continue.

Example

// Wait for 3 seconds before doing something else.
await wait(3000);

Migrating from @codebundlesbyvik/js-*-operations

In case anyone was actually using any of my previous, now deprecated JavaScript helper packages: here's how to make a smooth transition.

• Functions that already existed haven't undergone breaking changes.
  • Any new features aren't breaking.
• Some functions have been renamed.

So in the worst case, all you need to do is update your imports.

Renamed functions

• getPropValue() > getElPropValue()
• getRandomIntUnder() > getPseudoRandomIntBelow()
• getUnit() > getCssUnit()
• motionAllowed() > isMotionAllowed()
• timeToMs() > cssTimeToMs()

License

MIT © 2023 Viktor Chin-Kon-Sung