#jsCore JavaScript library

The library consists of a complex polyfill and a set of methods in the lib namespace.

To use jsCore, just drop a single JavaScript file into your page:

<script src="jscore.js"></script>

Download the latest jsCore from GitHub or install via Bower:

bower install jscore

This is designed to be run in a browser and it depends on there being a document. It does not work in a Node.js or worker environment.

##Contents

• Polyfill
  • Notes/known issues
• Namespace lib
  • Method .classExtends
  • Constructor .Template()
  • Constructor .I18n()
    • Instance methods .add() and .use()
  • Namespace .html
    • Method .parse()
    • Method .escape()
    • Method .unescape()
  • Namespace .array
    • Method .count()
    • Method .all()
    • Method .unique()
    • Method .refine()
    • Method .shuffle()
    • Method .range()
    • Method .remove()
  • Namespace .css
    • Method .prefix()
    • Method .get()
    • Method .set()
    • Method .getTransitionTime()
    • Prefixed property names
  • Namespace .dom
    • Method .ready()
    • Methods .addClass(), .removeClass() and .toggleClass()
  • Namespace .event
    • Method .on()
    • Method .off()
    • Method .one()
    • Method .when()
    • Method .preventDefault()
    • Method .stopPropagation()
    • Method .awaitTransitionEnd()
    • Method .awaitAnimationEnd()
    • Method .awaitTransAnimEnd()
    • Prefixed event types
  • Namespace .date
    • Method .isLeapYear()
    • Method .getMonthLength()
  • Namespace .cookie
    • Method .get()
    • Method .set()
    • Method .has()
    • Method .remove()
    • Method .keys()
  • Namespace and method .request()
    • Method .get()
    • Method .post()
    • Method .json()
    • Method .script()
    • Method .jsonp()
    • Method .toQueryParam()
    • Method .toQueryString()
• License

##Polyfill

Object/Scope	Methods/Properties
global	FormData()12, Set(), Map(), WeakSet(), WeakMap()
window	.setImmediate(), .clearImmediate(), .requestAnimationFrame(), .cancelAnimationFrame(), .getComputedStyle()
Object generics	.create()1, .assign()2, .is(), .keys()3, .setPrototypeOf()16
Array generics4	.isArray(), .from(), .of(), .concat(), .every(), .fill(), .filter(), .find(), .findIndex(), .forEach(), .indexOf(), .join(), .lastIndexOf(), .map(), .pop(), .push(), .reduce(), .reduceRight(), .reverse(), .shift(), .slice()5, .some(), .sort(), .splice()6, .unshift()
Array.prototype	.every(), .fill(), .filter(), .find(), .findIndex(), .forEach(), .indexOf(), .lastIndexOf(), .map(), .reduce(), .reduceRight(), .some(), .includes()
String generics	.charAt(), .charCodeAt(), .concat(), .includes(), .endsWith(), .indexOf(), .lastIndexOf(), .match(), .repeat(), .replace(), .search(), .slice(), .split(), .startsWith(), .substr(), .substring(), .toLowerCase(), .toUpperCase(), .trim()
String.prototype	.includes(), .endsWith(), .repeat(), .startsWith(), .trim()
Number generics	.isInteger(), .isFinite(), .isNaN(), .parseInt(), .parseFloat()
Math generics	.trunc(), .sign()
Function.prototype	.bind()
Text.prototype	.textContent
HTMLElement.prototype	.matches(), .addEventListener(), .removeEventListner(), .dispatchEvent(), .children7, .firstElementChild, .lastElementChild, .childElementCount, .nextElementSibling, .previousElementSibling, .textContent, .classList8, .dataset9
HTMLScriptElement.prototype	.onload()10, .onerror()10
CSSStyleDeclaration.prototype	.getPropertyValue(), .removeProperty(), .setProperty(), .cssFloat, .opacity
document	.head, .createEvent()11
FormData.prototype	.append()
Event.prototype13	.initEvent()14, .initUIEvent()14, .initMouseEvent()14, .initCustomEvent(), .pageX, .pageY, .timeStamp, .target, .relatedTarget
XMLHttpRequest.prototype	.send()15, .onload(), .onerror(), .onabort()
Date generics	.now()
Promise generics	.resolve(), .reject(), .all(), .race()
Promise.prototype	.then, .catch17
Set.prototype	.add(), .has(), .delete()17, .clear(), .size
Map.prototype	.set(), .get(), .has(), .delete()17, .clear(), .size
WeakSet.prototype	.add(), .has(), .delete()17, .clear()
WeakMap.prototype	.set(), .get(), .has(), .delete()17, .clear()

