Tutorial series - #3 Schemas

Schemas are one of the Total.js core feature. With schemas you can control incoming data and convert them to your defined types. You can use them as main data handlers for you operations like listing, creating, updating or removing data.

Example of simple schema:

NEWSCHEMA('Users', function(schema) {
    schema.define('name', 'String', true);
    schema.define('age', 'Number');

    schema.setQuery(function($, model) {
        var message = 'Hi, ' + model.name;

        if (model.age)
            message += '(' + model.age + ')';

        $.success(message);
    },'page:Number');

});

Schema Users has two fields:

• name which must be type string and is required parameter.
• age which must be type number and is not required

After executing query method in Users schema, you will recieve success object with value of provided name in field name and with age (if was provided).

// Request
{
    name: 'Jakub',
    age: 21
}

// Response
{
    success: true,
    value: 'Hi, Jakub (21)'
}

Data validation

Data validation will help you with converting values, setting default values, making fields required and allowing only relevant fields. If recieved value is not defined in schema it will be automatically removed.

Some of the most used data types:

• String - you can also define maximum length of string String(25), everything over 25 characters will be removed
• Number - can be also float number
• Email - has special validation to accept only valid email (e.g. xxxx@xxx.xx)

All data types can be found in Total.js's documentation

Default values:

Most of the data types has pre-defined default values so there is no need to worry about recieveing null or undefined in String for example.

Nested object:

Sometimes you want to validate nested objects inside your schema for more complex data structure. There are two ways to declare nested object inside schema. Creating new dedicated schema or using inline declaring.

// Dedicated schema
NEWSCHEMA('Orders/Address', function(schema) {
    schema.define('countryid', 'Uppercase(2)');
    schema.define('city', 'String(100)');
    schema.define('street', 'String(50)');
    schema.define('zip', 'ZIP');
});

NEWSCHEMA('Orders', function(schema) {
    schema.define('address', 'Orders/Address');
});

// Inline declare
NEWSCHEMA('Orders', function(schema) {
    schema.define('address', 'countryid:Uppercase(2),city:String(100),street:String(50),zip:ZIP');
});

Required values

To make value required you can use third argument inside schema.define() which can be Boolean or Function. If you are using custom validation function make sure to return true or false. Fourth argument is custom error message.

// If age is less than 18, throw error "Only adults are allowed"
NEWSCHEMA('Posts', function(schema) {
    schema.define('age', 'Number', age => age < 18, 'Only adults are allowed');
});

Methods

Schema methods are usually main logic of every Total.js application. They recieve formatted and relatively safe data ready to be used thanks to schema's data type definintions.

Total.js provides predefined schema methods names which are commonly used inside almost every application. You can also define your own name through addWorkflow. Predefined names with meant but not mandatory usage:

• setQuery: List of items
• setRead: Details of item
• setInsert: Create new item
• setSave: Create new item or update existing item
• setUpdate: Update item
• setPatch: Update existing item (partly)
• setRemove: Remove item

Filter

Filter is simple validation for provided query arguments. After method function simply add string comma-separated with query argument and values:

schema.setInsert(function($) {
    $.callback($.filter); // { type: 'open', page: 1, limit: 25 }
}, 'type:String,page:Number,limit:Number');

Usage

In most cases you want use schema methods with routes -ROUTE. After hitting endpoint schema will handle request.

ROUTE('GET /api/posts/    *Posts --> query');

Multiple execution

Executing multiple schema methods in single request is also possible. Methods are executed one by one but previous method needs to be successful - $.success()

ROUTE('POST /api/posts/   *Posts --> validate insert (response)');

NEWSCHEMA('Posts', function(schema) {

    schema.addWorkflow('validate', function($) {
        $.success('Response #1 (will be ignored)');
    });

    schema.setInsert(function($) {
        $.success('Response #2');
    });

});

Typing (response) after method name will tell controller to apply response from insert method only. All other responses will be ignored. HTTP response will be Response #2.

Manual execution

Sometimes you want execute schema manually without route. To achive that use global function called EXEC():

var data = {};
data.title = 'Total blog #3';
data.tags = ['total', 'total4', 'schemas'];

EXEC('+Posts --> insert', data, function(err, res) {
    console.log(err, res);
});

First argument is directing EXEC() function to requested schema method:

• + validate data from selected schema (- will ignore require flag of fields)
• Posts schema name
• insert method name inside Posts schema

Second argument is object with body data that will be recieved inside our schema (can be null). Last argument is response callback with error or response data. If you want inhert request with headers and cookies you can pass controller instance as fourth optional argument or add customer user object:

EXEC('+Posts --> insert', data, function(err, res) {
    console.log(err, res);
}, $);

var controller = EXEC('-Posts --> query', null, NOOP);
controller.user = { id: '123', username: 'Admin' };

More about EXEC() function