UIZE JavaScript Framework

MODULES Uize.Flo

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Flo module...

DEVELOPERS: Chris van Rensburg

1.1. Key Features

The Uize.Flo module offers a number of unique features that sets it apart from many other async libraries.

Supports Familiar Control Flow Constructs - Unlike most async libraries, Flo supports familiar control flow constructs, with the ability to break from loop flos and return from "function" flos. Flo also supports multi-stage (a)synchronous if and switch conditional flos.
Supports Mixed Synchronous and Asynchronous Execution - Unlike many async libraries that expect functions to be asynchronous (or even worse, force all synchronous execution to become asynchronous), Flo lets synchronous and asynchronous execution mix harmoniously, even allowing functions to dynamically be either synchronous or asynchronous, or to change between synchronous and asynchronous as an application evolves over time.
Has the Ability to Breathe - Flo implements an innovative feature that allows us to configure a threshold for how long execution should remain synchronous before taking a "breath" by introducing an asynchronous interruption.
Uses Regular Old Callbacks - Unlike many other async libraries, Flo does not use promises or deferreds - just plain old callbacks - sweet and simple.
Works on Client and Server - Flo works just as well in NodeJS as it does in a browser, so you can safely use it in code that might be executed on either side of the client-server divide.
No Compilation Required - You don't need to set up any code pre-compilation process on a server, or anything like that, in order to use Flo in parts of your code - just require it and use it.
Works in Older Browsers - Flo doesn't rely upon the features of newer versions of JavaScript, such as the yield statement, in order to work its magic. That means that your code using Flo can even run in IE7 (see A Note on Older Browsers).
Unifies Error Handling
A Small Module - The Uize.Flo module is relatively small for what it provides, at around 2K scrunched and gzipped.

1.2. A Note on Older Browsers

Because the Uize.Flo module provides methods for creating (a)synchronous control flow structures that are equivalent to JavaScript's built-in control flow structures, many of the methods are named after reserved words.

For example, the Flo equivalent of a for loop can be set up using the Uize.Flo.for method. This is not a problem in browsers that support ES5 (ECMAScript version 5) or later, but it will be a problem in some older browsers like IE8 and earlier. Because this restriction is going away, it was decided to not avoid this issue by coming up with different names for the methods (like some weird prefix character or uppercasing) but, instead, to rely on property name quoting for cases where older browser support is desired.

SAFE ONLY IN ES5 AND LATER

Uize.Flow.for (
  setupStatementFUNC,
  testStatementFUNC,
  advanceStatementFUNC,
  iterationStatementFUNC
);

SAFE FOR ALL

Uize.Flow ['for'] (
  setupStatementFUNC,
  testStatementFUNC,
  advanceStatementFUNC,
  iterationStatementFUNC
);

NOTES

If you're using Flo inside an environment like NodeJS, then this is not an issue that you need to worry about.
If you're writing your code in CoffeeScript, this issue is detected and the naked reserved word property names are automatically "clothed" in quotes for you when your code is compiled to JavaScript.

1.3. Examples

There are no dedicated showcase example pages for the Uize.Flo module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Flo module...

SEARCH

1.4. Implementation Info

The Uize.Flo module defines the Uize.Flo object under the Uize namespace.

1.4.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

abort | block | break | call | continue | do | for | forEach | forIn | function | if | next | ongoing | return | switch | throw | try | while

STATIC METHODS

Uize.Flo.abort | Uize.Flo.async | Uize.Flo.block | Uize.Flo.break | Uize.Flo.breathe | Uize.Flo.call | Uize.Flo.continue | Uize.Flo.declare | Uize.Flo.do | Uize.Flo.dualContextMethods | Uize.Flo.dualContextProperties | Uize.Flo.for | Uize.Flo.forEach | Uize.Flo.forIn | Uize.Flo.function | Uize.Flo.if | Uize.Flo.instanceMethods | Uize.Flo.instanceProperties | Uize.Flo.mixins | Uize.Flo.next | Uize.Flo.ongoing | Uize.Flo.staticMethods | Uize.Flo.staticProperties | Uize.Flo.subclass | Uize.Flo.switch | Uize.Flo.try | Uize.Flo.while

STATIC PROPERTIES

Uize.Flo.moduleName | Uize.Flo.pathToResources

1.4.2. Features Overridden in This Module

No features have been overridden in this module.

1.4.3. Features Inherited From Other Modules

This module has no inherited features.

1.4.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.4.5. Unit Tests

The Uize.Flo module is unit tested by the Uize.Test.Uize.Flo test module.

