gugutz / vanilla-commons

Lightweight common vanilla utilities for the modern web development
MIT License
37 stars 4 forks source link

vanilla-commons

Lightweight common vanilla utilities for the modern web development

npm Travis Coveralls David gzip size

Table of Contents

Install

This project uses node and npm. Go check them out if you don't have them locally installed.

$ npm install --save vanilla-commons

The UMD build is also available on jsdelivr:

<script src="https://cdn.jsdelivr.net/npm/vanilla-commons/dist/vanilla-commons.umd.min.js"></script>

You can find the library on window.commons.

Usage

import {
  addMinutes,
  addHours,
  addDays,
  addMonths,
  addYears,
  formatDate,
  pipe
} from 'vanilla-commons'

const date = new Date('December 17, 1995 03:24:00')
const format = '{DD}/{MM}/{YYYY} {HH}:{mm}:{ss}:{ms}'

const finalDate = pipe(
  addMinutes(1),
  addHours(9),
  addDays(7),
  addMonths(-9),
  addYears(-2),
  formatDate(format)
)(date)
// '24/03/1993 12:25:00:00'

Array Commons

flattenArray(arr)

Flatten nested arrays.

Parameters

Returns

Array flattened.

Examples

import {flattenArray} from 'vanilla-commons'

flattenArray([[1], [2, [3, 4]]])
// [1, 2, 3, 4]

Date Commons

addDays(days, date)

Add days to a Date.

Parameters

Returns

Date with the days added.

Examples

import {addDays} from 'vanilla-commons'

addDays(6, new Date('December 17, 1995 03:24:00'))
// Sat, 23 Dec 1995 03:24:00

addDays(-6, new Date('December 17, 1995 03:24:00'))
// Mon, 11 Dec 1995 03:24:00

addDays(6)(new Date('December 17, 1995 03:24:00'))
// Sat, 23 Dec 1995 03:24:00

addHours(hours, date)

Add hours to a Date.

Parameters

Returns

Date with the hours added.

Examples

import {addHours} from 'vanilla-commons'

