Tutorial series - #4 Operations & Tasks

Operations and Tasks are Total's features which can be used in many different cases. Operation is something like global function in your app but with some extra functionality. Task has multiple smaller functions which can be called separatly from that task or even outside of that task. You can even chain them inside single task to create complex recursive flows.

Operations

Operations are global functions with some extra functionality. They are often used as alternative way to handle client requests or used as wrappers.

Declare:

Operations are usually stored in operations directory inside root of your application. To declare new operation you need to use global function NEWOPERATION(). Function takes two required and four optional arguments:

• *Name - Operation name.
• *Handler - Function with $ that will be executed when operation is called .
• Repeat - Repeat count of this operation.
• Stop - If operation was successful, don't run next operations (used with multioperation).
• Bind error - If operation throws error, framework will bind this as response error.
• Query schema - Used for converting query string values to specific data type. Parser is using CONVERT() on background. Converted values are stored in $.filter object.

To make operation successful use one of these functions $.success(), $.done() or $.callback().

To make operation un-successful (throw error in callback) you can use $.invalid().

*Required

NEWOPERATION('quickmaths', function($) {
    if (2 + 2 - 1 === 3)
        $.success('Skidi-kat-kat');
    else
        $.invalid('Boom');
});

Usage:

After declaring your operation you can simply execute it with OPERATION(). Function has two required and three optional arguments:

• *Name - Name of operation to run.
• Value - Value that will be passed to operation which can be accessed through $.value.
• *Callback - Function will be called after operation is finished. Function has error and response argument.
• Controller - Field for passing controller instance.

*Required

OPERATION('quickmaths', { data: 1 }, function(error, response) {
    // ...
});

You can also call operation directly from your ROUTE():

ROUTE('GET   /      *    -->   operation_name');

Multioperation:

To run multiple operations in your code you can use global function RUN(). This function has two required and four optional arguments:

RUN() function support multiple declaration syntaxes for operations:

• *Names - Names of operations to run (see code bellow).
• Value - Value that will be passed to operation which can be accessed through $.value in each operation.
• *Callback - Function will be called after last operation is finished. Function has error and response argument.
• Controller - Field for passing controller instance.
• Response name - Name of operation

*Required

// Operation names in a single string
RUN('operation1, operation2, operation3');

// Operation names in an array
RUN(['operation1', 'operation2', 'operation3']);

Response value in your callback function will be an object of all operation's responses. If you want only specific response you can name of that operation as fourth argument:

RUN(['first', 'second', 'third'], null, function(err, response, $) {
    console.log(response); // Output from operation 'second'
}, 'second');

This code bellow is equivalent of RUN()'s multioperation that is above but its targeted for ROUTE():

ROUTE('GET /operations/ * --> first second (response) third ');

After user hits GET /operations/ route, operations first, second and third will be executed and user will get response (or error) from second operation because it has (response).

Tasks

Tasks are very versatile because they can execute infinitely between themself. Tasks are great solution for your simple or complex processes.

Declare:

All tasks are usually stored in tasks directory inside root of your Total.js application. To declare new operation use global function NEWTASK():

• *Name - Name of new task.
• *Registration delegate - Function with push argument that is used for adding more "steps" to your task.

*Required

NEWTASK('Add', function(push) {

    push('init', function($, value) {
        value.num1 = 1;
        value.num2 = value.number;

        if (!num2)
            $.next('exec');
        else
            $.invalid('Argument "number" is required');
    });

    push('exec', function($, value) {
        $.end(value.num1 + value.num2);
    });

});

Useful $ methods for tasks:

• $.end(value) - Ends task and execute callback declared with TASK().
• $.end2(value) - Return $.end(value) wrapped in function (use this as callback function).
• $.next(step) - Call next task "step".
• $.next2(step) - Return $.next(step) wrapped in function (use this as callback function).
• $.success() and $.invalid() are also valid methods in task builder.

Usage:

To execute your tasks use global function TASK():

• *Name - Task name and "step" name separated with / ('Add/init' for example).
• *Callback - Callback function with error and response objects (depends on task's result). Callback is called after executing $.end() method in your task.
• Instance - Controller or $
• Value - Data that will be passed to task

*Required

var data = { number: 5 };

TASK('Add/init', function(err, response) {
    if (err)
        console.log('Task failed:', err);
    else
        console.log('Task was successful:', response);
}, null, data);