ku4node-kernel

kodmunki kernel

#ku4node-kernel

kodmunki™ utilities for node kernel is a node plugin for OO JavaScript development.

ku4node-kernel contains numerous useful classes including collections, math, geometry, and numerous common design patterns.

#Dependencies None


#Documentation The following is documentation for each class in the ku4node-kernel library organized by common domain to follow the directory structure found in /src. All constructors are empty unless otherwise noted.

##Class Class is a foundational class that numerous other classes inherit from offering the subclasses a common property API that includes get(), set(), and property() which is a getter/setter. It also exposes the inheritance API. To subclass JavaScript classes using the kernel Class one would first create their class and then subclass as follows:

var kernel = require("ku4node-kernel),
    $class = kernel.class;
 
function myClass() {
    myClass.base.call(this); //This line scopes the class hierarchy.
}
myClass.prototype = {
    /*All prototype methods go here*/
};
$class.extend(myClass, $class); //We are creating our subclass here.
 
module.exports = function() { return new myClass(); } //We are exposing myClass for use here

With the above implementation. A developer can now call $myApp.myClass() from within their application to instantiate a new myClass that contains get(), set(), and property(). Also, it is important to note that many ku4* classes can be inherited using the same convention as class. For example, to inherit from $mediator, a developer would simply replace $class.extend(myClass, $class) in the example above with $class.extend(myClass, $mediator.Class)

##Base

###math Convenient math operations, and some that fix some odd bugs.

APIReturnDescription
round(value:Number, nearest:Number)NumberRounds value to the nearest, where nearest is the base 10 exponent to which to round
roundUp(value:Number, nearest:Number)NumberRounds value up to the nearest, where nearest is the base 10 exponent to which to round
roundDown(value:Number, nearest:Number)NumberRounds value down to the nearest, where nearest is the base 10 exponent to which to round
roundTowardZero(value:Number, nearest:Number)NumberRounds value toward zero to the nearest, where nearest is the base 10 exponent to which to round

###str Convenient string operations.

APIReturnDescription
trimStart(value:String)StringReturns a string with leading whitespace trimmed.
trimEnd(value:String)StringReturns a string with trailing whitespace trimmed.
trim(value:String)StringReturns a string with leading and trailing whitespace trimmed.
format(value:String, ...:String)StringReturns a string replacing the format placeholders with the following arguments.
render(value:String, obj:object)StringReturns a string replacing the format placeholders with the values of the key, value pairs in the following object argument.
encodeBase64(value:String)StringReturns a base 64 encoded string from value.
decodeBase64(value:String)StringReturns a string from a base 64 encoded value.
parse(value:Number, ...:Number)StringReturns a string from the character code arguments.

###uid A 32 character random unique ID.

##Account

###emailAddress

APIReturnDescription
local()StringReturns the local portion of the email address.
domain()StringReturns the domain portion of the email address.
topLevelDomain()StringReturns the top level domain portion of the email address.
equals(other:emailAddress)BooleanReturns true if the email addresses are equal.
toString()StringReturns a string representation of the email address.
parse(string:String)emailAddressReturns an email address containing the corresponding components.

###phoneNumber

APIReturnDescription
value()NumberReturns a number value of the phone number.
equals(other:phoneNumber)BooleanReturns true if the this is equal to other.
toStringWithFormat(format:String)StringReturns a string value replacing each instance of "#" with the subsequent number in the value. Example: $phoneNumber(2224441234).toStringWithFormat("(###) ###-####") == "(222) 444-1234"
parse(string:String)phoneNumberReturns a phoneNumber with corresponding value.

###properName

APIReturnDescription
first()StringReturns the first name.
middle()StringReturns the middle name.
last()StringReturns the last name.
full()StringReturns the first middle and last name concatenated with space character separators.
initials()StringReturns the first letter of each name part capitalized and followed by a . character and a space character separator.
equals(other_properName_)StringReturns true if each part of this is equal to the corresponding part of other.
toStringWithFormat(format:String)StringReturns a string formatted with the passed format. The rules are: {F} = first name, {f} = first initial, {M} = middle name, {m} = middle initial, {L} = last name, {l} = last initial. Example $properName("John", "Jacob", "Doe").toStringWithFormat("{L} {F}, {m}.") == "Doe John, J."

##Collections

###hash

APIReturnDescription
count()NumberReturns the number of items in the hash.
keys()ArrayReturns an array of all keys.
values()ArrayReturns an array of all values.
add(key:String, value:Object)thisAdds value to hash with key.
update(key:String, value:Object)thisUpdates the value at key.
remove(key:String)thisRemoves the key, value pair that has key.
clear()thisRemoves all key, value pairs.
findKey(value:Object)StringReturns the key for value.
findValue(key:String)ObjectReturns the value at key.
each(func:function, scope:_Object?_)thisCalls func for each item in the hash passing the object {"key": key, "value": value} on each pass. If scope is passed function will be called in the passed scope.
quit()thisBreaks the call.
contains(value:hash/object)BooleanReturns true if the hash contains the passed value.
containsKey(key:String)BooleanReturns true if the hash contains the key.
containsValue(value:Object)BooleanReturns true if the hash contains the value.
isEmpty()BooleanReturns true if the hash is empty.
merge(other:hash/object)hashReturns a new hash contains key, value pairs are a combination of the current hash and other giving precedence to the current hash for common keys.
meld(other:hash/object)hashReturns a new hash contains key, value pairs are a combination of the current hash and other giving precedence to the other hash for common keys.
replicate()hashReturns a copy of the current hash.
toObject()objectReturns an object that contains key, value pairs equivalent to the key, value pairs of the current hash.

###list

APIReturnDescription
count()NumberReturns the number of items in the list.
add(item:Object, value:Object)thisAdds value to list with key.
remove(item:Object)thisRemoves the item.
clear()thisRemoves all items.
find(index:Number)StringReturns the key for value.
each(func:function, scope:_Object?_)thisCalls func for each item in the list passing the item on each pass. If scope is passed function will be called in the passed scope.
quit()thisBreaks the call.
contains(item:Object)BooleanReturns true if the list contains the value.
toArray()objectReturns an array that contains items equivalent to the items of the current list.

##Datetime

###dayPoint

APIReturnDescription
value()DateReturns the Date value
day()NumberReturns the zero indexed day of the week
date()NumberReturns the date
month()NumberReturns the month
year()NumberReturns the year
isWeekday()BooleanReturns true if the day is 1-5
isWeekend()BooleanReturns true if the day is 0 or 6
isLeapYear()BooleanReturns true if the year contains a 29th day in the second month
nextDay()dayPointReturns the next day
prevDay()dayPointReturns the previous day
add(years:Number, months:Number, days:Number)dayPoint
firstDayOfMonth()dayPointReturns the first day of the current month
LastDayOfMonth()dayPointReturns the last day of the current month
isBefore(other:dayPoint)BooleanReturns true if other is earlier than this dayPoint
isAfter(other:dayPoint)BooleanReturns true if other is later than this dayPoint
equals(other:dayPoint)BooleanReturns true if other is equal to than this dayPoint
toString()StringReturns the string value of the dayPoint
toStringWithFormat(format:String)StringReturns a string formatted per the passed format. Example: $dayPoint(2013, 5, 24).toStringWithFormat("mm/dd/yy") == "05/24/13"
toDate()DateReturns a Date value
toJson()StringReturns the JSON string value
canParse(string:String)BooleanReturns true if the string can be parsed into a dayPoint
parse(string:String)dayPointReturns a dayPoint with the appropriate value
tryParse(string:String)dayPointReturns a dayPoint with the appropriate value or null if the string value cannot be parsed
today()dayPointReturns a dayPoint with the value, today
assumeNow(dayPoint:dayPoint)voidSets today as dayPoint. Can be very useful in testing application features that are date dependent. This feature allows the development of date dependent features without the need to manipulate system time.

##Finance

###money

APIReturnDescription
cents()NumberReturns the fractional value of the money.
dollars()NumberReturns the whole value of the money.
type()StringReturns the denomination. "$" is the default.
value()NumberReturns the entire value of the money.
add(other:money)moneyReturns a money whose value is the sum on this value plus other value.
divide(divisor:Number)moneyReturns a money whose value is the quotient of this value divided by divisor.
equals(other:money)BooleanReturn true if this value equals other value.
exchange(rate:Number, currency:String)moneyReturn a money of currency with value or this times rate.
isOfType(other:money)BooleanReturn true if this type is equal to other type.
isGreaterThan(other:money)BooleanReturn true if this value > other value.
isLessThan(other:money)BooleanReturns true if this value < other value.
multiply(multiplier:Number)moneyReturns a money whose value is the product of this value times the multiplier.
round()moneyReturns a money whose value is the value of this money rounded to the nearest hundredth.
roundDown()moneyReturns a money whose value is the value of this money rounded down to the nearest hundredth.
roundUp()moneyReturns a money whose value is the value of this money rounded up to the nearest hundredth.
nearestDollar()moneyReturns a money whose value is the value of this money rounded to the nearest whole value.
subtract(other:money)moneyReturns a money whose value is the difference of this value minus other value.
toString(tens:String, tenths:String)StringReturns a string representation of the money. There are two optional parameters tens and tenths. These values act as the separators for the tens and the tenths respectively. That is as an example $money(12345678.90).toString("-", "
zero()moneyReturns a money with value 0.
isMoney(other:money)BooleanReturns true if other is and instance of money
canParse(string:String)moneyReturns true if the string can be parsed to money.
parse(string:String)moneyReturns a money with corresponding value.
tryParse(string:String)moneyReturns a money with corresponding value if string can be parsed. Otherwise, null.

##Geometry

###coord Documentation Coming Soon

APIReturnDescription

###point Documentation Coming Soon

APIReturnDescription

###rectangle Documentation Coming Soon

APIReturnDescription

###vector Documentation Coming Soon

APIReturnDescription

##Patterns

###iterator Documentation Coming Soon

APIReturnDescription

###mediator

APIReturnDescription
throwErrors()thisCauses errors that occur in the notification process to be thrown, which will kill the JavaScript process if left unhandled.
logErrors()thisCauses errors that occur in the notification process to be logged to the console, allowing the JavaScript process to continue.
catchErrors()thisCauses errors that occur in the notification process to be silenced, allowing the JavaScript process to continue.
isEmpty()BooleanReturns true if there are no subscribers.
count()NumberReturns that number of subscription managers.
activeSubscriptionKeys()ArrayReturns an array of active subscription keys.
subscribe(name_String_, method:function, scope:_Object?_, id:_String?_)thisSubscribes method to be called in scope when name is notified. id is optional and used to unsubscribe
unsubscribe(name_String_, id:_String?_)thisRemoves subscriber of id from all name notifications
notify(data:Object, ..., name:String, ...)thisNotifies subscribers of name with data. data and name are optional parameters and multiple data and multiple names may be passed. If no names are supplied all subscribers are notified. If no data is passed, no data is sent to the subscribers in the notification.
clear()thisClears all subscribers.

####mediator gotchas! This is a very powerful and useful pattern, but it comes with developer responsibilities. Below are some gotchas that may arise when used irresponsibly, ignorantly, or unknowingly.

  • When filtering a notification, that is, when calling notify and passing one or more name arguments to filter the call, be mindful that a mediator will recognize your name as data and not a filter if there are no subscribers under that name. This can lead to "Maximum call stack exceeded" exceptions if a developer has not been properly mindful of SoC and has pushed further notifications on the call stack that in turn cause a notification loop. It is important to manage your mediators and subscribe and unsubscribe responsibly. This is easily avoidable with proper unit tests!

  • Do not be afraid of setting the mediator to throwErrors or logErrors. Exceptions that arise in a methods that execute through notification can be difficult to debug. Setting how the mediator handles these exceptions can be of great help in development.

###observer Documentation Coming Soon

APIReturnDescription

###queue Documentation Coming Soon

APIReturnDescription

###specification Constructor: $spec(func:function). The function passed must take a value parameter and return a boolean value.

APIReturnDescription
and(other:spec)specReturns a new spec whose isSatisfiedBy method is an evaluation of the current spec AND the other spec
or(other:spec)specReturns a new spec whose isSatisfiedBy method is an evaluation of the current spec OR the other spec
xor(other:spec)specReturns a new spec whose isSatisfiedBy method is an evaluation of the current spec XOR the other spec
not()specInverts the return value of isSatisfiedBy
isSatisfiedBy(value)BooleanReturns a boolean value of true if the value passed satisfies the specification

####Spec Example:

var kernel = require("ku4node-kernel"),
    $spec = kernel.patterns.spec,
    oneSpec = $spec(function(value) { return value === 1; }),
    twoSpec = $spec(function(value) { return value === 2; }),
    oneOrTwoSpec = oneSpec.or(twoSpec);
 
console.log(oneSpec.isSatisfiedBy(1)) //Evaluates as true 
console.log(twoSpec.isSatisfiedBy(1)) //Evaluates as false 
console.log(oneOrTwoSpec.isSatisfiedBy(2)) //Evaluates as true 
console.log(oneOrTwoSpec.isSatisfiedBy(3)) //Evaluates as false 

###stack Documentation Coming Soon

APIReturnDescription