Merge pull request #684 from Jakobo/node_callbacks

Adding a backwards compatible node-style callback

README.md

@@ -42,7 +42,9 @@ If this project is missing an API or command line flag that has been added to [l
 
 ## Install
 
-    npm install node-sass
+```
+npm install node-sass
+```
 
 Some users have reported issues installing on Ubuntu due to `node` being registered to another package. [Follow the official NodeJS docs](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager) to install NodeJS so that `#!/usr/bin/env node` correctly resolved.
 
@@ -53,20 +55,18 @@ Compiling versions 0.9.4 and above on Windows machines requires [Visual Studio 2
 ```javascript
 var sass = require('node-sass');
 sass.render({
-	file: scss_filename,
-	success: callback
-	[, options..]
-	});
+  file: scss_filename,
+  [, options..]
+}, function(err, result) { /*...*/ });
 // OR
 var result = sass.renderSync({
-	data: scss_content
-	[, options..]
+  data: scss_content
+  [, options..]
 });
 ```
 
 ### Options
-
-The API for using node-sass has changed, so that now there is only one variable - an options hash. Some of these options are optional, and in some circumstances some are mandatory.
+The API for using node-sass has changed, so that now there is only one options hash. In the options hash, some items are optional, others may be mandatory depending on circumstances.
 
 #### file
 `file` is a `String` of the path to an `scss` file for [libsass] to render. One of this or `data` options are required, for both render and renderSync.
@@ -82,11 +82,11 @@ The callback function is passed a results object, containing the following keys:
 * `css` - The compiled CSS. Write this to a file, or serve it out as needed.
 * `map` - The source map
 * `stats` - An object containing information about the compile. It contains the following keys:
-    * `entry` - The path to the scss file, or `data` if the source was not a file
-    * `start` - Date.now() before the compilation
-    * `end` - Date.now() after the compilation
-    * `duration` - *end* - *start*
-    * `includedFiles` - Absolute paths to all related scss files in no particular order.
+  * `entry` - The path to the scss file, or `data` if the source was not a file
+  * `start` - Date.now() before the compilation
+  * `end` - Date.now() after the compilation
+  * `duration` - *end* - *start*
+  * `includedFiles` - Absolute paths to all related scss files in no particular order.
 
 #### error
 `error` is a `Function` to be called upon occurrence of an error when rendering the scss to css. This option is optional, and only applies to the render function.
@@ -140,64 +140,88 @@ You must define this option as well as `outFile` in order to generate a source m
 #### sourceMapContents
 `sourceMapContents` is a `Boolean` flag to determine whether to include `contents` in maps.
 
+### The `render` Callback (starting from v2.1)
+node-sass supports standard node style asynchronous callbacks with the signature of `function(err, result)`. In error conditions, the `error` argument is populated with the error object. In success conditions, the `result` object is populated with an object describing the result of the render call.
+
+#### The Error Object
+* `message` - The error message.
+* `line` - The line number of error.
+* `column` - The column number of error.
+* `status` - The status code.
+* `file` - The filename of error. In case `file` option was not set (in favour of `data`), this will reflect the value `stdin`.
+
+#### The Result Object
+* `css` - The compiled CSS. Write this to a file, or serve it out as needed.
+* `map` - The source map
+* `stats` - An object containing information about the compile. It contains the following keys:
+  * `entry` - The path to the scss file, or `data` if the source was not a file
+  * `start` - Date.now() before the compilation
+  * `end` - Date.now() after the compilation
+  * `duration` - *end* - *start*
+  * `includedFiles` - Absolute paths to all related scss files in no particular order.
+
 ### Examples
 
 ```javascript
 var sass = require('node-sass');
 sass.render({
-	file: '/path/to/myFile.scss',
-	data: 'body{background:blue; a{color:black;}}',
-	success: function(result) {
-		// result is an object: v2 change
-        console.log(result.css);
-        console.log(result.stats);
-        console.log(result.map)
-	},
-	error: function(error) { // starting v2.1 error is an Error-typed object
-		// error is an object: v2 change
-		console.log(error.message);
-		console.log(error.status); // changed from code to status in v2.1
-		console.log(error.line);
-		console.log(error.column); // new in v2
-	},
-	importer: function(url, prev, done) {
-		// url is the path in import as is, which libsass encountered.
-		// prev is the previously resolved path.
-		// done is an optional callback, either consume it or return value synchronously.
-		someAsyncFunction(url, prev, function(result){
-			done({
-				file: result.path, // only one of them is required, see section Sepcial Behaviours.
-				contents: result.data
-			});
-		});
-		// OR
-		var result = someSyncFunction(url, prev);
-		return {file: result.path, contents: result.data};
-	},
-	includePaths: [ 'lib/', 'mod/' ],
-	outputStyle: 'compressed'
+  file: '/path/to/myFile.scss',
+  data: 'body{background:blue; a{color:black;}}',
+  success: function(result) {
+    // result is an object: v2 change
+    console.log(result.css);
+    console.log(result.stats);
+    console.log(result.map)
+  },
+  error: function(error) { // starting v2.1 error is an Error-typed object
+    // error is an object: v2 change
+    console.log(error.message);
+    console.log(error.status); // changed from code to status in v2.1
+    console.log(error.line);
+    console.log(error.column); // new in v2
+  },
+  importer: function(url, prev, done) {
+    // url is the path in import as is, which libsass encountered.
+    // prev is the previously resolved path.
+    // done is an optional callback, either consume it or return value synchronously.
+    someAsyncFunction(url, prev, function(result){
+      done({
+        file: result.path, // only one of them is required, see section Sepcial Behaviours.
+        contents: result.data
+      });
+    });
+    // OR
+    var result = someSyncFunction(url, prev);
+    return {file: result.path, contents: result.data};
+  },
+  includePaths: [ 'lib/', 'mod/' ],
+  outputStyle: 'compressed'
+}, function(error, result) {
+  // starting v2.1 the node-style callback has error (Object) and result (Object)
+  // the objects are identical to those provided for the error and success keys
+  // in the options object
 });
 // OR
 var result = sass.renderSync({
-	file: '/path/to/file.scss',
-	data: 'body{background:blue; a{color:black;}}',
-	outputStyle: 'compressed',
-	outFile: '/to/my/output.css',
-	sourceMap: true, // or an absolute or relative (to outFile) path
-	importer: function(url, prev, done) {
-		// url is the path in import as is, which libsass encountered.
-		// prev is the previously resolved path.
-		// done is an optional callback, either consume it or return value synchronously.
-		someAsyncFunction(url, prev, function(result){
-			done({
-				file: result.path, // only one of them is required, see section Sepcial Behaviours.
-				contents: result.data
-			});
-		});
-		// OR
-		var result = someSyncFunction(url, prev);
-		return {file: result.path, contents: result.data};
-	},
+  file: '/path/to/file.scss',
+  data: 'body{background:blue; a{color:black;}}',
+  outputStyle: 'compressed',
+  outFile: '/to/my/output.css',
+  sourceMap: true, // or an absolute or relative (to outFile) path
+  importer: function(url, prev, done) {
+    // url is the path in import as is, which libsass encountered.
+    // prev is the previously resolved path.
+    // done is an optional callback, either consume it or return value synchronously.
+    someAsyncFunction(url, prev, function(result){
+      done({
+        file: result.path, // only one of them is required, see section Sepcial Behaviours.
+        contents: result.data
+      });
+    });
+    // OR
+    var result = someSyncFunction(url, prev);
+    return {file: result.path, contents: result.data};
+  },
 }));
 
 console.log(result.css);

lib/index.js

@@ -127,7 +127,7 @@ function getSourceMap(options) {
  * @param {Object} options
  * @api private
  */
-function getOptions(options) {
+function getOptions(options, cb) {
   options = options || {};
   options.comments = options.source_comments || options.sourceComments || false;
   options.data = options.data || null;
@@ -150,21 +150,30 @@ function getOptions(options) {
   var success = options.success;
 
   options.error = function(err) {
+    var payload = util._extend(new Error(), JSON.parse(err));
+
+    if (cb) {
+      cb.call(options.context, payload, null);
+    }
     if (error) {
-      error.call(options.context, util._extend(new Error(), JSON.parse(err)));
+      error.call(options.context, payload);
     }
   };
 
   options.success = function() {
     var result = options.result;
     var stats = endStats(result.stats);
+    var payload = {
+      css: result.css,
+      map: result.map,
+      stats: stats
+    };
 
+    if (cb) {
+      cb.call(options.context, null, payload);
+    }
     if (success) {
-      success.call(options.context, {
-        css: result.css,
-        map: result.map,
-        stats: stats
-      });
+      success.call(options.context, payload);
     }
   };
 
@@ -194,8 +203,8 @@ var binding = require(getBinding());
  * @api public
  */
 
-module.exports.render = function(options) {
-  options = getOptions(options);
+module.exports.render = function(options, cb) {
+  options = getOptions(options, cb);
 
   var importer = options.importer;
 
@@ -243,7 +252,6 @@ module.exports.renderSync = function(options) {
 
   if(status) {
     result.stats = endStats(result.stats);
-
     return result;
   }
 

test/api.js

@@ -411,6 +411,28 @@ describe('api', function() {
     });
   });
 
+  describe('.render(options, cb)', function() {
+    it('should compile sass to css with file', function(done) {
+      var expected = 'div {\n  color: yellow; }';
+      sass.render({
+        data: 'div {color: yellow;}'
+      }, function(err, result) {
+        assert.equal(result.css.trim(), expected);
+        done();
+      });
+    });
+
+    it('should throw error status 1 for bad input', function(done) {
+      sass.render({
+        data: '#navbar width 80%;'
+      }, function(err) {
+        assert(err.message);
+        assert.equal(err.status, 1);
+        done();
+      });
+    });
+  });
+
   describe('.renderSync(options)', function() {
     it('should compile sass to css with file', function(done) {
       var expected = read(fixture('simple/expected.css'), 'utf8').trim();