0.6.2 • Published 6 years ago

@unipro/dms-utils

Licence

ISC

Version

0.6.2

Deps

Size

97 kB

Vulns

Weekly

DeprecatedThis package is deprecated

Summary Dependency Versions

DMS Utility Library

arrayHelper

A module that provides common array helper functions.

arrayHelper
- ~sliceRandom(array, [outputArrayLength]) ⇒ Array
- ~flattenArrays(arrayOfArrays) ⇒ Array
- ~filterTallyByThreshold(tally, threshold, [noWarning]) ⇒ Array
- ~isItemInArray(array, item) ⇒ boolean
- ~findItemInArray(array, item) ⇒ string
- ~isArrayItemInArray(array1, array2) ⇒ boolean
- ~findArrayItemInArray(array1, array2) ⇒ string

arrayHelper~sliceRandom(array, [outputArrayLength]) ⇒ `Array`

Returns a new array containing randomly extracted elements. The passed array is not modified. The returned array contains shallow copies of the passed array.

Kind: inner method of arrayHelper
Returns: Array - A new array containing the randomly extracted elements.

Param	Type	Description
array	`Array`	The array to extract elements from.
[outputArrayLength]	`number`	The number of elements to extract. Negative values will be subtracted from the length of the passed array

Example

// Randomly select 2 names, then 3 names using a negative length.
const names = ['anne', 'bob', 'chip', 'deborah']
const randomCouple = unipro.sliceRandom(names, 2)
const randomTriplet = unipro.sliceRandom(names, -1)

arrayHelper~flattenArrays(arrayOfArrays) ⇒ `Array`

Flattens an array of arrays into a single array.

Kind: inner method of arrayHelper
Returns: Array - A new array containing all sub-array elements.

Param	Type	Description
arrayOfArrays	`Array.<Array>`	The array of arrays to flatten.

Example

const nestedArray = [1, 2, [3, 4]]
const flatArray = unipro.flattenArrays(nestedArray)
// [1, 2, 3, 4]

arrayHelper~filterTallyByThreshold(tally, threshold, [noWarning]) ⇒ `Array`

Filters tally items by the threshold of the number of counts on each item. Items below the threshold will not be returned.

Kind: inner method of arrayHelper
Returns: Array - filteredTally containing all items that are above the threshold.

Param	Type	Description
tally	`Array`	an array of objects from the tally.
threshold	`number`	the number of counts on an individual item to be filtered on.
[noWarning]	`Array`	custom warning message to be thrown if no items match the threshold.

arrayHelper~isItemInArray(array, item) ⇒ `boolean`

Tests whether an array includes a string, case insensitive and trims whitespace.

Kind: inner method of arrayHelper
Returns: boolean - true if the string is found, otherwise false.

Param	Type	Description
array	`Array.<string>`	An array of strings to search.
item	`string`	A string to search for.

arrayHelper~findItemInArray(array, item) ⇒ `string`

Finds a string within an array, case insensitive and trims whitespace.

Kind: inner method of arrayHelper
Returns: string - The matching string from array, otherwise undefined.

Param	Type	Description
array	`Array.<string>`	An array of strings to search.
item	`string`	A string to search for.

arrayHelper~isArrayItemInArray(array1, array2) ⇒ `boolean`

Tests whether an array includes a string from another array, case insensitive and trims whitespace.

Kind: inner method of arrayHelper
Returns: boolean - true if a string is found, otherwise false.

Param	Type	Description
array1	`Array.<string>`	An array of strings to search within.
array2	`Array.<string>`	An array of strings to search for.

arrayHelper~findArrayItemInArray(array1, array2) ⇒ `string`

Finds a matching string within 2 arrays, case insensitive and trims whitespace.

Kind: inner method of arrayHelper
Returns: string - The matching string from array 1, otherwise undefined.

Param	Type	Description
array1	`Array.<string>`	An array of strings to search within.
array2	`Array.<string>`	An array of strings to search for.

cookieHelper

A module that provides a cookie helper to encode and store objects and queues, on the appropriate domain.

dateHelper

A module that provides date validation functions.

deviceHelper

A module that provides common device check helpers.

deviceHelper
- ~isMobileDevice() ⇒ boolean
- ~isTabletDevice() ⇒ boolean
- ~isDesktopDevice() ⇒ boolean
- ~isMobileOrTabletDevice() ⇒ boolean
- ~isTabletOrDesktopDevice() ⇒ boolean

deviceHelper~isMobileDevice() ⇒ `boolean`

Determines whether the visitor's device type is mobile.

Kind: inner method of deviceHelper
Returns: boolean - true if mobile, false if not.
Example

