README

Stability: 3 - Stable

About

FutoIn AsyncSteps mimics traditional threads of execution in single threaded event loop. It supports all features including cancellation, exit handlers, thread local storage and synchronization primitives.

Additionally, it supports async/Promise integration as step through as.await() API.

Documentation --> FutoIn Guide

Reference implementation of:

FTN12: FutoIn Async API
Version: 1.13

Spec: FTN12: FutoIn Async API v1.x

Author: Andrey Galkin

Installation for Node.js

Command line:

$ npm install futoin-asyncsteps --save

$ yarn add futoin-asyncsteps

Hint: checkout FutoIn CID for all tools setup.

Browser installation

Pre-built ES5 CJS modules are available under es5/. These modules can be used with webpack without transpiler - default "browser" entry point points to ES5 version.

Webpack dists are also available under dist/ folder, but their usage should be limited to sites without build process. There are "full", "lite" and "development" version builds.

Warning: older browsers should use dist/polyfill-asyncsteps.js for WeakMap polyfill used in synchronization primitives.

The following globals are available:

$as - global reference to futoin-asyncsteps module
futoin - global namespace-like object for name clashing cases
futoin.$as - another reference to futoin-asyncsteps module
FutoInError - global reference to standard FutoIn error codes object
futoin.AsyncSteps - global reference to futoin-asyncsteps.AsyncSteps class

Examples

Simple steps

const $as = require('futoin-asyncsteps');

const root_as = $as();

root_as.add( ( as ) => {
    as.success( "MyValue" );
    // as.success() is implicit, if not called
} ).add(
    ( as, arg ) => {
        if ( arg === 'MyValue' ) {
            as.add( ( as ) => {
                as.error( 'MyError', 'Something bad has happened' );
            });
        }
    },
    ( as, err ) => {
        if ( err === 'MyError' ) {
            as.success( 'NotSoBad' );
            // as.add() acts as implicit as.success()
        }
    }
);

root_as.add( ( as, arg ) => {
    if ( arg === 'NotSoBad' ) {
        console.log( 'MyError was ignored: ' + as.state.error_info );
    }
    
    as.state.p1arg = 'abc';
    as.state.p2arg = 'xyz';
    
    const p = as.parallel();
    
    p.add( ( as ) => {
        console.log( 'Parallel Step 1' );
        
        as.add( ( as ) => {
            console.log( 'Parallel Step 1.1' );
            as.state.p1 = as.state.p1arg + '1';
        } );
    } );
    p.add( ( as ) =>{
        console.log( 'Parallel Step 2' );
        
        as.add( ( as ) => {
            console.log( 'Parallel Step 2.1' );
            as.state.p2 = as.state.p2arg + '2';
        } );
    } );
} ).add( ( as ) => {
    console.log( 'Parallel 1 result: ' + as.state.p1 );
    console.log( 'Parallel 2 result: ' + as.state.p2 );
} );
            
root_as.execute();

Result:

MyError was ignored: Something bad has happened
Parallel Step 1
Parallel Step 2
Parallel Step 1.1
Parallel Step 2.1
Parallel 1 result: abc1
Parallel 2 result: xyz2

External event wait

var async_steps = require('futoin-asyncsteps');


function dummy_service_read( success, error ){
    // We expect it calles success when data is available
    // and error, if error occurs
    // Returns some request handle
}

function dummy_service_cancel( reqhandle ){
    // We assume it cancels previously scheduled reqhandle
}

var root_as = async_steps();

root_as.add( function( as ){
    setImmediate( function(){
        as.success( 'async success()' );
    } );
    
    as.setTimeout( 10 ); // ms
} ).add(
    function( as, arg ){
        console.log( arg );
        
        var reqhandle = dummy_service_read(
            function( data ){
                as.success( data );
            },
            function( err ){
                if ( err !== 'SomeSpecificCancelCode' )
                {
                    as.error( err );
                }
            }
        );
        
        as.setCancel(function(as){
            dummy_service_cancel( reqhandle );
        });
        
        // OPTIONAL. Set timeout of 1s
        as.setTimeout( 1000 );
    },
    function( as, err )
    {
        console.log( err + ": " + as.state.error_info );
    }
);

