amp-utils v1.1.0
amp
A collection of handy utilities.
Installation
npm install amp-utils
Usage
const amp = require('amp-utils');
amp.string.slug('This string will be slugged.');
Array Utilities
amp.array.move(array, from, to)
Move an item within an array. Returns Array
.
Configuration
array
: The targetArray
from
: The oldInteger
index of the array itemto
: The newInteger
index of the array item
Examples
const breakfast = [
'eggs',
'toast',
'bacon',
];
amp.array.move(breakfast, 2, 0); // ['bacon', 'eggs', 'toast']
amp.array.unique(array)
Get unique items from an array. Returns Array
.
Configuration
array
: The targetArray
Examples
amp.array.unique(['a', 'a', 'b', 'c', 'c']); // ['a', 'b', 'c']
HTML Utilities
amp.html.closest(start, selector)
Get the closest matching HTML element parent by CSS selector. Returns HTMLElement
or null
(if no matching parent is found).
Configuration
start
: The startingHTMLElement
selector
: A valid CSS selectorString
for matching parent elements
Examples
amp.html.closest(document.getElementById('menu'), '.menu-container');
amp.html.matches(el, selector)
Does this DOM element match the provided CSS selector? Returns Boolean
.
Configuration
el
: TheHTMLElement
for comparisonselector
: A valid CSS selectorString
for matching
Examples
amp.html.matches(document.getElementById('menu'), '.menu');
Object Utilities
amp.object.byPath(search, path, value)
Get or set object value by key path. Returns Object
or null
if the target object is not found.
Configuration
search
: TheObject
that will be searchedpath
: TheString
path to the target object or value in dot notation (for example, 'parent.child.grandchild')value
: Set target object to this value instead of getting its value
Examples
const ride = {
type: 'Truck',
wheels: 4,
passengers: {
driver: {
name: 'Edith',
age: 30,
},
shotgun: {
name: 'Edmund',
age: 29,
}
},
};
amp.object.byPath(ride, 'type'); // 'Truck'
amp.object.byPath(ride, 'passengers.driver.name'); // 'Edith'
amp.object.byPath(ride, 'passengers.shotgun.name', 'Joe'); // Object ('Edmund' is now 'Joe')
amp.object.clone(obj)
Clone an object. Returns Object
.
Configuration
obj
: TheObject
that will be cloned
Examples
const original = {
a: 'one',
b: {
one: [1, 2, 3],
},
};
const clone = amp.object.clone(original);
amp.object.equal(a, b)
Compare two Objects
for equality. Returns Boolean
.
Configuration
a
: The firstObject
for comparisonb
: The secondObject
for comparison
Examples
amp.object.equal({ a: 'A'}, { a: 'A'}); // true
amp.object.equal({ a: 'A' }, { a: 'B' }); // false
amp.object.is(obj)
Is this an object? Returns Boolean
.
Configuration
obj
: TheObject
in question
Examples
amp.object.is({ a: 'A' }); // true
amp.object.is('A string!'); // false
amp.object.merge(target, ...sources)
Deep merge two or more objects. Returns Object
.
Configuration
target
: Properties will be copied into thisObject
sources
: One or more sourceObjects
to merge into the target
Examples
amp.object.merge({ a: 'A' }, { b: 'B' }); // { a: 'A', b: 'B' }
amp.object.merge({ a: 'A' }, { a: 'B' }); // { a: 'B' }
amp.object.options(defaultConfig, config)
Build a configuration object with default values. Returns Object
. This is similar to the amp.object.merge()
method, but does not overwrite the default configuration values. Note that you may also use amp.options()
, a synonym for this method.
Configuration
defaultConfig
: Default configuration optionsObject
config
: Configuration optionsObject
, will overwrite default options
Examples
const getAnimal = (config) => {
const options = amp.object.options({
name: 'Moby',
type: 'dog',
}, config);
return options;
};
getAnimal({ name: 'Mighty' }); // { name: 'Mighty', type: 'dog' }
getAnimal({ name: 'Edith', type: 'cat' }); // { name: 'Edith', type: 'cat' }
getAnimal({ name: 'T-Bone', type: 'bird', age: 3 }); // { name: 'T-Bone', type: 'bird', age: 3 }
Query String Utilities
amp.queryString.get(uri, key)
Parse query string for a parameter value. Returns String
or null
if no value is found.
Configuration
uri
: The URI or queryString
key
: The query string parameter name (String
)
Examples
const url = '?name=Edmund&type=cat';
amp.queryString.get(url, 'name'); // 'Edmund'
amp.queryString.get(url, 'type'); // 'cat'
amp.queryString.set(uri, key, value)
Update query string with a new parameter value. Returns String
.
Configuration
uri
: The URI or queryString
key
: The query string parameter name (String
)value
: The new parameter value
Examples
const url = '?name=Edmund&type=cat';
amp.queryString.set(url, 'name', 'Edith'); // '?name=Edith&type=cat'
amp.queryString.set(url, 'age', '3'); // '?name=Edmund&type=cat&age=3'
String Utilities
amp.string.guid()
Generate a globally unique identifier (GUID) string. Returns String
.
Examples
amp.string.guid(); // '5aac52a7-d431-aecc-8d35-ef18bf1cbb85'
amp.string.guid(); // 'f2295534-89e3-50cd-18d7-120c62311ac7'
amp.string.slug(str)
Slugify the given string. Returns String
.
Configuration
str
: TheString
to slugify
Examples
amp.string.slug('Pomp & Circumstance'); // 'pomp-circumstance'
amp.string.titleCase(str)
Transform a string to title case. Returns String
.
Configuration
str
: TheString
to transform
Examples
amp.string.titleCase('eine kleine nachtmusik'); // 'Eine Kleine Nachtmusik'
amp.string.trimSlashes(path)
Trim slashes from a string or path. Returns String
.
Configuration
path
: TheString
that will be trimmed
Examples
amp.string.trimSlashes('/dogs/moby/fetch/'); // 'dogs/moby/fetch'