// Run some conditional code on mobile devices
if (isMobileDevice()) {
  ...
}

deviceHelper~isTabletDevice() ⇒ `boolean`

Determines whether the visitor's device type is tablet.

Kind: inner method of deviceHelper
Returns: boolean - true if tablet, false if not.

deviceHelper~isDesktopDevice() ⇒ `boolean`

Determines whether the visitor's device type is desktop.

Kind: inner method of deviceHelper
Returns: boolean - true if desktop, false if not.

deviceHelper~isMobileOrTabletDevice() ⇒ `boolean`

Determines whether the visitor's device type is mobile or tablet.

Kind: inner method of deviceHelper
Returns: boolean - true if mobile or tablet, false if not.

deviceHelper~isTabletOrDesktopDevice() ⇒ `boolean`

Determines whether the visitor's device type is tablet or desktop.

Kind: inner method of deviceHelper
Returns: boolean - true if tablet or desktop, false if not.

elementHelper

A module that provides UI helper functions for interacting with the DOM.

elementHelper
- ~waitForScrollIntoView($element, [offset], [wait], [throttleOptions]) ⇒ Promise
- ~waitForElementVisible($target, toggle, [isVisibleCallback]) ⇒ Promise

elementHelper~waitForScrollIntoView($element, [offset], [wait], [throttleOptions]) ⇒ `Promise`

Waits for an element to be scrolled into view.

Kind: inner method of elementHelper
Returns: Promise - A Promise that resolves with $element. The returned Promise has an additional cancel property that can be called to stop the scroll listener early.

Param	Type	Default	Description
$element	`any`		The element to check.
[offset]	`number`	`0`	The amount of the element to be considered visible. This must be an integer number of pixels.
[wait]	`number`	`100`	The frequency to check in milliseconds.
[throttleOptions]	`object`		Lodash throttle options (leading/trailing).

Example

const $element = $('.carousel')
return unipro.waitForScrollIntoView($element)

elementHelper~waitForElementVisible($target, toggle, [isVisibleCallback]) ⇒ `Promise`

Waits for an element to be visible on the page.

Kind: inner method of elementHelper
Returns: Promise - A Promise that resolves with $target.

Param	Type	Description
$target	`any`	The element to check.
toggle	`any`	The element or jQuery object that can toggle visibility, e.g. a menu icon.
[isVisibleCallback]	`any`	An optional callback to override the check for visibility.

errorHelper

A module that provides helper functions for errors and warnings.

errorHelper
- ~onError(e)
- ~onErrorStop(e)
- ~Warning(message) ⇒ void

errorHelper~onError(e)

Kind: inner method of errorHelper

Param	Type
e	`Error`

errorHelper~onErrorStop(e)

Kind: inner method of errorHelper

Param	Type
e	`Error`

errorHelper~Warning(message) ⇒ `void`

Instantiates an Error object with a custom "warn" property, for reporting expected error conditions as warnings.

Kind: inner method of errorHelper

Param	Type	Description
message	`string`	The message describing the warning.

hooksHelper

A module that provides helper functions for the Qubit activation and removal events.

hooksHelper

hooksHelper~onRemove(callback, [namespace])

Attaches a clean function to be called on removal of the experience.

Kind: inner method of hooksHelper

Param	Type	Description
callback	`callback`	the clean up function to call on removal of the experience.
[namespace]	`string`	namespace so that callbacks can be grouped for removal.

hooksHelper~onActivation(callback, [removeCallback], [namespace])

Attaches a tracking function to be called on activation of the experience.

Kind: inner method of hooksHelper

Param	Type	Description
callback	`callback`	the tracking function to call on activation of the experience.
[removeCallback]	`callback`	the clean up function to call on removal of the experience.
[namespace]	`string`	namespace so that callbacks can be grouped for removal.

hooksHelper~removeCliStyle() ⇒ `HTMLElement`

Removes the style tag if the experience is running under the qubit CLI.

Kind: inner method of hooksHelper
Returns: HTMLElement - The removed style tag.

hooksHelper~runOnRemove([namespace])

Manually runs any clean up functions added by onRemove.

Kind: inner method of hooksHelper

Param	Type	Description
[namespace]	`string`	only call a subset of the callbacks identified by the namespace.

hooksHelper~runOnActivation([namespace])

Manually runs any tracking functions added by onActivation.

Kind: inner method of hooksHelper

Param	Type	Description
[namespace]	`string`	only call a subset of the callbacks identified by the namespace.

jQueryHelper

A module that provides helper functions for jQuery traversal, manipulation and AJAX requests.

