Fork

Fork from original project with updated fibers dependencies to support newer Node releases.

Fibers:

If you are running 64-bit nodejs version 12.x or 14.x on Linux, OS X, or Windows (7 or later) then you should be able to install fibers from npm just fine. If you are running nodejs v10.x then you will need to use npm install fibers@4. Older versions of nodejs will require older and older version of fibers.

Introduction

node-sync is a simple library that allows you to call any asynchronous function in synchronous way. The main benefit is that it uses javascript-native design - Function.prototype.sync function, instead of heavy APIs which you'll need to learn. Also, asynchronous function which was called synchronously through node-sync doesn't blocks the whole process - it blocks only current thread!

It built on node-fibers library as a multithreading solution.

Examples

Simply call asynchronous function synchronously:

var Sync = require('sync');

function asyncFunction(a, b, callback) {
	process.nextTick(function(){
		callback(null, a + b);
	})
}

// Run in a fiber
Sync(function(){
	
	// Function.prototype.sync() interface is same as Function.prototype.call() - first argument is 'this' context
	var result = asyncFunction.sync(null, 2, 3);
	console.log(result); // 5

	// Read file synchronously without blocking whole process? no problem
	var source = require('fs').readFile.sync(null, __filename);
    console.log(String(source)); // prints the source of this example itself
})

It throws exceptions!

var Sync = require('sync');

function asyncFunction(a, b, callback) {
	process.nextTick(function(){
		callback('something went wrong');
	})
}

// Run in a fiber
Sync(function(){

	try {
		var result = asyncFunction.sync(null, 2, 3);
	}
	catch (e) {
		console.error(e); // something went wrong
	}
})

// Or simply specify callback function for Sync fiber
// handy when you use Sync in asynchronous environment
Sync(function(){
	
	// The result will be passed to a Sync callback
	var result = asyncFunction.sync(null, 2, 3);
	return result;
	
}, function(err, result){ // <-- standard callback
	
	if (err) console.error(err); // something went wrong
	
	// The result which was returned from Sync body function
	console.log(result);
})

Transparent integration

var Sync = require('sync');

var MyNewFunctionThatUsesFibers = function(a, b) { // <-- no callback here
	
	// we can use yield here
	// yield();
	
	// or throw an exception!
	// throw new Error('something went wrong');
	
	// or even sleep
	// Sync.sleep(200);
	
	// or turn fs.readFile to non-blocking synchronous function
	// var source = require('fs').readFile.sync(null, __filename)
	
	return a + b; // just return a value
	
}.async() // <-- here we make this function friendly with async environment

// Classic asynchronous nodejs environment
var MyOldFashoinAppFunction = function() {
	
	// We just use our MyNewFunctionThatUsesFibers normally, in a callback-driven way
	MyNewFunctionThatUsesFibers(2, 3, function(err, result){
		
		// If MyNewFunctionThatUsesFibers will throw an exception, it will go here
		if (err) return console.error(err);
		
		// 'return' value of MyNewFunctionThatUsesFibers
		console.log(result); // 5
	})
}

// From fiber environment
Sync(function(){
	
	// Run MyNewFunctionThatUsesFibers synchronously
	var result = MyNewFunctionThatUsesFibers(2, 3);
	console.log(result); // 5
	
	// Or use sync() for it (same behavior)
	var result = MyNewFunctionThatUsesFibers.sync(null, 2, 3);
	console.log(result); // 5
})

Parallel execution:

var Sync = require('sync'),
	Future = Sync.Future();

// Run in a fiber
Sync(function(){
	try {
		// Three function calls in parallel
		var foo = asyncFunction.future(null, 2, 3);
		var bar = asyncFunction.future(null, 5, 5);
		var baz = asyncFunction.future(null, 10, 10);
	
		// We are immediately here, no blocking
	
		// foo, bar, baz - our tickets to the future!
	    console.log(foo); // { [Function: Future] result: [Getter], error: [Getter] }
	
		// Get the results
		// (when you touch 'result' getter, it blocks until result would be returned)
		console.log(foo.result, bar.result, baz.result); // 5 10 20
	
		// Or you can straightly use Sync.Future without wrapper
		// This call doesn't blocks
		asyncFunction(2, 3, foo = Future());
	
		// foo is a ticket
	    console.log(foo); // { [Function: Future] result: [Getter], error: [Getter] }

		// Wait for the result
		console.log(foo.result); // 5
	}
	catch (e) {
		// If some of async functions returned an error to a callback
		// it will be thrown as exception
		console.error(e);
	}
})

Timeouts support

var Sync = require('sync'),
	Future = Sync.Future;

function asyncFunction(a, b, callback) {
	setTimeout(function(){
		callback(null, a + b);
	}, 1000)
}

// Run in a fiber
Sync(function(){
	
	// asyncFunction returns the result after 1000 ms
	var foo = asyncFunction.future(null, 2, 3);
	// but we can wait only 500ms!
	foo.timeout = 500;

	try {
	    var result = foo.result;
	}
	catch (e) {
	    console.error(e); // Future function timed out at 500 ms
	}

	// Same example with straight future function
	asyncFunction(2, 3, foo = new Future(500));

	try {
	    var result = foo.result;
	}
	catch (e) {
	    console.error(e); // Future function timed out at 500 ms
	}
})

How to address non-uniform callbacks

Sometimes third-party libraries are not following convention and passing multiple result parameters to the callback, e.g. callback(err, recordsets, returnValue). In this situation, node-sync will simply return array of values instead of value.

// Asynchronous which returns multiple arguments to a callback and returning a value synchronously
function asyncFunctionReturningMultipleArguments(callback) {
    process.nextTick(function(){
        callback(null, 2, 3);
    })
}

Sync(function(){
    var result = asyncFunctionReturningMultipleArguments.sync();
    assert.equal(result, [2, 3]);
})

See more examples in examples directory.

Installation

install

$ npm install sync

and then

$ node your_file_using_sync.js