Namespace: Utils

VisSense. Utils

Methods

<static> async(callback, delay) → {function}

Returns a proxy function for the given callback which will defer the actual invocation until the current call stack has cleared.

Parameters:
Name Type Argument Default Description
callback function

The function that should be proxied.

delay number <optional>
0

The time in milliseconds to delay the invocation.

Returns:

A proxy function when called will defer the actual function call.

Type
function
Example
var prefetch = function () { ... };

var prefetchAsync = VisSense.Utils.async(prefetch, 2000);

var cancelPrefetch = prefetchAsync();
if ( someone_changed_his_mind ) {
  cancelPrefetch();
}
// => true

<private, static> computedStyle(element, referenceWindow) → {CSSStyleDeclaration}

Returns the elements computed style.

Parameters:
Name Type Argument Default Description
element DOMElement

A DOM element.

referenceWindow Window <optional>
window

The window object

Returns:

Returns the elements computed style.

Type
CSSStyleDeclaration
Example
var element = document.getElementById('myElement');
VisSense.Utils._computedStyle(element);
// => CSSStyleDeclaration {parentRule: null, length: 0, cssText: "", ... }

<static> debounce(callback, delay) → {function}

Returns a function that delays invoking callback until after delay milliseconds have elapsed since the last time it was invoked.

Parameters:
Name Type Description
callback function

The function to debounce.

delay number

The number of milliseconds to delay.

Returns:

A debounced version of the given function

Type
function
Example
window.addEventListener('resize', VisSense.Utils.debounce(function() {
  console.log('resized');
}, 200));
// => logs 'resized' after receiving resize events stopped for 200ms

<static> defaults(dest, source) → {Object}

Assigns all properties of the source object to the destination object if they are not present in the destination object.

Parameters:
Name Type Description
dest Object

The destination object.

source Object

The source object.

Returns:
Type
Object
Example
VisSense.Utils.defaults({
  name: 'Max',
  gender: 'male'
}, {
  name: 'Bradley',
  age: 31
});
// => { name: 'Max', gender: 'male', age: 31 }

<static> defer(callback, delay) → {function}

Defers executing the callback function until the current call stack has cleared. The request can be cancelled by calling the returned function.

Parameters:
Name Type Argument Default Description
callback function

The function to defer.

delay number <optional>
0

The time in milliseconds to delay the invocation.

Returns:

A function when called will cancel the invocation.

Type
function
Example
var prefetch = function () { ... };

var cancelPrefetch = VisSense.Utils.defer(prefetch, 9001);

if ( someone_changed_his_mind ) {
  cancelPrefetch();
}
// => true

<static> extend(dest, source, callback) → {Object}

Overwrites all properties of the destination object with the source object's properties. You can provide an optional callback function to modify the behaviour and/or to manipulate the return value.

Parameters:
Name Type Argument Description
dest Object

The destination object.

source Object

The source object.

callback VisSense.Utils.extendCallback <optional>

The function to customize assigning values.

Returns:
Type
Object
Example
VisSense.Utils.extend({
  name: 'Max',
  age: 31
  }, {
  name: 'Bradley',
  gender: 'male'
});
// => { name: 'Bradley', age: 31, gender: 'male' }


VisSense.Utils.extend({
  name: 'Max',
  age: 31
}, {
  name: 'Bradley',
  gender: 'male'
}, function(destValue, srcValue, key) {
  if(key === 'age') return destValue + 42;
  return srcValue;
});
// => { name: 'Bradley', age: 73, gender: 'male' }

<static> fireIf(when, callback) → {function}

Returns a function that when executed runs the given callback function only if when evaluates to a truthy value.

Parameters:
Name Type Description
when function | *

A function or any other value.

callback function

A callback function to run if when evaluates to a truthy value.

Returns:

Returns a function that runs the given callback function only if when evaluates to a truthy value.

Type
function
Example
var a = 6;
VisSense.Utils.fireIf(function() { return a % 2 === 0; }, function() {
  return a % 3 === 0;
})();
// => true

<static> forEach(array, callback, thisArg) → {*}