jQueryHelper
- ~ajax(url, [settings]) ⇒ Promise
- ~get(url, [data], [dataType]) ⇒ Promise
- ~post(url, [data], [dataType]) ⇒ Promise
- ~insertElement($element, target, insertionMethod) ⇒ any

jQueryHelper~ajax(url, [settings]) ⇒ `Promise`

Perform an asynchronous HTTP (Ajax) request.

Kind: inner method of jQueryHelper
Returns: Promise - A Promise that resolves with the data.

Param	Type	Description
url	`string`	A string containing the URL to which the request is sent.
[settings]	`any`	A set of key/value pairs that configure the Ajax request

jQueryHelper~get(url, [data], [dataType]) ⇒ `Promise`

Load data from the server using a HTTP GET request.

Kind: inner method of jQueryHelper
Returns: Promise - A Promise that resolves with the data.

Param	Type	Description
url	`string`	A string containing the URL to which the request is sent.
[data]	`any`	A plain object or string that is sent to the server with the request.
[dataType]	`string`	The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html).

jQueryHelper~post(url, [data], [dataType]) ⇒ `Promise`

Load data from the server using a HTTP POST request.

Kind: inner method of jQueryHelper
Returns: Promise - A Promise that resolves with the data.

Param	Type	Description
url	`string`	A string containing the URL to which the request is sent.
[data]	`any`	A plain object or string that is sent to the server with the request.
[dataType]	`string`	The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html).

jQueryHelper~insertElement($element, target, insertionMethod) ⇒ `any`

Insert every element in the set of matched elements before or after the target.

Kind: inner method of jQueryHelper
Returns: any - The inserted element(s).
Throws:

Throws an error if the insertionMethod is not valid.

Param	Type	Description
$element	`any`	The element(s) to insert.
target	`any`	A selector, element, array of elements, HTML string, or jQuery object; the matched set of elements will be inserted before the element(s) specified by this parameter.
insertionMethod	`string`	insertBefore, insertAfter, prependTo or appendTo.

moneyHelper

A module that provides helper functions for working with currencies.

moneyHelper~formatPrice(price, locale, currency, [trim]) ⇒ `string`

Converts a number to a currency string for the specified locale and currency.

Kind: inner method of moneyHelper
Returns: string - The price in the specified language and currency.
Throws:

Invalid number format, if the price is not a number.

Param	Type	Description
price	`number`	The price to convert to a currency.
locale	`string`	The language that the price should be converted to.
currency	`string`	The currency that the price should be converted to.
[trim]	`boolean`	If true displays whole prices without decimal places (£1.00 => £1).

objectHelper

A module that provides helper functions for working with objects.

objectHelper~deepCopy(object) ⇒ `Object`

Creates a deep copy of an object.

Kind: inner method of objectHelper
Returns: Object - a deep copied object.

Param	Type	Description
object	`Object`	the object to be copied.

getOptions

A module that provides custom logging to assist with filtering the console log.

pollerHelper

A module that wraps the Qubit poller in a Promise and uses named properties for the poller conditions.

pollerHelper~pollerPromise(pollFor, [timeoutMessage]) ⇒ `Object`

Provides a Promise wrapper around the jQuery version of the Qubit poller (v1.6).

Kind: inner method of pollerHelper
Returns: Object - A Promise that resolves with a object containing the property names and the results from the poller conditions. The Promise has an additional cancel property to stop the poller.

Param	Type	Description
pollFor	`Object`	Object containing the property names and poller conditions (selector/variable/function).
[timeoutMessage]	`string`	Message to report as a Warning if the poller conditions are not met.

Example

// To poll for a selector, variable and function
const pollFor = { $header: 'h1', dataLayer: 'window.dataLayer', someCondition: functionThatChecksSomething }
unipro.poller(pollFor, 'Could not find heading')
  .then(({ $header, dataLayer}) => doSomethingWithHeading($heading))
  .catch(onError)

Example

// Simple poller with an immediate call to cancel
const logoPoller = unipro.poller({ $logo: 'img.logo'})
logoPoller.cancel()

requireHelper

A module that wraps the Qubit AMD require function for commonly used packages.

requireHelper
- ~requireCountdownPackage() ⇒ Promise
- ~requireSlickPackage() ⇒ Promise

requireHelper~requireCountdownPackage() ⇒ `Promise`

Gets the Countdown package for Qubit.

Kind: inner method of requireHelper
Returns: Promise - Promise that resolves with the Countdown object.

requireHelper~requireSlickPackage() ⇒ `Promise`

Gets the custom Slick package for Qubit.

Kind: inner method of requireHelper
Returns: Promise - Promise that resolves with the Slick object.

segmentHelper

