futoin-asyncsteps

v2.5.4

Published

2 years ago

Mimic traditional threads in single threaded event loop

Downloads

207

0High
0Medium
0Low

andvgal

futoin async steps parallel exceptions loops browser webpack synchronization mutex throttle

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

Modules

Classes

Members

Objects

Functions

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

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

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

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

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

FutoInErrors.UnknownInterface : string

Unknown interface requested.

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

FutoInErrors.NotSupportedVersion : string

Not supported interface version.

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

FutoInErrors.NotImplemented : string

In case interface function is not implemented on Executor side

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

FutoInErrors.Unauthorized : string

Security policy on Executor side does not allow to access interface or specific function.

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

FutoInErrors.InternalError : string

Unexpected internal error on Executor side, including internal CommError.

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

FutoInErrors.InvokerError : string

Unexpected internal error on Invoker side, not related to CommError.

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

FutoInErrors.InvalidRequest : string

Invalid data is passed as FutoIn request.

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

FutoInErrors.DefenseRejected : string

Defense system has triggered rejection

Kind: static constant of FutoInErrors
Note: Must be generated on Executor side, but also possible to be triggered on Invoker

FutoInErrors.PleaseReauth : string

Executor requests re-authorization

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

FutoInErrors.SecurityError : string

'sec' request section has invalid data or not SecureChannel

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

FutoInErrors.Timeout : string

Timeout occurred in any stage

Kind: static constant of FutoInErrors
Note: Must be used only internally and should never travel in request message

$as_test(func, [onerror]) ⇒ function

Mocha-compatible test case based on AsyncSteps.

Example:

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

Kind: global function
Returns: function - suitable for it() Mocha call

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

installAsyncToolTest([install])

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

Kind: global function

| Param | Type | Default | Description | | --- | --- | --- | --- | | [install] | boolean | true | true - install AsyncToolTest, false - AsyncTool as scheduler |

assertAS(as)

Ensure parameter is instance of AsyncSteps interfaces

Kind: global function

| Param | Type | Description | | --- | --- | --- | | as | any | paramter to check |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

About

Installation for Node.js

Browser installation

Examples

Simple steps

External event wait

Model steps (avoid closure creation overhead on repetitive execution)

Simple Async Loops

Browser example

Mutex example

Throttle example

Test case aid

async/await/Promise integration

API reference

Modules

Classes

Members

Objects

Functions

futoin-asyncsteps

futoin-asyncsteps

ISync

Limiter

new Limiter([options])

Mutex

new Mutex([max], [max_queue])

Throttle

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

AsyncTool

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

AsyncTool.cancelCall(handle)

AsyncTool.callImmediate(func) ⇒ Object

AsyncTool.cancelImmediate(handle)

AsyncToolTest

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

AsyncToolTest.callLater(handle)

AsyncToolTest.nextEvent()

AsyncToolTest.hasEvents() ⇒ boolean

AsyncToolTest.getEvents() ⇒ array

AsyncToolTest.resetEvents()

AsyncToolTest.run()

$as

$as

FutoInError

AsyncSteps

asyncSteps.state ⇒ object

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

asyncSteps.parallel([onerror]) ⇒ AsyncSteps

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

asyncSteps.error(name, [error_info])

asyncSteps.copyFrom(other) ⇒ AsyncSteps

asyncSteps.cancel() ⇒ AsyncSteps

asyncSteps.execute() ⇒ AsyncSteps

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

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

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

asyncSteps.successStep() ⇒ AsyncSteps

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

asyncSteps.promise() ⇒ Promise

asyncSteps.newInstance() ⇒ AsyncSteps

asyncSteps.success([..._arg])

asyncSteps.setTimeout(timeout_ms) ⇒ AsyncSteps

asyncSteps.setCancel(oncancel) ⇒ AsyncSteps

asyncSteps.waitExternal() ⇒ AsyncSteps

asyncSteps.break([label])

asyncSteps.continue([label])

$as

$as

FutoInError

AsyncSteps

asyncSteps.state ⇒ object

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

asyncSteps.parallel([onerror]) ⇒ AsyncSteps

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

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