Interoperability Details

As mentioned in the README, streamline interoperates seamlessly with standard node.js code: you can call node.js APIs from streamline code, and you can call functions written with streamline from normal node.js code.

There is nevertheless one area that deserves a bit of attention: exception handling. Streamline gives you three options:

• a safe option for those who don't want to worry about the details and are ready to pay a slight performance hit.
• a fast option for those who care about details and want optimal code.
• a pedantic option for those who have strong principles and are ready to sacrifice performance for them.

The safe option

The safe option the default option. With this option, streamline will add try/catch logic in the generated code to guarantee that exceptions thrown by callbacks will be properly caught and propagated.

The pedantic option

The pedantic option is stronger than the safe option. It guarantees that all exceptions (thrown synchronously or thrown by a callback) will be propagated via the callback mechanism (as callback(err)).

This option can be set by including the following comment in the source file:

// streamline.options = { "tryCatch" : "pedantic" }

This option increases the size of the generated code and generates less efficient code. The safe mode is sufficient if you do your exception handling with try/catch blocks inside streamline source files but the pedantic mode may help you if you call streamline modules from regular Javascript modules and if you want to handle exceptions in the regular Javascript modules. With this option, the streamlined functions will never throw an exception directly to their caller. Instead, they will catch all exceptions and pass them as first parameter to their callback.

The fast option

With this option, streamline does not add any try/catch logic to the generated code. So you get optimal performance.

This option can be set by including the following comment in the source file:

// streamline.options = { "tryCatch" : "fast" }

If you use this option, you have to be careful when calling external libraries that haven't been written with streamline. You need to protect these calls with a special callback wrapper. For example:

// var count = fs.readFile(path, "utf8", __wrapOut(_)).split('\n');

The __wrapOut wrapper will ensure that exceptions that get thrown from the callback flow will be correctly propagated. You need this wrapper in all external function calls (including innocuous-looking calls like process.nextTick) but not on calls to streamlined functions.

The fast option is best for modules that are layered on top of other streamlined modules and that don't call external libraries directly.

Note: the safe option is more or less equivalent to the fast option with a __wrapOut(_) around every callback.

Other wrappers

Streamline provides the built-in __wrapOut wrapper to handle APIs that follow the node conventions. If you need to call non standard APIs that use a different callback signature, you can provide your own wrappers. There is one gotcha, though: you have to follow a special naming convention and call these wrappers __wrapXxx because streamline needs to transform these wrapper calls in a special way.