Nutella with Pepperoni and Mushrooms
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    draftpublic

    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

    install

    npm i draft

    Downloadsweekly downloads

    118

    version

    0.2.3

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar