The JavaScript ux utility library for common methods equals, format, extend, isPlainObject that can work with or without jQuery
npm install ux-util
bash
$ grunt ci
`
$3
location: dist/browser
The browser distribution will use closures to wrap functionality and it uses the global variable of "ux.util". If you wish to use a method you can do the following:
`html
`
`js
var equals = self.ux.util.equals;
if(equals(left, right))
{
// do something
}
`
$3
location: dist/amd[/lib]
The amd distribution has the main file in the root and the rest of the files are pushed into the lib folder. This is
so that the same require statements will work with node and when using something like require js with a browser.
$3
location: lib
The files are located inside of the lib folder.
API
$3
__apply__ is similar to Function.prototype.apply, but invokes a direct function when there thisArg is not present, otherwise, it uses call, which is faster than apply in most cases.
based on findings from http://jsperf.com/function-calls-direct-vs-apply-vs-call-vs-bind
##### example
`js
var util = require('ux-util/lib/apply');
var callback = function(data) {
var copy = data;
if(this.data) {
for(var prop in this.data)
copy[prop] = this.data[prop];
}
copy.status = "data has been retrieved";
return copy;
};
var data = apply(callback, [{firstName: "nathan", lastName: "fillion"}]);
if(data.self)
console.log("self exists");
else
console.log(data.status);
var data2 = apply(callback, {self: true}, [{firstName: "nathan", lastName: "fillion"}]);
if(data2.self)
console.log("self exists");
else
console.log(data2.status);
`
$3
__create__ dynamically creates an instance of a object by passing the array of arguments
to the constructor.
##### example
`js
var util = require('ux-util/lib/create');
var Person = function(first, last, middle) {
this.firstName = first || "";
this.lastName = last || "";
this.middleName = middle || "";
};
var actor = create(Person, ["Alan", "Tudyk"]);
console.log(actor.firstName); // Alan
console.log(actor.lastName); // Tudyk
console.log(actor.middleName); // ""
`
$3
__equals__ will assert if two values or objects are equal to each other. If an object
has an equals method, that method will be used to determine equality.
##### example
`js
var util = require('ux-util/lib/equals');
var log = console.log;
log(util.equals("one", "one")); // true
log(util.equals(["one"], ["one"])); // true
log(util.equals(2, 3)); // false
var Person = function(firstName, lastName, email) {
this.firstName = firstName;
this.lastName = email;
this.email = email;
};
Person.prototype.equals = function(right) {
if(right == null)
return false;
return (left.firstName === right.firstName &&
left.lastName === left.lastName &&
left.email === left.email);
};
var nathan = new Person("Nathan", "Fillion");
nathan.meta = "awesomeness";
var nathan2 = new Person("Nathan", "Fillion");
console.log(util.equals(nathan, nathan2)); // true
`
$3
__extend__ will merge functions and values from multiple objects into the target object using a
deep copy if specified.
##### example
`js
var util = require("ux-util/lib/extend");
var Animal = function() {
this.type = "animal";
this.sound = null;
this.attack = 0.2;
};
var Fox = function() {
Animal.call(this);
this.type = "fox";
this.sound = "what does the fox say?";
this.att
};
util.inherit(Fox, Animal);
var extensions = {
options: {
hp: 100,
mp: 50,
spells: ["burn"]
},
claw: function() {
return this.attack * 12;
}
};
util.extend(true, Fox.prototype, extensions, {
tailAttack: function() {
return this.attack * 20;
}
});
var fox = new Fox();
console.log(fox.options.spells === extensions.spells); // false, its a copy
`
$3
__format__ will inject values into placeholders of a string template. This is based upon .NET''s string.Format method.
##### example
`js
var util = require("ux-util/lib/format");
var message = util.format("[{0}] - {1}", "#tag", 2);
console.log(message); // [#tag] - 2
// format.globalizeFormat must have a signature of
// function(value, format)
// jQuery Globalize already uses this.
util.format.globalizeFormat = Globalize.format;
console.log(util.format("{0:n2}", 10.045234));
console.log(util.format("{0:c}", 1.25));
`
$3
__globals__ returns the global namespace. This variable can be used in all environments.
##### example
`js
var util = require('ux-util/lib/global');
if(util.globals.window)
{
// browser environment
var div = util.globals.document.createElement("div");
console.log(div);
}
// create variable in the global namespace.
util.globals.ux = {};
`
$3
__href__ expands a relative url with a tilda prefix into the correct relative path. The function
can also be bound create a localized version that has a different configuration.
##### example
`js
var util = require('ux-util/lib/href');
util.href.url = "/app"
var url = util.href("~/home/about");
console.log(url); // "/app/home/about"
var customHref = util.href.bind({url: "http://bob.com/"});
var about = customHref("~/about");
console.log(about); // "http://bob.com/about"
`
$3
__inherits__ will apply JavaScript inheritance to a subclass/function.
##### example
`js
var util = require('ux-util/lib/inherits');
var Animal = function() {
this.type ="animal";
this.name = "";
};
var Dog = function() {
Animal.call(this);
this.name = "dog";
};
// Sub Class, Base Class, properties
inherits(Dog, Animal, {test: {value: "test"}});
var dog = new Dog();
console.log(dog.name); // dog
console.log(dog.test); // test
console.log(dog instance of Dog); // true
console.log(dog instance of Animal); // true
`
$3
__isGlobal__ determines if the instance is the global namespace. The global namespace
varies depending on the environment.
* browser: window
* nodejs: global
* web worker: self
* other: this
##### example
`js
var util = require('ux-util/lib/global'),
obj = {},
obj2 = util.globals;
console.log( util.isGlobal(obj) ); // false
console.log( util.isGlobal(obj2) ); // true
`
$3
__isPlainObject__ determines if an object is a vanilla JavaScript object. Based on
jQuery's implementation.
##### example
`js
var util = require("ux-util/lib/is-plain-object");
// if browser
console.log(util.isPlainObject(window)); // false
// if node
console.log(util.isPlainObject(global)); // false
console.log(util.isPlainObject({})); // true
`
$3
__isWindow__ determines if the instance is the window object. This method is safe to use
in the node environment.
##### example
`js
var util = require('ux-util/lib/global'),
obj = {},
obj2 = util.globals;
console.log( util.isWindow(obj) ); // false
console.log( util.isWindow(obj2) ); // true if this code is in the browser, otherwise false.
`
$3
__logFactory__ is a singleton instance that finds or creates loggers based upon
the specified type name. This is simlar to LogManager in log4x frameworks. This
is meant to be more of a common.logging wrapper which defaults to using the console.
You can implement your own logging factory.
##### example
`js
var logManager = require("ux-util/lib/log-factory").logFactory;
var logger = logManager.getLogger("util");
if(logger.isDebugEnabled)
logger.debug("here is the message");
logManager.setFactory(new CustomLogFactory())
`
$3
__makeArray__ transforms various values into an array.
* null or undefined or zero => empty array
* multiple arguments => [argument1, argument2, etc]
* array like objects (i.e. arguments) => [argument1, argument2, etc]
* HtmlCollection => [element1, element2, etc]
* Iterator => [next1, next2, etc]
##### example
`js
var makeArray = require("ux-util/lib/make-array").makeArray;
// Array Like
var func = function() {
var args = makeArray(arguments);
return args.filter(function(o) { return typeof o === "string"; });
};
var filtered = func("one", "two", 3);
console.log(filtered); // ["one", "two"];
// HtmlCollection
var forms = makeArray(document.forms);
console.log(forms);
var function generator() {
yield 1;
yield 2;
};
// Iterator
var values = makeArray(generator());
console.log(values); // [1, 2];
var arr = makeArray("one");
console.log(arr); // ["one"];
`
$3
__mixin__ will merge functions and values from multiple objects into the target object using
a shallow copy.
##### example
`js
var util = require("ux-util/lib/mixin");
var Animal = function() {
this.type = "animal";
this.sound = null;
this.attack = 0.2;
};
var Fox = function() {
Animal.call(this);
this.type = "fox";
this.sound = "what does the fox say?";
this.att
};
util.inherit(Fox, Animal);
var spells = ["freeze"];
util.mixin(Fox.prototype, {
options: {
spells: spells
},
claw: function() {
return this.attack * 12;
}
});
var fox = new Fox();
console.log(fox.sound); // what does the fox say?
console.log(fox.claw()); // 2.4
console.log(fox.options.spells === spells); // true, because it is the same reference.
`
$3
__using__ is similar to the using method found in c#. Using will create an instance if the first
argument is a function. The object will be disposed and destroyed after its use, even if it throws
an error.
##### example
`js
var using = require("ux/lib/using");
var Db = function() {
};
Db.prototype = {
dispose: function() {
},
insert: function(entity) {
},
save: function() {
}
};
using(Db, function(db) {
db.insert({id: 1, name: "Serenity"});
db.save();
});
``