fmjs
v5.10.1
Published
A bunch of JavaScript functions that we use a lot at Fusionary.
Downloads
250
Readme
Fusionary JavaScript
This repo contains a bunch of plain JavaScript functions that we use often at Fusionary. They are mostly provided as ES6 modules, but a subset of them are also offered as CommonJS modules so they can easily be used in a node.js environment.
Install
If you want to install fmjs via npm or yarn, go ahead:
npm install fmjs
yarn add fmjs
ES6 Modules
If your bundler supports ES6 module tree shaking, you can do import any function like this:
import {$, debounce, deepCopy} from 'fmjs';
(Note: For Webpack, you might need to configure it to treat fmjs as ES6)
Otherwise, for any of the modules, you can do this:
import {example1, example2} from 'fmjs/example'
example1('foo');
example2('bar');
or this (not recommended):
import * as examples from 'fmjs/example'
examples.example1('foo');
examples.example2('bar');
CommonJS Modules
The following modules & their corresponding functions can be used in a node.js environment:
- array
- color
- math
- object
- promise
- string
- timer
- url
You can require them from their respective files in the cjs
directory, like so:
const {example1} = require('fmjs/cjs/example');
example1('foo');
or like so:
const examples = require('fmjs/cjs/example');
examples.example1('foo');
Modules
- ajax
- analytics
- array
- color
- cookie
- dom
- event
- form
- jsonp
- math
- object
- promise
- selection
- storage
- string
- timer
- url
ajax
ES6 Import Example:
import {getJSON} from 'fmjs';
// or:
import {getJSON} from 'fmjs/ajax.js';
- ajax
- ajax([url], [options]) ⇒ Promise
- getJSON([url], [options]) ⇒ Promise
- postJSON([url], [options]) ⇒ Promise
- postFormData([url], [options]) ⇒ Promise
ajax([url], [options]) ⇒ Promise
Low-level ajax request
Returns: Promise - A resolved or rejected Promise from the server
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [url] | string | location.href | The URL of the resource |
| [options] | Object | | |
| [options.dataType] | string | | One of 'json', 'html', 'xml', 'form', 'formData'. Used for setting the Content-Type
request header (e.g. multipart/form-data
when 'formData) and processing the response (e.g. calling JSON.parse() on a string response when 'json'); |
| [options.data] | <code>Object</code> \| <code>string</code> | | Data to send along with the request. If it's a GET request and
options.datais an object, the object is converted to a query string and appended to the URL. |
| [options.method] | <code>string</code> | <code>"GET"</code> | One of 'GET', 'POST', etc. |
| [options.cache] | <code>boolean</code> | <code>true</code> | If set to
false, will not let server use cached response |
| [options.memcache] | <code>boolean</code> | <code>false</code> | If set to
true, and a previous request sent to the same url was successful, will circumvent request and use the previous response |
| [options.headers] | <code>Object</code> | <code>{}</code> | **Advanced**: Additional headers to send with the request. If headers such as 'Accept', 'Content-Type', 'Cache-Control', 'X-Requested-With', etc., are set here, they will override their respective headers set automatically based on other options such as
options.dataTypeand
options.cache`. |
getJSON([url], [options]) ⇒ Promise
Send a GET request and return parsed JSON response from the resolved Promise
Returns: Promise - A resolved or rejected Promise from the server
See: ajax
| Param | Type | Default | Description | | --- | --- | --- | --- | | [url] | string | location.href | The URL of the resource | | [options] | Object | {} | See ajax for details |
postJSON([url], [options]) ⇒ Promise
Send a POST request and return parsed JSON response from the resolved Promise
Returns: Promise - A resolved or rejected Promise from the server
See: ajax
| Param | Type | Default | Description | | --- | --- | --- | --- | | [url] | string | location.href | The URL of the resource | | [options] | Object | {} | See ajax for details |
postFormData([url], [options]) ⇒ Promise
Send a POST request with FormData
derived from form element provided by options.form
Returns: Promise - A resolved or rejected Promise from the server
See: ajax
| Param | Type | Default | Description | | --- | --- | --- | --- | | [url] | string | location.href | The URL of the resource | | [options] | Object | {} | See ajax for details |
analytics
ES6 Import Example:
import {analytics} from 'fmjs';
// or:
import {analytics} from 'fmjs/analytics.js';
analytics
Load the google analytics script and set it up to track page views. If the document title has "page not found" in it (case insensitive). It'll prepend /404/
to the url for the page-view tracking.
- Warning: untested
| Param | Type | Description |
| --- | --- | --- |
| id | string | The google analytics ID |
| [type] | string | The only possible value for the type
argument is 'legacy'
. |
array
ES6 Import Example:
import {isArray} from 'fmjs';
// or:
import {isArray} from 'fmjs/array.js';
CommonJS Require Example:
const {isArray} = require('fmjs/cjs/array.js');
- array
- isArray(arr) ⇒ boolean
- inArray(el, arr) ⇒ boolean
- randomItem(arr) ⇒ Any
- pluck(arr, prop) ⇒ array
- shuffle(arr) ⇒ array
- collapse(array1, array2, ...arrays) ⇒ array
- merge(array1, array2) ⇒ array
- intersect(arr1, arr2, [prop]) ⇒ array
- unique(arr, [prop]) ⇒ array
- diff(arr1, arr2, [prop]) ⇒ array
- chunk(arr, num) ⇒ array
- pad(arr, size, value) ⇒ array
isArray(arr) ⇒ boolean
Determine whether "arr" is a true array
Returns: boolean - true
if arr is array, false
if not
| Param | Type | Description | | --- | --- | --- | | arr | array | item to determine whether it's an array |
Example
import {isArray} from 'fmjs/array.js';
if (isArray(window.foo)) {
window.foo.push('bar');
}
inArray(el, arr) ⇒ boolean
Determine whether item "el" is in array "arr"
Returns: boolean - Boolean (true
if el is in array, false
if not)
| Param | Type | Description | | --- | --- | --- | | el | Any | An item to test against the array | | arr | array | The array to test against |
randomItem(arr) ⇒ Any
Return a random item from the provided array
Returns: Any - A random element from the provided array
| Param | Type | Description | | --- | --- | --- | | arr | array | An array of elements |
pluck(arr, prop) ⇒ array
Take an array of objects and a property and return an array of values of that property
Returns: array - Array of values of the property (if the value is undefined
, returns null
instead)
| Param | Type | Description | | --- | --- | --- | | arr | array | Array from which to pluck | | prop | string | Property to pluck |
Example
import {pluck} from 'fmjs/array.js';
let family = [
{
id: 'dad',
name: 'Karl'
},
{
id: 'mom',
name: 'Sara',
color: 'blue'
},
{
id: 'son',
name: 'Ben',
color: 'green'
},
{
id: 'daughter',
name: 'Lucy'
}
];
let names = pluck(family, 'name');
let ids = pluck(family, 'id');
let colors = pluck(family, 'color');
console.log(names);
// Logs: ['Karl', 'Sara', 'Ben', 'Lucy']
console.log(ids);
// Logs: ['dad', 'mom', 'son', 'daughter']
console.log(colors);
// Logs: [null, 'blue', 'green', null]
shuffle(arr) ⇒ array
Fisher-Yates (aka Knuth) shuffle. Takes an array of elements and returns the same array, but with its elements shuffled
Returns: array - The array passed to arr
, shuffled
See: knuth-shuffle
| Param | Type | Description | | --- | --- | --- | | arr | array | Array to be shuffled |
collapse(array1, array2, ...arrays) ⇒ array
Collapse two or more arrays into a single, new array. Same as merge()
, but not limited to two arrays.
Returns: array - A new collapsed array
- Warning: untested
See: merge
| Param | Type | Description | | --- | --- | --- | | array1 | array | First array | | array2 | array | Second array | | ...arrays | array | Additional arrays to collapse |
merge(array1, array2) ⇒ array
Merge two arrays into a single, new array. Same as collapse()
but only works with two array arguments.
Returns: array - A new merged array
- Warning: untested
See: collapse
| Param | Type | Description | | --- | --- | --- | | array1 | array | First array | | array2 | array | Second array |
intersect(arr1, arr2, [prop]) ⇒ array
Return a subset of array1
, only including elements from array2
that are also in array1
.
- If
prop
is provided, only that property of an element needs to match for the two arrays to be considered intersecting at that element
Returns: array - A new filtered array
| Param | Type | Description | | --- | --- | --- | | arr1 | array | First array | | arr2 | array | Second array | | [prop] | any | Optional property to compare in each element of the array |
Example
const array1 = [{name: 'Foo', id: 'a'}, {name: 'Bar', id: 'b'}];
const array2 = [{name: 'Foo', id: 'z'}, {name: 'Zippy', id: 'b'}];
console.log(intersect(array1, array2, 'name'));
// Logs [{name: 'Foo', id: 'a'}]
console.log(intersect(array1, array2, 'id'));
// Logs [{name: 'Bar', id: 'b'}]
unique(arr, [prop]) ⇒ array
Take an array of elements and return an array containing unique elements. If an element is an object or array:
- when
prop
is undefined, usesJSON.stringify()
when checking the elements - when
prop
is provided, only that property needs to match for the element to be considered a duplicate and thus excluded from the returned array
Returns: array - A new filtered array
| Param | Type | Description |
| --- | --- | --- |
| arr | array | Array to be filtered by uniqueness of elements (or property of elements) |
| [prop] | Any | Optional property to be tested if an element in arr
is an object or array |
Example
const array1 = [1, 2, 3, 2, 5, 1];
const uniq = unique(array1);
console.log(uniq);
// Logs: [1, 2, 3, 5]
diff(arr1, arr2, [prop]) ⇒ array
Return a subset of array1
, only including elements that are NOT also in array2
. The returned array won't include any elements from array2
.
If an element is an object or array:
- when
prop
is undefined, usesJSON.stringify()
when performing the comparison on an object or array - when
prop
is provided, only that property needs to match for the item to be excluded fom the returned array
Returns: array - A filtered array
| Param | Type | Description |
| --- | --- | --- |
| arr1 | array | Array for which to return a subset |
| arr2 | array | Array to use as a comparison |
| [prop] | string | Optional property to be tested if an element in arr1
is an object or array |
Example
const array1 = [1, 2, 3, 4];
const array2 = [2, 3, 5, 6, -1];
console.log(diff(array1, array2));
// Logs: [1, 4]
chunk(arr, num) ⇒ array
From an array passed into the first argument, create an array of arrays, each one consisting of num
items. (The final nested array may have fewer than num
items.)
Returns: array - A new, chunked, array
| Param | Type | Description | | --- | --- | --- | | arr | array | Array to be chunked. This array itself will not be modified. | | num | number | Number of elements per chunk |
pad(arr, size, value) ⇒ array
Pad an array with value
until its length equals size
Returns: array - The array passed to arr
, padded
| Param | Type | Description | | --- | --- | --- | | arr | array | Array to pad | | size | number | Total length of the array after padding it | | value | any | Value to use for each "padded" element of the array |
color
ES6 Import Example
import {rgb2Hex} from 'fmjs'
// or:
import {rgb2Hex} from 'fmjs/color.js'
CJS Require Example
const {rgb2Hex} = require('fmjs/cjs/color.js');
- color
- static
- inner
- rgb2Hex(rgb) ⇒ string
- rgba2Hex(rgba) ⇒ string
- rgb2Luminance(rgb) ⇒ number
- getContrastColor(bgColor, [darkColor], [lightColor]) ⇒ string
hex2Rgb
Convert a hex value to an rgb or rgba value
| Param | Type | Description | | --- | --- | --- | | hex | string | Hex color code in shorthand format (e.g. #333, #333a) or longhand (e.g. #333333, #333333aa) | | [alpha] | number | Optional number from 0 to 1 to be used with 3- or 6-character hex format |
rgb2Hex(rgb) ⇒ string
Convert an rgb value to a 6-digit hex value. If an rgba value is passed, the opacity is ignored
Returns: string - Hex value (e.g. #ff780a
)
| Param | Type | Description |
| --- | --- | --- |
| rgb | string | array | either an rgb string such as 'rgb(255, 120, 10)'
or an rgb array such as [255, 120, 10]
|
Example
rgb2Hex('rgb(255, 136, 0)')
// => '#ff8800'
rgb2Hex([255, 136, 0])
// => '#ff8800'
rgb2Hex('rgba(255, 136, 0, .8)')
// => '#ff8800'
rgba2Hex(rgba) ⇒ string
Convert an rgba value to an 8-digit hex value, or an rgb value to a 6-digit hex value
Returns: string - Hex value (e.g. #ff780a80
)
| Param | Type | Description |
| --- | --- | --- |
| rgba | string | array | either an rgba string such as 'rgba(255, 120, 10, .5)'
or an rgba array such as [255, 120, 10, .5]
|
Example
rgba2Hex('rgba(255, 136, 0, .8)')
// => '#ff8800cc'
rgba2Hex([255, 136, 0, .8])
// => '#ff8800cc'
rgba2Hex('rgb(255, 136, 0)')
// => '#ff8800'
rgb2Luminance(rgb) ⇒ number
Convert an RGB color to a luminance value. You probably don't want to use this on its own
Returns: number - The luminance value
See
- getContrastColor()
- StackOverflow for more information
| Param | Type | Description |
| --- | --- | --- |
| rgb | string | array | RGB value represented as a string (e.g. rgb(200, 100, 78)
) or an array (e.g. [200, 100, 78]
) |
getContrastColor(bgColor, [darkColor], [lightColor]) ⇒ string
Return darkColor if bgColor is light and lightColor if bgColor is dark. "Light" and "dark" are determined by the rgb2Luminance algorithm
Returns: string - Contrasting color
- Warning: untested
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bgColor | string | | hex code (e.g. #daf or #3d31c2) of the color to contrast |
| [darkColor] | string | "#000" | The dark color to return if bgColor
is considered light |
| [lightColor] | string | "#fff" | The light color to return if bgColor
is considered dark |
cookie
ES6 Import Example:
import {getCookie} from 'fmjs';
// or:
import {getCookie} from 'fmjs/cookie.js';
getCookie(name) ⇒ string
Get the value of a cookie
Returns: string - value The value of the cookie
| Param | Type | Description | | --- | --- | --- | | name | string | The name of the cookie whose value you wish to get |
setCookie(name, value, [options]) ⇒ string
Set the value of a cookie. Use either expires or maxAge (or max-age). NOT BOTH.
Returns: string - The new cookie
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| name | string | | Name of the cookie |
| value | string | | Value of the cookie |
| [options] | Object | | Optional object |
| [options.path] | string | "/" | Path within which the cookie can be read. Default is '/' |
| [options.domain] | string | | If not specified, browser defaults to host portion of current location. If domain specified, subdomains always included. (Note: don't use leading "."). Default is undefined. |
| [options.expires] | number | | Number of days after which the cookie should expire. Default is undefined. |
| [options.maxAge] | number | | Number of seconds after which the cookie should expire. Default is undefined. |
| [options.samesite] | string | | One of 'strict' or 'lax'. Default is undefined. |
| [options.secure] | boolean | | If true
, cookie can only be sent over secure protocol (e.g. https). Default is undefined. |
removeCookie(name, [path])
Remove a cookie
| Param | Type | Description |
| --- | --- | --- |
| name | string | Name of the cookie to remove |
| [path] | string | Optional path of the cookie to remove. If not provided, all name
cookies in location.pathname
or any of its parents will be removed. |
dom
ES6 Import Example:
import {addClass} from 'fmjs';
// or:
import {addClass} from 'fmjs/dom.js';
- dom
- toNodes(element(s)) ⇒ array
- $(selector, [context]) ⇒ Array
- $1(selector, [context]) ⇒ Element
- addClass(el, className, [...classNameN]) ⇒ string
- removeClass(el, className, [...classNameN]) ⇒ string
- toggleClass(el, className, [toggle]) ⇒ string
- replaceClass(el, oldClass, newClass) ⇒ string
- getOffset(el) ⇒ Object
- setStyles(el, styles) ⇒ Element
- setAttrs(el, attrs) ⇒ Element
- getAttrs(el, attrs) ⇒ Object
- toggleAttr(el, attribute, [toggle]) ⇒ string
- prepend(el, toInsert) ⇒ Element
- append(el, toInsert) ⇒ Element
- before(el, toInsert) ⇒ Element
- after(el, toInsert) ⇒ Element
- createTree(options) ⇒ Element(s)
- remove(el) ⇒ Element
- empty(el) ⇒ Element
- replace(oldEl, replacement)
- loadScript(options) ⇒ Promise
toNodes(element(s)) ⇒ array
Converts a selector string, DOM element, or collection of DOM elements into an array of DOM elements
Returns: array - An array of DOM elements
| Param | Type | Description | | --- | --- | --- | | element(s) | Element | NodeList | array | string | The selector string, element, or collection of elements (NodeList, HTMLCollection, Array, etc) |
$(selector, [context]) ⇒ Array
Return an array of DOM Nodes within the document or provided element/nodelist
Returns: Array - Array of DOM nodes matching the selector within the context
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| selector | string | | The CSS selector of the DOM elements |
| [context] | Element | NodeList | array | string | document | The selector string, element, or collection of elements (NodeList, HTMLCollection, Array, etc) representing one or more elements within which to search for selector
|
$1(selector, [context]) ⇒ Element
Return the first found DOM Element within the document or provided element/nodelist/HTMLCollection
Returns: Element - First DOM Element matching the selector within the context
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| selector | string | | Selector string for finding the DOM element |
| [context] | Element | NodeList | array | string | document | The selector string, element, or collection of elements (NodeList, HTMLCollection, Array, etc) representing one or more elements within which to search for selector
|
addClass(el, className, [...classNameN]) ⇒ string
Add one or more classes to an element
Returns: string - the resulting class after classes have been removed
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM element for which to add the class | | className | string | class to add to the DOM element | | [...classNameN] | string | one or more additional className arguments representing classes to add to the element |
removeClass(el, className, [...classNameN]) ⇒ string
Remove one or more classes from an element
Returns: string - the resulting class after classes have been removed
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM element from which to remove the class | | className | string | class to remove from the DOM element | | [...classNameN] | string | one or more additional className arguments representing classes to remove from the element |
toggleClass(el, className, [toggle]) ⇒ string
Add a class if it's not present (or if toggle is true); remove the class if it is present (or if toggle is false)
Returns: string - The className
property of the element after the class has been toggled
| Param | Type | Description | | --- | --- | --- | | el | Element | Element on which to toggle the class | | className | string | The class name to either add or remove | | [toggle] | boolean | Optional boolean argument to indicate whether className is to be added (true) or removed (false) |
replaceClass(el, oldClass, newClass) ⇒ string
Replace oldClass with newClass
Returns: string - The className
property of the element after the class has been replaced
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM element for which you want to replace oldClass with newClass | | oldClass | string | The class name you want to get rid of | | newClass | string | The class name you want to add in place of oldClass |
getOffset(el) ⇒ Object
Get the top and left distance to the element (from the top of the document)
Returns: Object - Object with top
and left
properties representing the top and left offset of the element
- Warning: untested
| Param | Type | Description | | --- | --- | --- | | el | Element | Element for which to get the offset |
setStyles(el, styles) ⇒ Element
Set one or more styles on an element.
Returns: Element - The original element, with the styles set
| Param | Type | Description | | --- | --- | --- | | el | Element | element on which to add styles | | styles | Object.<string, (string|number)> | object of styles and their values to add to the element |
setAttrs(el, attrs) ⇒ Element
Set one or more attributes on an element. For boolean attributes ('async', 'required', etc.), set the element's property to either true
or false
Returns: Element - The original element, with the attributes set
| Param | Type | Description | | --- | --- | --- | | el | Element | element on which to add attributes | | attrs | Object.<string, (string|boolean|number)> | object of attributes and their values to add to the element |
getAttrs(el, attrs) ⇒ Object
Given an array of attribute names, get an object containing attribute names/values for an element
Returns: Object - Object of attribute names along with their values
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM Element. If NodeList is provided, uses the first element in the list | | attrs | array.<string> | Array of attribute names |
toggleAttr(el, attribute, [toggle]) ⇒ string
Add an attribute to an element if it's not present (or if toggle is true
); remove the attribute if it is present (or if toggle is false
)
Returns: string - The attribute name if it has been added, undefined
if it has been removed
| Param | Type | Description | | --- | --- | --- | | el | Element | Element on which to toggle the attribute | | attribute | string | The attribute to either add or remove | | [toggle] | boolean | Optional boolean argument to indicate whether the attribute is to be added (true) or removed (false) * |
prepend(el, toInsert) ⇒ Element
Insert an element as the first child of el
Returns: Element - The inserted element
| Param | Type | Description |
| --- | --- | --- |
| el | Element | Reference element |
| toInsert | Element | string | DOM element or HTML string to insert as the first child of el
|
append(el, toInsert) ⇒ Element
Insert an element as the last child of el
Returns: Element - The inserted element
| Param | Type | Description |
| --- | --- | --- |
| el | Element | Reference element |
| toInsert | Element | string | DOM element or HTML string to insert as the last child of el
|
before(el, toInsert) ⇒ Element
Insert an element as the previous sibling of el
Returns: Element - The inserted element
| Param | Type | Description |
| --- | --- | --- |
| el | Element | Reference element |
| toInsert | Element | string | DOM element or HTML string to insert as the previous sibling of el
|
after(el, toInsert) ⇒ Element
Insert an element as the next sibling of el
Returns: Element - The inserted element
| Param | Type | Description |
| --- | --- | --- |
| el | Element | Reference element |
| toInsert | Element | string | DOM element or HTML string to insert as the next sibling of el
|
createTree(options) ⇒ Element(s)
Provide an object, along with possible child objects, to create a node tree ready to be inserted into the DOM.
Returns: Element(s) - The created Element node tree
| Param | Type | Description | | --- | --- | --- | | options | Object | | | [options.tag] | string | Optional tag name for the element. If none provided, a document fragment is created instead | | [options.text] | string | Optional inner text of the element. | | [options.children] | Array.<Object> | Optional array of objects, with each object representing a child node | | [...options[attr]] | string | One or more optional attributes to set on the element |
remove(el) ⇒ Element
Remove an element from the DOM
Returns: Element - DOM element removed from the DOM
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM element to be removed |
empty(el) ⇒ Element
Empty an element's children from the DOM
Returns: Element - DOM element provided by el
argument
| Param | Type | Description | | --- | --- | --- | | el | Element | DOM element to clear of all children |
replace(oldEl, replacement)
Replace a DOM element with one or more other elements
| Param | Type | Description |
| --- | --- | --- |
| oldEl | Element | The element to be replaced |
| replacement | Element | Array.<Element> | An element, or an array of elements, to insert in place of oldEl
|
loadScript(options) ⇒ Promise
Insert a script into the DOM with reasonable default properties, returning a promise. If options.id
is set, will avoid loading script if the id is already in the DOM.
Returns: Promise - Promise that is either resolved or rejected. If options.id
is NOT provided or if no element exists with id of options.id
, promise is resolved when script is loaded. If options.id
IS provided and element with same id exists, promise is resolved or rejected (depending on options.onDuplicateId
) with no attempt to load new script.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| options | Object | | An object of options for loading the script. All except complete
and completeDelay
will be set as properties on the script element before it is inserted. |
| [options.src] | string | | The value of the script's src
property. Required if options.textContent
not set |
| [options.textContent] | string | | The text content of the script. Ignored if options.src
set. Required if options.src
NOT set. |
| [options.async] | boolean | true | The value of the script's async
property. Default is true
. |
| [options.completeDelay] | number | 0 | Number of milliseconds to wait when the script has loaded before resolving the Promise to account for time it might take for the script to be parsed |
| [options.id] | string | | String representing a valid identifier to set as the script element's id
property. If set, the script will not be loaded if an element with the same id already appears in the DOM |
| [options.onDuplicateId] | string | "resolve" | One of 'resolve' or 'reject'. Whether to return a resolved or rejected promise when a script with an id matching the provided options.id
is already in the DOM. Either way, the function will not attempt to load the script again and the resolved/rejected promise will be passed an object with {duplicate: true}
. |
| [...options[scriptProperties]] | boolean | string | | Any other values to be set as properties of the script element |
event
ES6 Import Example:
import {addEvent} from 'fmjs';
// or:
import {addEvent} from 'fmjs/event.js';
addEvent(el, type, handler(event), [options])
A wrapper around addEventListener
that deals with browser inconsistencies (e.g. capture
, passive
, once
props on options
param; see param documentation below for details) and handles window load similar to how jQuery handles document ready by triggering handler immediately if called after the event has already fired.
For triggering window load, this file MUST be imported before window.load occurs.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| el | Element | | DOM element to which to attach the event handler |
| type | string | | Event type |
| handler(event) | function | | Handler function. Takes event
as its argument |
| [options] | Object | boolean | false | Optional object or boolean. If boolean, indicates whether the event should be in "capture mode" rather than starting from innermost element and bubbling out. Default is false
. If object, and browser does not support object, argument is set to capture property if provided |
| [options.capture] | boolean | false | Indicates if the event should be in "capture mode" rather than starting from innermost element and bubbling out. Default is false
. |
| [options.passive] | boolean | | If true
, uses passive mode to reduce jank. This is automatically set to true
for supported browsers if not explicitly set to false
for the following event types: touchstart, touchmove, wheel, mousewheel. Ignored if not supported. |
| [options.once] | boolean | | If true
, removes listener after it is triggered once on the element. |
removeEvent(el, type, [handler], [options])
A wrapper around removeEventListener
that naïvely deals with oldIE inconsistency.
| Param | Type | Default | Description | | --- | --- | --- | --- | | el | Element | | DOM element to which to attach the event handler | | type | string | | Event type. | | [handler] | function | | Handler function to remove. | | [options] | Object | boolean | false | Optional object or boolean. If boolean, indicates whether event to be removed was added in "capture mode". Important: non-capturing here only removes non-capturing added event and vice-versa. | | [options.capture] | boolean | | Indicates whether event to be removed was added in "capture mode" |
triggerEvent(el, type, detail)
Trigger a custom event on an element for which a listener has been set up
Derived from emitEvent(): (c) 2019 Chris Ferdinandi, MIT License, https://gomakethings.com
| Param | Type | Description |
| --- | --- | --- |
| el | Element | DOM element on which to trigger the event |
| type | string | Name representing the custom event type |
| detail | Object | Object to make available as the detail
property of the event handler's event
argument |
Example
// Using this module's addEvent() function
// Add a custom event handler
addEvent(document.body, 'myCustomEvent', (event) => console.log(event.detail.weather));
// Later…
// Trigger the custom event
triggerEvent(document.body, 'myCustomEvent', {weather: 'sunshine'});
// Logs: 'sunshine'
form
ES6 Import Example:
import {getFormData} from 'fmjs';
// or:
import {getFormData} from 'fmjs/form.js';
getFormData ⇒ Any
Return the set of successful form controls of the provided form
element in one of four types: object, string, formData, or array.
Returns: Any - The set of successful form controls as the provided type
| Param | Type | Default | Description | | --- | --- | --- | --- | | form | Element | | The form element | | [type] | string | "object" | One of 'object', 'string', 'formData', or 'array' |
Methods
| Name | Type | Description |
| --- | --- | --- |
| .object(form) | function | Return form data as an object of key/value pairs |
| .string(form) | function | Return form data as a query string |
| .formData(form) | function | Return a FormData
instance |
| .array(form) | function | Return form data as an array of objects with name
and value
properties |
Example
const myform = document.getElementById('myform');
console.log(getFormData.object(myform));
// Logs:
// {
// email: '[email protected]',
// gender: 'female',
// meals: ['breakfast', 'dinner']
// }
Example
const myform = document.getElementById('myform');
console.log(getFormData.string(myform));
// Logs:
// email=name%40example.com&gender=female&meals[]=breakfast&meals[]=dinner
Example
const myform = document.getElementById('myform');
console.log(getFormData.array(myform));
// Logs:
// [
// {
// name: 'email',
// value: '[email protected]'
// },
// {
// name: 'gender',
// value: 'femail'
// },
// {
// name: 'meals[]',
// value: 'breakfast'
// },
// {
// name: 'meals[]',
// value: 'dinner'
// }
// ]
jsonp
ES6 Import Example:
import {getJSONP} from 'fmjs';
// or:
import {getJSONP} from 'fmjs/jsonp.js';
getJSONP(options, callback(json))
Function for those times when you just need to make a "jsonp" request (and you can't set up CORS on the server). In other words, x-site script grabbing.
- Warning: untested
- Warning: requires setup on server side
- Warning: not entirely safe
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| options | Object | | |
| options.url | string | | URL of the jsonp endpoint |
| [options.data] | Object | | Optional data to include with the request |
| [options.data.callback] | string | "jsonp.[timestamp]" | Optional value of the callback query-string parameter to append to the script's src
|
| callback(json) | function | | Function to be called when request is complete. A json object is passed to it. |
Example
getJSONP({url: 'https://example.com/api/'})
math
ES6 Import Example:
import {median} from 'fmjs';
// or:
import {median} from 'fmjs/math.js';
CommonJS Require Example:
const {median} = require('fmjs/cjs/math.js');
- math
- add(array) ⇒ number
- subtract(array) ⇒ number
- multiply(array) ⇒ number
- divide(array) ⇒ number
- mod(dividend, [divisor]) ⇒ number
- average(nums) ⇒ number
- median(nums) ⇒ number
- min(nums) ⇒ number
- max(nums) ⇒ number
add(array) ⇒ number
Return the result of adding an array of numbers (sum)
Returns: number - Sum
| Param | Type | Description | | --- | --- | --- | | array | array | Array of numbers |
subtract(array) ⇒ number
Return the result of subtracting an array of numbers (difference)
Returns: number - Difference
| Param | Type | Description | | --- | --- | --- | | array | array | Array of numbers |
multiply(array) ⇒ number
Return the result of multiplying an array of numbers (product)
Returns: number - Product
| Param | Type | Description | | --- | --- | --- | | array | array | Array of numbers |
divide(array) ⇒ number
Return the result of dividing an array of numbers (quotient)
Returns: number - Quotient
| Param | Type | Description | | --- | --- | --- | | array | array | Array of numbers |
mod(dividend, [divisor]) ⇒ number
Return the remainder after dividing two numbers (modulo)
Returns: number - Remainder
| Param | Type | Description | | --- | --- | --- | | dividend | number | array | A number representing the dividend OR an array of [dividend, divisor] | | [divisor] | number | Number representing the divisor if the first argument is a number |
average(nums) ⇒ number
Return the average of an array of numbers
Returns: number - Average
| Param | Type | Description | | --- | --- | --- | | nums | array | Array of numbers |
median(nums) ⇒ number
Return the median of an array of numbers
Returns: number - Median
| Param | Type | Description | | --- | --- | --- | | nums | array | Array of numbers |
min(nums) ⇒ number
Return the number with the lowest value from an array of numbers
Returns: number - Minimum value
| Param | Type | Description | | --- | --- | --- | | nums | array | Array of numbers |
max(nums) ⇒ number
Return the number with the highest value from an array of numbers
Returns: number - Maximum value
| Param | Type | Description | | --- | --- | --- | | nums | array | Array of numbers |
object
ES6 Import Example:
import {deepCopy} from 'fmjs';
// or:
import {deepCopy} from 'fmjs/object.js';
CommonJS Require Example:
const {deepCopy} = require('fmjs/cjs/object.js');
- object
- isObject(obj)
- isPlainObject(obj)
- deepCopy(obj, [cache]) ⇒ Object
- extend(target, ...object) ⇒ Object
- getProperty(root, properties, fallbackVaue) ⇒ *
- isEmptyObject(object) ⇒ boolean
- setProperty(root, properties) ⇒ Object
- forEachValue(obj, fn) ⇒ undefined
- pick(obj, props) ⇒ Object
- omit(obj, props) ⇒ Object
isObject(obj)
Indicate if the provided argument is an object/array
| Param | Type | Description | | --- | --- | --- | | obj | Object | The argument that will be checked to see if it is an object |
isPlainObject(obj)
Indicate if the provided argument is a plain object Derived from lodash _.isPlainObject
| Param | Type | Description | | --- | --- | --- | | obj | Object | The argument that will be checked to see if it is a plain object |
deepCopy(obj, [cache]) ⇒ Object
Deep copy an object, avoiding circular references and the infinite loops they might cause.
Returns: Object - A copy of the object
| Param | Type | Description | | --- | --- | --- | | obj | Object | The object to copy | | [cache] | Array.<Object> | Used internally to avoid circular references |
extend(target, ...object) ⇒ Object
Deep merge two or more objects in turn, with right overriding left
Heavily influenced by/mostly ripped off from jQuery.extend
Returns: Object - The merged object
| Param | Type | Description |
| --- | --- | --- |
| target | Object | The target object that will be mutated. Use {}
to create new object |
| ...object | Object | One or more objects to merge into the first |
Example
const foo = {
one: 'singular',
two: 'are better'
};
const bar = {
one: 'taste',
choco: 'hershey',
saloon: 'wild west',
};
const merged = extend(foo, bar);
// merged is now:
// {
// one: 'taste',
// two: 'are better',
// choco: 'hershey',
// saloon: 'wild west',
// }
// because foo was mutated, it is also:
// {
// one: 'taste',
// two: 'are better',
// choco: 'hershey',
// saloon: 'wild west',
// }
getProperty(root, properties, fallbackVaue) ⇒ *
Get a nested property of an object in a safe way
Returns: * - The value of the nested property, or undefined
, or the designated fallback value
| Param | Type | Description | | --- | --- | --- | | root | Object | The root object | | properties | Array.<String> | String | Either an array of properties or a dot-delimited string of properties | | fallbackVaue | Any | A value to assign if it's otherwise undefined |
Example
const foo = {
could: {
keep: {
going: 'but will stop'
}
};
console.log(getProperty(foo, 'could.keep.going'))
// Logs: 'but will stop'
console.log(getProperty(foo, ['could', 'keep', 'going']))
// Logs: 'but will stop'
console.log(getProperty(foo, ['broken', 'not', 'happening']))
// Logs: undefined
};
isEmptyObject(object) ⇒ boolean
Determine whether an object (or array) is "empty"
Returns: boolean - true
if object has no keys or array no elements
| Param | Type | Description | | --- | --- | --- | | object | Object | array | The object to test |
setProperty(root, properties) ⇒ Object
Set a nested property of an object in a safe way
Returns: Object - The modified root object
| Param | Type | Description | | --- | --- | --- | | root | Object | The root object | | properties | array.<String> | String | Either an array of properties or a dot-delimited string of properties |
forEachValue(obj, fn) ⇒ undefined
Loop through an object, calling a function for each element (like forEach, but for an object)
| Param | Type | Description | | --- | --- | --- | | obj | Object | The object to iterate over | | fn | function | A function to be called for each member of the object. The function takes two parameters: the member's value and the member's key, respectively |
pick(obj, props) ⇒ Object
Return a new object containing only the properties included in the props array.
Returns: Object - A copy of the object, containing only the props
properties
| Param | Type | Description | | --- | --- | --- | | obj | Object | The object from which to get properties | | props | array | Propertes to get from the object |
omit(obj, props) ⇒ Object
Return a new object, excluding the properties in the props array.
Returns: Object - A modified copy of the object
| Param | Type | Description | | --- | --- | --- | | obj | Object | The object from which to get properties | | props | array | Propertes to exclude from the object |
promise
ES6 Import Example:
import {peach} from 'fmjs';
// or:
import {peach} from 'fmjs/promise.js';
CommonJS Require Example:
const {peach} = require('fmjs/cjs/promise.js');
peach(arr, callback(item,i)) ⇒ array.<Promise>
"Promised each()
" for iterating over an array of items, calling a function that returns a promise for each one. So, each one waits for the previous one to resolve before being called
Returns: array.<Promise> - Array of promises
| Param | Type | Description | | --- | --- | --- | | arr | array | Array to iterate over | | callback(item,i) | callback | Function that is called for each element in the array, each returning a promise |
selection
ES6 Import Example:
import {getSelection} from 'fmjs';
// or:
import {getSelection} from 'fmjs/selection.js';
replaceSelection ⇒ Object
Replace the selected text in a given element with the provided text
Returns: Object - Selection object containing the following properties: {start, end, length, text}
| Param | Type | Description | | --- | --- | --- | | elem | Element | Element containing the selected text | | replaceString | string | String to replace the selected text |
setSelection(elem, [startPos], [endPos])
Set the selection of an element's contents. NOTE: If startPos and/or endPos are used on a non-input element, only the first text node within the element will be used for selection
| Param | Type | Default | Description | | --- | --- | --- | --- | | elem | Element | | The element for which to set the selection | | [startPos] | number | 0 | The start position of the selection. Default is 0. | | [endPos] | number | | The end position of the selection. Default is the last index of the element's contents. |
setSelectionAll(el)
Sets the selection of all of the element's contents (including all of its children)
- Warning: untested
| Param | Type | Description | | --- | --- | --- | | el | Element | The element for which to select all content |
getSelection(el)
Return an object with the following properties related to the selected text within the element:
start
: 0-based index of the start of the selectionend
: 0-based index of the end of the selectionlength
: the length of the selectiontext
: the selected text within the element
| Param | Type | Description | | --- | --- | --- | | el | Element | An element with selected text |
storage
ES6 Import Example:
import {Storage} from 'fmjs';
// or:
import {Storage} from 'fmjs/storage.js';
- storage
- instance
- getLength() ⇒ number
- get(key) ⇒ Any
- set(key, value) ⇒ string
- remove(key)
- clear()
- getAll() ⇒ Object
- keys() ⇒ array
- inner
- instance
getLength() ⇒ number
Get the number of items in the storage
Returns: number - The number of items
get(key) ⇒ Any
Get and JSON.parse the value of the storage item identified by key
Returns: Any - The JSON.parsed value of the storage item
| Param | Type | Description | | --- | --- | --- | | key | string | The key of the storage item |
set(key, value) ⇒ string
Set the JSON.stringified value of the storage item identified by key
Returns: string - The stringified value that is set
| Param | Type | Description |
| --- | --- | --- |
| key | string | The key of the storage item |
| value | Any | The value to be set for key
|
remove(key)
Remove the storage item identified by key
| Param | Type | Description | | --- | --- | --- | | key | string | The key of the storage item to remove |
clear()
Remove all storage items
getAll() ⇒ Object
Get an object of key/value pairs of all storage items
Returns: Object - All storage items
keys() ⇒ array
Loop through all storage items and return an array of their keys
Returns: array - Array of the keys of all storage items
Storage
Storage([type], [namespace])
Constructor for storage functions.
| Param | Type | Default | Description | | --- | --- | --- | --- | | [type] | string | "local" | Type of storage: either 'local' or 'session' | | [namespace] | string | "fm" | Namespace for keys to prevent potenial collisions with storage items used by libraries, etc. |
string
ES6 Import Example:
import {slugify} from 'fmjs';
// or:
import {slugify} from 'fmjs/string.js';
CommonJS Require Example:
const {slugify} = require('fmjs/cjs/string.js');
- string
- stringTo(value, [type], [options]) ⇒ Boolean | Number | Array
- pluralize(str, num, [ending]) ⇒ string
- changeCase(str, type) ⇒ string
- slugify(str) ⇒ string
- commafy(val, [separator]) ⇒ string
- rot13(string) ⇒ string
- hashCode(str, [prefix]) ⇒ number | string
- base64Encode(str) ⇒ string
- base64Decode(str) ⇒ string
stringTo(value, [type], [options]) ⇒ Boolean | Number | Array
Casts a value to the specified type
or to best guess at a type if none given
| Param | Type | Description | | --- | --- | --- | | value | string | Value to cast | | [type] | function | (Boolean|Number|Array) | | [options] | object | |
pluralize(str, num, [ending]) ⇒ string
Converts a singular word to a plural
Returns: string - Pluralized string
| Param | Type | Default | Description | | --- | --- | --- | --- | | str | string | | Word to pluralize | | num | number | | Number of items | | [ending] | string | "s" | Optional ending of the pluralized word |
changeCase(str, type) ⇒ string
Changes the case of the provided words according to the type
.
Returns: string - Converted string
| Param | Type | Description |
| --- | --- | --- |
| str | string | String that will be cased as determined by type
|
| type | string | One of 'title|sentence|caps|camel|slug' |
Example
const oldMan = 'the old man and the sea';
console.log(changeCase(oldMan, 'title'));
// Logs: 'The Old Man and the Sea'
console.log(changeCase(oldMan, 'sentence'));
// Logs: 'The old man and the sea'
console.log(changeCase(oldMan, 'camel'));
// Logs: 'theOldManAndTheSea'
slugify(str) ⇒ string
Slugify a string by lowercasing it and replacing white spaces and non-alphanumerics with dashes.
Returns: string - "Slugified" string
| Param | Type | Description | | --- | --- | --- | | str | string | String to be converted to a slug |
Example
console.log(slugify('Hello there, how are you?'));
// Logs: 'hello-there-how-are-you'
console.log(slugify(' You? & Me<3* '));
// Logs: 'you-me-3'
commafy(val, [separator]) ⇒ string
Add commas (or provided separator
) to a number, or a string representing a number, of 1000 or greater.
Returns: string - number formatted as string
| Param | Type | Default | Description | | --- | --- | --- | --- | | val | string | number | | Number to be formatted as a string | | [separator] | string | "," | punctuation to be used for thousands, millions, etc |
rot13(string) ⇒ string
ROT13 encode/decode a string
Returns: string - The encoded (or decoded) string
| Param | Type | Description | | --- | --- | --- | | string | string | String to be converted to or from ROT13 |
hashCode(str, [prefix]) ⇒ number | string
Convert a string to Java-like numeric hash code
Returns: number | string - The converted hash code as numeral (or string, if prefix is provided)
See: http://werxltd.com/wp/2010/05/13/javascript-implementation-of-javas-string-hashcode-method/
| Param | Type | Description | | --- | --- | --- | | str | string | String to be converted | | [prefix] | string | Optional prefix to the hash |
base64Encode(str) ⇒ string
Return a base64-encoded string based on the provided string. If the browser does not support this type of encoding, returns the string unchanged.
Returns: string - base64-encoded string
| Param | Type | Description | | --- | --- | --- | | str | string | String to be base4 encoded |
base64Decode(str) ⇒ string
Return a decoded string based on the provided base64-encoded string. If the browser does not support this type of encoding, returns the string unchanged.
Returns: string - decoded string
| Param | Type | Description | | --- | --- | --- | | str | string | base4-encoded string |
timer
ES6 Import Example:
import {debounce} from 'fmjs';
// or:
import {debounce} from 'fmjs/timer.js';
CommonJS Require Example:
const {debounce} = require('fmjs/cjs/timer.js');
HOUR : number
Constant representing the number of milliseconds in an hour
DAY : number
Constant representing the number of milliseconds in a day
YEAR : number
Constant representing the number of milliseconds in a year
debounce(fn, [timerDelay], [ctx])
Set up a function to be called once at the end of repeated potential calls within a given delay
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| fn | function | | The function to trigger once at the end of a series of potential calls within delay
|
| [timerDelay] |