#fire-validations

Validations module for fire.js and fire-assert

Installing

using NPM

npm install fire-validations

using Github(unstable)

In the root of your project run:

git clone git://github.com/firejs/fire-validations.git node_modules/fire-validations

Introduction

Validation works providing the context for assertions based on fire-assert and tracking the paths of the errors found.

Expressions

@Validations.Context

Executes a set of validations on a variable path given in the hint. Returns an array with all the errors found. A variable called "validation" is provided in the input and contains the context of the current validation and also the path. "validation.target" contains what is the object being validated and "validation.path" contains what is the path of the validation.

@Validations.Property

Takes a hint with the name of the member to validate in the current target. Bypass the result in the block.

@Validations.Array

Takes a hint with the name of the array to validate in the current target. Executes the input per item in the array. If the member is not an array it will bypass. Bypass the result in the block.

The member name in the hint is optional, this way to can validate the current target as an array.

Note: @Validations.Array is not a loop, using @break or @continue will not affect the iteration. If you want to interrupt the sequence on the first error in the array use @Validations.Checkpoint.

@Validations.Checkpoint

Check for errors reported by previous validations and stop the execution of further validations, otherwise it just bypass:

Example:

"@Validations.Context(contacts)": {
	"@Validations.Property(name)": {
		"@Assert.NotEmpty": null
	},
	"@Validations.Property(age)": {
		"@Assert.NotEmpty": null
	},
	"@Validations.Checkpoint": null,
	"@Validations.Property(tags)": {
		"@Assert.NotEmpty": null
	}
}

Examples:

Validating a Simple Field

"@set(person)": {
	"email": ""
},
"@Validations.Context(person)": {
	"@Validations.Property(email)": {
		"@Assert.NotEmpty": null
	}
}

The result:

[{"path":"/email","message":"Can't be empty"}]

Validating an Array

"@set(person)": {
	"emails": ["chuch@examplecom", "chuch at examplescom"]
},
"@Validations.Context(person)": {
	"@Validations.Array(emails)": {
		"@Assert.NotEmpty": null,
		"@Assert.Email": null
	}
}

The result, both email addresses are invalid so we get two messages:

[{"path":"/emails/0","message":"Not a valid Email address"},{"path":"/emails/1","message":"Not a valid Email address"}]

Validating nested objects in Arrays

"@set(categories)": [
	{
		"name": "Category A",
		"description": null 
	},
	{
		"description": "Description for Category B" 
	}]
,
"@Validations.Context(categories)": {
	"@Validations.Array": {
		"@Validations.Property(name)": {
			"@Assert.NotEmpty": null
		},
		"@Validations.Property(description)": {
			"@Assert.NotEmpty": null
		}
	}
}

The result:

[{"path":"/0/description","message":"Can't be empty"},{"path":"/1/name","message":"Can't be empty"}]

Understanding Paths

paths provide an easy and readable way to know at which level of the object the error occurred.

All the paths begins with slash '/', this is known as the root of the validation which is the value in the variable path to @Validations.Context. A slash is also the separator of the path.

Examples:

• /: the error was reported at the root value.
• /name: the error was reported at the name property .
• /tags/0/: the error was reported at the index 0 of the tags array.
• /tags/0/name: the error was reported at the property name of the index 0 of the tags array.
• /0: the root value is an Array and the error was reported at index 0.

Considerations with empty values.

A validator will validate only a certain aspect of the logic and just bypass if they can't accomplish the validation, the goal of this is to avoid repeating validation logic across different validators.

In the following example the Email validator will not report any error because the field is empty:

"@set(contact)": {
    "email": null
}
,
"@Validations.Context(contact)": {
    "@Validations.Property(email)": {
        "@Assert.Email": null
    }
}

This makes sense because Email will only validate if the value matches an email address, it will not validate the presence of the field because that's not part of what 'validating the email address' means, in fact, checking if the field is empty or not is part of another validator called @Assert.NotEmpty.

This is when you must use multiple validators over the same field.

Like this:

{
    "name": "TestVal.Main",
    "json": {
        "@set(contact)": {
            "email": null
        }
        ,
        "@Validations.Context(contact)": {
            "@Validations.Property(email)": {
				"@Assert.NotEmpty": null,
                "@Assert.Email": null
            }
        }
    }
}

The result:

[{"path":"/email","message":"Can't be empty"}]

Still you will not see the Email validator reporting any error because NonEmpty is reporting first. This situations changes when Email validator founds a value to validate like in the following example:

{
    "name": "TestVal.Main",
    "json": {
        "@set(contact)": {
            "email": "some invalid email value"
        }
        ,
        "@Validations.Context(contact)": {
            "@Validations.Property(email)": {
				"@Assert.NotEmpty": null,
                "@Assert.Email": null
            }
        }
    }
}

The result:

[{"path":"/email","message":"Not a valid Email address"}]

Now you see the Email validator doing it's job.

Localization Support

fire-validations has built-in support for a small set of languages via fire-i18n, check the wiki for more information.

Reporting validation errors

If you want to report validations errors you can use @Validations.Error, which input is the message of the error:

Example

@Validations.Context(contacts)": {
	"@Validations.Error": "This is my custom error report"
}

The result is:

[{ "path": "/", "message": "This is my custom error report" }]

Cloning the Repository

git clone git://github.com/firejs/fire-validations.git

Tests

make

Contributors

• Johan (author). Email: [email protected]

MIT License

Copyright (c) 2011 Firebase.co - http://www.firebase.co

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.