livecodingspace-app/public/vwf/utility.js

"use strict";

// Copyright 2012 United States Government, as represented by the Secretary of Defense, Under
// Secretary of Defense (Personnel & Readiness).
// 
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
// in compliance with the License. You may obtain a copy of the License at
// 
//   http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software distributed under the License
// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
// or implied. See the License for the specific language governing permissions and limitations under
// the License.

/// Kernel utility functions.
/// 
/// @module vwf/utility

define( [ "module",
    "vwf/utility/xpath",
    "vwf/utility/color",
    "vwf/utility/coordinates"
], function( module,
    xpath,
    color,
    coordinates
) {

    var exports = {

        // -- transform ----------------------------------------------------------------------------

        /// Recursively transform an arbitrary object using the provided transformation function.
        /// Containers are duplicated where necessary so that the original object and any contained
        /// objects are not modified. Unchanged objects will be referenced directly in the result.
        /// 
        /// @param {Object} object
        ///   The object to transform. `Object` and `Array` contents are recursively transformed
        ///   using the same transformation function.
        /// @param {Function} transformation
        ///   The transformation function: `function( object, names, depth, finished ) { return object }`
        ///   Call `finished()` from the transformation function to stop recursion for the current
        ///   object.
        /// @param {(Number|String)[]} [names]
        ///   Array of the names or indexes that refer to `object` in its container and in its
        ///   containers' containers, parent first (recursive calls only).
        /// @param {Number} [depth]
        ///   Recursion depth (recursive calls only).
        /// 
        /// @returns {Object}
        ///   The transformed object.

        transform: function( object, transformation /* ( object, names, depth, finished ) */, names, depth ) {

            names = names || [];
            depth = depth || 0;

            var finished = false, item;

            var result = object = transformation( object, names, depth, function() { finished = true } );

            if ( typeof object === "object" && object !== null && ! finished ) {

                if ( object instanceof Array ) {

                    // Recursively transform the elements if the object is an Array.

                    for ( var index = 0; index < object.length; index++ ) {

                        if ( ( item = this.transform( object[index], transformation,
                                [ index ].concat( names ), depth + 1 ) ) !== object[index] ) {

                            // If the item changed, and it's the first change in the array, then
                            // duplicate the array.

                            if ( result === object ) {
                                result = [].concat( object );  // shallow copy into a new Array
                            }

                            // Assign the transformed item.

                            result[index] = item;
                        }
                    }

                } else {

                    // Recursively transform the properties if the object is an Object.

                    Object.keys( object ).forEach( function( key ) {

                        if ( ( item = this.transform( object[key], transformation,
                                [ key ].concat( names ), depth + 1 ) ) !== object[key] ) {

                            // If the item changed, and it's the first change in the object, then
                            // duplicate the object.

                            if ( result === object ) {

                                result = {};

                                Object.keys( object ).forEach( function( k ) {
                                    result[ k ] = object[ k ];  // shallow copy into a new Object
                                } );

                                // Also copy the non-enumerable `length` property for an `arguments`
                                // object.

                                var lengthDescriptor = Object.getOwnPropertyDescriptor( object, "length" );

                                if (  lengthDescriptor && ! lengthDescriptor.enumerable ) {
                                    Object.defineProperty( result, "length", lengthDescriptor );
                                }

                            }

                            // Assign the transformed item.

                            result[key] = item;
                        }

                    }, this );

                }

            }

            return result;
        },

        // -- transforms ---------------------------------------------------------------------------

        /// Transformation functions for vwf.utility.transform. Invoke these as:
        /// 
        ///   utility.transform( object, utility.transforms.*transform* )
        ///
        /// to apply the transform utility.transforms.*transform* to object.

        transforms: {

            // -- transit --------------------------------------------------------------------------

            /// A vwf.utility.transform transformation function to convert an object for proper JSON
            /// serialization. Array-like objects are converted to actual Arrays. All other objects
            /// are unchanged. Invoke as: utility.transform( object, utility.transforms.transit ).
            /// 
            /// @param {Object} object
            ///   The object being transformed or one of its descendants.
            /// 
            /// @returns {Object}
            ///   An Array-like converted to an Array, or *object*.

            transit: function( object ) {

                // Determine if an object is Array-like (but not an Array) to identify objects that
                // need to be converted to Arrays for normalization.

                function isArraylike( candidate ) {

                    var arraylike = false;

                    // Filter with typeof and instanceof since they're much faster than toString().
                    // Then check for typed arrays (Int8Array, Uint8Array, ...) or the Arguments
                    // object using the type string.

                    if ( typeof candidate == "object" && candidate != null && ! ( candidate instanceof Array ) ) {
                        var typeString = Object.prototype.toString.call( candidate ) // eg, "[object *Type*]"
                        arraylike = ( typeString.slice( -6 ) == "Array]" || typeString == "[object Arguments]" );
                    }

                    return arraylike;
                };

                // Convert typed arrays to regular arrays.

                return isArraylike( object ) ?
                    Array.prototype.slice.call( object ) : object;

            },

            // -- hash -----------------------------------------------------------------------------

            /// A vwf.utility.transform transformation function to normalize an object so that it
            /// can be serialized and hashed with consistent results. Numeric precision is reduced
            /// to match the precision retained by the reflector. Non-Array objects are reordered so
            /// that their keys are in alphabetic order. Other objects are unchanged. Invoke as:
            /// utility.transform( object, utility.transforms.hash ).
            /// 
            /// @param {Object} object
            ///   The object being transformed or one of its descendants.
            /// 
            /// @returns {Object}
            ///   A reduced-precision number, an Object with alphabetic keys, or *object*.

            hash: function( object ) {

                // Apply the `transit` transform first to convert Array-likes into Arrays.

                object = exports.transforms.transit( object );

                // Reduce numeric precision slightly to match what passes through the reflector.

                if ( typeof object == "number" ) {

                    return Number( object.toPrecision(15) );
                }

                // Order objects alphabetically.

                else if ( typeof object == "object" && object != null && ! ( object instanceof Array ) ) {

                    var ordered = {};

                    Object.keys( object ).sort().forEach( function( key ) {
                        ordered[key] = object[key];
                    } );

                    return ordered;
                }

                return object;
            },

        },

        // -- exceptionMessage ---------------------------------------------------------------------

        /// Format the stack trace for readability.
        /// 
        /// @param {Error} error
        ///   An Error object, generally provided by a catch statement.
        /// 
        /// @returns {String}
        ///   An error message that may be written to the console or a log.

        exceptionMessage: function( error ) {

            // https://github.com/eriwen/javascript-stacktrace sniffs the browser type from the
            // exception this way.

            if ( error.arguments && error.stack ) { // Chrome

                return "\n  " + error.stack;

            } else if ( window && window.opera ) { // Opera

                return error.toString();

            } else if ( error.stack ) { // Firefox

                return "\n  " + error.toString() + "\n" + // somewhat like Chrome's
                    error.stack.replace( /^/mg, "    " );

            } else { // default

                return error.toString();

            }

        },

        // -- resolveURI ---------------------------------------------------------------------------

        /// Convert a relative URI to an absolute URI.
        /// 
        /// @param {String} uri
        ///   The URI to resolve. If uri is relative, it will be interpreted with respect to
        ///   baseURI, or with respect to the document if baseURI is not provided.
        /// @param {String} [baseURI]
        ///   An optional URI that provides the reference for uri. If baseURI is not provided, uri
        ///   will be interpreted with respect to the document. If baseURI is relative, it will be
        ///   interpreted with respect to the document before resolving uri.
        /// 
        /// @returns {String}
        ///   uri as an absolute URI.

        resolveURI: function( uri, baseURI ) {

            var doc = document;

            if ( baseURI ) {

                // Create a temporary document anchored at baseURI.

                var doc = document.implementation.createHTMLDocument( "resolveURI" );

                // Insert a <base/> with the reference URI: <head><base href=*baseURI*/></head>.

                var base = doc.createElement( "base" );
                base.href = this.resolveURI( baseURI ); // resolve wrt the document

                var head = doc.getElementsByTagName( "head" )[0];
                head.appendChild( base );

            }

            // Create an <a/> and resolve the URI.

            var a = doc.createElement( "a" );
            a.href = uri;

            return a.href;
        },

        // -- merge --------------------------------------------------------------------------------

        /// Merge fields from the `source` objects into `target`.

        merge: function( target /* [, source1 [, source2 ... ] ] */ ) {

            for ( var index = 1; index < arguments.length; index++ ) {
                var source = arguments[index];

                Object.keys( source ).forEach( function( key ) {
                    if ( source[key] !== undefined ) {
                        target[key] = source[key];
                    }
                } );
            }

            return target;
        },

        validObject: function( obj ) {
            var objType = ( {} ).toString.call( obj ).match( /\s([a-zA-Z]+)/ )[ 1 ].toLowerCase();
            return ( objType != 'null' && objType != 'undefined' );
        },

        hasFileType: function( value ) {
            return ( this.fileType( value ) !== undefined )
        },

        fileType: function( filename ) {
            var fileFormat = undefined;

            var temp = filename.split( '.' );
            if ( temp.length > 1 ) {
                fileFormat = temp.pop();
                if ( fileFormat.length > 5 ) {
                    fileFormat = undefined;
                }
            }
            return fileFormat;
        },  

        ifPrototypeGetId: function( appID, prototypes, nodeID, childID ) {
            var prototypeID = undefined;
            if ( ( nodeID == 0 && childID != appID ) || prototypes[ nodeID ] !== undefined ) {
                if ( nodeID != 0 || childID != appID ) {
                    prototypeID = nodeID ? nodeID : childID;
                    if ( prototypes[ prototypeID ] !== undefined ) {
                        prototypeID = childID;
                    }
                    return prototypeID;
                } 
            }
            return undefined;
        },

        isString: function( s ) {
            return ( typeof( s ) === 'string' || s instanceof String );
        },

        isFunction: function( obj ) {
            return ( typeof obj === 'function' || obj instanceof Function );
        },


        // -- xpath --------------------------------------------------------------------------------

        /// XPath resolution functions.

        xpath: xpath,

        // -- color --------------------------------------------------------------------------------

        /// HTML/CSS color conversion functions.

        color: color,

        // -- coordinates --------------------------------------------------------------------------

        /// DOM element coordinate conversion functions.

        coordinates: coordinates,

    };

    return exports;

} );