psyncho-fibers v1.0.2

Psyncho-fibers

A library designed to provide as thin a layer as possible which allows async operations in Node.js to be handled in a linear fashion.

Overview

This version is provided for use in environments which don't support generators. If you want the generator based version instead, simply replace the package name "psyncho-fibers" with "psyncho", the API is consistent between the two implementations. http://gitlab.com/IanWizard/Psyncho
While there is no difference in usage, you should use the generator based version if you are able. In addition to not having any dependencies, it works in browsers supporting ES6, whereas this version will never offer browser support.

Often times you'll find yourself in a situation where you're calling an asynchronous function, but your code can't do anything further until that async function finishes. Traditionally the way you would handle this is with nested callbacks or promises.
This makes sense logically, however, it can become unruly, and causes many developers to avoid the language.

The chief goals of Psyncho are to:
1. Alieviate this by allowing for more linear and logical flow by handling callbacks and promises in a sensible manner.
2. Do so in a minimally intrusive way. Unlike other libraries, nothing is done to modify the functions themselves, or otherwise tinker with the internals of either Node or any libraries.

Psyncho allows you to work in a similar way, while still maintaining a more linear flow.
Often times you will still use a callback function to handle the result of the original async function. The difference is that when you first call the async function, your code is paused immediately afterward. Then, when the async function finishes, your callback is run, and only after it has finished, is your code resumed. See below for examples.

Installation

npm install psyncho-fibers

Usage

Psyncho.init()

Before you can use the Psyncho() function, you have to wrap your "pauseable" code using the Psyncho.init() function. Your "pauseable" code is the block of code which will be paused while waiting for an async operation to complete. The Psyncho() function will only work properly within code that has been wrapped in a call to Psyncho.init(). This does add one layer of nesting, however, it allows you to control what is paused and when, rather than hijacking the event loop as some other libraries do.

Psyncho.init(function() {
	// do stuff
});

Psyncho()

The Psyncho() function takes a function as it's only argument, and returns a function which will execute synchronously.
This will be unfamiliar to some, and to others will resemble that of libraries which augment the functions themselves, however, all it does is pause execution after the function is called. This convention was chosen to allow more flexibility in use.
For the moment, ignore the details of Psyncho.callback(), just know that it returns a function which will "unpause" your code when it's called. We'll cover it in more detail in a moment.

Psyncho.init(function() {
	// A synchronous version of setTimeout is effectively the same as sleeping for the specified duration.
	// In this case, we're just telling it to resume our code in 5 seconds.
	var sleep = Psyncho(setTimeout);

	sleep(Psyncho.callback(), 5000);

	// Alternatively you may prefer to write the above more like this.
	Psyncho(someAsyncFunction)(Psyncho.callback(), 5000);
});

Both of these options do the same thing, and there is ultimately very little difference in style.

Psyncho.callback()

Now let's look at that Psyncho.callback() function.
It's purpose is to generate a function to be used as a callback. The function that it returns will simply resume execution of your code. When used with no arguments, that's all it does, however, if you supply an Array or an Object as an argument, then it will take any arguments passed to the generated function, and assign them to the given Array or Object.
Take for example, an asynchronous function which takes one callback as it's argument, and passes a status code, or error to that callback:

var someAsyncArgs = [];

Psyncho(someAsyncFunction)(Psyncho.callback(someAsyncArgs));

When execution resumes, someAsyncArgs will contain the values passed from someAsyncFunction to it's callback.
An example of this may look like:

[
	200,
	null
]

If an Object is passed instead of an Array, then each argument is assigned to the index of the original argument, for example:

{
	0: 200,
	1: null
}

Finally, there is a third type of argument which may be passed to Psyncho.callback(), which is where it's true power lies.
If a function is passed as the argument to Psyncho.callback(), then that function is run as if it were being run as the actual callback to the async function.

Psyncho(someAsyncFunction)(Psyncho.callback(function(status, error) {
	if (error)
		throw error;
	else
		console.log("Yay, no error!  We got a status of: ", status);
}));

Of course, you can do much more complex processing to handle whatever your async function passes in.

NOTE: There is a potential for breakage if a callback generated by Psyncho.callback() is run more than once, or if more than one generated callback is called.
Each time a one of the handlers generated by Psyncho.callback() is called, the "pauseable" code will be started, even if it has already been resumed. This is potentially an issue and could easily cause unexpected behaviour. Be aware of this when using Psyncho in such scenarios. This is a known issue, and will be resolved in 1.1.0.

Return values

If the async function returns a value immediately (via a return statement) when it is called, that value is returned when the function generated by Psyncho() is run. For example, given the code below, the timeout variable will be the timeout which is returned by setTimeout.

var sleep = Psyncho(setTimeout);

var timeout = sleep(Psyncho.callback(), 5000);

License

This project is distributed under the Internet Software Consortium (ISC) license: http://opensource.org/licenses/ISC