root_as.execute();

Result:

async success()
Timeout:

Model steps (avoid closure creation overhead on repetitive execution)

var async_steps = require('futoin-asyncsteps');


var model_as = async_steps();
model_as.state.var = 'Vanilla';

model_as.add( function(as){
    console.log('-----');
    console.log( 'Hi! I am from model_as' );
    console.log( 'State.var: ' + as.state.var );
    as.state.var = 'Dirty';
});

for ( var i = 0; i < 3; ++i )
{
    var root_as = async_steps();
    root_as.copyFrom( model_as );
    root_as.add( function(as){
        as.add(function( as ){
            console.log('>> The first inner step');
        });
        as.copyFrom( model_as );
    });
    root_as.execute();
}

Result. Please note the order as only the first step is executed in the loop. The rest is executed quasi-parallel by nature of async programming. The model_as closure gets executed 6 times, but created only once.

-----
Hi! I am from model_as
State.var: Vanilla
-----
Hi! I am from model_as
State.var: Vanilla
-----
Hi! I am from model_as
State.var: Vanilla
>> The first inner step
>> The first inner step
>> The first inner step
-----
Hi! I am from model_as
State.var: Dirty
-----
Hi! I am from model_as
State.var: Dirty
-----
Hi! I am from model_as
State.var: Dirty

Simple Async Loops

var async_steps = require('futoin-asyncsteps');

var root_as = async_steps();

root_as.add(
    function( as ){
        as.repeat( 3, function( as, i ) {
            console.log( "> Repeat: " + i );
        } );
        
        as.forEach( [ 1, 2, 3 ], function( as, k, v ) {
            console.log( "> forEach: " + k + " = " + v );
        } );
        
        as.forEach( { a: 1, b: 2, c: 3 }, function( as, k, v ) {
            console.log( "> forEach: " + k + " = " + v );
        } );
    }
);

root_as.execute();

Result:

> Repeat: 0
> Repeat: 1
> Repeat: 2
> forEach: 0 = 1
> forEach: 1 = 2
> forEach: 2 = 3
> forEach: a = 1
> forEach: b = 2
> forEach: c = 3

Browser example

<script src="../dist/futoin-asyncsteps.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
$as()
.add(function(as){
    console.log( 'Step1' );
})
.add(function(as){
    console.log( 'Step2' );
})
.execute();
</script>

Result:

Step1
Step2

Mutex example

'use strict';

const $as = require('futoin-asyncsteps');
// Note: Mutex requires ES6 and is not provided as member of $as
const Mutex = require( 'futoin-asyncsteps/Mutex' );

const mtx = new Mutex();
let curr_concurrency = 0;

for ( let i = 0; i < 3; ++i )
{
    $as()
        .sync(mtx, (as) => {
            // regular AsyncSteps in critical section
            ++curr_concurrency;
            
            as.add((as) => {
                as.success(curr_concurrency--);
            });
        })
        .add((as, val) => {
            console.log(`Max concurrency ${i}: ${val}`);
        })
        .execute();
}

// Max concurrency 0: 1
// Max concurrency 1: 1
// Max concurrency 2: 1

Throttle example

const thrtl = new Throttle(10, 100);
const as = $as();
const p = as.parallel();
let passed = 0;

for ( let i = 0; i < 100; ++i ) {
    p.add((as) => {
        as.sync(thrtl, (as) => { passed += 1 });
    });
}

as.execute();

setTimeout(() => {
    expect(passed).to.equal(50);
}, 450);

Test case aid

// NOTE: it's not exposed through main entry point
$as_test = require( 'futoin-asyncsteps/testcase' );