Iterates of the provided array

Parameters:
Name Type Argument Description
array Array

The target array to iterate.

callback function

Function that consumes an elements of the array

thisArg * <optional>

Value to use as this when executing callback.

Returns:

the result of the callback or undefined

Type
*
Example
var myArray = [1,2,3];
VisSense.Utils.forEach([1,2,3], function(num, index) {
  console.log('myArray[', index, '] = ', num);
});

<static> identity(value) → {*}

This function returns the first argument provided to it.

Parameters:
Name Type Description
value *

Any value.

Returns:

The given value.

Type
*
Example
var object = { 'name': 'Bradley' };
VisSense.Utils.identity(object) === object;
// => true

<static> isArray(value) → {boolean}

Checks if value is classified as an Array object

Parameters:
Name Type Description
value *

The value to check.

Returns:

true if value is an Array, otherwise false.

Type
boolean
Example
VisSense.Utils.isArray([1, 2, 3]);
// => true

(function() { return VisSense.Utils.isArray(arguments); })();
// => false

From lodash: [isArray](https://lodash.com/docs#isArray)

<static> isDefined(value) → {boolean}

Checks if the given value is undefined

Parameters:
Name Type Description
value *

Any value.

Returns:

true if the given value is undefined, otherwise false.

Type
boolean
Example
VisSense.Utils.isDefined(undefined) === false;
// => true

<private, static> isDisplayed(element, style) → {boolean}

A recursive function that checks if the element is visible by its and all parent nodes position style. There is an optional style parameter which can be provided if you already have computed the style of the element. NOTE: This function calls window.getComputedStyle which is rather expensive!

Parameters:
Name Type Argument Description
element DOMElement

A DOM element

style CSSStyleDeclaration <optional>

the elements style

See:
Returns:

true if the element is visible by its style and by the style of its parents, otherwise false.

Type
boolean
Example
var element = document.getElementById('myElement');
var style =
VisSense.Utils._isDisplayed(element);
// => true

<static> isElement(value) → {boolean}

Checks if value is a DOM Element.

Parameters:
Name Type Description
value *

The value to check.

Returns:

true if the given value is a DOM Element, otherwise false.

Type
boolean
Example
var elem = document.getElementById('myElement')
VisSense.Utils.isElement(elem);
// => true

VisSense.Utils.isElement(document);
// => false

VisSense.Utils.isElement(document.body);
// => true

<static> isFunction(value) → {boolean}

Checks if value is classified as a function object.

Parameters:
Name Type Description
value *

The value to check.

Returns:

true if the value is a function, otherwise false.

Type
boolean
Example
VisSense.Utils.isFunction(VisSense);
// => true

VisSense.Utils.isFunction(/abc/);
// => false

From lodash: [isFunction](https://lodash.com/docs#isFunction)

<private, static> isInViewport(rect, viewport) → {boolean}

Checks if the provided rectangle is in the given viewport. The function solely exists for the fact that "All calls to get any calculated dimension from the DOM should be cached or avoided".

Parameters:
Name Type Description
rect BoundingClientRect

An object representing a rectangle with properties ´bottom´, ´top´, ´left´ and ´right´ relative to the viewport.

viewport Viewport

An object representing the viewport with properties ´height´ and ´width´.

See:
Returns:

true of the provided rectangle is in the given viewport, otherwise false.

Type
boolean
Example
var rect = element.getBoundingClientRect();
var view = VisSense.Utils.viewport();
VisSense.Utils._isInViewport(rect, viewport);
// => true

<static> isObject(value) → {boolean}

Checks if value is the language type of Object. (e.g. arrays, functions, objects, regexes, new Number(0), and new String(''))

Parameters:
Name Type Description
value *

The value to check.

Returns:

Returns true if value is an object, otherwise false.

Type
boolean
Example
VisSense.Utils.isObject({});
// => true

VisSense.Utils.isObject([1, 2, 3]);
// => true

VisSense.Utils.isObject(1);
// => false


From lodash: [isObject](https://lodash.com/docs#isObject)

<static> isPageVisible(referenceWindow) → {boolean}

This method determines the visibility of the current tab and returns true if it is the foreground. If the browser does not communicate the state via ´document.hidden´ (or vendor specific derivatives) it will always return true.

Parameters:
Name Type Argument Default Description
referenceWindow Window <optional>
window

The window object.

See:
Returns:

Returns true if the current tab is in the foreground otherwise false.

Type
boolean
Example
VisSense.Utils.isPageVisible();
// => true

<static> isVisibleByStyling(element) → {boolean}

Checks if the element is visible by its style. If the given element is the document then it will always return true (even if document.hidden is true - this does not affect it's styling).

Parameters:
Name Type Description
element DOMElement

A DOM element

Returns:

true if the element is visible by style and the style of its parents, otherwise false.

Type
boolean
Example
var element = document.getElementById('myElement');
VisSense.Utils.isVisibleByStyling(element);
// => true

<static> noop()

A no-operation function.

Returns:

undefined

Example
var object = { 'name': 'Bradley' };
VisSense.Utils.noop(object) === undefined;
// => true

<static> now() → {number}

Gets the number of milliseconds that have elapsed since the Unix epoch (1 January 1970 00:00:00 UTC).

Returns:

Returns milliseconds since the Unix epoch.

Type
number
Example
var start = VisSense.Utils.now();
VisSense.Utils.defer(function() {
  console.log(VisSense.Utils.now() - start);
});
// => logs the time it took for the deferred function to be invoked

<static> once(callback, wait) → {function}

Returns a function that is restricted to invoking callback once. Repeat calls to the function return the value of the first call.

Parameters:
Name Type Argument Default Description
callback function

The function to throttle.

wait number <optional>
0

The number of milliseconds to throttle invocations to.

Returns:

A throttled version of the given function

Type
function
Example
var calculateExpensiveNumber = function() { ... };
var expensiveNumber = once(calculateExpensiveNumber);

var a = expensiveNumber() * 3.1415 + expensiveNumber();
// => exensiveNumber is actually invocing `calculateExpensiveNumber` only once

<static> percentage(element) → {number}

Parameters:
Name Type Description
element DOMElement

A DOM element.

Returns:

the percentage of the elements surface area within the visible area of a viewer's browser window on an in focus web page.

Type
number
Example
var element = document.getElementById('myElement');
VisSense.Utils.percentage(element);
// => e.g. 0.333

<private, static> styleProperty(style, property) → {*}

Returns the elements computed style property by name.

Parameters:
Name Type Description
style CSSStyleDeclaration

A style of an element.

property string

A name of the property to fetch.

Returns:

The value of the property.

Type
*
Example
var element = document.getElementById('myElement');
var style = VisSense.Utils._computedStyle(element);
VisSense.Utils._styleProperty(style, 'display');
// => 'block'

<static> throttle(callback, wait) → {function}

Returns a function that only invokes callback at most once per every wait milliseconds.

Parameters:
Name Type Argument Default Description
callback function

The function to throttle.

wait number <optional>
0

The number of milliseconds to throttle invocations to.

Returns:

A throttled version of the given function

Type
function
Example
window.addEventListener('resize', VisSense.Utils.throttle(function() {
  console.log('resizing..');
}, 100));
// => logs 'resizing..' at most every 100ms while resizing the browser window

<private, static> viewport() → {Viewport}

Gets the current viewport size of the browser window.

Returns:

The current viewport size.

Type
Viewport
Example
VisSense.Utils._viewport();
// => e.g. { height: 1280, width: 790 }

Type Definitions

extendCallback(destValue, sourceValue, destKey, sourceKey, dest, source)

This callback lets you intercept the assignment of individual properties. The return value will be assigned to the destKey property of the dest object. If this callback is not provided sourceValue will be assigned.

Parameters:
Name Type Description
destValue *

The destination value that will be replaced.

sourceValue *

The source value than will replace the destination value.

destKey *

The destination key.

sourceKey *

The source key.

dest *

The given destination.

source *

The given source.