ku4node-kernel

6.0.0 • Public • Published

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("-", "
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

Readme

Keywords

Package Sidebar

Install

npm i ku4node-kernel

Weekly Downloads

2

Version

6.0.0

License

MIT

Last publish

Collaborators

  • kodmunki