Promise
* [getJSON([url], [options])](#module_ajax..getJSON) ⇒ Promise
* [postJSON([url], [options])](#module_ajax..postJSON) ⇒ Promise
* [postFormData([url], [options])](#module_ajax..postFormData) ⇒ Promise
* [fetchHTML(url, selector)](#module_ajax..fetchHTML) ⇒ Promise
### ajax([url], options) ⇒ Promise
Low-level ajax request
**Returns**: Promise - A resolved or rejected Promise from the serverstring | 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] | Object \| string | | Data to send along with the request. If it's a GET request and `options.data` is an object, the object is converted to a query string and appended to the URL. |
| [options.method] | string | "GET" | One of 'GET', 'POST', etc. |
| [options.cache] | boolean | true | If set to `false`, will not let server use cached response |
| [options.memcache] | boolean | false | 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] | Object | {} | **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.dataType` and `options.cache`. |
| [options.form] | HTMLFormElement | | An optional form element |
### 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 serverstring | location.href | The URL of the resource |
| [options] | Object | {} | See [ajax](#module_ajax..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 serverstring | location.href | The URL of the resource |
| [options] | Object | {} | See [ajax](#module_ajax..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 serverstring | location.href | The URL of the resource |
| [options] | Object | {} | See [ajax](#module_ajax..ajax) for details |
### fetchHTML(url, selector) ⇒ Promise
Fetch an HTML document and return the html string (or a subset of it) from the resolved Promise
**Returns**: Promise - A resolved or rejected Promise, resolving to an HTML stringstring | The URL of the resource to fetch |
| selector | string | A selector specifying the html content in the resource to return |
## array
ESM Import Example:
```js
import {isArray} from 'ksjs';
// or:
import {isArray} from 'ksjs/array.mjs';
// or:
import {isArray} from 'ksjs/array.js';
```
CommonJS Require Example:
```js
const {isArray} = require('ksjs/array.cjs');
// or:
const {isArray} = require('ksjs/cjs/array.js');
```
* [array](#module_array)
* [isArray(arr)](#module_array..isArray) ⇒ boolean
* [inArray(el, arr)](#module_array..inArray) ⇒ boolean
* [objectToArray(obj)](#module_array..objectToArray) ⇒ array
* [makeArray(value, [delimiter], [wrapObject])](#module_array..makeArray) ⇒ array
* [randomItem(arr)](#module_array..randomItem) ⇒ any
* [pluck(arr, prop)](#module_array..pluck) ⇒ array
* [shuffle(els)](#module_array..shuffle) ⇒ array
* [merge(...arrays)](#module_array..merge) ⇒ array
* ~~[collapse()](#module_array..collapse)~~
* [intersect(array1, array2, [prop])](#module_array..intersect) ⇒ array
* [unique(arr, [prop])](#module_array..unique) ⇒ array
* [diff(array1, array2, [prop])](#module_array..diff) ⇒ array
* [chunk(arr, n)](#module_array..chunk) ⇒ array
* [range(a, [b])](#module_array..range) ⇒ array
* [pad(arr, size, value)](#module_array..pad) ⇒ array
* [sort(arr, [prop], [options])](#module_array..sort) ⇒ array
### isArray(arr) ⇒ boolean
Determine whether "arr" is a true array
**Returns**: boolean - `true` if arr is array, `false` if notarray | item to determine whether it's an array |
**Example**
```js
import {isArray} from 'ksjs/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)any | An item to test against the array |
| arr | array | The array to test against |
### objectToArray(obj) ⇒ array
Convert an object to an array of objects with name and value properties
**Returns**: array - An array of objects with name and value propertiesobject | The object to convert |
**Example**
```js
import {objectToArray} from 'ksjs/array.js';
const obj = {
foo: 'bar',
baz: 'qux'
};
const arr = objectToArray(obj);
// arr = [
// {name: 'foo', value: 'bar'},
// {name: 'baz', value: 'qux'}
// ];
```
### makeArray(value, [delimiter], [wrapObject]) ⇒ array
Return an array based on the given value:
a) Strings are split by a delimiter (defaults to /\s+/).
b) Plain objects are converted to an array of objects with name and value properties.
b2) …unless wrapObject is true in which case they are just wrapped in an array
c) Undefined and null are returned as an empty array.
d) Arrays are returned as is.
e) Anything else is wrapped in an array.
**Returns**: array - The value converted to an arrayany | | The value to convert to an array |
| [delimiter] | string \| RegExp | "= /\\s+/" | A string or regular expression to use for splitting a string into an array (defaults to /\s+/) |
| [wrapObject] | Boolean | | Whether to simply wrap an object in an array (true) or convert to array of objects with name/value properties |
**Example**
```js
import {makeArray} from 'ksjs/array.js';
const foo = makeArray('one two three');
// foo is now ['one', 'two', 'three']
const bar = makeArray('one,two,three', ',');
// bar is now ['one', 'two', 'three']
const baz = makeArray(['one', 'two', 'three']);
// baz is still ['one', 'two', 'three']
const quz = makeArray({foo: 'bar'});
// quz is now [{name: 'foo': value: 'bar'}]
const quuz = makeArray(null);
// quuz is now []
```
### randomItem(arr) ⇒ any
Return a random item from the provided array
**Returns**: any - A random element from the provided arrayarray | 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)array | Array from which to pluck |
| prop | string | Property to pluck |
**Example**
```js
import {pluck} from 'ksjs/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(els) ⇒ 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`, shuffledarray | Array to be shuffled |
### merge(...arrays) ⇒ array
Merge two or more arrays into a single, new array.
**Returns**: array - A new merged arrayarray | 2 or more arrays to collapse |
### ~~collapse()~~
***Deprecated***
**See**: [merge](#module_array..merge) instead
### intersect(array1, array2, [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 arrayarray | First array |
| array2 | array | Second array |
| [prop] | any | Optional property to compare in each element of the array |
**Example**
```js
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*, uses `JSON.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 arrayarray | 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**
```js
const array1 = [1, 2, 3, 2, 5, 1];
const uniq = unique(array1);
console.log(uniq);
// Logs: [1, 2, 3, 5]
```
### diff(array1, array2, [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*, uses `JSON.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 arrayarray | Array for which to return a subset |
| array2 | array | Array to use as a comparison |
| [prop] | string | Optional property to be tested if an element in `array1` is an object or array |
**Example**
```js
const array1 = [1, 2, 3, 4];
const array2 = [2, 3, 5, 6, -1];
console.log(diff(array1, array2));
// Logs: [1, 4]
```
### chunk(arr, n) ⇒ array
From an array passed into the first argument, create an array of arrays, each one consisting of `n` items. (The final nested array may have fewer than `n` items.)
**Returns**: array - A new, chunked, arrayarray | Array to be chunked. This array itself will not be modified. |
| n | number | Number of elements per chunk |
### range(a, [b]) ⇒ array
Create an array of numbers from 0 to `a` - 1 (if `b` not provided) or from `a` to `b` (if `b` is provided).
**Returns**: array - A new array of numbersnumber | The length of the 0-based array to be returned if `b` is NOT provided; the first number in the array if `b` IS provided. |
| [b] | number | The (optional) last number of the array. |
### pad(arr, size, value) ⇒ array
Pad an array with `value` until its length equals `size`
**Returns**: array - The array passed to `arr`, paddedarray | 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 |
### sort(arr, [prop], [options]) ⇒ array
Sort an array with sensible defaults: numbers (or numeric strings) before letters and case and diacritics ignored
**Returns**: array - The sorted arrayarray | | Array to sort |
| [prop] | string | | If dealing with an array of objects, the property by which to sort |
| [options] | object | | Object indicating options to override defaults (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options) |
| [options.sensitivity] | string | "base" | One of 'base', 'accent', 'case', 'variant'. Default is 'base' |
| [options.numeric] | boolean | true | Whether to treat numeric strings as numbers. Default is true |
| [options[...rest]] | any | | Other options (besides sensitivity:'base' and numeric: true) per the spec for `Intl.Collator.prototype.compare` |
## color
ESM Import Example
```js
import {rgb2Hex} from 'ksjs'
// or:
import {rgb2Hex} from 'ksjs/color.mjs'
// or:
import {rgb2Hex} from 'ksjs/color.js'
```
CJS Require Example
```js
const {rgb2Hex} = require('ksjs/color.cjs');
// or:
const {rgb2Hex} = require('ksjs/cjs/color.js');
```
* [color](#module_color)
* *static*
* [hex2Rgb](#module_color.hex2Rgb)
* *inner*
* [rgb2Hex(rgb)](#module_color..rgb2Hex) ⇒ string
* [rgba2Hex(rgba)](#module_color..rgba2Hex) ⇒ string
* [rgb2Luminance(rgb)](#module_color..rgb2Luminance) ⇒ number
* [getContrastColor(bgColor, [darkColor], [lightColor])](#module_color..getContrastColor) ⇒ 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`)string \| array | either an rgb string such as `'rgb(255, 120, 10)'` or an rgb array such as `[255, 120, 10]` |
**Example**
```js
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`)string \| array | either an rgba string such as `'rgba(255, 120, 10, .5)'` or an rgba array such as `[255, 120, 10, .5]` |
**Example**
```js
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 valuestring \| 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](#module_color..rgb2Luminance) algorithm
**Returns**: string - Contrasting colorstring | | 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
ESM Import Example:
```js
import {getCookie} from 'ksjs';
// or:
import {getCookie} from 'ksjs/cookie.mjs';
// or:
import {getCookie} from 'ksjs/cookie.js';
```
* [cookie](#module_cookie)
* [getCookie(name)](#module_cookie..getCookie) ⇒ string
* [setCookie(name, value, [options])](#module_cookie..setCookie) ⇒ string
* [removeCookie(name, [path])](#module_cookie..removeCookie)
### getCookie(name) ⇒ string
Get the value of a cookie
**Returns**: string - value The value of the cookiestring | 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 cookiestring | | 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
ESM Import Example:
```js
import {addClass} from 'ksjs';
// or:
import {addClass} from 'ksjs/dom.mjs';
// or:
import {addClass} from 'ksjs/dom.js';
```
* [dom](#module_dom)
* [toNodes(element(s))](#module_dom..toNodes) ⇒ array
* [\$(selector, [context])](#module_dom..$) ⇒ Array
* [\$1(selector, [context])](#module_dom..$1) ⇒ Element
* [addClass(el, className, [...classNameN])](#module_dom..addClass) ⇒ string
* [removeClass(el, className, [...classNameN])](#module_dom..removeClass) ⇒ string
* [toggleClass(el, className, [toggle])](#module_dom..toggleClass) ⇒ string
* [replaceClass(el, oldClass, newClass)](#module_dom..replaceClass) ⇒ string
* [getOffset(el)](#module_dom..getOffset) ⇒ Object
* [setStyles(el, styles)](#module_dom..setStyles) ⇒ Element
* [setAttrs(el, attrs)](#module_dom..setAttrs) ⇒ Element
* [getAttrs(el, attrs)](#module_dom..getAttrs) ⇒ Object
* [toggleAttr(el, attribute, [toggle])](#module_dom..toggleAttr) ⇒ string
* [insertHTML(element, position, toInsert)](#module_dom..insertHTML)
* [prepend(el, toInsert)](#module_dom..prepend) ⇒ Element
* [append(el, toInsert)](#module_dom..append) ⇒ Element
* [before(el, toInsert)](#module_dom..before) ⇒ Element
* [after(el, toInsert)](#module_dom..after) ⇒ Element
* [createTree(options)](#module_dom..createTree) ⇒ Element(s)
* [createHTML(options)](#module_dom..createHTML) ⇒ Element(s)
* [remove(el)](#module_dom..remove) ⇒ Element
* [empty(el)](#module_dom..empty) ⇒ Element
* [replace(oldEl, replacement)](#module_dom..replace)
* [loadScript(options)](#module_dom..loadScript) ⇒ 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 elementsElement \| 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 contextstring | | 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 contextstring | | 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 removedElement | 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 removedElement | 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 toggledElement | 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 replacedElement | 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 elementElement | 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 setElement | 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 setElement | 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 valuesElement | 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 removedElement | 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) * |
### insertHTML(element, position, toInsert)
| Param | Type | Description |
| --- | --- | --- |
| element | Element | html element |
| position | string | position for insertion |
| toInsert | string | html string to insert |
### prepend(el, toInsert) ⇒ Element
Insert an element as the first child of `el`
**Returns**: Element - The inserted elementElement | 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 elementElement | 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 elementElement | 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 elementElement | 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 treeobject | |
| [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 |
### createHTML(options) ⇒ Element(s)
Provide an object, along with possible child objects, to create an HTML string that can be inserted into the DOM.
**Returns**: Element(s) - The created Element node treeobject | |
| [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 DOMElement | DOM element to be removed |
### empty(el) ⇒ Element
Empty an element's children from the DOM
**Returns**: Element - DOM element provided by `el` argumentElement | 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.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
ESM Import Example:
```js
import {addEvent} from 'ksjs';
// or:
import {addEvent} from 'ksjs/event.mjs';
// or:
import {addEvent} from 'ksjs/event.js';
```
* [event](#module_event)
* [addEvent(el, type, handler(event), [options])](#module_event..addEvent)
* [removeEvent(el, type, [handler], [options])](#module_event..removeEvent)
* [triggerEvent(el, type, detail)](#module_event..triggerEvent)
### 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 | Window \| 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**
```js
// 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
ESM Import Example:
```js
import {getFormData} from 'ksjs';
// or:
import {getFormData} from 'ksjs/form.mjs';
// or:
import {getFormData} from 'ksjs/form.js';
```
* [form](#module_form)
* [getFormData](#module_form..getFormData) ⇒ any
* [valuesToFormData(values)](#module_form..valuesToFormData) ⇒ FormData
### 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`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**
```js
const myform = document.getElementById('myform');
console.log(getFormData.object(myform));
// Logs:
// {
// email: 'name@example.com',
// gender: 'female',
// meals: ['breakfast', 'dinner']
// }
```
**Example**
```js
const myform = document.getElementById('myform');
console.log(getFormData.string(myform));
// Logs:
// email=name%40example.com&gender=female&meals[]=breakfast&meals[]=dinner
```
**Example**
```js
const myform = document.getElementById('myform');
console.log(getFormData.array(myform));
// Logs:
// [
// {
// name: 'email',
// value: 'name@example.com'
// },
// {
// name: 'gender',
// value: 'femail'
// },
// {
// name: 'meals[]',
// value: 'breakfast'
// },
// {
// name: 'meals[]',
// value: 'dinner'
// }
// ]
```
### valuesToFormData(values) ⇒ FormData
Note: if the value of a key is an object with a `files` property, each file in the files array will be appended to the FormData object.
**Returns**: FormData - The form data objectObject \| Array | The object or array of objects to convert |
## jsonp
ESM Import Example:
```js
import {getJSONP} from 'ksjs';
// or:
import {getJSONP} from 'ksjs/jsonp.mjs';
// or:
import {getJSONP} from 'ksjs/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**
```js
getJSONP({url: 'https://example.com/api/'})
```
## math
ESM Import Example:
```js
import {median} from 'ksjs';
// or:
import {median} from 'ksjs/math.mjs';
// or:
import {median} from 'ksjs/math.js';
```
CommonJS Require Example:
```js
const {median} = require('ksjs/math.cjs');
// or:
const {median} = require('ksjs/cjs/math.js');
```
* [math](#module_math)
* [add(array)](#module_math.add) ⇒ number
* [subtract(array)](#module_math.subtract) ⇒ number
* [multiply(array)](#module_math.multiply) ⇒ number
* [divide(array)](#module_math.divide) ⇒ number
* [mod(dividend, [divisor])](#module_math.mod) ⇒ number
* [average(nums)](#module_math.average) ⇒ number
* [median(nums)](#module_math.median) ⇒ number
* [min(nums)](#module_math.min) ⇒ number
* [max(nums)](#module_math.max) ⇒ number
### add(array) ⇒ number
Return the result of adding an array of numbers (sum)
**Returns**: number - Sumarray | Array of numbers |
### subtract(array) ⇒ number
Return the result of subtracting an array of numbers (difference)
**Returns**: number - Differencearray | Array of numbers |
### multiply(array) ⇒ number
Return the result of multiplying an array of numbers (product)
**Returns**: number - Productarray | Array of numbers |
### divide(array) ⇒ number
Return the result of dividing an array of numbers (quotient)
**Returns**: number - Quotientarray | Array of numbers |
### mod(dividend, [divisor]) ⇒ number
Return the remainder after dividing two numbers (modulo)
**Returns**: number - Remaindernumber \| 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 - Averagearray | Array of numbers |
### median(nums) ⇒ number
Return the median of an array of numbers
**Returns**: number - Medianarray | Array of numbers |
### min(nums) ⇒ number
Return the number with the lowest value from an array of numbers
**Returns**: number - Minimum valuearray | Array of numbers |
### max(nums) ⇒ number
Return the number with the highest value from an array of numbers
**Returns**: number - Maximum valuearray | Array of numbers |
## object
ESM Import Example:
```js
import {deepCopy} from 'ksjs';
// or:
import {deepCopy} from 'ksjs/object.mjs';
// or:
import {deepCopy} from 'ksjs/object.js';
```
CommonJS Require Example:
```js
import {deepCopy} from 'ksjs/object.cjs';
// or:
const {deepCopy} = require('ksjs/cjs/object.js');
```
* [object](#module_object)
* [isObject(obj)](#module_object..isObject)
* [isPlainObject(obj)](#module_object..isPlainObject)
* [clone(obj)](#module_object..clone) ⇒ Object
* [deepCopy(obj, [forceFallback], [cache])](#module_object..deepCopy) ⇒ Object
* [isDeepEqual(objectA, objectB)](#module_object..isDeepEqual) ⇒ Boolean
* [extend(target, ...objects)](#module_object..extend) ⇒ Object
* [getProperty(root, properties, fallbackValue)](#module_object..getProperty) ⇒ \*
* [getLastDefined(root, properties)](#module_object..getLastDefined) ⇒ \*
* [isEmptyObject(obj)](#module_object..isEmptyObject) ⇒ boolean
* [setProperty(root, properties, value)](#module_object..setProperty) ⇒ Object
* [forEachValue(obj, fn)](#module_object..forEachValue) ⇒ void
* [getObject(obj, options)](#module_object..getObject)
* [pick(obj, props, [options])](#module_object..pick) ⇒ Object
* [omit(obj, props, [options])](#module_object..omit) ⇒ 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 |
### clone(obj) ⇒ Object
Deep copy an object (alternative to deepCopy), using graph theory and new Map(). Avoids circular refs and infinite loops.
**Returns**: Object - A copy of the objectObject |
### deepCopy(obj, [forceFallback], [cache]) ⇒ Object
Deep copy an object, avoiding circular references and the infinite loops they might cause.
**Returns**: Object - A copy of the objectObject | The object to copy |
| [forceFallback] | Boolean | If set to `true`, doesn't try to use native `structuredClone` function first. |
| [cache] | Array.<Object> | Used internally to avoid circular references |
### isDeepEqual(objectA, objectB) ⇒ Boolean
Compare two items for equality, recursing through nested objects or arrays
**Returns**: Boolean - True if the items are deeply equal, false otherwise\* | The first item to compare |
| objectB | \* | The second item to compare |
### extend(target, ...objects) ⇒ 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 objectObject | The target object that will be mutated. Use `{}` to create new object |
| ...objects | Object | One or more objects to merge into the first |
**Example**
```js
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, fallbackValue) ⇒ \*
Get a nested property of an object in a safe way
**Returns**: \* - The value of the nested property, or `undefined`, or the designated fallback valueObject | The root object |
| properties | Array.<String> \| String | Either an array of properties or a dot-delimited string of properties |
| fallbackValue | any | A value to assign if it's otherwise undefined |
**Example**
```js
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
};
```
### getLastDefined(root, properties) ⇒ \*
Get a nested property of an object in a safe way
**Returns**: \* - The value of the last nested property referenced in `properties` arg that has a defined valueObject | The root object |
| properties | Array.<String> \| String | Either an array of properties or a dot-delimited string of properties |
**Example**
```js
const foo = {
could: {
keep: {
going: 'but will stop'
},
shortStop: 'ride ends here'
};
console.log(getLastDefined(foo, 'could.keep.going'))
// Logs: 'but will stop'
console.log(getLastDefined(foo, ['shortStop', 'stops', 'short']))
// Logs: 'ride ends here'
};
```
### isEmptyObject(obj) ⇒ boolean
Determine whether an object (or array) is "empty"
**Returns**: boolean - `true` if object has no keys or array no elementsobject \| array | The object to test |
### setProperty(root, properties, value) ⇒ Object
Set a nested property of an object in a safe way
**Returns**: Object - The modified root objectObject | The root object |
| properties | Array.<String> \| String | Either an array of properties or a dot-delimited string of properties |
| value | any | The value to set for the nested property |
### forEachValue(obj, fn) ⇒ void
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 |
### getObject(obj, options)
INTERNAL: Return either the same object passed in first parameter or a deep copy of the object, depending on the deep option.
| Param | Type | Description |
| --- | --- | --- |
| obj | Object | The object to return |
| options | Object | Options object |
| options.deep | boolean | Whether to deep-clone the object or not before returning it |
### pick(obj, props, [options]) ⇒ 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` propertiesObject | | The object from which to get properties |
| props | array.<string> | | Properties to get from the object |
| [options] | Object | | Options object |
| [options.deep] | boolean | true | Whether to deep-clone the object before assigning its properties to the new object |
### omit(obj, props, [options]) ⇒ Object
Return a new object, excluding the properties in the props array.
**Returns**: Object - A modified copy of the objectObject | | The object from which to get properties |
| props | array | | Properties to exclude from the object |
| [options] | Object | | Options object |
| [options.deep] | boolean | true | Whether to deep-clone the object before assigning its properties to the new object |
## promise
ESM Import Example:
```js
import {peach} from 'ksjs';
// or:
import {peach} from 'ksjs/promise.mjs';
// or:
import {peach} from 'ksjs/promise.js';
```
CommonJS Require Example:
```js
import {peach} from 'ksjs/promise.cjs';
// or:
const {peach} = require('ksjs/cjs/promise.js');
```
* [promise](#module_promise)
* [peach(arr, fn)](#module_promise..peach) ⇒ Array.<Promise>
* [pmap(arr, fn, [order])](#module_promise..pmap) ⇒ Promise
* [pfilter(arr, fn(item,index,array), [order])](#module_promise..pfilter) ⇒ Promise
* [ArrayCallback](#module_promise..ArrayCallback) ⇒ Promise
### peach(arr, fn) ⇒ 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 promisesarray | Array to iterate over |
| fn | ArrayCallback | Function that is called for each element in the array, each returning a promise |
### pmap(arr, fn, [order]) ⇒ Promise
"Promised `map()`" for iterating over an array of items sequentially (or in parallel), calling a function that returns either the Promise of a modified item or the modified item itself, ultimately returning a single resolved Promise containing the modified array.
**Returns**: Promise - A resolved Promise, fulfilled with an array containing the mapped items of `arr`array | | Array to iterate over |
| fn | ArrayCallback | | Function that is called for each element in the array, each returning a modified result |
| [order] | string | "sequence" | Whether to call the callback for each item sequentially (`'sequence'`, default) or at the same time (`'parallel'`). |
**Example**
```js
import {pmap} from 'ksjs/promise.js';
const fruits = ['apple', 'banana', 'pear'];
const indexedFruits = pmap(fruits, (fruit, i) => {
});
```
### pfilter(arr, fn(item,index,array), [order]) ⇒ Promise
"Promised `filter()`" to iterate over an array of items sequentially (or in parallel), which acts just like `Array.prototype.filter()` but allows the callback function to return either a Promise containing a truthy/falsy value or the truthy/falsy value itself. Returns a single resolved Promise containing the filtered array.
**Returns**: Promise - A resolved Promise, fulfilled with an array containing the mapped items of `arr`array | | Array to iterate over |
| fn(item,index,array) | ArrayCallback | | Function that is called for each element in the array, each returning a modified result |
| [order] | string | "sequence" | Whether to call the callback for each item sequentially (`'sequence'`, default) or at the same time (`'parallel'`). |
**Example**
```js
import {pmap} from 'ksjs/promise.js';
const fruits = ['apple', 'banana', 'pear'];
const indexedFruits = pmap(fruits, (fruit, i) => {
});
```
### ArrayCallback ⇒ Promise
| Param | Type |
| --- | --- |
| item | any |
| [index] | number |
| [array] | array |
## selection
ESM Import Example:
```js
import {getSelection} from 'ksjs';
// or:
import {getSelection} from 'ksjs/selection.mjs';
// or:
import {getSelection} from 'ksjs/selection.js';
```
* [selection](#module_selection)
* [replaceSelection](#module_selection.replaceSelection) ⇒ Object
* [setSelection(elem, [startPos], [endPos])](#module_selection.setSelection)
* [setSelectionAll(el)](#module_selection.setSelectionAll)
* [getSelection(el)](#module_selection.getSelection)
### 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}`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 selection
* `end`: 0-based index of the end of the selection
* `length`: the length of the selection
* `text`: the selected text within the element
| Param | Type | Description |
| --- | --- | --- |
| el | Element | An element with selected text |
## storage
ESM Import Example:
```js
import {Storage} from 'ksjs';
// or:
import {Storage} from 'ksjs/storage.mjs';
// or:
import {Storage} from 'ksjs/storage.js';
```
* [storage](#module_storage)
* *instance*
* [getLength()](#module_storage+getLength) ⇒ number
* [get(key)](#module_storage+get) ⇒ any
* [set(key, value)](#module_storage+set) ⇒ string
* [remove(key)](#module_storage+remove)
* [clear()](#module_storage+clear)
* [getAll()](#module_storage+getAll) ⇒ Object
* [keys()](#module_storage+keys) ⇒ array
* *inner*
* [Storage](#module_storage..Storage)
* [new Storage([type], [ns])](#new_module_storage..Storage_new)
### getLength() ⇒ number
Get the number of items in the storage
**Returns**: number - The number of itemsany
Get and JSON.parse the value of the storage item identified by `key`
**Returns**: any - The JSON.parsed value of the storage itemstring | 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 setstring | 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 itemsarray
Loop through all storage items and return an array of their keys
**Returns**: array - Array of the keys of all storage itemsstring | "local" | Type of storage: either 'local' or 'session' |
| [ns] | string | "bamf" | Namespace for keys to prevent potenial collisions with storage items used by libraries, etc. |
## string
ESM Import Example:
```js
import {slugify} from 'ksjs';
// or:
import {slugify} from 'ksjs/string.mjs';
// or:
import {slugify} from 'ksjs/string.js';
```
CommonJS Require Example:
```js
const {slugify} require('ksjs/string.cjs');
// or:
const {slugify} = require('ksjs/cjs/string.js');
```
* [string](#module_string)
* *static*
* [pluralize(str, num, [ending])](#module_string.pluralize) ⇒ string
* [changeCase(str, type, [options])](#module_string.changeCase) ⇒ string
* [slugify(str)](#module_string.slugify) ⇒ string
* [truncate(string, options)](#module_string.truncate) ⇒ string
* [rot13(string)](#module_string.rot13) ⇒ string
* [hashCode(str, [prefix])](#module_string.hashCode) ⇒ number \| string
* [base64Encode(str)](#module_string.base64Encode) ⇒ string
* [base64Decode(str)](#module_string.base64Decode) ⇒ string
* [randomString([sep], [prefix])](#module_string.randomString) ⇒ string
* *inner*
* [parseStringTemplate(str, obj)](#module_string..parseStringTemplate) ⇒ string
* [stringTo(value, [type], [options])](#module_string..stringTo) ⇒ Boolean \| Number \| Array
* [stripTags(str)](#module_string..stripTags) ⇒ string
### pluralize(str, num, [ending]) ⇒ string
Converts a singular word to a plural
**Returns**: string - Pluralized stringstring | | Word to pluralize |
| num | number | | Number of items |
| [ending] | string | "s" | Optional ending of the pluralized word |
### changeCase(str, type, [options]) ⇒ string
Changes the case of the provided words according to the `type`.
**Returns**: string - Converted stringstring | String that will be cased as determined by `type` |
| type | string | One of 'title|sentence|caps|camel|pascal|slug|snake' |
| [options] | object | Optional options object. Its use depends on the type of case change |
**Example**
```js
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('the-old-man-and-the-sea', 'sentence', {unslugify: true}));
// 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" stringstring | String to be converted to a slug |
**Example**
```js
console.log(slugify('Hello there, how are you?'));
// Logs: 'hello-there-how-are-you'
console.log(slugify(' You? & Me<3* '));
// Logs: 'you-me-3'
```
### truncate(string, options) ⇒ string
**Returns**: string - The truncated string, or the full string if it's shorter than the total amount to truncatestr | | The string to be truncated |
| options | object | | Options object. |
| [options.start] | int | | The number of characters to keep at the start of the string. If falsy, no truncation will occur at the start. |
| [options.end] | int | | The number of characters to keep at the end of the string. If falsy, no truncation will occur at the end. |
| [options.separator] | string | "'...'" | The separator to use when truncating the string. Defaults to '...' |
**Example**
```js
const str = 'Collaboratively administrate empowered markets';
console.log(truncate(str, {start: 10}));
// Logs: 'Collaborat...'
console.log(truncate(str, {start: 10, separator: ''}));
// Logs: 'Collaborat'
console.log(truncate(str, {end: 10}));
// Logs: '...ed markets'
console.log(truncate(str, {start: 10, end: 10}));
// Logs: 'Collaborat...ed markets'
console.log(truncate(str, {start: 50, end: 50}));
// Logs: 'Collaboratively administrate empowered markets'
```
### rot13(string) ⇒ string
ROT13 encode/decode a string
**Returns**: string - The encoded (or decoded) stringstring | 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)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 stringstring | 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 stringstring | base4-encoded string |
### randomString([sep], [prefix]) ⇒ string
Return a pseudo-random string consisting of two base-36 strings, separated by the optional provided `sep` argument.
The first number is derived from a random 11-digit number
The second number is derived from the current date, including milliseconds
The string can begin with an optional `prefix`
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [sep] | string | "." | Optional separator for the two base-36 strings, Default is "." |
| [prefix] | string | "''" | Optional prefix for the string |
### parseStringTemplate(str, obj) ⇒ string
**Returns**: string - String with tokens replaced with valuesstring | String with tokens ( `${example}` ) to parse |
| obj | object | Object of properties with values to be used when replacing tokens |
### 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 | |
### stripTags(str) ⇒ string
Strip tags from a string
**Returns**: string - Stripped stringstring | String to be stripped of tags |
**Example**
```js
console.log(stripTags('Hello
')); // Logs: 'Hello' console.log(stripTags('Hello
World
')); // Logs: 'HelloWorld' ``` ## timer ESM Import Example: ```js import {debounce} from 'ksjs'; // or: import {debounce} from 'ksjs/timer.mjs'; // or: import {debounce} from 'ksjs/timer.js'; ``` CommonJS Require Example: ```js import {debounce} from 'ksjs/timer.cjs'; // or: const {debounce} = require('ksjs/cjs/timer.js'); ``` * [timer](#module_timer) * [HOUR](#module_timer..HOUR) :number
* [DAY](#module_timer..DAY) : number
* [YEAR](#module_timer..YEAR) : number
* [debounce(fn, [timerDelay], [ctx])](#module_timer..debounce)
* [unbounce(fn, [timerDelay], [ctx])](#module_timer..unbounce)
* [throttle(fn, [timerDelay], [context])](#module_timer..throttle)
* [raf(fn, [context])](#module_timer..raf)
* [idle(fn, [context])](#module_timer..idle)
* [deadline(promise, ms, exception)](#module_timer..deadline) ⇒ any
* [delay(timeout)](#module_timer..delay)
### 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] | number | 200 | Number of milliseconds to delay before firing once at the end |
| [ctx] | Element | this | The context in which to call `fn` |
**Example**
```js
const scrollLog = function(event) {
console.log('Started resizing the window!');
};
window.addEventListener('resize', debounce(scrollLog));
```
### unbounce(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 beginning of a series of potential calls within `delay` |
| [timerDelay] | number | 200 | Number of milliseconds within which to avoid calling the same function |
| [ctx] | Element | this | The context in which to call `fn` |
**Example**
```js
const scrollLog = function(event) {
console.log('Started resizing the window!');
};
window.addEventListener('resize', debounce(scrollLog));
```
### throttle(fn, [timerDelay], [context])
Set up a function to be called no more than once every `timerDelay` milliseconds
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| fn | function | | The function to throttle |
| [timerDelay] | number | 200 | Number of milliseconds to throttle the function calls |
| [context] | Element | this | The context in which to call `fn` |
### raf(fn, [context])
Set up a function to be called immediately before the next repaint using `requestAnimationFrame()`
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| fn | function | | The function to call |
| [context] | Element | this | The context in which to call `fn` |
### idle(fn, [context])
Set up a function to be called when the UI thread is idle by using `requestIdleCallback()`.
Falls back to using `requestAnimationFrame (or an rAF polyfill) if`requestIdleCallback()` is not supported.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| fn | function | | The function to call |
| [context] | Element | this | The context in which to call `fn` |
### deadline(promise, ms, exception) ⇒ any
**Returns**: any - The result of the promise if it is resolved or the exception if it is rejectedPromise | A promise to be resolved |
| ms | number | The number of milliseconds to wait for the promise to be resolved before rejecting |
| exception | any | An optional exception to be thrown if the promise is rejected |
### delay(timeout)
Like setTimeout, but with a promise that resolves when the timeout has expired.
| Param | Type | Description |
| --- | --- | --- |
| timeout | number | The number of ms to wait before resolving the promise |
## url
ESM Import Example:
```js
import {serialize} from 'ksjs';
// or:
import {serialize} from 'ksjs/url.mjs';
// or:
import {serialize} from 'ksjs/url.js';
```
CommonJS Require Example:
```js
import {serialize} from 'ksjs/url.cjs';
// or:
const {serialize} = require('ksjs/cjs/url.js');
```
* [url](#module_url)
* [pathname([obj])](#module_url..pathname) ⇒ string
* [basename([obj], [ext])](#module_url..basename) ⇒ string
* [segments([obj])](#module_url..segments) ⇒ array
* [segment(index, [obj])](#module_url..segment) ⇒ array
* [serialize(data, [options])](#module_url..serialize) ⇒ string
* [unserialize([string], [options])](#module_url..unserialize) ⇒ Object
### pathname([obj]) ⇒ string
Return a normalized `pathname` (old IE doesn't include initial "/" for `this.pathname`) of a passed object if it has an `href` property, or return the derived path name from string representing a URL
**Returns**: string - pathnameObject \| Location \| string | window.location | An object with a `pathname` propety or a string representing a URL |
### basename([obj], [ext]) ⇒ string
Return the basename of an object with `pathname` property or a string. Similar to node.js `path.basename()`
**Returns**: string - basenameObject \| string | window.location | An object with a `pathname` property, or a string representing a URL |
| [ext] | string | | Extension (e.g. '.html') to remove from the end of the basename) |
### segments([obj]) ⇒ array
Return an array consisting of each segment of a URL path
**Returns**: array - Array of segmentsObject \| string | window.location | An object with a `pathname` property, or a string representing a URL |
### segment(index, [obj]) ⇒ array
Return the `index`th segment of a URL path
**Returns**: array - A segment of the path derived from `obj` at `index`number | | Index of the segment to return. If < 0, works like `[].slice(-n)` |
| [obj] | Object \| string | window.location | An object with a `pathname` property, or a string representing a URL |
### serialize(data, [options]) ⇒ string
Convert an object to a serialized string
**Returns**: string - A query stringObject | Plain object to be serialized |
| [options] | Object | Optional settings |
| [options.raw] | boolean | If `true`, property values are NOT url-decoded |
| [options.prefix] | string | If set, and `data` is an array, sets as if prefix were the name of the array |
| [options.arrayToString] | boolean | If `true`, calls .toString() on arrays. So `{foo: ['won', 'too']}` becomes `foo=won%2Ctoo`. Used in conjunction with `{raw: true}`, the same object becomes `foo=won,too` |
| [options.arrayBrackets] | boolean | If `true` (and `options.arrayToString` is NOT `true`), arrays take the form of `foo[]=won&foo[]=too`; otherwise, `foo=won&foo=too` |
| [options.indexed] | boolean | If `true` (and `options.arrayToString` is NOT `true`), arrays take the form of `foo[0]=won&foo[1]=too` |
**Example**
```js
console.log(serialize({foo: 'yes', bar: 'again}));
// Logs: 'foo=yes&bar=again'
```
**Example**
```js
console.log(serialize({foo: ['yes', 'again']}));
// Logs: 'foo=yes&foo=again'
console.log(serialize({foo: ['yes', 'again']}, {arrayToString: true}));
// Logs: 'foo=yes,again'
console.log(serialize({foo: ['yes', 'again']}, {arrayBrackets: true}));
// Logs: 'foo[]=yes&foo[]=again'
console.log(serialize({foo: ['yes', 'again']}, {indexed: true}));
// Logs: 'foo[0]=yes&foo[1]=again'
console.log(serialize(['yes', 'again'], {prefix: 'foo'}));
// Logs: 'foo[0]=yes&foo[1]=again'
console.log(serialize(['yes', 'again'], {prefix: 'foo', indexed: false}));
// Logs: 'foo[]=yes&foo[]=again'
```
### unserialize([string], [options]) ⇒ Object
Convert a serialized string to an object
**Returns**: Object - An object of key/value pairs representing the query string parametersstring | "location.search" | Query string |
| [options] | Object | | Optional options |
| [options.raw] | boolean | false | If `true`, param values will NOT be url-decoded |
| [options.empty] | any | true | The returned value of a param with no value (e.g. `?foo&bar&baz`). Typically, this would be either `true` or `''` |
| [options.splitValues] | Boolean \| RegExp \| String | false | If NOT `false`, splits converts to an array all values with one or more matches of the `splitValues` option. If `true`, splits on commas (`/,/`). So, `?foo=bar,baz` becomes `{foo: ['bar', 'baz']}` |
| [options.shallow] | boolean | false | If `true`, does NOT attempt to build nested object |