Home Intro Source Mebo GitHub 
import Handler from 'mebo/src/Handler.js'
public class | source

Handler

Direct Subclass:

Cli, Web

A handler is used to bridge an execution method to Mebo.

The data used to perform the execution of action through a handler (Handler.runAction) is parsed using a reader Reader.

The result of a handler is done through a Writer. Writers are designed to support reporting a success output and an error output as well. The way the result is serialized is determined by the writer implementation (Writer._successOutput, Writer._errorOutput). All writers shipped with Mebo have support for streams where in case of any readable stream or buffer value they are piped to the output, otherwise the result is encoded using JSON.

Both reader and writer can be customized through options that can be either defined through the action's metadata or directly through the handler. If you would like to know more about the available options check out the respective Reader & Writer documentation for the handler implementation you are interested.

Defining options through actions (detailed information can be found at Metadata):

@Mebo.register('myAction')
class MyAction extends Mebo.Action{
   constructor(){
     super();

     // change 'name' for the registration name of the handler you
     // want to define the read options
     this.setMeta('handler.name.readOptions', {
       someReadOption: true
     });
   }

   async _perform(data){
     // ...
   }

   async _after(err, value){

     // change 'name' for the registration name of the handler you
     // want to define the write options
     if (!err){
       // defining the write option inside of the _after to keep _perform as
       // abstract as possible. Since, _after is always called (even during
       // an error) after the execution of the action, it provides a way to
       // hook and define custom metadata related with the result.
       this.setMeta('handler.name.writeOptions', {
           someWriteOption: 10,
       });
     }
   }
}

Defining options directly through the handler:

// read options
myHandler.runAction('myAction', {
 someReadOption: true,
})

// write options
myHandler.output(value, {
 someWriteOption: 10,
})

Handlers are created by their registration name (Handler.register), the creation is done by Handler.create:

// creating a handle based on the handler registration name
const handler = Mebo.Handler.create('myHandler');

// loading the parsed information to the action
handler.runAction('actionName').then((result) => {

   // success output
   handler.output(result);

// error output
}).catch((err) => {
   handler.output(err);
});

Tip: You can set the env variable NODE_ENV=development to get the traceback information included in the error output.

Tip: In case you want to know the name of the handler from inside of the action you can retrieved this information from the session session().get('handler') (Action.session).

Static Method Summary

Static Public Methods
public static

Removes all listeners connected to the signal emitted through Handler.onErrorDuringOutput.
public static

create(handlerName: string, mask: string, args: ...args): Handler

Creates a handler based on the registered name
public static

get(handlerName: string, handlerMask: string): Handler

Returns the registered handler
public static

grantAction(handlerName: string, actionName: string, args: ...args)

Grants the execution of the action through the handler
public static

Returns a list granted actions for the input handler
public static

Adds a listener to an exception raised during the Handler.output process.
public static

register(handlerClass: Handler, handlerName: string, handlerMask: string)

Register an Handler type to the available handlers
public static

registerReader(readerClass: Reader, handlerName: string, handlerMask: string)

Register a Reader for the handler
public static

registerWriter(writerClass: Writer, handlerName: string, handlerMask: string)

Register a Writer for the handler
public static

registeredHandler(handlerName: string, handlerMask: string): Handler

Returns the registered handler
public static

Returns a list of registered handler makers for the input handler name
public static

Returns a list containing the names of the registered handler types
public static

registeredReader(handlerName: string, handlerMask: string): Reader

Returns the reader registered for the handler
public static

registeredWriter(handlerName: string, handlerMask: string): Writer

Returns the writer registered for the handler
Static Protected Methods
protected static

_grantingAction(handlerName: string, actionName: string, args: ...args)

This method can be re-implemented by derived classes to hook when an Action is granted for a handler (Handler.grantAction)

Constructor Summary

Public Constructor
public

Creates a Handler

Method Summary

Public Methods
public

meta(path: string, defaultValue: *): *

Returns a value under the handler's metadata.
public

output(value: *, options: Object, finalizeSession: boolean)

Results a value through the handler.
public

async runAction(actionName: string, options: Object): *

Executes an action through the handler.
public

Returns the session
public

setMeta(path: string, value: *, merge: boolean)

Sets a value to the handler's metadata.