2. Instance Methods

see also the related if instance method

NOTES

2.1. abort

Aborts execution of the flo statements in the flo on which the method is called.

SYNTAX

floInstance.abort ();

EXAMPLE

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. block

Creates a parented block flo that will sequentially execute a set of statements, where any or all of the statements can be either synchronous or asynchronous.

SYNTAX

floInvokerFUNC = flo.block (
  statement0FUNC,
  statement1FUNC,
  ...,
  statementNFUNC
);

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. break

Breaks execution of the nearest loop up the flo chain.

SYNTAX

floInstance.break ();

EXAMPLE

flo.forIn (
  fs.dir,
  function (next) {
    if (next.flo.value) {
      next.flo.break ();
    }
  }
) (function () {console.log ('finished with asynchronous for')});

2.3.1. Must be Within a Loop or Switch Flo

If the break method is called on a flo and there is no breakable flo up the parent chain, then an error will be thrown.

A breakable flo is defined as either a loop flo (created by methods like do, for, forIn, and while) or a switch flow (created by the switch method).

EXAMPLE

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. call

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. continue

.

SYNTAX

flo.continue ();

NOTES

see also the related break instance method

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. do

Create a do...while loop flo

SYNTAX

floInvokerFUNC = flo.do (
  iterationStatementFUNC
  testStatementFUNC,
)

EXAMPLE

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. for

Creates a for flo, where any or all of the setup, test, advance, and iteration statements can be either synchronous or asynchronous.

SYNTAX

floInvokerFUNC = flo.for (
  setupStatementFUNC,
  testStatementFUNC,
  advanceStatementFUNC,
  iterationStatementFUNC
)

EXAMPLE

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. forEach

.

SYNTAX

floInvokerFUNC = flo.while (
  sourceGeneratorStatementFUNC,
  iterationStatementFUNC
)

NOTES

IMPLEMENTATION INFO

this feature was introduced in this module

2.9. forIn

SYNTAX

floInvokerFUNC = flo.forIn (
  sourceGeneratorStatementFUNC,
  iterationStatementFUNC
)

NOTES

IMPLEMENTATION INFO

this feature was introduced in this module

2.10. function

.

SYNTAX

floInvokerFUNC = flo.function (
  statement0FUNC,
  statement1FUNC,
  ...,
  statementNFUNC
);

NOTES

see also the related return instance method

IMPLEMENTATION INFO

this feature was introduced in this module

2.11. if

Creates an if flo, with support for an arbitrary number of optional elseif sections and an optional final else statement, and where any or all of the statements can be either synchronous or asynchronous.

DIFFERENT USAGES

Create a Simple if...then Flo

floInvokerFUNC = flo.if (
  testStatementFUNC,
  thenStatementFUNC
)

Create an if...then...else Flo

floInvokerFUNC = flo.if (
  testStatementFUNC,
  thenStatementFUNC,
  elseStatementFUNC
)

Create an if...then...elseif...then Flo

floInvokerFUNC = flo.if (
  testStatementFUNC,
  thenStatementFUNC,
  elseifTestStatementFUNC,
  elseifThenStatementFUNC
)

Create an if...then...elseif...then...else Flo

floInvokerFUNC = flo.if (
  testStatementFUNC,
  thenStatementFUNC,
  elseifTestStatementFUNC,
  elseifThenStatementFUNC,
  elseStatementFUNC
)

IMPLEMENTATION INFO

this feature was introduced in this module

2.12. next

Continues execution of the flo on which the method is called, optionally passing back a result value.

DIFFERENT USAGES

Advance to the Next Statement

flo.next ();

Advance to the Next Statement, Passing a Result Value

flo.next (resultANYTYPE);

IMPLEMENTATION INFO

this feature was introduced in this module

2.13. ongoing

Returns a flo invoker function for invoking a flo that executes the specified one or more statements in an ongoing loop.

SYNTAX

floInvokerFUNC = flo.ongoing (
  statement0FUNC,
  statement1FUNC,
  ...,
  statementNFUNC
)

2.13.1. Breaking an Ongoing Loop

Because an ongoing loop flo has no built-in terminating test step, it is your responsibility to break the loop. This can be done in one of two ways...

internal break - within any statement of the flo or any sub-flo, the break instance method can be called to break the execution of the ongoing loop
external break - provided that code external to the flo has a reference to the flo or one of its sub-flos, the break instance method can be called on such a reference in order to break execution of the ongoing loop

2.13.2. Beware of Synchronous Ongoing Loops

