Fluid.js

Fluid.js is a simple fluent interface API for javascript and node.js. It is used to create fluent interfaces around existing vanilla objects, without all the boiler plate.

This is a useful extension to the excellent Async module.

NOTE: Fluid.js will only wrap methods which implement the following asynchronous signature:-

function(options, callback) -> callback(err, result)

Quick Examples

Example objects

For the sake of these examples imagine we have the following custom objects

var myFirstObj = {
	doSomething : function(options, callback) { 
		//do something
		callback(err, result);
	},
	doSomethingElse : function(options, callback) {
		//do something else
		callback(err, result);
	}
};

var mySecondObj = {
	doSomethingMore : function(options, callback) {
		//do something more
		callback(err, result);
	}
};

Setup

var fluid = require("fluid");

Expressive Example

fluid().series()		
	.with(myFirstObj)
		.doSomething({ /* args */ })
		.doSomethingElse({ /* args */ })
	.with(mySecondObj)
		.doSomethingMore({ /* args */ })
.go(function(err, results) {
	// results is now an array of return values passed to each method callback
});

Streamlined example

Note: series is the default flow control mode, so it can be ommitted

fluid(myFirstObj).doSomething({ /* args */ }).doSomethingElse({ /* args */ })
	.with(mySecondObj).doSomethingMore({ /* args */ })
.go(function(err, results) {
	// results is now an array of return values passed to each method callback
});

Multiple flow control types example

fluid()
	.series()		
		.with(myFirstObj)
			.doSomething({ /* args */ })
			.doSomethingElse({ /* args */ })
	.parallel()		
		.with(mySecondObj)
			.doSomethingMore({ /* args */ })
			.doSomethingMorer({ /* args */ })
			.doSomethingMorerer({ /* args */ })
	.go(function(err, results) {
		/*
			results is now an array (item for each queue) of arrays (item for each method return value)
		*/
	});

Install

To install with node package manager:

npm install fluid

Download

Releases are available for download from GitHub.

Appreciation

Thanks to caolan for his great module Async

Documentation

• fluid

Fluid Context Methods

• with
• series
• parallel
• go
• context methods

Creates a new fluent interface (fluid context), optionally wrapping an initial user specifed application context.

Note, if desired, the initial context can be left blank and applied later using the with command.

Arguments

• context - An initial application context to wrap with fluent methods.
• Returns a new fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).doSomething({ /* args */ })  
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

Fluid Context Methods

Switches the current application context to the one specified.

Note, The context can be switch as many times as required. Useful for cleanly working with multiple objects.

Arguments

• context - An application context to wrap with fluent methods.
• Returns the current fluid context.

Example

// assuming a objects exist called myObj and myObj2
var fluid = require("fluid");

fluid(myObj).doSomething({ /* args */ })
	.with(myObj2).doSomethingElse({ /* args */ }) 
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

Creates a new queue of method calls that will be executed in series. Multiple queues with different flow control types can be created, and will themselves be executed in series when the go command is called.

Note, This is the default execution mode when a new fluid context has been created.

Arguments

• Returns the current fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).series()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }
	
	

Creates a new queue of method calls that will be executed in parallel. Multiple queues with different flow control types can be created, and will themselves be executed in series when the go command is called.

Note, see the Async module for more information on the difference between series and parallel flow controls.

Arguments

• Returns the current fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).parallel()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

	

Executes all queued method calls against their registered application contexts, then invokes the specified callback when successfully completed, or any of the methods error.

Arguments

