README.md

modelate

A data modeling tool for NodeJS. It's 100% database agnostic, and 100% customizable.

Warning! Breaking changes in v1.0!

If you have been using this package in versions under 1.0.0, you have to update your code. Follow the migration guide to use the v1.x library.

How to install

Use NPM to install the package:

npm install modelate --save

How does it work?

Create a model, and turn your objects into that model.

var Modelate = require('modelate');

var model = {
	name: {
		type: 'string',
		length: {	
			max: 10,
			min: 1
		},
		value: {
			eq: 'Paco'
		}
	},
	age: {
		type: 'number',
		value: {
			max: 95,
			min: 18
		}
	}
}

var user = Modelate('User').model(model);
var data = {
	name: 'Paco',
	age: 17  // Age does not match with min value
};

var result = user.modelate(data); 
/* Result:
{ data: { 
	name: 'Paco 
  }, 
  error: [{ 
  	model: 'User', 
  	field: 'age', 
  	validator: 'value', 
  	constrains: { max: 95, min: 18 }
  }]
}
*/

Modifiers

Modifiers are just functions. It will be executed for each property, and return a modified (or not) version of the data to match requirements.

• Default

Default

If there are not data for that property, it will create a given default value:

{
	default: 'Default value'
}

So, if no value given, the object will be modified to add that field with Default value value.

Validators

Validators are just functions. It will be executed for each property, and return a boolean value indicating if the content match the model requirements or not.

• Type
• Length
• Value
• Custom function
• Date
• Model
• Email
• Regex

Type

If the data has not the specifed type, validation will fail, and that field will not be added to final validated data.

It uses typeof, so arrays will be considered valid objects. Also, there is a type "array", wich ensures data is an array.

{
	type: String	// Check if data has a JS type
}

Length

Check data length. It uses default .length param, so it's valid for so much types.

{
	length: {
		eq: Number,		// Exact allowed value
		max: Number,	// Maximum allowed value
		min: Number		// Minimum allowed value
	}
}

Value

Check data length. It uses default .length param, so it's valid for so much types.

{
   value: {
		eq: String || Number,		// Exact allowed value (equals)
		max: Number,				// Maximum allowed value
		min: Number,				// Minimum allowed value
		contains: String || Number	// The value contains 
	}
}

Custom function

Use a custom function to check at your own criteria. The only necessary thing is the function to return true or false-

{
	func: function	A function to validate. Must return true or false.
}

The function might look like this:

function is42(value) {
	var allowed = [42, '42', 'cuarenta y dos', 'fourty two', 'the answer to the life the universe and everything'];
	if (allowedValues.indexOf(value) === -1) {
		return false;
	}
	return true;
}

Date

Check if data is a JavaScript Date. Just need to set a boolean date parameter, like:

{
	date: Boolean	// Check if data is a JS Date
}

Remember that JavaScript dates has type Object

Model

Yes, models can also validate (and modelate) other models. It's just neccessary the model to exists. To add that model validation, just set a property "model", with the string value of the model name:

{
	model: String	// Check if data is of a defined model
}

An example of when and how to use it, would be a geopoint:

var coords = Modelate('Coords').set({ 
	lat: {
		type: 'number'
	}, 
	lon: {
		type: 'number'
	}
});

var geopoint = Modelate('Geopoint').set({
	coords: {
		model: 'Coords'
	},
	name: {
		type: 'String',
		length: {
			max: 140
		}
	}
});

// Now, you can validate Geopoint objects ^^
var myGeopoint = {
	name: 'Batman Symbol',
	coords: {
		lat: 26.357896,
		long: 127.783809
	}
};

var batman = geopoint.modelate(myGeopoint);
console.log(batman);

Email

Check if data is an email. Might be just a boolean, or an object to check domains:

{
	email: Boolean	// Check if data is an email
}

Also, to check domains:

{
	email: {
		domain: 'gmail.com'
	}
}

Or, to enable more than one valid domains:

{
	email: {
		domain: ['gmail.com', 'google.com']
	}
}

Regex

Test a regular expression over the data.

{
	regex: Regex	// Check if data is regex valid
}

An example might be:

{
	regex: /[a]/
}

This will validate asd but not sdf

Tests

Are built with Jasmine, and stored in /spec folder.

First time you run tests, you might need to install Jasmine, and other dependencies. Just execute:

npm install

To run tests, just execute:

npm test

Contribute

You can use this code as you like. If you find a bug, or want to ask for a feature, just open an issue, and we'll do our best. If you can fix it, do a pull request to dev branch, and we promise to review it as fast as possible to merge it.

If you are new on this open source world, here is a short guide about how to make a pull request to contribute:

1. Fork then clone git clone git@github.com:your-username/modelate.git CodingCarlos/modelate repository.
2. Create a new branch in your personal forked repo, with a name similar to your edits, such as fix-whatever.
3. Make your edits inside your new branch.
4. Commit them and push them back to your personal github fork.
5. Make a new Pull Request on the CodingCarlos/modelate repo. Point your branch to the dev CodingCarlos/modelate's branch and submit.
6. We will do my best to review and accept the code as soon as possible.