A module that wraps the Qubit getMembershipsAsync function with a poller.

segmentHelper~getSegments() ⇒ `Promise`

Gets the Qubit segments Ids that the visitor is a member of.

Kind: inner method of segmentHelper
Returns: Promise - Promise that resolves with an array of strings containing the segment IDs.

storageHelper

A module that provides helper functions for local and session storage, with support for queues of objects.

storageHelper
- ~isSessionStorageAccessible() ⇒ boolean
- ~isLocalStorageAccessible() ⇒ boolean
- ~getQueueFromSessionStorage(storageKey) ⇒ Array
- ~getQueueFromLocalStorage(storageKey) ⇒ Array
- ~queueItemToSessionStorage(storageKey, value, max, [uniqueProperty]) ⇒ Array
- ~queueItemToLocalStorage(storageKey, value, max, [uniqueProperty]) ⇒ Array
- ~removeItemFromSessionStorage(storageKey, value, [uniqueProperty]) ⇒ Array
- ~removeItemFromLocalStorage(storageKey, value, [uniqueProperty]) ⇒ Array

storageHelper~isSessionStorageAccessible() ⇒ `boolean`

Determines whether session storage is accessible.

Kind: inner method of storageHelper
Returns: boolean - true if storage is accessible, false if not.
Throws:

Does not throw any exceptions.

storageHelper~isLocalStorageAccessible() ⇒ `boolean`

Determines whether local storage is accessible.

Kind: inner method of storageHelper
Returns: boolean - true if storage is accessible, false if not.
Throws:

Does not throw any exceptions.

storageHelper~getQueueFromSessionStorage(storageKey) ⇒ `Array`

Gets a queue of items that have been stored in session storage.

Kind: inner method of storageHelper
Returns: Array - an array of the queued items, if no items have been queued an empty array is returned.

Param	Type	Description
storageKey	`string`	key name for the queue to be returned.

Example