addHours(6, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:00

addHours(-6, new Date('December 17, 1995 03:24:00'))
// Fri, 16 Dec 1995 21:24:00

addHours(6)(new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:00

addMilliseconds(milliseconds, date)

Add milliseconds to a Date.

Parameters

Returns

Date with the milliseconds added.

Examples

import {addMilliseconds} from 'vanilla-commons'

addMilliseconds(1000, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:01

addMilliseconds(-1000, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:23:59

addMilliseconds(1000)(new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:01

addMinutes(minutes, date)

Add minutes to a Date.

Parameters

Returns

Date with the minutes added.

Examples

import {addMinutes} from 'vanilla-commons'

addMinutes(6, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:06

addMinutes(-6, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:23:54

addMinutes(6)(new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:24:06

addMonths(months, date)

Add months to a Date.

Parameters

Returns

Date with the months added.

Examples

import {addMonths} from 'vanilla-commons'

addMonths(6, new Date('December 17, 1995 03:24:00'))
// Mon, 17 Jun 1996 09:24:00

addMonths(-6, new Date('December 17, 1995 03:24:00'))
// Sat, 17 Jun 1995 09:24:00

addMonths(6)(new Date('December 17, 1995 03:24:00'))
// Mon, 17 Jun 1996 09:24:00

addSeconds(seconds, date)

Add seconds to a Date.

Parameters

Returns

Date with the seconds added.

Examples

import {addSeconds} from 'vanilla-commons'

addSeconds(6, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:30:00

addSeconds(-6, new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:18:00

addSeconds(6)(new Date('December 17, 1995 03:24:00'))
// Sun, 17 Dec 1995 09:30:00

addWeeks(weeks, date)

Add weeks to a Date.

Parameters

Returns

Date with the weeks added.

Examples

import {addWeeks} from 'vanilla-commons'

addWeeks(1, new Date('December 17, 1995 03:24:00'))
// Sun, 24 Dec 1995 09:24:00

addWeeks(-1, new Date('December 17, 1995 03:24:00'))
// Sun, 10 Dec 1995 09:24:00

addWeeks(6)(new Date('December 17, 1995 03:24:00'))
// Sun, 24 Dec 1995 09:24:00

addYears(years, date)

Add years to a Date.

Parameters

Returns

Date with the years added.

Examples

import {addYears} from 'vanilla-commons'

addYears(1, new Date('December 17, 1995 03:24:00'))
// Tue, 17 Dec 1996 09:24:00

addYears(-1, new Date('December 17, 1995 03:24:00'))
// Sat, 17 Dec 1994 09:24:00

addYears(1)(new Date('December 17, 1995 03:24:00'))
// Tue, 17 Dec 1996 09:24:00

diffDate(firstDate, secondDate)

Calculate the diff of two Date objects.

Parameters

Returns

Date with the years added.

Examples

import {diffDate} from 'vanilla-commons'

diffDate(
  new Date('December 17, 1995 03:24:00'),
  new Date('December 17, 1996 03:25:00')
)
// {
//   milliseconds: 31622460000,
//   seconds: 31622460,
//   minutes: 527041,
//   hours: 8784.02,
//   days: 366,
//   weeks: 52.29,
//   months: 12.2,
//   years: 1
// }

formatDate(format, date)

Format a date given a expected format. Use the following patterns inside your format:

Parameters

Returns

string formatted date.

Examples

import {formatDate} from 'vanilla-commons'

formatDate(
  '{DD}/{MM}/{YYYY} {HH}:{mm}:{ss}:{ms}',
  new Date('December 17, 1995 03:24:00')
)
// '17/12/1995 03:24:00:00'

isValidDate(format, dateStr)

Checks the validity of a given date string. Use the following patterns inside your format:

Parameters

Returns

Boolean true if the date is valid.

Examples

import {isValidDate} from 'vanilla-commons'

isValidDate('{DD}/{MM}/{YYYY} {HH}:{mm}:{ss}:{ms}', '17/12/1995 03:24:00:00')
// true

isValidDate('{DD}/{MM}/{YYYY} {HH}:{mm}:{ss}:{ms}', '29/02/1995 03:24:00:00')
// false

parseDate(format, dateStr)

Parse a date string to a date object given a format. Use the following patterns inside your format:

Parameters

Returns

Date parsed date.

Examples

import {parseDate} from 'vanilla-commons'

parseDate('{DD}/{MM}/{YYYY} {HH}:{mm}:{ss}:{ms}', '17/12/1995 03:24:00:00')
// Sun, 17 Dec 1995 03:24:00

Element Commons

addClass(newClass, element)

Add a class to a DOM Element.

Parameters

Returns

Element in which the changes were made.

Examples

import {addClass} from 'vanilla-commons'

const element = document.querySelector('.element')
addClass('hey')(element)
// <div class="element hey"></div>

addClass(['there', 'man'], element)
// <div class="element hey there man"></div>

clearEvents(element)

Remove all the event listeners of a element and its children.

Parameters

Returns

Element element that the events were removed.

Examples

// See the tests for better examples https://github.com/gugutz/vanilla-commons/blob/master/test/element/clear-events.test.js
import {clearEvents} from 'vanilla-commons'

const element = document.querySelector('.element')
clearEvents(element)

createElement(selector?, props?, children?)

Create a DOM element.

Parameters

Returns

Element created.

Examples

// See the tests for better examples https://github.com/gugutz/vanilla-commons/blob/master/test/element/create-element.test.js
import {createElement} from 'vanilla-commons'

createElement()
// <div></div>

createElement('input#id.class[type=text][required]')
// <input id="id" class="class" type="text" disabled required/>

createElement('div', {
  data: {
    ref: 'hey',
    error: 'bad'
  }
})
// <div data-ref="hey" data-error="bad"></div>

createElement('p', {
  className: 'hey there man'
})
// <p class="hey there man"></p>

createElement('p', {
  onclick: function() {
    console.log('clicked')
  }
})
// It's easy to work with events!

createElement('div', [
  createElement('input[type=text]'),
  'hey',
  createElement('img[src=coolimage.jpg]')
])
// <div>
//   <input type=""/>
//   hey
//   <img src="https://github.com/gugutz/vanilla-commons/raw/master/coolimage.jpg"/>
// </div>

getParents(element)

Get all the parents of a given element.

Parameters

Returns

Array the parents of the element, including the body.

Examples

// See the tests for better examples https://github.com/gugutz/vanilla-commons/blob/master/test/element/get-parents.test.js
import {getParents} from 'vanilla-commons'

const element = document.querySelector('.element')
getParents(element)

hasClass(classToCheck, element)

Check if a DOM Element has the specified class.

Parameters

Returns

Element to check if has the specified class.

Examples

import {hasClass} from 'vanilla-commons'

const element = document.createElement('div')
element.className = 'hey there'

hasClass('hey')(element)
// true

hasClass('hey', element)
// true

hasClass('man', element)
// false

hasClass(['hey', 'there'], element)
// true

hasClass(['hey', 'man'], element)
// false

hideElement(elementToHide)

Hide a Element from the DOM.

Parameters

Returns

(Array | Element) element or array of elements that were hidden.

Examples

import {hideElement} from 'vanilla-commons'

const element = document.createElement('div')
element.style.display
// block

hideElement(element)
element.style.display
// none
import {hideElement} from 'vanilla-commons'

const element1 = document.createElement('div')
element1.style.display
// block

const element2 = document.createElement('div')
element2.style.display
// block

hideElement([element1, element2])

element1.style.display
// none

element2.style.display
// none

insertElementAfter(referenceElement, newElement)

Insert a element after a reference element.

Parameters

Returns

Element that were inserted.

Examples

import {insertElementAfter} from 'vanilla-commons'

insertElementAfter(referenceElement, newElement)

insertElementBefore(referenceElement, newElement)

Insert a element before a reference element.

Parameters

Returns

Element that were inserted.

Examples

import {insertElementBefore} from 'vanilla-commons'

insertElementBefore(referenceElement, newElement)

killElement(elementToKill)

Kill a Element from the DOM.

Parameters

Examples

import {killElement} from 'vanilla-commons'

killElement(element)

killElement([element1, element2])

removeClass(classToRemove, element)

Remove a class of a DOM Element.

Parameters

Returns

Element that the had the class removed.

Examples

import {removeClass} from 'vanilla-commons'

removeClass('hey')(element)

removeClass('hey', element)

removeClass(['hey', 'there'], element)

replaceElement(originalElement, newElement)

Replace a DOM element with another element.

Parameters

Returns

Element element that replaced the old one.

Examples

import {replaceElement} from 'vanilla-commons'

replaceElement(originalElement, newElement)

showElement(elementToShow)

Show a hidden Element from the DOM.

Parameters

Returns

(Array | Element) element or array of elements that were showed.

Examples

import {showElement} from 'vanilla-commons'

showElement(element)

showElement([element1, element2])

toggleClass(classToToggle, element)

Toggle a class from a DOM Element.

Parameters

Returns

Element that the changes were made.

Examples

import {toggleClass} from 'vanilla-commons'

toggleClass('hey')(element)

toggleClass('hey', element)

toggleClass(['hey', 'there'], element)

Function Commons

compose(fn[, fn1, ..., fnN])

Performs right-to-left function composition.

Parameters

Returns

Examples

import {curry, compose} from 'vanilla-commons'

const add = curry((a, b) => a + b)

const multiply = curry((a, b) => a * b)

const composedFunction = compose(add(5), multiply(4), add(3))
composedFunction(2)
// (((2 + 3) * 4) + 5) = 25

curry(fn)

Returns a curried equivalent of the provided function

Parameters

Returns

Examples

import {curry} from 'vanilla-commons'

const addFourNumbers = (a, b, c, d) => a + b + c + d

const curriedAddFourNumbers = curry(addFourNumbers)
curriedAddFourNumbers(1, 2)(3)(4)
// 10

curriedAddFourNumbers(1, 2)(3, 4)
// 10

curriedAddFourNumbers(1)(2)(3)(4)
// 10

curriedAddFourNumbers(1, 2, 3)(4)
// 10

pipe(fn[, fn1, ..., fnN])

Performs left-to-right function composition.

Parameters

Returns

Examples

import {curry, pipe} from 'vanilla-commons'

const add = curry((a, b) => a + b)

const multiply = curry((a, b) => a * b)

const pipedFunction = pipe(add(5), multiply(4), add(3))
pipedFunction(2)
// (((2 + 5) * 4) + 3) = 31

throttle(limit, fn)

Creates a function that will call fn at most once every wait milliseconds.

Parameters

Returns

Examples

import {throttle} from 'vanilla-commons'

window.addEventListener('scroll', throttle(100, e => {
  console.log(e)
}))

Number Commons

round(num)

Round a number to two decimal places.

Parameters

Returns

Number rounded number.

Examples

import {round} from 'vanilla-commons'

round(3.141592)
// 3.14

round(-27.817987)
// -27.82

Object Commons

mapKeys(fn, obj)

Map over the keys of a object.

Parameters

Returns

Object mapped object.

Examples

import {mapKeys} from 'vanilla-commons'

mapKeys(function(key) {
  return key + 'hey'
}, {
  captain: 'picard',
  firstOfficer: 'riker'
})
// {
//   captainhey: 'picard',
//   firstOfficerhey: 'riker'
// }

mapValues(fn, obj)

Map over the values of a object.

Parameters

Returns

Object mapped object.

Examples

import {mapValues} from 'vanilla-commons'

mapValues(function(value) {
  return value + 'hey'
}, {
  captain: 'picard',
  firstOfficer: 'riker'
})
// {
//   captain: 'picardhey',
//   firstOfficer: 'rikerhey'
// }

String Commons

capitalize(str)

Converts the first character of string to upper case.

Parameters

Returns

string capitalized string.

Examples

import {capitalize} from 'vanilla-commons'

capitalize('vanilla')
// Vanilla

cleanUpString(str)

Removes the all line breaks in the entire string and also the white spaces from the both ends of the string.

Parameters

Returns

string clean string.

Examples

import {cleanUpString} from 'vanilla-commons'

cleanUpString('\n \n\r \r\n')
// ''

cleanUpString('\n \n\r hjhj ')
// 'hjhj'

Prior Art

Vanilla Commons is fully inspired by these projects:

Contributing

See the contributing file.

License

MIT License © Gustavo P Borges