Class: Operation

(abstract) capsula.Operation()

Operation is capsule's public property. It is like a method (or function) and much more. It can be used either by calling it (just like a method) or by calling methods on it (to exploit its additional features). For example, if o is an operation it is meant to be called like this: o(optional_arguments). But it can also be used as an object to call methods on it, for example o.getName(). By default, calling an operation does nothing, but this can be changed by "wiring" (connecting) operation to other operations or methods that do something. Wiring operation to other operations or methods actually specifies propagation of operation (method) calls. The result of calling an operation is a combined result of all operations and methods downstream.

Operation can either be input or output. Input operation serves as a propagator of calls from the outside towards the inside of the capsule the operation is property of. Output operation does the opposite, it serves as a propagator of calls from the inside towards the outside of its capsule.

Constructor

(abstract) new Operation()

Since:
  • 0.1.0
Source:

Methods

disclose(opt_nameopt) → {module:capsula.Input|module:capsula.Output}

Creates a new operation of the same type (input or output) as this operation for the capsule that represents the current context of execution (with the given name, if provided). Then, wires that newly created operation to this operation. Returns the newly created operation.

In other words, it discloses (publishes) this operation to the interface of the capsule that represents the current context of execution.

Assumes this operation belongs to a part capsule of the capsule that represents the current context of execution. Otherwise it throws error.

Parameters:
Name Type Attributes Description
opt_name string <optional>
 the name of the operation to create
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT, FORBIDDEN_NAME
Type
Error
Returns:
the newly created operation
Type
module:capsula.Input | module:capsula.Output

getFilter() → {function|Array.<Object>|module:capsula.STOP}

Returns the filter associated with this operation, if it exists; or null otherwise. The filter can be one of the following: a filter function, an array of objects, or the STOP constant.
Since:
  • 0.1.0
Source:
See:
Returns:
the filter associated with this operation, or null if there is no such a filter
Type
function | Array.<Object> | module:capsula.STOP

getFQName(opt_sepopt) → {string}

Returns the fully qualified name of this operation, using the given separator if provided (if not, the :: is used by default).

The fully qualified name comprises the name of this operation, the name of the owner capsule of this operation, the name of its owner, and so on all the way up the capsule hierarchy.

Parameters:
Name Type Attributes Description
opt_sep string <optional>
 the separator to use to separate names in the returned fully qualified name
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
the fully qualified name of this operation
Type
string

getId() → {number}

Returns the id of this operation.
Since:
  • 0.1.0
Source:
Returns:
the id of this operation
Type
number

getLastArguments() → {Array.<Object>}

Returns the arguments of the last call to this operation. By default arguments are returned as they were after filtering; unless opt_beforeFiltering is true, in which case the arguments are returned as they were before filtering is applied. For more information on filtering see operation's documentation).
Since:
  • 0.1.0
Source:
Returns:
the arguments of the last call to this operation
Type
Array.<Object>

getName() → {string}

Returns the name of this operation.
Since:
  • 0.1.0
Source:
Returns:
the name of this operation
Type
string

getOwner() → {module:capsula.Capsule}

Returns the owner capsule of this operation.
Since:
  • 0.1.0
Source:
Returns:
the owner capsule of this operation
Type
module:capsula.Capsule

getSources() → {Array.<module:capsula.Operation>}

Returns an array of operations (sources) this operation is wired to acting as a target in the current context of execution; or an empty array if it is not wired to any operation (as a target).
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
an array of operations this operation is wired to acting as a target in the current context of execution; or an empty array
Type
Array.<module:capsula.Operation>

getTargets() → {Array.<(module:capsula.Operation|function())>}

Returns an array of operations and functions (targets) this operation is wired to acting as a source in the current context of execution; or an empty array if it is not wired to any operation (as a source).
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
an array of operations and functions this operation is wired to acting as a source in the current context of execution; or an empty array
Type
Array.<(module:capsula.Operation|function())>

