VisSense.js Namespace: 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:

http://jsperf.com/getcomputedstyle-vs-style-vs-css/2

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:

http://dcousineau.com/blog/2013/09/03/high-performance-js-tip/

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:

https://developer.mozilla.org/en-US/docs/Web/Guide/User_experience/Using_the_Page_Visibility_API

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.