###Notes/Known Issues

¹ – Object.create implementation:

• only accepts the first parameter in IE8
• Object.create(null) instanceof Object returns true in IE8
• fixes a bug with numeric keys in IE9-11

² – Object.assign() supports a variable number of sources @rwaldron

³ – Object.keys fixes a DontEnum bug in IE8

⁴ – some Firefox's built-in methods are missed in standard or in drafts of future standards, but these must-have features

< Array.slice.toString()
> "function slice() {
     [native code]
  }"

⁵ – Array.slice() supports array-like DOM objects in IE8

⁶ – Array.splice() fixes a bug with array-like objects in IE8

⁷ – element.children fixes a bug with comment nodes in IE8

⁸ – element.classList doesn't update automatically when you change element.className

⁹ – element.dataset doesn't add an attribute when you add a new property

¹⁰ – don't use script.onload() and script.onerror() with script.onreadystatechange()

¹¹ – document.createEvent() supports CustomEvent

¹² – FormData() doesn't support <input type="file">, but if you know file contents, it can be added using .append()

¹³ – global event constructors (Event(), CustomEvent(), etc.) not available, use document.createEvent()

¹⁴ – event methods (.initEvent(), .initMouseEvent(), etc.) just copy all function parameters to the instance of Event(), the main purpose is to set the type of the event without IE8 check

¹⁵ – xhr.send() supports FormData()

¹⁶ – Object.setPrototypeOf implementation requires __proto__ support (IE10+)

¹⁷ – IE8 doesn't allow to use the dot notation as accessor for methods called “catch” and “delete”

##lib

###lib.classExtends()

.classExtends() is the standard inheritance pattern

lib.classExtends(Class, SuperClass);
Class.Super //→ SuperClass

###lib.Template()

.Template() is a very simple string templating tool (not to be confused with HTML templating)

var tmpl = new lib.Template('Hi, {NAME}');
tmpl({name: 'John'}) //→ 'Hi, John'
tmpl({name: 'Luke'}) //→ 'Hi, Luke'

###lib.I18n()

.I18n() is a handy tool for the internationalization

var i18n = new lib.I18n([locale[, messageBundle]]);
i18n.add(locale, messageBundle)
i18n.use(locale)
i18n(message[, replacements]) //→ string

example:

var ruRU = {currency: 'руб.'},
    enUS = {currency: '$'},
    i18n = new lib.I18n;

i18n.add('ru-RU', ruRU);
i18n.add('en-US', enUS);

i18n.use('ru-RU');
100 + i18n('currency') // → '100руб.'

i18n.use('en-US');
100 + i18n('currency') // → '100$'

i18n() function can take a list of replacements

var i18n = new lib.I18n('ru-Ru', {currency: '{COST} руб.'});
i18n('currency', {cost: 100}) // → '100 руб.'

###lib.html

####lib.html.parse()

.parse() converts a HTML code into a document fragment

var docFragment = lib.html.parse('<h1>Example</h1><p>...</p>');
document.body.appendChild(docFragment);

####lib.html.escape()

.escape() converts special HTML characters to mnemonics

lib.html.escape('<h1>Example</h1>') // → '&lt;h1&gt;Example&lt;/h1&gt;'

####lib.html.unescape()

.unescape() converts HTML mnemonics to characters

lib.html.unescape('&lt;h1&gt;Example&lt;/h1&gt;') // → '<h1>Example</h1>'

###lib.array

####lib.array.count()

.count() counts the actual number of elements

var iterable = [,'a',,'b',];
iterable.length //→ 4
lib.array.count(iterable) //→ 2

####lib.array.all()

.all() like Array.every(), but it is sensitive to the length of the array and missing indexes

