#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.

| API | Return | Description | | --- | --- | --- | | round(value:Number, nearest:Number) | Number | Rounds value to the nearest, where nearest is the base 10 exponent to which to round | | roundUp(value:Number, nearest:Number) | Number | Rounds value up to the nearest, where nearest is the base 10 exponent to which to round | | roundDown(value:Number, nearest:Number) | Number | Rounds value down to the nearest, where nearest is the base 10 exponent to which to round | | roundTowardZero(value:Number, nearest:Number) | Number | Rounds value toward zero to the nearest, where nearest is the base 10 exponent to which to round |

###str Convenient string operations.

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

###uid A 32 character random unique ID.

##Account

###emailAddress | API | Return | Description | | --- | --- | --- | | local() | String | Returns the local portion of the email address. | | domain() | String | Returns the domain portion of the email address. | | topLevelDomain() | String | Returns the top level domain portion of the email address. | | equals(other:emailAddress) | Boolean | Returns true if the email addresses are equal. | | toString() | String | Returns a string representation of the email address. | | parse(string:String) | emailAddress | Returns an email address containing the corresponding components. |

###phoneNumber | API | Return | Description | | --- | --- | --- | | value() | Number | Returns a number value of the phone number. | | equals(other:phoneNumber) | Boolean | Returns true if the this is equal to other. | | toStringWithFormat(format:String) | String | Returns a string value replacing each instance of "#" with the subsequent number in the value. Example: $phoneNumber(2224441234).toStringWithFormat("(###) ###-####") == "(222) 444-1234" | | parse(string:String) | phoneNumber | Returns a phoneNumber with corresponding value. |

###properName | API | Return | Description | | --- | --- | --- | | first() | String | Returns the first name. | | middle() | String | Returns the middle name. | | last() | String | Returns the last name. | | full() | String | Returns the first middle and last name concatenated with space character separators. | | initials() | String | Returns the first letter of each name part capitalized and followed by a . character and a space character separator. | | equals(other_properName_) | String | Returns true if each part of this is equal to the corresponding part of other. | | toStringWithFormat(format:String) | String | Returns 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 | API | Return | Description | | --- | --- | --- | | count() | Number | Returns the number of items in the hash. | | keys() | Array | Returns an array of all keys. | | values() | Array | Returns an array of all values. | | add(key:String, value:Object) | this | Adds value to hash with key. | | update(key:String, value:Object) | this | Updates the value at key. | | remove(key:String) | this | Removes the key, value pair that has key. | | clear() | this | Removes all key, value pairs. | | findKey(value:Object) | String | Returns the key for value. | | findValue(key:String) | Object | Returns the value at key. | | each(func:function, scope:Object?) | this | Calls 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() | this | Breaks the call. | | contains(value:hash/object) | Boolean | Returns true if the hash contains the passed value. | | containsKey(key:String) | Boolean | Returns true if the hash contains the key. | | containsValue(value:Object) | Boolean | Returns true if the hash contains the value. | | isEmpty() | Boolean | Returns true if the hash is empty. | | merge(other:hash/object) | hash | Returns 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) | hash | Returns 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() | hash | Returns a copy of the current hash. | | toObject() | object | Returns an object that contains key, value pairs equivalent to the key, value pairs of the current hash. |

###list | API | Return | Description | | --- | --- | --- | | count() | Number | Returns the number of items in the list. | | add(item:Object, value:Object) | this | Adds value to list with key. | | remove(item:Object) | this | Removes the item. | | clear() | this | Removes all items. | | find(index:Number) | String | Returns the key for value. | | each(func:function, scope:Object?) | this | Calls 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() | this | Breaks the call. | | contains(item:Object) | Boolean | Returns true if the list contains the value. | | toArray() | object | Returns an array that contains items equivalent to the items of the current list. |

##Datetime