// To get the last 10 unique products viewed.
const items = getQueueFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`)

storageHelper~getQueueFromLocalStorage(storageKey) ⇒ `Array`

Gets a queue of items that have been stored in local storage.

Kind: inner method of storageHelper
Returns: Array - an array of the queued items, if no items have been queued an empty array is returned.

Param	Type	Description
storageKey	`string`	key name for the queue to be returned.

Example

// To get the last 10 unique products viewed.
const products = getQueueFromLocalStorage(`qb_${_ticket}-${options.meta.experienceId}`)

storageHelper~queueItemToSessionStorage(storageKey, value, max, [uniqueProperty]) ⇒ `Array`

Adds an item to the beginning of a unique queue that is stored in session storage.

Kind: inner method of storageHelper
Returns: Array - The updated array of queued items.

Param	Type	Description
storageKey	`string`	key name for the queue to be stored.
value	`any`	The object or primitive type to be added to the queue.
max	`number`	Maximum number of items to store. Older items will be deleted once this value is met.
[uniqueProperty]	`string`	The object's property name to use for uniqueness within the queue.

Example

// To store the last 10 unique products viewed.
queueItemToSessionStorage`qb_${_ticket}-${options.meta.experienceId}`, product, 10, 'productId')

Example

// To store the last 10 unique product IDs viewed.
queueItemToSessionStorage`qb_${_ticket}-${options.meta.experienceId}`, productId, 10)

storageHelper~queueItemToLocalStorage(storageKey, value, max, [uniqueProperty]) ⇒ `Array`

Adds an item to the beginning of a unique queue that is stored in local storage.

Kind: inner method of storageHelper
Returns: Array - The updated array of queued items.

Param	Type	Description
storageKey	`string`	key name for the queue to be stored.
value	`any`	The object or primitive type to be added to the queue.
max	`number`	Maximum number of items to store. Older items will be deleted once this value is met.
[uniqueProperty]	`string`	The object's property name to use for uniqueness within the queue.

Example

// To store the last 10 unique products viewed.
queueItemToLocalStorage`qb_${_ticket}-${options.meta.experienceId}`, product, 10, 'productId')

Example

// To store the last 10 unique product IDs viewed.
queueItemToLocalStorage`qb_${_ticket}-${options.meta.experienceId}`, productId, 10)

storageHelper~removeItemFromSessionStorage(storageKey, value, [uniqueProperty]) ⇒ `Array`

Removes an item with a unique queue that is stored in session storage.

Kind: inner method of storageHelper
Returns: Array - The updated array of queued items.

Param	Type	Description
storageKey	`string`	key name for the queue that has been stored.
value	`any`	The object or primitive type to be removed from the queue.
[uniqueProperty]	`string`	The object's property name to use for uniqueness within the queue.

Example

// To remove a unique product Id from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, productId)

Example

// To remove a unique product from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, product, 'productId')

storageHelper~removeItemFromLocalStorage(storageKey, value, [uniqueProperty]) ⇒ `Array`

Removes an item with a unique queue that is stored in local storage.

Kind: inner method of storageHelper
Returns: Array - The updated array of queued items.

Param	Type	Description
storageKey	`string`	key name for the queue that has been stored.
value	`any`	The object or primitive type to be removed from the queue.
[uniqueProperty]	`string`	The object's property name to use for uniqueness within the queue.

Example

// To remove a unique product Id from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, productId)

Example

// To remove a unique product from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, product, 'productId')

stringHelper

A module that provides helper functions for strings and URIs.

stringHelper
- ~toTitleCase(string) ⇒ string
- ~toLowerTrim(string) ⇒ string
- ~toRelativeUrl(url) ⇒ string
- ~toAbsoluteUrl(url, [domain]) ⇒ string

stringHelper~toTitleCase(string) ⇒ `string`

Capitalises first letter of each word in a space separated string

Kind: inner method of stringHelper
Returns: string - Converted string.

Param	Type	Description
string	`string`	String to transform.

Example

'Converted String' = convertToTitleCase('converted string').

stringHelper~toLowerTrim(string) ⇒ `string`

Converts a string to lower case and trims whitespace

Kind: inner method of stringHelper
Returns: string - Trimmed lower case string

Param	Type	Description
string	`string`	The string to convert

stringHelper~toRelativeUrl(url) ⇒ `string`

Converts an absolute (or protocol relative) URL to a relative URL

Kind: inner method of stringHelper
Returns: string - The relative URL

Param	Type	Description
url	`string`	The absolute URL to convert

stringHelper~toAbsoluteUrl(url, [domain]) ⇒ `string`

Converts a relative (not protocol relative) URL to an absolute URL

Kind: inner method of stringHelper
Returns: string - The absolute URL

Param	Type	Description
url	`string`	The relative URL to convert
[domain]	`string`	The optional domain to use, otherwise use current domain

tallyHelper

A module that provides a helper for the Qubit tally, including error handling and encoding/decoding of keys and data.

uvHelper

A module that provides helper functions for Qubit API events including page, product, basket, and transactions.

uvHelper
- ~waitForPage() ⇒ Promise
- ~waitForProductDetails() ⇒ Promise
- ~waitForProductListing() ⇒ Promise
- ~waitForBasketSummary([allowEmpty]) ⇒ Promise
- ~waitForTransactionSummary([allowEmpty]) ⇒ Promise
- ~waitForBasketItems([allowEmpty]) ⇒ Promise
- ~waitForTransactionItems([allowEmpty]) ⇒ Promise
- ~waitForUser() ⇒ Promise

uvHelper~waitForPage() ⇒ `Promise`

Waits for an ecView, trView, or egView event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecView event data.

uvHelper~waitForProductDetails() ⇒ `Promise`

Waits for an ecProduct detail event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecProduct event data.

uvHelper~waitForProductListing() ⇒ `Promise`

Waits for an ecProduct listing event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecProduct event data.

uvHelper~waitForBasketSummary([allowEmpty]) ⇒ `Promise`

Waits for an ecBasketSummary event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecBasketSummary event data.
Throws:

Throws a warning if the basket is empty and allowEmpty has not been specified.

Param	Type	Description
[allowEmpty]	`boolean`	If true the function can resolve with empty baskets.

uvHelper~waitForTransactionSummary([allowEmpty]) ⇒ `Promise`

Waits for an ecBasketTransactionSummary event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecBasketTransactionSummary event data.
Throws:

Throws a warning if the transaction is empty and allowEmpty has not been specified.

Param	Type	Description
[allowEmpty]	`boolean`	If true the function can resolve with empty transactions.

uvHelper~waitForBasketItems([allowEmpty]) ⇒ `Promise`

Waits for an ecBasketSummary followed by all ecBasketItem events.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with all the event data { summary, items }.
Throws:

Throws a warning if the basket is empty and allowEmpty has not been specified.

Param	Type	Description
[allowEmpty]	`boolean`	If true the function can resolve with empty baskets.

uvHelper~waitForTransactionItems([allowEmpty]) ⇒ `Promise`

Waits for an ecBasketTransactionSummary followed by all ecBasketItemTransaction events.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with all the event data { summary, items }.
Throws:

Throws a warning if the transaction is empty and allowEmpty has not been specified.

Param	Type	Description
[allowEmpty]	`boolean`	If true the function can resolve with empty transactions.