// Positive test example
it( 'should ...', $as_test(
    ( as ) => {
        // some test logic
    }
) );

// Negative test example
it( 'should ...', $as_test(
    ( as ) => {
        // some test logic
        // Forced as.error('NegativeTestMustThrow') step in the end
    },
    ( as, err ) => {
        if ( err === 'ExpectedError' ) {
            as.success();
        }
    }
) );

// Access "this" provided by Mocha
it( 'should ...', $as_test(
    function( as ) {
        // note use a full function instead of a light arrow function
        this.timeout( 1e3 );
    }
) );

`async`/`await`/`Promise` integration

const func = async () => {
    // AsyncSteps can be used as Promise
    await $as().add( (as) => {} ).promise();
};

// AsyncSteps can await Promise
$as.await(func);

API reference

Classes

ISync: Base interface for synchronization primitives
Limiter: Limiter - complex processing limit for AsyncSteps
Mutex: Mutual exclusion mechanism for AsyncSteps
Throttle: Throttling for AsyncSteps

Members

AsyncTool: Neutral interface to event scheduler
AsyncToolTest: Special event scheduler for testing to be installed with installAsyncToolTest()
$as: window.$as - browser-only reference to futoin-asyncsteps module
$as: window.FutoIn.$as - browser-only reference to futoin-asyncsteps module
FutoInError: window.FutoInError - browser-only reference to futoin-asyncsteps.FutoInError
AsyncSteps: window.futoin.AsyncSteps - browser-only reference to futoin-asyncsteps.AsyncSteps
$as: window.$as - browser-only reference to futoin-asyncsteps module
$as: window.FutoIn.$as - browser-only reference to futoin-asyncsteps module
FutoInError: window.FutoInError - browser-only reference to futoin-asyncsteps.FutoInError
AsyncSteps: window.futoin.AsyncSteps - browser-only reference to futoin-asyncsteps.AsyncSteps

Objects

FutoInErrors : object: List of standard FutoIn Core errors. It may static get extended in runtime.

Functions

$as_test(func, [onerror]) ⇒ function

Mocha-compatible test case based on AsyncSteps.

Example:

it('should ...', $as_test( (as) => {}, (as, err) => {} );

installAsyncToolTest([install])

Use for unit testing to fine control step execution. It installs AsyncToolTest in place of AsyncTool

assertAS(as)

Ensure parameter is instance of AsyncSteps interfaces

futoin-asyncsteps

ISync

Base interface for synchronization primitives

Kind: global class

Limiter

Limiter - complex processing limit for AsyncSteps

Kind: global class

new Limiter([options])

C-tor

Param	Type	Default	Description
[options]	`object`	`{}`	option map
[options.concurrent]	`integer`	`1`	maximum concurrent flows
[options.max_queue]	`integer`	`0`	maximum queued
[options.rate]	`integer`	`1`	maximum entries in period
[options.period_ms]	`integer`	`1000`	period length
[options.burst]	`integer`	`0`	maximum queue for rate limiting

Mutex

Mutual exclusion mechanism for AsyncSteps

Kind: global class

new Mutex([max], [max_queue])

C-tor

Param	Type	Default	Description
[max]	`integer`	`1`	maximum number of simultaneous critical section entries
[max_queue]	`integer`		limit queue length, if set

Throttle

Throttling for AsyncSteps

Kind: global class

new Throttle([max], [period_ms], [max_queue])

C-tor

Param	Type	Default	Description
[max]	`integer`	`1`	maximum number of simultaneous critical section entries
[period_ms]	`intger`	`1000`	time period in milliseconds
[max_queue]	`integer`		limit queue length, if set

AsyncTool

Neutral interface to event scheduler

Kind: global variable

AsyncTool
- .callLater(func, [timeout_ms]) ⇒ Object
- .cancelCall(handle)
- .callImmediate(func) ⇒ Object
- .cancelImmediate(handle)

AsyncTool.callLater(func, [timeout_ms]) ⇒ `Object`

Wrapper for setTimeout()

Kind: static method of AsyncTool
Returns: Object - - timer handle

Param	Type	Default	Description
func	`function`		callback to execute
[timeout_ms]	`number`	`0`	optional timeout in ms

AsyncTool.cancelCall(handle)

Wrapper for clearTimeout()/clearImmediate()

Kind: static method of AsyncTool

Param	Type	Description
handle	`Object`	Handle returned from AsyncTool.callLater

AsyncTool.callImmediate(func) ⇒ `Object`

Wrapper for setImmediate()

Kind: static method of AsyncTool
Returns: Object - - timer handle

Param	Type	Description
func	`function`	callback to execute

AsyncTool.cancelImmediate(handle)

Wrapper for clearImmediate()

Kind: static method of AsyncTool

Param	Type	Description
handle	`Object`	Handle returned from AsyncTool.callImmediate

AsyncToolTest

Special event scheduler for testing to be installed with installAsyncToolTest()

Kind: global variable

AsyncToolTest
- .callLater(func, [timeout_ms]) ⇒ Object
- .callLater(handle)
- .nextEvent()
- .hasEvents() ⇒ boolean
- .getEvents() ⇒ array
- .resetEvents()
- .run()

AsyncToolTest.callLater(func, [timeout_ms]) ⇒ `Object`

Adds callback to internal queue

Kind: static method of AsyncToolTest
Returns: Object - timer handle

Param	Type	Default	Description
func	`function`		callback to execute
[timeout_ms]	`number`	`0`	optional timeout in ms

AsyncToolTest.callLater(handle)

Removed callback from internal queue

Kind: static method of AsyncToolTest

Param	Type	Description
handle	`Object`	Handle returned from AsyncToolTest.callLater

AsyncToolTest.nextEvent()

Process next even in the internal queue

Kind: static method of AsyncToolTest

AsyncToolTest.hasEvents() ⇒ `boolean`

Check if there are any events scheduled

Kind: static method of AsyncToolTest
Returns: boolean - true, if pending events

AsyncToolTest.getEvents() ⇒ `array`

Get internal even queue

Kind: static method of AsyncToolTest
Returns: array - event queue

AsyncToolTest.resetEvents()

Clear internal event queue

Kind: static method of AsyncToolTest

AsyncToolTest.run()

Execute all remaining events in the internal queue

Kind: static method of AsyncToolTest

$as

window.$as - browser-only reference to futoin-asyncsteps module

Kind: global variable

$as

window.FutoIn.$as - browser-only reference to futoin-asyncsteps module

Kind: global variable

FutoInError

window.FutoInError - browser-only reference to futoin-asyncsteps.FutoInError

Kind: global variable

AsyncSteps

window.futoin.AsyncSteps - browser-only reference to futoin-asyncsteps.AsyncSteps

Kind: global variable

AsyncSteps
- .state ⇒ object
- .add(func, [onerror]) ⇒ AsyncSteps
- .parallel([onerror]) ⇒ AsyncSteps
- .sync(object, func, [onerror]) ⇒ AsyncSteps
- .error(name, [error_info])
- .copyFrom(other) ⇒ AsyncSteps
- .cancel() ⇒ AsyncSteps
- .execute() ⇒ AsyncSteps
- .loop(func, [label]) ⇒ AsyncSteps
- .repeat(count, func, [label]) ⇒ AsyncSteps
- .forEach(map_or_list, func, [label]) ⇒ AsyncSteps
- .successStep() ⇒ AsyncSteps
- .await(promise, [onerror]) ⇒ AsyncSteps
- .promise() ⇒ Promise
- .newInstance() ⇒ AsyncSteps
- .success([..._arg])
- .setTimeout(timeout_ms) ⇒ AsyncSteps
- .setCancel(oncancel) ⇒ AsyncSteps
- .waitExternal() ⇒ AsyncSteps
- .break([label])
- .continue([label])

asyncSteps.state ⇒ `object`

Get AsyncSteps state object.

Note: There is a JS-specific improvement: as.state === as.state()

The are the following pre-defined state variables:

error_info - error description, if provided to as.error()
last_exception - the last exception caught
async_stack - array of references to executed step handlers in current stack

Kind: instance property of AsyncSteps

asyncSteps.add(func, [onerror]) ⇒ `AsyncSteps`

Add sub-step. Can be called multiple times.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
func	`ExecFunc`	function defining non-blocking step execution
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.parallel([onerror]) ⇒ `AsyncSteps`

Creates a step internally and returns specialized AsyncSteps interfaces all steps of which are executed in quasi-parallel.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - interface for parallel step adding

Param	Type	Description
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.sync(object, func, [onerror]) ⇒ `AsyncSteps`

Add sub-step with synchronization against supplied object.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
object	`ISync`	Mutex, Throttle or other type of synchronization implementation.
func	`ExecFunc`	function defining non-blocking step execution
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.error(name, [error_info])

Set error and throw to abort execution.

NOTE: If called outside of AsyncSteps stack (e.g. by external event), make sure you catch the exception

Kind: instance method of AsyncSteps
Throws:

Error

Param	Type	Description
name	`string`	error message, expected to be identifier "InternalError"
[error_info]	`string`	optional descriptive message assigned to as.state.error_info

asyncSteps.copyFrom(other) ⇒ `AsyncSteps`

Copy steps and not yet defined state variables from "model" AsyncSteps instance

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
other	`AsyncSteps`	model instance, which must get be executed

asyncSteps.cancel() ⇒ `AsyncSteps`

Use only on root AsyncSteps instance. Abort execution of AsyncSteps instance in progress.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

asyncSteps.execute() ⇒ `AsyncSteps`

Start execution of AsyncSteps using AsyncTool

It must not be called more than once until cancel/complete (instance can be re-used)

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

asyncSteps.loop(func, [label]) ⇒ `AsyncSteps`

Execute loop until as.break() or as.error() is called

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
func	`LoopFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.repeat(count, func, [label]) ⇒ `AsyncSteps`

Call func(as, i) for count times

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
count	`integer`	how many times to call the func
func	`RepeatFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.forEach(map_or_list, func, [label]) ⇒ `AsyncSteps`

For each map or list element call func( as, key, value )

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
map_or_list	`integer`	map or list to iterate over
func	`ForEachFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.successStep() ⇒ `AsyncSteps`

Shortcut for this.add( ( as ) => as.success( ...args ) )

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
[args...]	`any`	argument to pass, if any

asyncSteps.await(promise, [onerror]) ⇒ `AsyncSteps`

Integrate a promise as a step.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
promise	`Promise`	promise to add as a step
[onerror]	`function`	error handler to check

asyncSteps.promise() ⇒ `Promise`

Execute AsyncSteps with Promise interface

Kind: instance method of AsyncSteps
Returns: Promise - - promise wrapper for AsyncSteps

asyncSteps.newInstance() ⇒ `AsyncSteps`

Create a new instance of AsyncSteps for independent execution

Kind: instance method of AsyncSteps
Returns: AsyncSteps - new instance

asyncSteps.success([..._arg])

Successfully complete current step execution, optionally passing result variables to the next step.

Kind: instance method of AsyncSteps

Param	Type	Description
[..._arg]	`*`	unlimited number of result variables with no type constraint

asyncSteps.setTimeout(timeout_ms) ⇒ `AsyncSteps`

Set timeout for external event completion with async as.success() or as.error() call. If step is not finished until timeout is reached then Timeout error is raised.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

Param	Type	Description
timeout_ms	`number`	Timeout in ms

asyncSteps.setCancel(oncancel) ⇒ `AsyncSteps`

Set cancellation handler to properly handle timeouts and external cancellation.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

Param	Type	Description
oncancel	`CancelFunc`	cleanup/cancel logic of external processing

asyncSteps.waitExternal() ⇒ `AsyncSteps`

Mark currently executing step as waiting for external event.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

asyncSteps.break([label])

Break execution of current loop, throws exception

Kind: instance method of AsyncSteps

Param	Type	Description
[label]	`string`	Optional. unwind loops, until label named loop is exited

asyncSteps.continue([label])

Continue loop execution from the next iteration, throws exception

Kind: instance method of AsyncSteps

Param	Type	Description
[label]	`string`	Optional. unwind loops, until label named loop is found

$as

window.$as - browser-only reference to futoin-asyncsteps module

Kind: global variable

$as

window.FutoIn.$as - browser-only reference to futoin-asyncsteps module

Kind: global variable

FutoInError

window.FutoInError - browser-only reference to futoin-asyncsteps.FutoInError

Kind: global variable

AsyncSteps

window.futoin.AsyncSteps - browser-only reference to futoin-asyncsteps.AsyncSteps

Kind: global variable

AsyncSteps
- .state ⇒ object
- .add(func, [onerror]) ⇒ AsyncSteps
- .parallel([onerror]) ⇒ AsyncSteps
- .sync(object, func, [onerror]) ⇒ AsyncSteps
- .error(name, [error_info])
- .copyFrom(other) ⇒ AsyncSteps
- .cancel() ⇒ AsyncSteps
- .execute() ⇒ AsyncSteps
- .loop(func, [label]) ⇒ AsyncSteps
- .repeat(count, func, [label]) ⇒ AsyncSteps
- .forEach(map_or_list, func, [label]) ⇒ AsyncSteps
- .successStep() ⇒ AsyncSteps
- .await(promise, [onerror]) ⇒ AsyncSteps
- .promise() ⇒ Promise
- .newInstance() ⇒ AsyncSteps
- .success([..._arg])
- .setTimeout(timeout_ms) ⇒ AsyncSteps
- .setCancel(oncancel) ⇒ AsyncSteps
- .waitExternal() ⇒ AsyncSteps
- .break([label])
- .continue([label])

asyncSteps.state ⇒ `object`

Get AsyncSteps state object.

Note: There is a JS-specific improvement: as.state === as.state()

The are the following pre-defined state variables:

error_info - error description, if provided to as.error()
last_exception - the last exception caught
async_stack - array of references to executed step handlers in current stack

Kind: instance property of AsyncSteps

asyncSteps.add(func, [onerror]) ⇒ `AsyncSteps`

Add sub-step. Can be called multiple times.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
func	`ExecFunc`	function defining non-blocking step execution
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.parallel([onerror]) ⇒ `AsyncSteps`

Creates a step internally and returns specialized AsyncSteps interfaces all steps of which are executed in quasi-parallel.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - interface for parallel step adding

Param	Type	Description
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.sync(object, func, [onerror]) ⇒ `AsyncSteps`

Add sub-step with synchronization against supplied object.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
object	`ISync`	Mutex, Throttle or other type of synchronization implementation.
func	`ExecFunc`	function defining non-blocking step execution
[onerror]	`ErrorFunc`	Optional, provide error handler

asyncSteps.error(name, [error_info])

Set error and throw to abort execution.

NOTE: If called outside of AsyncSteps stack (e.g. by external event), make sure you catch the exception

Kind: instance method of AsyncSteps
Throws:

Error

Param	Type	Description
name	`string`	error message, expected to be identifier "InternalError"
[error_info]	`string`	optional descriptive message assigned to as.state.error_info

asyncSteps.copyFrom(other) ⇒ `AsyncSteps`

Copy steps and not yet defined state variables from "model" AsyncSteps instance

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
other	`AsyncSteps`	model instance, which must get be executed

asyncSteps.cancel() ⇒ `AsyncSteps`

Use only on root AsyncSteps instance. Abort execution of AsyncSteps instance in progress.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

asyncSteps.execute() ⇒ `AsyncSteps`

Start execution of AsyncSteps using AsyncTool

It must not be called more than once until cancel/complete (instance can be re-used)

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

asyncSteps.loop(func, [label]) ⇒ `AsyncSteps`

Execute loop until as.break() or as.error() is called

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
func	`LoopFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.repeat(count, func, [label]) ⇒ `AsyncSteps`

Call func(as, i) for count times

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
count	`integer`	how many times to call the func
func	`RepeatFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.forEach(map_or_list, func, [label]) ⇒ `AsyncSteps`

For each map or list element call func( as, key, value )

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
map_or_list	`integer`	map or list to iterate over
func	`ForEachFunc`	loop body
[label]	`string`	optional label to use for as.break() and as.continue() in inner loops

asyncSteps.successStep() ⇒ `AsyncSteps`

Shortcut for this.add( ( as ) => as.success( ...args ) )

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
[args...]	`any`	argument to pass, if any

asyncSteps.await(promise, [onerror]) ⇒ `AsyncSteps`

Integrate a promise as a step.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self

Param	Type	Description
promise	`Promise`	promise to add as a step
[onerror]	`function`	error handler to check

asyncSteps.promise() ⇒ `Promise`

Execute AsyncSteps with Promise interface

Kind: instance method of AsyncSteps
Returns: Promise - - promise wrapper for AsyncSteps

asyncSteps.newInstance() ⇒ `AsyncSteps`

Create a new instance of AsyncSteps for independent execution

Kind: instance method of AsyncSteps
Returns: AsyncSteps - new instance

asyncSteps.success([..._arg])

Successfully complete current step execution, optionally passing result variables to the next step.

Kind: instance method of AsyncSteps

Param	Type	Description
[..._arg]	`*`	unlimited number of result variables with no type constraint

asyncSteps.setTimeout(timeout_ms) ⇒ `AsyncSteps`

Set timeout for external event completion with async as.success() or as.error() call. If step is not finished until timeout is reached then Timeout error is raised.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

Param	Type	Description
timeout_ms	`number`	Timeout in ms

asyncSteps.setCancel(oncancel) ⇒ `AsyncSteps`

Set cancellation handler to properly handle timeouts and external cancellation.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

Param	Type	Description
oncancel	`CancelFunc`	cleanup/cancel logic of external processing

asyncSteps.waitExternal() ⇒ `AsyncSteps`

Mark currently executing step as waiting for external event.

Kind: instance method of AsyncSteps
Returns: AsyncSteps - self
Note: Can be used only within ExecFunc body.

asyncSteps.break([label])

Break execution of current loop, throws exception

Kind: instance method of AsyncSteps

Param	Type	Description
[label]	`string`	Optional. unwind loops, until label named loop is exited

asyncSteps.continue([label])

Continue loop execution from the next iteration, throws exception

Kind: instance method of AsyncSteps

Param	Type	Description
[label]	`string`	Optional. unwind loops, until label named loop is found

FutoInErrors : `object`

List of standard FutoIn Core errors. It may static get extended in runtime.

Kind: global namespace

FutoInErrors : object
- .ConnectError : string
- .CommError : string
- .UnknownInterface : string
- .NotSupportedVersion : string
- .NotImplemented : string
- .Unauthorized : string
- .InternalError : string
- .InvokerError : string
- .InvalidRequest : string
- .DefenseRejected : string
- .PleaseReauth : string
- .SecurityError : string
- .Timeout : string

FutoInErrors.ConnectError : `string`

Connection error before request is sent.

Kind: static constant of FutoInErrors
Note: Must be generated on Invoker side

FutoInErrors.CommError : `string`

Communication error at any stage after request is sent and before response is received.

Kind: static constant of FutoInErrors
Note: Must be generated on Invoker side