###dayPoint | API | Return | Description | | --- | --- | --- | | value() | Date | Returns the Date value | | day() | Number | Returns the zero indexed day of the week | | date() | Number | Returns the date | | month() | Number | Returns the month | | year() | Number | Returns the year | | isWeekday() | Boolean | Returns true if the day is 1-5 | | isWeekend() | Boolean | Returns true if the day is 0 or 6 | | isLeapYear() | Boolean | Returns true if the year contains a 29th day in the second month | | nextDay() | dayPoint | Returns the next day | | prevDay() | dayPoint | Returns the previous day | | add(years:Number, months:Number, days:Number) | dayPoint | | | firstDayOfMonth() | dayPoint | Returns the first day of the current month | | LastDayOfMonth() | dayPoint | Returns the last day of the current month | | isBefore(other:dayPoint) | Boolean | Returns true if other is earlier than this dayPoint | | isAfter(other:dayPoint) | Boolean | Returns true if other is later than this dayPoint | | equals(other:dayPoint) | Boolean | Returns true if other is equal to than this dayPoint | | toString() | String | Returns the string value of the dayPoint | | toStringWithFormat(format:String) | String | Returns a string formatted per the passed format. Example: $dayPoint(2013, 5, 24).toStringWithFormat("mm/dd/yy") == "05/24/13" | | toDate() | Date | Returns a Date value | | toJson() | String | Returns the JSON string value | | canParse(string:String) | Boolean | Returns true if the string can be parsed into a dayPoint | | parse(string:String) | dayPoint | Returns a dayPoint with the appropriate value | | tryParse(string:String) | dayPoint | Returns a dayPoint with the appropriate value or null if the string value cannot be parsed | | today() | dayPoint | Returns a dayPoint with the value, today | | assumeNow(dayPoint:dayPoint) | void | Sets 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 | API | Return | Description | | --- | --- | --- | | cents() | Number | Returns the fractional value of the money. | | dollars() | Number | Returns the whole value of the money. | | type() | String | Returns the denomination. "$" is the default. | | value() | Number | Returns the entire value of the money. | | add(other:money) | money | Returns a money whose value is the sum on this value plus other value. | | divide(divisor:Number) | money | Returns a money whose value is the quotient of this value divided by divisor. | | equals(other:money) |Boolean | Return true if this value equals other value. | | exchange(rate:Number, currency:String) | money | Return a money of currency with value or this times rate. | | isOfType(other:money) | Boolean | Return true if this type is equal to other type. | | isGreaterThan(other:money) | Boolean | Return true if this value > other value. | | isLessThan(other:money) | Boolean | Returns true if this value < other value. | | multiply(multiplier:Number) | money | Returns a money whose value is the product of this value times the multiplier. | | round() | money | Returns a money whose value is the value of this money rounded to the nearest hundredth. | | roundDown() | money | Returns a money whose value is the value of this money rounded down to the nearest hundredth. | | roundUp() | money | Returns a money whose value is the value of this money rounded up to the nearest hundredth. | | nearestDollar() | money | Returns a money whose value is the value of this money rounded to the nearest whole value. | | subtract(other:money) | money | Returns a money whose value is the difference of this value minus other value. | | toString(tens:String, tenths:String) | String | Returns 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("-", "|") == "$12-345-678|90". | | zero() | money | Returns a money with value 0. | | isMoney(other:money) | Boolean | Returns true if other is and instance of money | | canParse(string:String) | money | Returns true if the string can be parsed to money. | | parse(string:String) | money | Returns a money with corresponding value. | | tryParse(string:String) | money | Returns a money with corresponding value if string can be parsed. Otherwise, null. |

##Geometry

###coord Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

###point Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

###rectangle Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

###vector Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

##Patterns

###iterator Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

###mediator | API | Return | Description | | --- | --- | --- | | throwErrors() | this | Causes errors that occur in the notification process to be thrown, which will kill the JavaScript process if left unhandled. | | logErrors() | this | Causes errors that occur in the notification process to be logged to the console, allowing the JavaScript process to continue. | | catchErrors() | this | Causes errors that occur in the notification process to be silenced, allowing the JavaScript process to continue. | | isEmpty() | Boolean | Returns true if there are no subscribers. | | count() | Number | Returns that number of subscription managers. | | activeSubscriptionKeys() | Array | Returns an array of active subscription keys. | | subscribe(name_String_, method:function, scope:Object?, id:String?) | this | Subscribes method to be called in scope when name is notified. id is optional and used to unsubscribe | | unsubscribe(name_String_, id:String?) | this | Removes subscriber of id from all name notifications | | notify(data:Object, ..., name:String, ...) | this | Notifies 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() | this | Clears 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

| API | Return | Description | | --- | --- | --- | | | | |

###queue Documentation Coming Soon

| API | Return | Description | | --- | --- | --- | | | | |

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

| API | Return | Description | | --- | --- | --- | | and(other:spec) | spec | Returns a new spec whose isSatisfiedBy method is an evaluation of the current spec AND the other spec | | or(other:spec) | spec | Returns a new spec whose isSatisfiedBy method is an evaluation of the current spec OR the other spec | | xor(other:spec) | spec | Returns a new spec whose isSatisfiedBy method is an evaluation of the current spec XOR the other spec | | not() | spec | Inverts the return value of isSatisfiedBy | | isSatisfiedBy(value) | Boolean | Returns 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

| API | Return | Description | | --- | --- | --- | | | | |