FutoIn AsyncSteps

2.5.6 verified Fri May 01 auth: no javascript

FutoIn AsyncSteps mimics traditional threads of execution in a single-threaded event loop, supporting cancellation, exit handlers, thread-local storage, and synchronization primitives like mutexes and throttles. Current stable version is 2.5.6, released under a stable maturity (status 3). It builds on the FTN12: FutoIn Async API v1.13 specification. Key differentiators include explicit step-based control flow (add, parallel, error handling) rather than Promises or async/await, though it integrates with Promises via as.await(). It is designed for both Node.js (>=8) and browser environments, providing ES5 CJS modules under es5/ and pre-built webpack dists under dist/. Synchronization primitives like Mutex are available for coordinated concurrent execution.

Common errors

error TypeError: $as is not a function ↓

cause Imported default incorrectly (e.g., import { $as } instead of import $as).

fix

Use import $as from 'futoin-asyncsteps' or const $as = require('futoin-asyncsteps').

error Cannot find module 'futoin-asyncsteps' ↓

cause Package not installed or wrong path in require/import.

fix

Run npm install futoin-asyncsteps and ensure import path is correct.

error as.success is not a function ↓

cause Calling as.success outside of a step callback (e.g., in the root scope or after step ends).

fix

Only call as.success() inside a step function passed to add(), parallel().add(), etc.

Warnings

gotcha Calling as.success() more than once or after as.error() in a step causes undefined behavior. ↓

fix Ensure exactly one call to as.success() or as.error() per step (or none for implicit success).

gotcha Synchronization primitives (Mutex, Throttle) require WeakMap polyfill in older browsers. ↓

fix Include dist/polyfill-asyncsteps.js before using Sync primitives in legacy browsers.

gotcha The as.state object is shared among all steps in the same AsyncSteps instance; mutations persist across steps. ↓

fix Use as.state for cross-step data, but be aware of unintended sharing when passing AsyncSteps instances or creating nested scopes.

gotcha Using as.await() with a rejected Promise will trigger error handling in the AsyncSteps flow, not throw an unhandled rejection. ↓

fix Ensure error handling steps are added after as.await() to catch rejections.

gotcha Parallel step results are not automatically merged; you must store results in as.state manually inside each parallel branch. ↓

fix Assign to as.state inside each parallel add() callback to collect outputs.

Install

npm install futoin-asyncsteps

yarn add futoin-asyncsteps

pnpm add futoin-asyncsteps

Imports

$as
wrong
```
const $as = require('futoin-asyncsteps').default
```
correct
```
import $as from 'futoin-asyncsteps'
```
Default export is a factory function returning AsyncSteps instance. In CommonJS, use require('futoin-asyncsteps') directly.
AsyncSteps
wrong
```
import AsyncSteps from 'futoin-asyncsteps'
```
correct
```
import { AsyncSteps } from 'futoin-asyncsteps'
```
AsyncSteps is a named export, not default. In CommonJS: const { AsyncSteps } = require('futoin-asyncsteps').

Mutex

wrong

const Mutex = require('futoin-asyncsteps').Mutex

correct

import { Mutex } from 'futoin-asyncsteps'

Mutex is a named export. In browser, it may require WeakMap polyfill.

$as (browser)

wrong

import $as from 'futoin-asyncsteps' in non-module script

correct

<script src='dist/futoin-asyncsteps.min.js'></script>... $as(...)

In browser, $as is a global; no import needed. Use script tag loading the dist.

Quickstart

Shows basic step execution chain with add() and success().

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

const root = $as();
root.add((as) => {
    console.log('Step 1');
    as.success('done');
}).add((as, result) => {
    console.log('Step 2 received:', result);
    as.success();
});
root.execute();