draft

Construct Object schemas and models

npm install draft
30 downloads in the last week
60 downloads in the last month

draft

draft

Give your object and models schemas

Build Status browser support

--

install

nodejs

$ npm install draft --save

component

$ component install jwerle/draft

bower

$ bower install draft

browser

<script type="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

var User = draft({ name: String, email: String })
  , Post = draft({ owner: Object, content: String })

var werle = new User({ name: 'werle', email: 'joseph@werle.io' })
  , post  = new Post({ owner: werle, content: "I like draft :)"})

api

draft(descriptor, options)

Creates a schema form a descriptor and returns a model constructor

example

var Post = 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

var schema = new draft.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

var siteSchema = new draft.Schema({
  name : String,
  url  : String
});

siteSchema.static('createSites', function createSites (map) {
  return Object.keys(map).map(function (site) {
    return new this({ name: site, url: map[site] });
  }, this);
});

// create Site model
var Site = siteSchema.createModel();

var sites = 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

var schema = new draft.Schema({
  name  : String,
  email : String
});

var User = schema.createModel();
var user = new User({ 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

var schema = new draft.Schema({
  name   : String,
  albums : [Album],
  fans   : [Fan]
});

var bob = schema.new({
  name: 'bob',
  albums: [new Album({ name: "Sun Is Shining" }), new Album({ 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

new draft.Schema({ name : String })

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

new draft.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

var tree = new draft.Tree({
  name: String
});

// tree.name is an instance of draft.Type who's constructor is a String constructor
tree.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

var tree = new draft.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

var stringType = new draft.Type(String);
stringType.coerce(123); // '123'

var numberType = new draft.Type(Number);
numberType.coerce('123'); // 123

var booleanType = new draft.Type(Boolean);
booleanType.coerce(1); // true
booleanType.coerce(0); // false

Creating a custom type

var customType = new draft.Type(function CustomType (value) {
  return {
    toString: function () {
      return value.toString();
    },

    valueOf: function () {
      return value;
    },

    add: function (n) {
      return CustomType(value + n);
    },

    sub: function (n) {
      return CustomType(value - n);
    }
  };
});

+customType.coerce(4).add(5); // 9
+customType.coerce(10).sub(9); // 1
customType.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

var someType.valueOf(); // some value

.get(value)

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

var stringType = new draft.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()

var stringType = new draft.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

var numberType = new draft.Type(Number)

numberType.validate('123'); // false
numberType.validate(true); // false
numberType.validate(123); // true

.coerce(input)

Coerces a given input with the set Constructor type

  • input - Input to coerce to a type

example

var booleanType = new draft.Type(Boolean)

booleanType.coerce(1); // true
booleanType.coerce(123); // true
booleanType.coerce(0); // false
booleanType.coerce(null); // false
booleanType.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

var schema = new draft.Schema({
  name: String,
  email: String
});

var user = new draft.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

var draft = require('draft')
var schema = new draft.Schema({
  name : String,
  profile : {
    email : String,
    age : Number
  }
});

Create a model constructor from the schema defaulting to strict mode

var User = 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

var user = new User({
  name: 'werle',
  profile: { email: 'joseph@werle.io' },
  somePropertyNotInSchema: 'someValue'
});

Only values in the schema were set on the object

user.name // werle
user.profile.email // joseph@werle.io
user.somePropertyNotInSchema // undefined

todo

  • write more tests
  • document more

license

MIT

npm loves you