Divhide javascript core components for NodeJs, Browser, Titanium, ... and everything that runs javascript.
npm install divhide   
 !alt text !alt text
Javascript codebase to use on the Browser, NodeJS and other javascript platforms. This provides a set of utilities that you can use everywhere.
The intent of this library is to expose some building blocks that you can use when building a library, a mobile application, a web page, a web server, a command line utility...
Please note that all examples are integrated on the CI build and that's the reason why you'll see expect statements.
``
npm install divhide
`
` js
var Divhide = require("divhide");
...
`
`bash
bower install divhide
`
` html
`
`
Download dist/divhide.js from github and use it as a library.
e.g.
var Divhide = require("/vendor/divhide");
`
* API
* I18N
* Exception
* Assert
* Assertion
* Chain
* Schema
* CustomSchema
* Type
* Safe
* Obj
* Arr
* Contribute
* Authors
* License
The Internationalization package. This package provides you with some utilities that will help you
on your internationalization tasks.
There's no intention for this library to contain translations for other languages.
#### I18NString
The I18NString is a String representation that can be translated. This string can be a plain String or
a lodash template.
This implementation creates a clear separation between the translation mechanism and it's internal logic. This package is used across the library in order to provide I18N out of the box!
Constructor
* new I18N.String(message, data?, translations?)
Creates a String instance with the given message, associated data, and an object which contain the translation.
Methods
* .toString(translations?)
Gets the string representation of the error. If _translations_ object is provided the message Error message will try to be translated.
Example
`js
var I18NString = Divhide.I18N.String;
/// the external translation data
var Portuguese = {
"hello <%= username %>": "olá <%= username %>"
};
/// create a I18NString (message + data)
var message = new I18NString("hello <%= username %>", { username: "oscar" });
/// Gets the English message
var en = message.toString();
expect(en)
.toBe("hello oscar");
/// Gets the Portuguese message
var en = message.toString(Portuguese);
expect(en)
.toBe("olá oscar");
`
The Exception package provides some utilities created in order to normalize the Error handling.
All the Exceptions classes inherit from Error. Also, these classes are using the I18N
package.
#### Exception
The Exception class inherits from Error. This class is integrated with I18N package.
Constructor
* new Exception.Exception(message, data?)
Creates an instance of an exception with the given _message_ and _data_.
Methods
* .message
Gets the string representation of the error.
* .toString(translations?)
Gets the string representation of the I18NString. You can provide a translation object.
Example
`js
var Exception = Divhide.Exception.Exception;
/// the external translation data
var Portuguese = {
"The maximum value allowed is <%= value %>.": "Valor máximo é <%= value %>."
};
var error = new Exception(
"The maximum value allowed is <%= value %>.",
{ value: 10 });
/// Exception instance is an error!
expect(error instanceof Error)
.equals(true);
/// Exception message
expect(error.toString())
.equals("The maximum value allowed is 10.");
/// I18N Exception message
expect(error.toString(Portuguese))
.equals("Valor máximo é 10.");
`
#### ExceptionList
This allows you to create an Exception that contains inner exceptions.
The ExceptionList is also an instance of Error and compatible with the I18N package.
Constructor
* new Exception.ExceptionList()
Methods
* .message
Gets the string representation of the ExceptionList.
* .items
Gets the list of inner Error.
* .length
Gets length of the ExceptionList
* .clear()
Clear the ExceptionList
* .push(Error)
Push an Error instance to the ExceptionList
* .push(ExceptionList)
Merge the given ExceptionList into the instance
* .toString(translations?)
Gets the string representation of the I18NString. You can provide a translation object.
Example
`js
var Exception = Divhide.Exception.Exception,
ExceptionList = Divhide.Exception.ExceptionList;
var errors = new ExceptionList();
/// is an instance of Error
expect(errors instanceof Error)
.toEqual(true);
/// adding errors to ExceptionList ( you can also merge other ExceptionList! )
errors.push( new Exception("Error1") );
errors.push( new Exception("Error2") );
errors.push( new Exception("Error3") );
/// get length of the list
expect(errors.length)
.toEqual(3);
/// get an error from the list
expect(errors.items[0].toString())
.toEqual("Error1");
/// get the translated error
expect(errors.toString({ "Error1": "Error 1", "Error2": "Error 2", "Error3": "Error 3" }))
.toEqual("Error 1, Error 2, Error 3");
`
The Assert facility provides an assertion expression builder with some pre-built functions.
Methods
* .required()
Set the expected value to be defined
* .string()
Set the expected value to be a string
* .array()
Set the expected value to be an array
* .object()
Set the expected value to be an object
* .number()
Set the expected value to be a number
* .max(number)
Set the expected value to have a specified maximum. In the case of String or Array the context will be the value length. In the case of an object will be the number of keys
* .min(number)
Set the expected value to have a specified minimum. In the case of String or Array the context will be the value length. In the case of an object will be the number of keys
* .instanceOf(fn)
Set the expected value to be an instance of the given function.
* .regex(value)
Set the expected value to pass the regex
* .isValid(value)
Test if the given value is valid within the current assertion
* .assert(value)
Return the given value if valid; otherwise will throw an Exception
Example
`js
var Assert = Divhide.Assert;
/// Test if the value is valid
var isValid = Assert.required()
.string()
.regex("^M")
.max(10)
.min(5)
.isValid("Mary");
expect(isValid)
.toBe(false);
/// Valid assertion:
var obj = Assert.required()
.array()
.max(5)
.assert([1, 2, 4, 5]);
expect(obj)
.equals([1, 2, 4, 5]);
/// Invalid assertion:
var fn = function(){
Assert.required()
.array()
.max(1) /// will be on array context
.assert(["first", "second"]);
};
expect(fn)
.toThrow();
`
Assertion facility provides a way to build custom Asserts. You can create your own assertion functions
and integrate them with the Assert facility.
Constructor
* new Assertion(methods)
Creates a custom assertion instance that contains the given methods plus the default methods (see Assert).
`js
/// Assertion builder
var Assertion = Divhide.Assertion;
/// Create the custom Assert facility
var Assert = new Assertion({
/**
*
* Tests if the string starts with the given value
*
* @param {String} val
* @param {String} str
* @return {String}
*/
startsWith: function(val, str){
if(val.indexOf(str) !== 0){
throw new Error("Does not starts with " + str);
}
}
});
/// Test if the value is valid
var isValid = Assert
.required()
.string()
.startsWith("Mary")
.isValid("Mary and Peter");
expect(isValid)
.toBe(true)
/// Assert value
var value = Assert
.required()
.string()
.startsWith("Mary")
.assert("Mary and Peter");
expect(value)
.equals("Mary and Peter");
`
Chain facility provides an API to create chainable functions. Each Chain is created by a list of chainable functions, a list of evaluation
function and some options.
Constructor
* new Chain(chainableFns, evaluationFns, options)
Creates a Chain instance that allows you to execute chainable methods (__chainableFns__). The chain is only executed
when an evaluation method (__evaluationFns__) is called.
* chainableFns
* evaluationFns
options - .
`js
var Chain = Divhide.Chain;
var Maths = new Chain(
/// the chaining fns
{
sum: function(i,j){
return i + j;
},
sub: function(i, j){
return i - j;
}
},
/// the evaluation fns
{
calculate: function(result, err){
return result;
}
},
/// the options
{
/// if true the return of a function is passed as an argument to the next one
/// if false, the evaluation arguments are passed to every chain function (default)
pipe: true
});
var value = Maths.sum(5)
.sub(3)
.sum(10)
.calculate(0);
expect(value)
.toBe(12);
`
The Schema facility provide an easy way to write validation rules. Using a chainable API you can
compile and/or evaluate the rules.
Methods
.any()
Set the expected type as any object.
.strict()
Disable the type coercion. Strict types are required.
.string()
Set the expected type as a string
.number()
Set the expected type as a number
.boolean()
Set the expected type as a boolean
.object(value)
Set the expected type as an object. The value is an object with rules.
.array(value)
Set the expected type as an object. The value is an array with rules.
.function()
Set the expected type as a function.
.required()
Set as required.
.optional()
Set as optional
.default(value)
Set the default value. This is used when the schema its required and the provided value is null.
.repeatable()
Set the type as repeatable. This repeats the schema through the structure (array only!).
.min(value)
Set the min value expected. If in number context the value is used. If in string context the length is used.
If in array context the length is used. If in object context the number of keys is used.
.max(value)
Set the max value expected. If in number context the value is used. If in string context the length is used.
If in array context the length is used. If in object context the number of keys is used.
.regex(value)
Sets a regexp condition ( only use on string context! )
.compile()
Compiles the schema. If you are using the same Schema multiple time you can compile it for performance reasons.
This avoid compiling the Schema before every usage.
.value(value)
Test the schema returning the normalized value if valid. Throws an Error if invalid.
.isValid(value)
Test the schema return if its valid or not.
.errors(value)
Test the schema returning an Array with the errors
.serialize()
Gets the serialized schema representation.
.deserialize(value)
Gets the Schema from the given value.
Example overview
`js
var Schema = Divhide.Schema;
/// get the schema
var schema = Schema.object({
/// array with multiple strings
data: Schema.array([ "" ]).repeatable().max(10),
/// every other object key is optional
"/.*/": Schema.number().optional()
}).required();
/// apply the schema to the value
var value = schema.value({
data: [ 1, 2, 3, 4, 5, 6],
timestamp: "1404373579473"
});
/// test the value
expect(value).equals({
data: [ '1', '2', '3', '4', '5' , '6'],
timestamp: 1404373579473
});
`
Example String Schema
`js
var Schema = Divhide.Schema;
var serialized =
Schema.object({
"name" : "",
"friends" : Schema.array([
{
name: ""
}
]).optional(),
})
.required()
.serialize();
/// deserialize the object
var schema = Schema.deserialize(serialized);
/// let's get the object
var value = schema.value({
id: 1,
name: "Oscar",
friends: [{ name: "Solange" }]
});
expect(value).equals({
name: "Oscar",
friends: [{ name: "Solange" }]
});
`
Time to see some code! Some usage examples are described below.
Example Number Schema
`js
var Schema = Divhide.Schema;
var schema = Schema.number()
.optional()
.min(3)
.max(5)
.compile();
/// value is correct
var value = schema.value(3);
expect(value).toBe(3);
/// optional value
var value = schema.value();
expect(value).equals(null);
/// value is undefined
expect(
function(){
schema.value(0);
})
.toThrow(
new Error("The minimum value allowed is 3.")
);
/// values exceed the max
expect(
function(){
schema.value(10);
})
.toThrow(
new Error("The maximum value allowed is 5.")
);
/// because is optional, is valid!
var isValid = schema.isValid();
expect(isValid).toBe(true);
isValid = schema.isValid(3);
expect(isValid).toBe(true);
isValid = schema.isValid(10);
expect(isValid).toBe(false);
`
Example Schema (de)serialization
`js
var Schema = Divhide.Schema;
/// String schema
var schema = Schema.string()
.required()
.min(3)
.max(5);
/// returns the value
var value = schema.value("hello");
expect(value).toBe("hello");
/// value is required!
expect(
function(){
schema.value();
})
.toThrowError("Value is required., The minimum value allowed is 3.");
/// value is required!
expect(
function(){
schema.value("hello world");
})
.toThrow(new Error("The maximum value allowed is 5."));
/// Check if is valid
var isValid = schema.isValid("");
expect(isValid).toBe(false);
var isValid = schema.isValid("hello");
expect(isValid).toBe(true);
var isValid = schema.isValid("hello world");
expect(isValid).toBe(false);
`
Example Object Schema
Objects schema is set by applying rules to each property of the object. You can also use regular expressions on
the schema object keys to give better filtering.
You can also set the schema object keys to primitive values which will be interpreted as required().default(value)
in the schema.
`js
var Schema = Divhide.Schema;
var schema =
Schema.object({
"/^optional/" : Schema.string().optional(),
"number" : 0,
"string" : "",
})
.required()
/// TIP: When compiled the schema is faster
.compile();
/// let's get the object
var value = schema.value({
string : "awesome!",
number : "0",
optional1 : "1",
optional2 : "2",
other : 1
});
/// Please notice that some of the object properties were
/// not included!
expect(value).equals({
"number": 0,
"string": "awesome!",
"optional1": "1",
"optional2": "2"
});
`
Example Array Schema
The following example describe an array rule that is optional and its expecting three items.
`js
var Schema = Divhide.Schema;
/// Array schema ( no repeatable)
var schema = Schema
.array([ Schema.string().default("value"), Schema.number(), Schema.string() ])
.optional()
.compile();
/// because its optional it returns null
var value = schema.value();
expect(value).toBe(null);
/// The value is right!
value = schema.value([ '1', 2, '3' ]);
expect(value).equals([ '1', 2, '3']);
/// array have more items than it should
expect(
function(){
schema.value([ '1', 2, '3', 4, 5, 6 ])
})
.toThrow(
new Error("Expected list with 3 items but found 6.")
);
/// Wrong type!
expect(
function(){
schema.value(10);
})
.toThrow(
new Error("'array' was expected but found 'number' instead.")
);
///
/// Just another way to write the rule!
///
var schema = Schema
.array([ Schema.string(), Schema.number() ])
.repeatable()
.optional()
.compile();
// Get the value
var value = schema.value(["1", 2, "3", 4]);
expect(value).equals(["1", 2, "3", 4]);
// because the number of item on the array must be multiple of 2
// an error is thrown
expect(
function(){
schema.value(["1", 2, "3"])
})
.toThrow(
new Error("Expected list length to be multiple of 2 but found length of 3.")
);
`
Type facility provides an API that can help you with typical operations using the javascript
data Types.
Methods
* .of(value)
Gets the string representation of the given value.
* .isArray(value)
* .isBoolean(value)
* .isFunction(value)
* .isString(value)
* .isObject(value)
* .isBoolean(value)
* .isRegExp(value)
* .isRegExpStr(value)
* .isNumber(value)
* .instanceOf(value)
* .isDefined(value)
Checks if the value is defined.
* .isEmpty(value)
Checks if the value is empty (executed in string, list and object context ).
`js
var Type = Divhide.Type;
var type = Type.of({});
expect(type).toBe("object");
var type = Type.of([]);
expect(type).toBe("array");
var type = Type.of(1);
expect(type).toBe("number");
var type = Type.of("name");
expect(type).toBe("string");
var type = Type.of(true);
expect(type).toBe("boolean");
var isArray = Type.isArray([]);
expect(isArray).toBe(true);
var isBoolean = Type.isBoolean(true);
expect(isBoolean).toBe(true);
var isFunction = Type.isFunction(function(){});
expect(isFunction).toBe(true);
var isString = Type.isString("");
expect(isString).toBe(true);
var isObject = Type.isObject({});
expect(isObject).toBe(true);
var isObject = Type.isObject(null);
expect(isObject).toBe(false);
var isRegExp = Type.isRegExp(/reg/);
expect(isRegExp).toBe(true);
var isNumber = Type.isNumber(1);
expect(isNumber).toBe(true);
var isNumber = Type.isNumber("1.1");
expect(isNumber).toBe(true);
var isDefined = Type.isDefined(null);
expect(isDefined).toBe(false);
var isDefined = Type.isDefined(undefined);
expect(isDefined).toBe(false);
var isEmpty = Type.isEmpty("");
expect(isEmpty).toBe(true);
var isEmpty = Type.isEmpty([]);
expect(isEmpty).toBe(true);
var isEmpty = Type.isEmpty({});
expect(isEmpty).toBe(true);
var isEmpty = Type.isEmpty(null);
expect(isEmpty).toBe(true);
var isString = Type.instanceOf("string", String);
expect(isString).toBe(true);
`
Safe facility provides an API that can helps you safelly working with javascript data types. This methods
are supposed to work with different value types.
Methods
* Safe.array(value, defaultValue?)
Gets the value in the array representation. __defaultValue__ is returned if defined and if value is not
an array.
* Safe.boolean(value, defaultValue?)
* Safe.string(value, defaultValue?)
* Safe.object(value, defaultValue?)
* Safe.number(value, defaultValue?)
* Safe.function(value, defaultValue?)
* Safe.value(value, defaultValue?)
* Safe.regexp(value, defaultValue)
* Safe.instanceOf(value, Class)
Gets an instance of the given value if is an instance of the given Class, otherwise it will
create an instance.
* Safe.length(value)
Gets the length of the value.
* Safe.coerce(value, expected)
Gets the value coerced by the expected value type.
Example Array
`js
var Safe = Divhide.Safe;
var value = Safe.array(1);
expect(value)
.equals([1]);
var value = Safe.array(1);
expect(value)
.equals([1]);
var value = Safe.array([1, 2]);
expect(value)
.equals([1, 2]);
var value = Safe.array(null, [ 1, 2 ]);
expect(value)
.equals([1, 2]);
var value = Safe.array("1", [1, 2]);
expect(value)
.equals(["1"]);
`
Example Boolean
`js
var Safe = Divhide.Safe;
var value = Safe.boolean(true);
expect(value).toBe(true);
var value = Safe.boolean(false);
expect(value).toBe(false);
var value = Safe.boolean(1);
expect(value).toBe(true);
var value = Safe.boolean("1");
expect(value).toBe(true);
var value = Safe.boolean("0");
expect(value).toBe(false);
var value = Safe.boolean({});
expect(value).toBe(false);
var value = Safe.boolean({}, true);
expect(value).toBe(true);
var value = Safe.boolean([]);
expect(value).toBe(false);
var value = Safe.boolean(null);
expect(value).toBe(false);
`
Example Function
`js
var Safe = Divhide.Safe;
var fn = Safe.function(function(){});
expect(fn())
.toBe(undefined);
var fn = Safe.function("");
expect(fn())
.toBe(undefined);
var fn = Safe.function("", function(){ return 1; });
expect(fn())
.toBe(1);
`
Example Length
`js
var Safe = Divhide.Safe;
var value = Safe.length([1, 2]);
expect(value).toBe(2);
var value = Safe.length({ one: 1, two: 2});
expect(value).toBe(2);
var value = Safe.length(2);
expect(value).toBe(2);
var value = Safe.length("hello");
expect(value).toBe(5);
`
Example Number
`js
var Safe = Divhide.Safe;
var value = Safe.number(1);
expect(value).equals(1);
var value = Safe.number("");
expect(value).equals(0);
var value = Safe.number("1");
expect(value).equals(1);
var value = Safe.number({});
expect(value).equals(0);
var value = Safe.number("", 1);
expect(value).equals(1);
`
Example Object
`js
var Safe = Divhide.Safe;
var value = Safe.object({ one: 1 });
expect(value).equals({ one: 1 });
var value = Safe.object([]);
expect(value).equals({});
var value = Safe.object([], { one: 1 });
expect(value).equals({ one: 1 });
`
Example Regex
`js
var Safe = Divhide.Safe;
var value = Safe.regexp(/regexp/);
expect(value)
.toEqual(/regexp/);
var value = Safe.regexp("/regexp/");
expect(value)
.toEqual(/regexp/);
var value = Safe.regexp("");
expect(value)
.toEqual(/^$/);
var value = Safe.regexp("name");
expect(value)
.toEqual(/^name$/);
var value = Safe.regexp({}, /regexp/);
expect(value)
.toEqual(/regexp/);
`
Example String
`js
var Safe = Divhide.Safe;
var value = Safe.string("");
expect(value).toBe("");
var value = Safe.string({});
expect(value).toBe("");
var value = Safe.string({}, "default");
expect(value).toBe("default");
`
Example Value
`js
var Safe = Divhide.Safe;
var value = Safe.value(1);
expect(value).toBe(1);
var value = Safe.value("1");
expect(value).toBe("1");
var value = Safe.value(null);
expect(value).toBe(null);
var value = Safe.value(undefined);
expect(value).toBe(null);
var value = Safe.value(null, 1);
expect(value).toBe(1);
`
Object facility provides some utility function to use on Objects.
Methods
* filter(value, filter)
Returns an array with all the keys that match the __filter__.
Example
`js
var Obj = Divhide.Obj;
var results = Obj.filter({ "one": 1, "two": 2 });
expect(results)
.toEqual(["one", "two"]);
var results = Obj.filter({ "one": 1, "two": 2 }, "one");
expect(results)
.toEqual(["one"]);
var results = Obj.filter({ "one": 1, "two": 2 }, "three");
expect(results)
.toEqual([]);
`
Array facility provides an API to easily manage array references.
Methods
* index(value, index)
Gets the value of the index.
* first(value)
* last(value)
* length(value)
* insert(array, value, index?)
Inserts the given value(s) on the given index of the __array__.
* remove(array, index, n?)
Removes the given __n__ elements from the __index__ from the __array__.
Example
`js
var Arr = Divhide.Arr;
var value = Arr.index([1 ,2, 3], 0);
expect(value).toBe(1);
var value = Arr.index([1 ,2, 3], 10);
expect(value).toBeNull();
var first = Arr.first([1 ,2, 3]);
expect(first).toBe(first);
var last = Arr.last([1 ,2, 3]);
expect(last).toBe(3);
var length = Arr.length([1 ,2, 3]);
expect(last).toBe(3);
var array = [1, 2, 3];
Arr.insert(array, 4);
expect(array).toEqual([1, 2, 3, 4]);
var array = Arr.insert([1 ,2, 3], [4, 5]);
expect(array).toEqual([1, 2, 3, 4, 5]);
var array = Arr.insert([1 ,2, 3], -1, 0);
expect(array).toEqual([-1, 1, 2, 3]);
var array = [1, 2, 3];
Arr.remove(array, 0);
expect(array).toEqual([2, 3]);
var array = [1, 2, 3];
Arr.remove(array, 0, 2);
expect(array).toEqual([3]);
`
#### Testing
The purpose of the project is to provide a library that can be used across every platform that uses javascript. The tests are done using jasmine and using the browser to debug. Every file save on the "src" folder will recompile
the browserify bundle.
` bash
`
#### Build
The build process will run a set of tasks including linting and testing. To contribute please add
tests to the fix/feature you've worked.
Also, when building the documention is compiled into the README.md. Each module iniside the "src" directory
should contain a ".md" file to document it's behaviour.
The following command will run the build.
` bash
grunt build
`
#### Release
` bash
``
Oscar Brito
+ github/aetheon
+ twitter/aetheon