instructions in readme
This commit is contained in:
parent
e98e9689fb
commit
26bc1f33ee
171
README
171
README
|
@ -1 +1,170 @@
|
|||
a quick way to validate objects from incoming post/get params using json notation as the schema
|
||||
#v0.1.2
|
||||
|
||||
### schemajs
|
||||
|
||||
validate objects (including http request params) against a schema. includes express middleware.
|
||||
|
||||
### Installing
|
||||
|
||||
npm install schemajs
|
||||
|
||||
# FEATURES
|
||||
- validates schema for deep objects and arrays as well
|
||||
- schema is in JSON, making it portable
|
||||
- properties, types and filters are extensible
|
||||
|
||||
# EXAMPLE USAGE - validate an object
|
||||
|
||||
var schema = require("./path/to/schemajs");
|
||||
var model = schema.create({
|
||||
name: {type:"string", filters:"trim", properties:{max:255}, required:true},
|
||||
email: {type:"email", filters:"trim", required:true},
|
||||
wins: {type:"int", filters:["trim", "toInt"], default:0},
|
||||
average: {type:"float", filters:["trim", "toFloat"], default:0}
|
||||
});
|
||||
|
||||
var form = model.validate({name:" your name ", email:" name@example.com "});
|
||||
|
||||
// form.valid - boolean, true if object matches schema
|
||||
// form.data - contains filtered version of the object {name:"your name", email:"name@example.com", wins:0, average:0}
|
||||
// form.errors - contains associative array of any errors found
|
||||
|
||||
# EXAMPLE USAGE - in expressjs, validate the get parameters
|
||||
|
||||
var schema = require("./path/to/schemajs");
|
||||
var query = schema.create({
|
||||
wins: {type:"int", filters:"toInt"},
|
||||
query: {type:"string", filters:"trim", required:true, error:"invalid query"}
|
||||
});
|
||||
|
||||
app.get("/users", schema.middleware(query), function(req, res)
|
||||
{
|
||||
// schema validation is attached to req.form
|
||||
if(req.form.valid)
|
||||
{
|
||||
db_lookup({query:req.form.data.query, wins: req.form.data.wins});
|
||||
}
|
||||
else
|
||||
next(new Error("invalid request"));
|
||||
//next(req.form.errors, 400);
|
||||
});
|
||||
|
||||
# API
|
||||
|
||||
## schema.create(schema)
|
||||
|
||||
// schema for a simple object of one integer value
|
||||
schema =
|
||||
{
|
||||
// [string] value for acceppted parameters of the object you want to test
|
||||
"wins":
|
||||
{
|
||||
// [string (build in types) or function (custom types)] the type declaration for accepted values
|
||||
"type": "int",
|
||||
|
||||
// [string (built in filters) or function (custom filters) or array (mix and match!)] OPTIONAL, filters to process and optionally modify values
|
||||
"filters": ["trim", "toInt", custom_filter],
|
||||
|
||||
// [anything] OPTIONAL, the default value if none is supplied by the object
|
||||
"default": 0,
|
||||
|
||||
// [boolean] OPTIONAL, if true, this parameter must exist to validate
|
||||
"required": true
|
||||
|
||||
// [object] OPTIONAL, functions are custom property checks, else a built in property will be looked up
|
||||
"properties": {max:100, min:0, special:custom_property}
|
||||
|
||||
// [string, object] OPTIONAL, if there is an error, you can override the message that is returned
|
||||
// use a string or the "default" key to use the default error message
|
||||
// keys can be any property key that was used as well as "filters", "required", "type"
|
||||
"error": {max: "too many wins", min: "too few wins", "default": "something is wrong with your wins value"}
|
||||
}
|
||||
}
|
||||
|
||||
// schema looking at two complex values (object and an array) with embedded schemas
|
||||
schema =
|
||||
{
|
||||
"user":
|
||||
{
|
||||
"type": "object",
|
||||
"schema":
|
||||
{
|
||||
"name": { type: "string", property: { max: 255 }, required: true},
|
||||
"email": { type: "email", error: "email is not a valid email address"}
|
||||
}
|
||||
"error": "user needs an email and a name"
|
||||
},
|
||||
|
||||
"tags":
|
||||
{
|
||||
"type": "array",
|
||||
"schema":
|
||||
{
|
||||
"type": "string"
|
||||
}
|
||||
"properties": { max: 10, min: 3}
|
||||
"error": { max: "too many tags", min: "too few tags" }
|
||||
}
|
||||
}
|
||||
|
||||
## schema.types
|
||||
|
||||
// built in types
|
||||
[string, alpha, alphanum, email, object, array, date, number, int, boolean, url, zipcode]
|
||||
|
||||
// to extend, add a function onto schema.types that accepts a value and returns a boolean if the type matches
|
||||
// test is run AFTER schema.filters are run
|
||||
schema.types.awesome = function(value)
|
||||
{
|
||||
if(isAwesome(value))
|
||||
return true;
|
||||
else
|
||||
return false;
|
||||
}
|
||||
|
||||
## schema.filters
|
||||
|
||||
// built in filters
|
||||
[toInt, toFloat, toString, toDate, toBoolean (converts on/off, true/false, 1/0, yes/no to bools), trim]
|
||||
|
||||
// to extend, add a function onto schema.filters that takes in a value and returns the updated value
|
||||
// filters are run BEFORE schema.test is run
|
||||
schema.filters.surround = function(value)
|
||||
{
|
||||
if(value == needs_surrounding)
|
||||
return "----" + value + "----";
|
||||
else
|
||||
return value;
|
||||
}
|
||||
|
||||
## schema.properties
|
||||
|
||||
// built in properties
|
||||
[max, min, regex, in]
|
||||
|
||||
// to extend, add a function onto schema.properties that takes in a value and any additional arguments
|
||||
// properties are run AFTER test and filters
|
||||
schema.properties.unique = function(value)
|
||||
{
|
||||
if(isArray(value) && allUnique(value))
|
||||
return true;
|
||||
else
|
||||
return false;
|
||||
}
|
||||
|
||||
schema.properties.notIn = function(value, badwords)
|
||||
{
|
||||
if(badwords.indexOf(value) != -1)
|
||||
return false;
|
||||
else
|
||||
return true;
|
||||
}
|
||||
|
||||
# ideas
|
||||
|
||||
- make it work in the browser for client side validation
|
||||
- strict mode, dissallowing extra parameters from being passed in
|
||||
- dependency property making one parameters existance depend on another
|
||||
- more types (phone numbers, credit card, ip address)
|
||||
- more filters (camelcase, encode/unencode)
|
||||
- more properties
|
||||
|
|
50
lib/rules.js
50
lib/rules.js
|
@ -62,10 +62,20 @@ Rules.prototype.apply = function(value)
|
|||
|
||||
if(this.rules.type)
|
||||
{
|
||||
if(!is[this.rules.type](value))
|
||||
{
|
||||
throw this.Error("%s is not a " + this.rules.type, "type", value);
|
||||
}
|
||||
if(typeof(this.rules.type) == "string" && typeof(is[this.rules.type]) == "function")
|
||||
{
|
||||
if(!is[this.rules.type](value))
|
||||
throw this.Error("%s is not a " + this.rules.type, "type", value);
|
||||
}
|
||||
else if(typeof(this.rules.type == "function"))
|
||||
{
|
||||
if(!this.rules.type(value))
|
||||
throw this.Error("%s is not a valid type", "type", value);
|
||||
}
|
||||
else
|
||||
{
|
||||
throw this.Error("%s is not a valid type", "type", value);
|
||||
}
|
||||
}
|
||||
|
||||
if(this.rules.properties)
|
||||
|
@ -147,12 +157,34 @@ var checks =
|
|||
{
|
||||
'max': function(value, length)
|
||||
{
|
||||
return value.length <= length;
|
||||
if(Array.isArray(value) || typeof(value) == "string")
|
||||
{
|
||||
return value.length <= length;
|
||||
}
|
||||
else if(typeof(value) == "number")
|
||||
{
|
||||
return value <= length;
|
||||
}
|
||||
else
|
||||
{
|
||||
return false;
|
||||
}
|
||||
},
|
||||
|
||||
'min': function(value, length)
|
||||
{
|
||||
return value.length >= length;
|
||||
if(Array.isArray(value) || typeof(value) == "string")
|
||||
{
|
||||
return value.length >= length;
|
||||
}
|
||||
else if(typeof(value) == "number")
|
||||
{
|
||||
return value >= length;
|
||||
}
|
||||
else
|
||||
{
|
||||
return false;
|
||||
}
|
||||
},
|
||||
|
||||
'regex': function(value, regex)
|
||||
|
@ -175,12 +207,12 @@ var is =
|
|||
|
||||
'alphanum': function(value)
|
||||
{
|
||||
return /^[a-z0-9]+$/i.test(value);
|
||||
return (/^[a-z0-9]+$/i).test(value);
|
||||
},
|
||||
|
||||
'alpha': function(value)
|
||||
{
|
||||
return /^[a-z]+$/i.test(value);
|
||||
return (/^[a-z]+$/i).test(value);
|
||||
},
|
||||
|
||||
'object': function(value)
|
||||
|
@ -272,7 +304,7 @@ var filters =
|
|||
}
|
||||
};
|
||||
|
||||
exports.create = function(param, rules) { return new Rules(param, rules); }
|
||||
exports.create = function(param, rules) { return new Rules(param, rules); };
|
||||
exports.types = is;
|
||||
exports.filters = filters;
|
||||
exports.properties = checks;
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"name": "schemajs",
|
||||
"description": "extensible object validator",
|
||||
"version": "0.1.1",
|
||||
"version": "0.1.2",
|
||||
"author": "eleith",
|
||||
"contributors": [],
|
||||
"repository":
|
||||
|
|
Reference in New Issue