.

2.13.3. You May Want to Breathe

.

IMPLEMENTATION INFO

this feature was introduced in this module

2.14. return

Returns from the nearest function flo up the flo chain.

DIFFERENT USAGES

Return from a Function Flo

flo.return ()

2.14.1. Must be Within a Function Flo

If the return method is called on a flo and there is no function flo up the parent chain, then an error will be thrown.

EXAMPLE

IMPLEMENTATION INFO

this feature was introduced in this module

2.15. switch

Creates a switch flo, with support for an arbitrary number of case sections and an optional default statement, and and where any or all of the statements can be either synchronous or asynchronous.

SYNTAX

floInvokerFUNC = flo.switch (
  switchExpressionFUNC,

  case0ExpressionFUNC,
  case0StatementFUNC,

  case1ExpressionFUNC,
  case1StatementFUNC,

  ...

  caseNExpressionFUNC,
  caseNStatementFUNC,

  defaultStatementFUNC
)

2.15.1. Breaking from a Switch Flo

.

IMPLEMENTATION INFO

this feature was introduced in this module

2.16. throw

.

SYNTAX

flo.throw (errorSTRorOBJ);

NOTES

see also the related try instance method

IMPLEMENTATION INFO

this feature was introduced in this module

2.17. try

.

SYNTAX

floInvokerFUNC = flo.try (
  tryStatementFUNC,
  catchStatementFUNC
);

NOTES

see also the related throw instance method

IMPLEMENTATION INFO

this feature was introduced in this module

2.18. while

.

SYNTAX

floInvokerFUNC = flo.while (
  testStatementFUNC,
  iterationStatementFUNC
)

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Methods

3.1. Uize.Flo.abort

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Flo.async

IMPLEMENTATION INFO

this feature was introduced in this module

3.3. Uize.Flo.block

.

IMPLEMENTATION INFO

this feature was introduced in this module

3.4. Uize.Flo.break

IMPLEMENTATION INFO

this feature was introduced in this module

3.5. Uize.Flo.breathe

IMPLEMENTATION INFO

this feature was introduced in this module

3.6. Uize.Flo.call

IMPLEMENTATION INFO

this feature was introduced in this module

3.7. Uize.Flo.continue

IMPLEMENTATION INFO

this feature was introduced in this module

3.8. Uize.Flo.declare

IMPLEMENTATION INFO

this feature was introduced in this module

3.9. Uize.Flo.do

IMPLEMENTATION INFO

this feature was introduced in this module

3.10. Uize.Flo.dualContextMethods

IMPLEMENTATION INFO

this feature was introduced in this module

3.11. Uize.Flo.dualContextProperties

IMPLEMENTATION INFO

this feature was introduced in this module

3.12. Uize.Flo.for

IMPLEMENTATION INFO

this feature was introduced in this module

3.13. Uize.Flo.forEach

IMPLEMENTATION INFO

this feature was introduced in this module

3.14. Uize.Flo.forIn

IMPLEMENTATION INFO

this feature was introduced in this module

3.15. Uize.Flo.function

IMPLEMENTATION INFO

this feature was introduced in this module

3.16. Uize.Flo.if

Same as for the if instance method, but creates a flo invoker with no imposed parent flo.

IMPLEMENTATION INFO

this feature was introduced in this module

3.17. Uize.Flo.instanceMethods

IMPLEMENTATION INFO

this feature was introduced in this module

3.18. Uize.Flo.instanceProperties

IMPLEMENTATION INFO

this feature was introduced in this module

3.19. Uize.Flo.mixins

IMPLEMENTATION INFO

this feature was introduced in this module

3.20. Uize.Flo.next

IMPLEMENTATION INFO

this feature was introduced in this module

3.21. Uize.Flo.ongoing

IMPLEMENTATION INFO

this feature was introduced in this module

3.22. Uize.Flo.staticMethods

IMPLEMENTATION INFO

this feature was introduced in this module

3.23. Uize.Flo.staticProperties

IMPLEMENTATION INFO

this feature was introduced in this module

3.24. Uize.Flo.subclass

IMPLEMENTATION INFO

this feature was introduced in this module

3.25. Uize.Flo.switch

IMPLEMENTATION INFO

this feature was introduced in this module

3.26. Uize.Flo.try

IMPLEMENTATION INFO

this feature was introduced in this module

3.27. Uize.Flo.while

IMPLEMENTATION INFO

this feature was introduced in this module

4. Static Properties

4.1. Uize.Flo.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

4.2. Uize.Flo.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module