Detailed information about the metadata support can be found at Metadata.
public

setSession(session: Session)

Associates a Session with the handler.
Protected Methods
protected

_createReader(action: Action, options: Object, additionalArgs: ...additionalArgs): Reader

Creates an instance of a reader for the current handler
protected

_createWriter(value: *, options: Object, additionalArgs: ...additionalArgs): Writer

Creates an instance of a writer for the current handler

Static Public Methods

public static clearErrorDuringOutput() source

Removes all listeners connected to the signal emitted through Handler.onErrorDuringOutput.

public static create(handlerName: string, mask: string, args: ...args): Handler source

Creates a handler based on the registered name

Alternatively this method can be called directly from Mebo as Mebo.Handler.create(...)

Also, the handler name gets included in the session as arbitrary data, it can be retrieved through 'handler'. This name follows the registration pattern where this value is represented in lowercase internally:

Session.get('handler');

Params:

NameTypeAttributeDescription
handlerName string

registered handler name
mask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler (it allows to have custom handler implementations for specific masks)
args ...args

custom args passed to the constructor during factoring

Return:

Handler

public static get(handlerName: string, handlerMask: string): Handler source

Returns the registered handler

(it can be also done via Handler.registeredHandler).

Params:

NameTypeAttributeDescription
handlerName string

registered handler name
handlerMask string
  • optional

optional handler mask

Return:

Handler

public static grantAction(handlerName: string, actionName: string, args: ...args) source

Grants the execution of the action through the handler

Params:

NameTypeAttributeDescription
handlerName string

registered name of the handler
actionName string

registered action name
args ...args

custom args passed to Handler._grantingAction

public static grantedActionNames(handlerName: string): Array<string> source

Returns a list granted actions for the input handler

Params:

NameTypeAttributeDescription
handlerName string

registered handler name

Return:

Array<string>

public static onErrorDuringOutput(listener: function) source

Adds a listener to an exception raised during the Handler.output process. It can happen either during the serialization process (Writer.serialize) or during the finalization of the session (Session.finalize). This event passes as argument: error, handlerName and handlerMask.

Currently this event is static to make easy to hook it in your application, if none listener is registered to it then the error is thrown, a stack trace is printed, and the Node.js process exits.

// registering a listener for the error
Mebo.Handler.onErrorDuringOutput((err, handlerName, handlerMask => {
   console.error(err.stack);
}));

Params:

NameTypeAttributeDescription
listener function

listener function

public static register(handlerClass: Handler, handlerName: string, handlerMask: string) source

Register an Handler type to the available handlers

Params:

NameTypeAttributeDescription
handlerClass Handler

handler implementation that will be registered
handlerName string
  • optional

string containing the registration name for the handler. In case of an empty string, the registration is done by using the name of the type (this information is stored in lowercase)
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler (it allows to have custom handler implementations for specific masks)

public static registerReader(readerClass: Reader, handlerName: string, handlerMask: string) source

Register a Reader for the handler

Params:

NameTypeAttributeDescription
readerClass Reader

reader class
handlerName string

registered handler name
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler (it allows to have custom handler implementations for specific masks)

public static registerWriter(writerClass: Writer, handlerName: string, handlerMask: string) source

Register a Writer for the handler

Params:

NameTypeAttributeDescription
writerClass Writer

writer class
handlerName string

registered handler name
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler (it allows to have custom handler implementations for specific masks)

public static registeredHandler(handlerName: string, handlerMask: string): Handler source

Returns the registered handler

(it can be also done via Handler.get)

Params:

NameTypeAttributeDescription
handlerName string

name of the registered handler type
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler

Return:

Handler

public static registeredHandlerMasks(handlerName: string): Array<string> source

Returns a list of registered handler makers for the input handler name

Params:

NameTypeAttributeDescription
handlerName string

registered handler name

Return:

Array<string>

public static registeredHandlerNames(): Array<string> source

Returns a list containing the names of the registered handler types

Return:

Array<string>

public static registeredReader(handlerName: string, handlerMask: string): Reader source

Returns the reader registered for the handler

Params:

NameTypeAttributeDescription
handlerName string

name of the registered handler type
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler

Return:

Reader

public static registeredWriter(handlerName: string, handlerMask: string): Writer source

Returns the writer registered for the handler

