draft

Give your object and models schemas

--

install

nodejs

$ npm install draft --save

component

$ component install jwerle/draft

bower

$ bower install draft

browser

<scripttype="text/javascript" src="https://raw.github.com/jwerle/draft/master/draft.js"></script>

usage

Creating a model with draft is as simple as passing it a schema descriptor

varUser=draft({name: String,email: String}),Post=draft({owner: Object,content: String})varwerle=newUser({name: 'werle',email: 'joseph@werle.io'}),post=newPost({owner: werle,content: "I like draft :)"})

api

draft(descriptor, options)

Creates a schema form a descriptor and returns a model constructor

example

varPost=draft({owner : User,comments : [Comment],content : String,created : Date,updated : Date});

--

Schema(descriptor, options)

Schema constructor

• descriptor - An object defining a descriptor for the schema instance
• options - An object of options:
• strict - Strict mode. Model from schema will be frozen from schema updates after instantiation. (Default: true)

example

varschema=newdraft.Schema({name: String,email: String});

.add(key, descriptor)

Adds an object to the schema tree

• key - A key used to identify the property in the schema
• descriptor - An object descriptor or constructor function

example

schema.add({age: Number});

.static(name, func)

Creates a static function on the schema's model constructor

• name - The name of the static function
• func - The actual function

example

varsiteSchema=newdraft.Schema({name : String,url : String});siteSchema.static('createSites',functioncreateSites(map){returnObject.keys(map).map(function(site){returnnewthis({name: site,url: map[site]});},this);});// create Site modelvarSite=siteSchema.createModel();varsites=Site.createSites({'google' : "http://google.com",'github' : "https://github.com",'twitter' : "https://twitter.com",});sites[0].name;// 'google'sites[0].url;// 'http://google.com'sites[1].name;// 'github'sites[1].url;// 'https://github.com'

.createModel()

Creates a constructor from the defined schema

example

varschema=newdraft.Schema({name : String,email : String});varUser=schema.createModel();varuser=newUser({name: 'werle',email: 'joseph@werle.io'});

.new(data)

Accepts an object of data and passes it to the Model constructor from the Schema instance

• data - An object of data to pass to the schema instance model constructor

example

varschema=newdraft.Schema({name : String,albums : [Album],fans : [Fan]});varbob=schema.new({name: 'bob',albums: [newAlbum({name: "Sun Is Shining"}),newAlbum({name: "Roots of a Legend"})],fans: [sally,frank,joe]});

using schema descriptors

A schema descriptor is a key to type descriptor object. The key for each property on the object represents a possible key on a model instance created from the schema instance.

A simple example of a schema who defines a model which accepts an object that defines a single property name of the type string

newdraft.Schema({name : String})

A more advanced example would be to define the descriptor object for the property:

newdraft.Schema({name: {type: String}})

--

Tree(descriptor, options)

Tree constructor. Creates an object tree for a schema. This is used for aggregating types

A tree instance is intended to be used with a schema

• descriptor - A schema descriptor used to define the tree.
• options - An object of options. If present and array is set to true then an array is returned who's prototype is an instance of the tree .

example

vartree=newdraft.Tree({name: String});// tree.name is an instance of draft.Type who's constructor is a String constructortree.name;// { Constructor: [Function: String] }

.add(parent, key, descriptor)

Adds a key to the tree on a given parent tree. Defaults to 'this' as the parent if one is not provided.

• parent - The parent tree object in which the descriptor is added to by the provided key. Defaults to the tree instance caller.
• key - The key of the item in the tree to add
• descriptor - The object descriptor for the key being added to the tree

example

vartree=newdraft.Tree({domain: String});tree.add('subdomains',{});tree.subdomains;// {} (Tree instance)tree.add(tree.subdomains,'primary',String);tree.subdomains.primary;// { Constructor: [Function: String] }tree.add(tree.subdomains,'secondary',String);tree.subdomains.secondary;// { Constructor: [Function: String] }tree.subdomains.add('cdn',String);tree.subdomains.cdn;// { Constructor: [Function: String] }tree.add('host',String);tree.host;// { Constructor: [Function: String] }

--

Type(Constructor, descriptor)

Type constructor. Creates a Type used in a Tree instance for a Schema instance. It is meant to provide methods for validation and coercion.

• Constructor - A valid type constructor who will NEVER be invoked with the new operator
• descriptor - A valid schema constructor

example

varstringType=newdraft.Type(String);stringType.coerce(123);// '123'varnumberType=newdraft.Type(Number);numberType.coerce('123');// 123varbooleanType=newdraft.Type(Boolean);booleanType.coerce(1);// truebooleanType.coerce(0);// false

Creating a custom type

varcustomType=newdraft.Type(functionCustomType(value){return{toString: function(){returnvalue.toString();},valueOf: function(){returnvalue;},add: function(n){returnCustomType(value+n);},sub: function(n){returnCustomType(value-n);}};});+customType.coerce(4).add(5);// 9+customType.coerce(10).sub(9);// 1customType.coerce('j').add('o').add('e').toString();// 'joe'

.toString

Returns a string representation of a Type instance

example

someType.toString();// '[object Type]'

.valueOf

Returns the valueOf return value from the original constructor on the Type instance

varsomeType.valueOf();// some value

.get(value)

Default getter that coerces a value. This method that can be implemented by the descriptor. Defaults to .coerce()

varstringType=newdraft.Type(String)stringType.get(12345);// '12345'

.set(value)

Default setter that coerces a value. This method that can be implemented by the descriptor. Defaults to .coerce()

varstringType=newdraft.Type(String)stringType.set(12345);// '12345'

.validate(input)

Validates a defined type. It performs instance of checks on values that are not primitive. Primitive inputs are validated with a 'typeof' check

• input - Mixed input to validate against the type

example

varnumberType=newdraft.Type(Number)numberType.validate('123');// falsenumberType.validate(true);// falsenumberType.validate(123);// true

.coerce(input)

Coerces a given input with the set Constructor type

• input - Input to coerce to a type

example

varbooleanType=newdraft.Type(Boolean)booleanType.coerce(1);// truebooleanType.coerce(123);// truebooleanType.coerce(0);// falsebooleanType.coerce(null);// falsebooleanType.coerce();// false

--

Model(data, schema)

Base constructor for all created Model instances. Usually a Model constructor is created from a schema, but passing a schema to a Model constructor works too.

• data - An object of data is validated against the schema used to create the Model
• schema - An instance of a schema.

example

varschema=newdraft.Schema({name: String,email: String});varuser=newdraft.Model({name: 'werle',email: 'joseph@werle.io'},schema);

.refresh()

Refreshes the state of the model based on its schema

.set()

Sets data on the model based on the schema

.toObject()

Returns a plain object representation of the model

.toJSON()

Called with JSON.stringify

.toString()

Returns a string representation of a Model instance

.valueOf()

Returns a value representation of a Model instance

--

example

Define a schema for an object with types. Strict mode default

vardraft=require('draft')varschema=newdraft.Schema({name : String,profile : {email : String,age : Number}});

Create a model constructor from the schema defaulting to strict mode

varUser=schema.createModel();

Instantiate the model passing in an object. In strict mode all properties on an object must be defined in the schema that was used to create it

varuser=newUser({name: 'werle',profile: {email: 'joseph@werle.io'},somePropertyNotInSchema: 'someValue'});

Only values in the schema were set on the object

user.name// werleuser.profile.email// joseph@werle.iouser.somePropertyNotInSchema// undefined

todo

• write more tests
• document more

license

MIT