alamid-schema

alamid-schema

Extendable mongoose-like schemas for node.js and the browser

If you like mongoose schemas and you want to use them standalone, alamid-schema is the right module for you.

alamid-schema helps you with

• validation of data
• using mongoose-like schemas without using mongoose
• sharing data-definition between client & server
• normalizing data (coming soon)
• striping readable/writeable fields (coming soon)

Use it on the server to...

• normalize and validate incoming requests
• strip private fields from the response

Use it on the client to...

• validate forms
• define view models

var Schema = require("alamid-schema");

var Panda = new Schema("Panda", {
    name: String,
    age: {
        type: Number,
        required: true,
        writable: false,
        readable: true
    },
    mood: {
        type: String,
        enum: ["grumpy", "happy"]
    },
    birthday: Date
});

Examples

Schema Definition

You can define your schema with concrete values...

var PandaSchema = new Schema({
    name: "panda",
    age: 12,
    friends: {
        type: []
    }
});

...or with abstract types...

var PandaSchema = new Schema({
    name: String,
    age: Number,
    friends: {
        type: Array
    }
});

Extend

Sometimes you want to extend your Schema and add new properties.

var PandaSchema = new Schema({
    name: String,
    age: Number,
    friends: {
        type: Array
    }
});

var SuperPanda = PandaSchema.extend("SuperPanda", {
    xRay: true,
    canFly: {
        type: Boolean
    }
});

We have a superpanda now... which can fly and has xray eyes! That's basically the same as...

var SuperPanda = new Schema({
    name: String,
    age: Number,
    friends: {
        type: Array
    },
    xRay: true, //added
    canFly: {   //added
        type: Boolean
    }
});

Overwriting properties

If you define a property in the schema you are extending with, the extending schema takes precedence.

var Animal = new Schema({
    name: String,
    age: String
});

var Panda = Animal.extend("Panda", {
    age: Number
    color: String
});

equals...

var Panda = new Schema("Panda", {
    name: String,
    age: Number,   //overwritten
    color: String  //added
});

Plugin: Validation

The validation plugins adds - suprise! - validation support.

var Schema = require("alamid-schema");

Schema.use(require("alamid-schema/plugins/validation"));

var PandaSchema = new Schema({
    name: {
        type: String,
        required: true
    },
    age: {
        type: Number,
        min: 9,
        max: 99
    },
    mood: {
        type: String,
        enum: ["happy", "sleepy"]
    },
    treasures: {
        type: Array,
        minLength: 3
    },
    birthday: Date
});

var panda = {
    name: "Hugo",
    age: 3,
    mood: "happy"
};

PandaSchema.validate(panda, function(validation) {
    if (!validation.result) {
        console.log(validation.errors);
        return;
    }

    console.log("happy panda");
});

outputs...

{
    result: false,
    errors: {
        age: [ 'min' ]
    }
}

Included validators:

• required
• min (works on Number)
• max (works on Number)
• enum
• minLength (works on String, Array)
• maxLength (works on String, Array)
• hasLength (works on String, Array)
• matches (performs a strict comparison, also accepts RegExp)

Writing custom validators:

You can write sync and async validators..

// sync
function oldEnough(age) {
    return age > 18 || "too-young";
}

// async
function nameIsUnique(name, callback) {
    fs.readFile(__dirname + "/names.json", function(err, names) {
        if(err) {
            throw err;
        }

        names = JSON.parse(names);
        callback(names.indexOf(name) === -1 || "name-already-taken");
    });
}

var PandaSchema = new Schema({
    name: {
        type: String,
        required: true,
        validate: nameIsUnique
    },
    age: {
        type: Number,
        validate: oldEnough,
        max: 99
    }
});

var panda = {
    name: "hugo",
    age: 3,
    mood: "happy"
};

PandaSchema.validate(panda, function(validation) {
    if(!validation.result) {
        console.log(validation.errors);
        return;
    }
    console.log("happy panda");
});

outputs...

{
    name: [ "name-already-taken" ],
    age:  [ "too-young" ]
}

Note: validators will be called with this bound to model.

Promises

The validate() method also returns a promise:

PandaSchema.validate(panda)
	.then(function (validation) {
		...
	})

The promise will still be resolved even when the validation fails, because a failed validation is not an error, it's an expected state.

The promise provides a reference to the final validation result object. It contains the intermediate result of all synchronous validators:

var promise = PandaSchema.validate(panda);

if (promise.validation.result) {
    console.log("Synchronous validation of " + Object.keys(validation.errors) + " failed");
}

Important notice: You must bring your own ES6 Promise compatible polyfill!

API

Core

Schema([name: String, ]definition: Object)

Creates a new schema.

.fields: Array

The array of property names that are defined on the schema. Do not modify this array.

.only(key1: Array|String[, key2: String, key3: String, ...]): Schema

Returns a subset with the given keys of the current schema. You may pass an array with keys or just the keys as arguments.

.extend([name: String, ]definition: Object): Schema

Creates a new schema that inherits from the current schema. Field definitions are merged where appropriate. If a definition conflicts with the parent definition, the child's definition supersedes.

.strip(model: Object)

Removes all properties from model that are not defined in fields. Will not remove properties that are inherited from the prototype.

Readable & Writable fields

You can define readable and writable fields in the schema. By default, every field is read- and writable.

var PandaSchema = new Schema({
    id: {
        type: Number,
        required: true,
        readable: true,
        writable: false
    },
    lastModified: {
        readable: true,
        writable: false
    }
};

.writableFields()

Returns an array containing the keys of all writable fields:

PandaSchema.writableFields(); // ["name", "age", "mood", "treasures", "birthday"]

.writable()

Creates a new schema that contains only the writable fields:

var PandaWritableSchema = PandaSchema.writable();

.readableFields()

Returns an array containing the keys of all readable fields:

PandaSchema.readableFields(); // ["name", "age", "mood", "treasures", "birthday"]

.readable()

Creates a new schema that contains only the readable fields:

var PandaReadableSchema = PandaSchema.readable();

Plugin: Validation

.validate(model: Object[, callback: Function]): Promise

Validate given model using the schema definitions. Callback will be called/Promise will be fulfilled with a validation object with result (Boolean) and errors (Object) containing the error codes.

Changelog

1.0.0

• Breaking: Remove Promise shim. You need to provide that now (commit).
• Breaking: Renamed readable- and writable-methods (commit).
• Breaking: Change error message casing of default validators from camelCased to dash-cased (commit).
• Breaking: Rename validation.failedFields to validation.errors (commit).
• Breaking: Do not reject promises when the validation has failed (commit).
• Breaking: Rename schema.keys to schema.fields (commit).
• Add minLength, maxLength, hasLength validators (pr).
• Add matches validator (commit).
• Add Schema.prototype.strip() method for removing extranous properties (commit).
• The synchronous validation result can now be retrieved synchronously (commit).