Params:

NameTypeAttributeDescription
handlerName string

name of the registered handler type
handlerMask string
  • optional
  • default: '*'

optional mask that supports a glob syntax used to match a custom registered handler

Return:

Writer

Static Protected Methods

protected static _grantingAction(handlerName: string, actionName: string, args: ...args) source

This method can be re-implemented by derived classes to hook when an Action is granted for a handler (Handler.grantAction)

Params:

NameTypeAttributeDescription
handlerName string

registered handler name
actionName string

registered action name
args ...args

custom args passed during Handler.grantAction

Public Constructors

public constructor() source

Creates a Handler

Public Methods

public meta(path: string, defaultValue: *): * source

Returns a value under the handler's metadata.

Params:

NameTypeAttributeDescription
path string

path about where the value is localized (the levels must be separated by '.'). In case of an empty string it returns the entire metadata. The path can be defined using option vars (Metadata.optionVar).
defaultValue *
  • optional

default value returned in case a value was not found for the path

Return:

*

public output(value: *, options: Object, finalizeSession: boolean) source

Results a value through the handler.

In case the value is an exception then it's treated as Writer._errorOutput otherwise the value is treated as Writer._successOutput.

When an action is executed through the handler (Handler.runAction) it can define writing options that are used by the output. These options are stored under the Handler.metadata where any options passed directly to the output method override them.

If finalizeSession is enabled (default) the Handler.session gets finalized at the end of the output process.

By default the Writer._errorOutput tries to handle the error as output. However you can tell a writer to do not handle specific errors, by doing that the writer will raise the errors instead of trying to handle them. This can be achieved by having output defined as member of the error (error.output = false), further information can be found at the error output documentation (Writer._errorOutput).

In case of any error raised during the output process the handler emits the signal Handler.onErrorDuringOutput.

Params:

NameTypeAttributeDescription
value *

raw value that should be resulted by the handler
options Object
  • optional

plain object containing options that should be used by the output where each handler implementation contains their own set of options.
finalizeSession boolean
  • optional
  • default: true

tells if it should finalize the session (Session.finalize)

public async runAction(actionName: string, options: Object): * source

Executes an action through the handler.

This process is done by creating an action that loads the information parsed by the Reader.

After the construction of the action it looks for reading options that can be defined as part of the action's metadata (Action.metadata) and when found they are passed to the reader. After the execution of the action it looks again inside of the action's metadata for writing options, which are later used during the output (Handler.output). To know how to define action's metadata for the handler take a look at the initial documentation about the Handler.

Params:

NameTypeAttributeDescription
actionName string

registered action name that should be executed
options Object

plain object containing the options that is passed to the Reader. for the handler should be fetched.

Return:

*

result of the action

public session(): Session source

Returns the session

Return:

Session

public setMeta(path: string, value: *, merge: boolean) source

Sets a value to the handler's metadata.

Detailed information about the metadata support can be found at Metadata.

Params:

NameTypeAttributeDescription
path string

path about where the value should be stored under the metadata (the levels must be separated by '.'). The path can be defined using option vars (Metadata.optionVar).
value *

value that is going to be stored under the collection
merge boolean
  • optional
  • default: true

this option is used to decide in case of the last level is already existing under the collection, if the value should be either merged (default) or overridden.

public setSession(session: Session) source

Associates a Session with the handler. The session assigned to the handler is cloned during the assignment (Session.clone).

Params:

NameTypeAttributeDescription
session Session

session object

Protected Methods

protected _createReader(action: Action, options: Object, additionalArgs: ...additionalArgs): Reader source

Creates an instance of a reader for the current handler

Params:

NameTypeAttributeDescription
action Action

action instance used by the reader to parse the values
options Object

plain object containing the options passed to the reader
additionalArgs ...additionalArgs

additional args passed to the constructor during factoring of the reader (should be used by derived classes)

Return:

Reader

protected _createWriter(value: *, options: Object, additionalArgs: ...additionalArgs): Writer source

Creates an instance of a writer for the current handler

Params:

NameTypeAttributeDescription
value *

arbitrary value passed to the writer
options Object

plain object containing the options passed to the writer
additionalArgs ...additionalArgs

additional args passed to the constructor during factoring of the reader (should be used by derived classes)

Return:

Writer