[].every(isTrue) //→ true
lib.array.all([], isTrue) //→ false

####lib.array.unique()

.unique() returns the new array consisting only of unique elements of the passed array

lib.array.unique([1, 2, 1]) //→ [1, 2]

####lib.array.refine()

.refine() shifts array indexes, so that was not missed

lib.array.refine([1,,2]) //→ [1, 2]

####lib.array.shuffle()

.shuffle() returns the new array consisting of mixed elements of the passed array

lib.array.shuffle(iterbale) //→ array

####lib.array.range()

.range() creates the array of integers

lib.array.range(2, 7) //→ [2, 3, 4, 5, 6]
lib.array.range(5) //→ [0, 1, 2, 3, 4]

####lib.array.remove()

.remove() removes the element from the array

var list = ['a', 'b', 'c'];
lib.array.remove(list, 'b');
console.log(list) //→ ['a', 'c']

###lib.css

####lib.css.prefix()

.prefix() returns prefixed propertyName or undefined

lib.css.prefix(propertyName) //→ prefixedPropertyName

example:

lib.css.prefix('animationName') //→ 'WebkitAnimationName'

####lib.css.get()

.get() returns computed property values

lib.css.get(element, property) //→ string
lib.css.get(element, arrayOfPropertyNames) //→ object

example:

//single property
var delay = lib.css.get(element, 'animationDelay'); //animationDelay will be prefixed automatically
if (delay) {
    //do something
}

//several properties
var rect = lib.css.get(element, ['top', 'left', 'height', 'width']);
if (parseInt(rect.width) > someValue) {
    //do something
}

####lib.css.set()

.set() changes property values and returns a promise that is fulfilled at the end of transitions and animations

lib.css.set(element, properties) //→ promise

example:

lib.css.set(element, {
    //properties will be prefixed automatically
    animationName: 'some-name',
    animationDuration: '5s'
}).then(doSomething);

####lib.css.getTransitionTime()

.getTransitionTime() returns the maximum CSS transition time

lib.css.getTransitionTime(style) //→ number (ms)

####Prefixed property names

For quick access prepared prefixed CSS animation, transition and transform property names: .animation, .animationName, .transitionProperty, .transform, etc.

if (lib.css.animation) {
    element.style[lib.css.animationDelay] = '5s';
}

###lib.dom

####lib.dom.ready()

.ready() returns a promise to perform actions after DOMContentLoaded

lib.dom.ready().then(function () {
    //do something
});

####lib.dom.add|remove|toggleClass()

.addClass(), .removeClass() and .toggleClass() returns the promise to perform actions at the end of all CSS transitions and animations

lib.dom.addClass(element, class1[, class2[, ...]]], element) //→ promise
lib.dom.removeClass(element, class1[, class2[, ...]]], element) //→ promise
lib.dom.toggleClass(element, class1[, class2[, ...]]], element) //→ promise

for example, call doSomething after 3 seconds of the transition:

.animated {
    position: fixed;
    top: 0;
    left: 0;
    transition: left 3s, top 1s;
}
.trans1 {
    top: 50%;
}
.trans2 {
    left: 50%;
}

var element = document.query('.animated');
lib.dom.addClass(element, 'trans1', 'trans2').then(doSomething);

###lib.event

####lib.event.on()

.on() registers a handler for an DOM event

lib.event.on(element[, selector], eventTypes, callback) //→ eventDetails

for example, delegating events using the CSS selector:

lib.event.on(menuContainer, '.menu-item', 'click', onMenuClick);

####lib.event.off()

.off() removes the handler for the DOM event

lib.event.off(eventDetails)

example:

var eventDetails = lib.event.on(window, 'focus blur', doSomething);
lib.event.off(eventDetails);

####lib.event.one()

.one() registers the handler for the DOM event, which runs once

lib.event.one(element[, selector], eventTypes, callback)

example:

lib.event.one(window, 'load', onLoad);

####lib.event.when()

.when() like .one(), but returns a promise, the callback is passed to .then()

lib.event.when(element[, selector], eventTypes) //→ promise

example:

lib.event.when(document, 'body', 'click').then(doSomething);

####lib.event.preventDefault()

.preventDefault() cancels the default action of the event

lib.event.on(someForm, 'submit', lib.event.preventDefault);

####lib.event.stopPropagation()

.stopPropagation() prevents further propagation of the event

lib.event.on(someElement, 'click', lib.event.stopPropagation);

####lib.event.awaitTransitionEnd()

.awaitTransitionEnd() returns the promise that is fulfilled at the end of CSS transitions

lib.event.awaitTransitionEnd(element[, computedStyle]) //→ promise

####lib.event.awaitAnimationEnd()

.awaitAnimationEnd() returns the promise that is fulfilled at the end of CSS animations

lib.event.awaitAnimationEnd(element[, previousAnimations]) //→ promise

####lib.event.awaitTransAnimEnd()

.awaitTransAnimEnd() returns the promise that is fulfilled at the end of transitions and animations

lib.event.awaitTransAnimEnd(element[, previousAnimations]) //→ promise

####Prefixed event types

For quick access prepared prefixed animation and transition event types: .animationStart, .animationEnd, .animationIteration and .transitionEnd

if (lib.event.animationEnd) {
    element.addEventListener(lib.event.animationEnd, onAnimationEnd);
}

###lib.date

####lib.data.isLeapYear()

.isLeapYear() determines whether a leap year

lib.date.isLeapYear([date]) //→ boolean

where date is instance of Date() or the four-digit number

####lib.date.getMonthLength()

.getMonthLength() returns the number of days in a month

lib.date.getMonthLength(monthIndex, fullYear) //→ number

if instead monthIndex pass the instance of Date(), then the second argument not needed

###lib.cookie

####lib.cookie.get()

.get() reads a cookie

lib.cookie.get(key) //→ 'value' or null

####lib.cookie.set()

.set() creates or overwrites a cookie

lib.cookie.set(key, value[, params]) //→ boolean

    //all parameters are optional
    params = {
        end:    number|string|Date, //seconds or GMTString or instance of Date
        path:   string,
        domain: string,
        secure: boolean
    }

####lib.cookie.has()

.has() checks if a cookie exists

lib.cookie.has(key) //→ boolean

####lib.cookie.remove()

.remove() deletes a cookie

lib.cookie.remove(key[, params]) //→ boolean

    //all parameters are optional
    params = {
        path:   string,
        domain: string
    }

####lib.cookie.keys()

.keys() returns an array of all readable cookies from this location

lib.cookie.keys() //→ ['key1', 'key2', …]

###lib.request()

.request() performs a request to a server using XMLHttpRequest(), returns a promise

lib.request({
    method:   string,
    url:      string,
    data:     string|Object|FormData,
    userName: string,
    password: string,
    timeout:  number,
    async:    boolean,
    caching:  boolean,
    mimeType: string,
    headers:  Object,
    advanced: Function
}) //→ promise

data can be a string, object (automatically converted into a query string), or an instance of FormData

####lib.request.get()

.get() like .request(), but it always performs the GET request and lets not pass additional parameters

lib.request.get(url) //→ promise
//or
lib.request.get(params) //→ promise

####lib.request.post()

.post() like .request(), but it always performs the POST request

####lib.request.json()

.json() is shorthand for:

lib.request.get(params).then(function (xhr) {
   return JSON.parse(xhr.responceText);
});

####lib.request.script()

.script() loads a JavaScript file from the server request, then execute it, returns the promise

lib.request.script({
    url:     string,
    data:    string|Object,
    caching: boolean
}) //→ promise

data can be the string or the object, which automatically converted into the query string

####lib.request.jsonp()

.jsonp() is equivalent to .script()

####lib.request.toQueryParam()

.toQueryParam() converts key-value pairs into the query string

lib.request.toQueryParam('chr', 'ю') //→ 'chr=%D1%8E'

####lib.request.toQueryString()

.toQueryString() converts the object containing key-value pairs into the query string

lib.request.toQueryString({
    chr1: 'ю',
    chr2: 'я'
}) //→ 'chr1=%D1%8E&chr2=%D1%8F'

##License

jsCore is released under the MIT license.