• callback(err, res) - A callback which is called after all the methods have been called successfully, or an error has occurred. If no errors occurr res will be an array of return values passed to each method callback. If multiple queues have been executed it will be an array (item for each queue) of arrays (item for each method return value)

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).series()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	.parallel()
	.doSomethingMore({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { 
	if (err) { /* error */ } else {
		console.log(res[0][0]);
		console.log(res[0][1]);
		
		console.log(res[1][0]);
		/* .etc.etc... */
	}
}

The fluid context will wrap all properties of an application context that are functions.

NOTE: It is only possible to wrap functions that implement the following asynchronous signature:-

function(options, callback) -> callback(err, result)

Example

var myObj = {
	doSomething : function(options, callback) {
		callback(null, { prop1 : 1 });
	},
	doSomethingElse : function(options, callback) {
		callback({ message : "Error!" });
	},
	doSomethingMore : function(options, callback) {
		callback(null, { prop2 : 1 });
	}
};

var fluid = require("fluid");

fluid(myObj)
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	.doSomethingMore({ /* args */ })
.go(function(err, res) {
	/* finished with error, without executing doSomethingMore */

=======

Fluid.js

Fluid.js is a simple fluent interface API for javascript and node.js. It is used to create fluent interfaces around existing vanilla objects, without all the boiler plate.

This is a useful extension to the excellent Async module.

NOTE: Fluid.js will only wrap methods which implement the following asynchronous signature:-

function(options, callback) -> callback(err, result)

Quick Examples

Example objects

For the sake of these examples imagine we have the following custom objects

var myFirstObj = {
	doSomething : function(options, callback) { 
		//do something
		callback(err, result);
	},
	doSomethingElse : function(options, callback) {
		//do something else
		callback(err, result);
	}
};

var mySecondObj = {
	doSomethingMore : function(options, callback) {
		//do something more
		callback(err, result);
	}
};

Setup

var fluid = require("fluid");

Expressive Example

fluid().series()		
	.with(myFirstObj)
		.doSomething({ /* args */ })
		.doSomethingElse({ /* args */ })
	.with(mySecondObj)
		.doSomethingMore({ /* args */ })
.go(function(err, results) {
	// results is now an array of return values passed to each method callback
});

Streamlined example

Note: series is the default flow control mode, so it can be ommitted

fluid(myFirstObj).doSomething({ /* args */ }).doSomethingElse({ /* args */ })
	.with(mySecondObj).doSomethingMore({ /* args */ })
.go(function(err, results) {
	// results is now an array of return values passed to each method callback
});

Multiple flow control types example

fluid()
	.series()		
		.with(myFirstObj)
			.doSomething({ /* args */ })
			.doSomethingElse({ /* args */ })
	.parallel()		
		.with(mySecondObj)
			.doSomethingMore({ /* args */ })
			.doSomethingMorer({ /* args */ })
			.doSomethingMorerer({ /* args */ })
	.go(function(err, results) {
		/*
			results is now an array (item for each queue) of arrays (item for each method return value)
		*/
	});

Install

To install with node package manager:

npm install fluid

Download

Releases are available for download from GitHub.

Appreciation

Thanks to caolan for his great module Async

Documentation

• fluid

Fluid Context Methods

• with
• series
• parallel
• go
• context methods

Creates a new fluent interface (fluid context), optionally wrapping an initial user specifed application context.

Note, if desired, the initial context can be left blank and applied later using the with command.

Arguments

• context - An initial application context to wrap with fluent methods.
• Returns a new fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).doSomething({ /* args */ })  
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

Fluid Context Methods

Switches the current application context to the one specified.

Note, The context can be switch as many times as required. Useful for cleanly working with multiple objects.

Arguments

• context - An application context to wrap with fluent methods.
• Returns the current fluid context.

Example

// assuming a objects exist called myObj and myObj2
var fluid = require("fluid");

fluid(myObj).doSomething({ /* args */ })
	.with(myObj2).doSomethingElse({ /* args */ }) 
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

Creates a new queue of method calls that will be executed in series. Multiple queues with different flow control types can be created, and will themselves be executed in series when the go command is called.

Note, This is the default execution mode when a new fluid context has been created.

Arguments

• Returns the current fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).series()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }
	
	

Creates a new queue of method calls that will be executed in parallel. Multiple queues with different flow control types can be created, and will themselves be executed in series when the go command is called.

Note, see the Async module for more information on the difference between series and parallel flow controls.

Arguments

• Returns the current fluid context.

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).parallel()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { /* finished */ }

	

Executes all queued method calls against their registered application contexts, then invokes the specified callback when successfully completed, or any of the methods error.

Arguments

• callback(err, res) - A callback which is called after all the methods have been called successfully, or an error has occurred. If no errors occurr res will be an array of return values passed to each method callback. If multiple queues have been executed it will be an array (item for each queue) of arrays (item for each method return value)

Example

// assuming an object exists called myObj
var fluid = require("fluid");

fluid(myObj).series()
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	.parallel()
	.doSomethingMore({ /* args */ })
	/* .etc.etc... */
.go(function(err, res) { 
	if (err) { /* error */ } else {
		console.log(res[0][0]);
		console.log(res[0][1]);
		
		console.log(res[1][0]);
		/* .etc.etc... */
	}
}

The fluid context will wrap all properties of an application context that are functions.

NOTE: It is only possible to wrap functions that implement the following asynchronous signature:-

function(options, callback) -> callback(err, result)

Example

var myObj = {
	doSomething : function(options, callback) {
		callback(null, { prop1 : 1 });
	},
	doSomethingElse : function(options, callback) {
		callback({ message : "Error!" });
	},
	doSomethingMore : function(options, callback) {
		callback(null, { prop2 : 1 });
	}
};

var fluid = require("fluid");

fluid(myObj)
	.doSomething({ /* args */ })
	.doSomethingElse({ /* args */ })
	.doSomethingMore({ /* args */ })
.go(function(err, res) {
	/* finished with error, without executing doSomethingMore */

Fixed package and readme }