getWires() → {Array.<(module:capsula.Operation|function())>}

Returns an array of operations and functions this operation is wired to in the current context of execution; or an empty array if it is not wired to any.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
an array of operations and functions this operation is wired to in the current context of execution; or an empty array
Type
Array.<(module:capsula.Operation|function())>

isEnabled() → {boolean}

Returns whether this operation is enabled or not. If disabled, this operation simply does not work, i.e. returns undefined.
Since:
  • 0.1.0
Source:
Returns:
whether this operation is enabled (working) or not
Type
boolean

isInput() → {boolean}

Returns whether this operation is input or not.
Since:
  • 0.1.0
Source:
Returns:
whether this operation is input or not
Type
boolean

isOutput() → {boolean}

Returns whether this operation is output or not.
Since:
  • 0.1.0
Source:
Returns:
whether this operation is output or not
Type
boolean

isPublic() → {boolean}

Returns whether this operation belongs to the capsule which represents the current context of execution.

In other words, returns whether this.getOwner() === "current context of execution".

Since:
  • 0.1.0
Source:
Returns:
whether this operation belongs to the capsule which represents the current context of execution
Type
boolean

isSourceOf(…var_args) → {boolean}

Checks whether this operation acting as a source in the current context of execution is wired to all the given operations and functions (targets). The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to check (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
whether this source operation is wired to all the given operations and functions (in the current context of execution)
Type
boolean

isTargetOf(…var_args) → {boolean}

Checks whether this operation acting as a target in the current context of execution is wired to all the given operations (sources). The function accepts both comma separated list of operations and an array of operations.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation <repeatable>
 operations to check (an array of operations also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
whether this target operation is wired to all the given operations (in the current context of execution)
Type
boolean

isUnpackResult() → {boolean}

Returns whether the unpacking (from array) of a single operation result is turned on (default) or not.

Since operation call may return multiple results (if it propagates to more than one function), in general the results are returned in an array. However, when there is only one result, it makes sense to unpack it from the array, which is the default behavior.

Since:
  • 0.1.0
Source:
Returns:
whether the unpacking (from array) of a single operation result is turned on (default) or not
Type
boolean

isWiredTo(…var_args) → {boolean}

Checks whether this operation is wired to all the given operations and functions in the current context of execution. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to check (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error
Returns:
whether this operation is wired to all the given operations and functions (in the current context of execution)
Type
boolean

resource(…var_args)

First, unwires this operation acting as a target in the current context of execution from all the operations (sources) it is wired to and then wires this operation to the given operations (sources). The function accepts both comma separated list of operations and an array of operations.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation <repeatable>
 operations to resource this target operation to (an array of operations also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

retarget(…var_args)

First, unwires this operation acting as a source in the current context of execution from all the operations and functions (targets) it is wired to and then wires this operation to the given operations and functions (targets). The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 target operations and functions to resource this source operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

rewire(…var_args)

First, unwires this operation from all the operations and functions it is wired to in the current context of execution and then wires this operation to the given operations and functions in the current context of execution. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to rewire this operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

(async) send(…var_args) → {Promise}

Calls this operation in an asynchronous way. Returns control immediately. Returns Promise.
Parameters:
Name Type Attributes Description
var_args Object <repeatable>
 operation arguments, as if it was called in a synchronous way
Since:
  • 0.1.0
Source:
Returns:
the promise object
Type
Promise

setEnabled(enabled)

Enables or disables this operation. If disabled, this operation simply does not work, i.e. returns undefined. Each operation is enabled by default.
Parameters:
Name Type Description
enabled boolean true to enable this operation, false to disable it
Since:
  • 0.1.0
Source:

setFilter(…var_args)

Associates the given filter with this operation. The filter can be one of the following: a filter function, a comma-separated list of objects, the STOP constant, or null.
Parameters:
Name Type Attributes Description
var_args Object <repeatable>
 the filter to associate with this operation. The filter can be one of the following: a filter function, a comma-separated list of objects, the STOP constant, or null.
Since:
  • 0.1.0
Source:
See:
Example

Examples of using filters

myCapsule.myOperation.setFilter(capsula.STOP); // stops propagation (execution) of calls to myCapsule.myOperation()

myCapsule.myOperation.setFilter('Hello', 'world', 'of', 'filters'); // each call to myCapsule.myOperation() would have these 4 arguments, regardless of the actual arguments

myCapsule.myOperation.setFilter(function(){
    return []; // each call to myCapsule.myOperation() would have arguments as returned here, regardless of the actual arguments
});

myCapsule.myOperation.setFilter(null); // removes the fiter from this operation

setName(name)

Sets a new name to this operation. New name can later be used to obtain a reference to this operation from its owner capsule using getOperation.
Parameters:
Name Type Description
name string a new name of this operation
Since:
  • 0.1.0
Source:

setUnpackResult(unpack)

Sets whether to turn on the unpacking (from array) of a single operation result or not.

Since operation call may return multiple results (if it propagates to more than one method), in general the results are returned in an array. However, when there is only one result, it makes sense to unpack it from the array, which is the default behavior.

This method sets the behavior of this operation in terms of unpacking of single operation result.

Parameters:
Name Type Description
unpack boolean whether to turn on the unpacking (from array) of a single operation result or not
Since:
  • 0.1.0
Source:
Example

Examples of packing and unpacking operation results

var result = myCapsule.myOperation(); // result is "Hello world!"

myCapsule.myOperation.setUnpackResult(false); // no unpacking

result = myCapsule.myOperation(); // result is ["Hello world!"]

source(…var_args)

Wires this operation acting as a target in the current context of execution to the given operations (sources). The function accepts both comma separated list of operations and an array of operations.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation <repeatable>
 operations to wire this target operation to (an array of operations also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

target(…var_args)

Wires this operation acting as a source in the current context of execution to the given operations and functions (targets). The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to wire this source operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

targetAt(at, …var_args)

Wires this operation acting as a source in the current context of execution to the given operations and functions (targets) according to the given at index. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
at number the index to use when wiring this source operation to the given target operations and functions
var_args module:capsula.Operation | function <repeatable>
 operations and functions to wire this source operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT, INDEX_OUT_OF_BOUNDS
Type
Error

unsource(…var_args)

Unwires this operation acting as a target in the current context of execution from the given operations (sources). The function accepts both comma separated list of operations and an array of operations.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation <repeatable>
 operations to unwire this target operation from (an array of operations also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

unsourceAll()

Unwires this operation acting as a target in the current context of execution from all the operations (sources) it is wired to.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

untarget(…var_args)

Unwires this operation acting as a source in the current context of execution from the given operations and functions (targets). The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 target operations and function to unwire this source operation from (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

untargetAll()

Unwires this operation acting as a source in the current context of execution from all the operations and functions (targets) it is wired to.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

unwire(…var_args)

Unwires this operation from the given operations and functions in the current context of execution. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to unwire this operation from (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

unwireAll()

Unwires this operation from all the operations and functions it is wired to in the current context of execution.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

wire(…var_args)

Wires this operation to the given operations and functions in the current context of execution. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
var_args module:capsula.Operation | function <repeatable>
 operations and functions to wire this operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT
Type
Error

wireAt(at, …var_args)

Wires this operation to the given operations and functions according to the given at index and the current context of execution. The function accepts both comma separated list of operations and functions and an array of operations and functions.
Parameters:
Name Type Attributes Description
at number the index to use when tying this operation to the given operations and functions
var_args module:capsula.Operation | function <repeatable>
 operations and functions to wire this operation to (an array of operations and functions also accepted)
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, OUT_OF_CONTEXT, INDEX_OUT_OF_BOUNDS
Type
Error