what should nodeJS/commonJS module.exports return

Question

what should nodeJS/commonJS module.exports return

I know that I can set module.exports to either an object or a function (and in some cases a function that will return an object).

I am also aware of the differences and ways to use exports vs. module.exports so no need to comment on that.

I also understand that whatever is returned is cached and will be returned on any consecutive call to require. So that if I choose to return a function and not an object then possibly this implies that on every require It is necessary to actually run this function.

I was wondering is there any defacto standard on which of those two should be used. Or if there is no such standard - what considerations would apply when deciding if my module should return an object, a function or anything more complicated...

The module I intend to write is expected to be used as part of an express application if it matters (maybe there is a "local defacto standard" for express/connect modules).

node.js
express
commonjs

Answer 1

If the require'd code is standalone, and does not need access to any objects from the parent code, I export an object.

edit - the above is my preferred way to do it. I do the below only when I need to pass stuff into the module, like configuration data, or my database object. I haven't found a more elegant way to give the module access to variables that are in the parents' scope.

So to pass an object from parent into module I use a function:

//parent.js
var config = { DBname:'bar' };
var child = require('./child.js')(config);

//child.js
module.exports = function(cfg){
  var innerchild = {};
  innerchild.blah = function(){
    console.log(cfg.DBname); // this is out of scope unless you pass it in
  }
  return innerchild;
};

Answer 2

"so that if I choose to return a function and not an object then possibly this implies that on every require It is necessary to actually run this function."

It does not matter whether you return an individual function or an object. In neither cases a function (or functions) are ran. unless you explicitly do so.

For instance, consider the a module hello.js:

exports = function () { return 'Hello'; };

You can use require to get that function:

var hello = require('hello');

If you want to run that function, you need to invoke it explicitly as follows:

var hello = require('hello')();

You wrote you want to make sure your function is executed exactly once. Intuitively this could lead you to writing your hello.js as follows:

var hello = function () { return 'Hello'; };
exports = hello();

In which case you could just store result from hello via require:

var hello = require('hello');

However: if you do that the export system may cache your module. In such cases, you do not get fresh result from hello, but instead, a cached value. This may or may not be what you want. If you want to make sure a function is invoked every time it is required, you need to export a function and call it after require.