Default options for NodeJS, NPM, and CommonJS modules

Defaultable is a simple drop-in tool to make your Node API very convenient for your users. It comes from internal Iris Couch tooling.

Defaultable is pure CommonJS Javascript, and is also available as an NPM module.

$ npm install defaultable

Is it any good?

Yes.

What your users see

With Defaultable, these are the promises you make to your users (in documentation, presentations, etc.)

Dear users, just require my code and use it like normal.

var api = require("my_mod");

api.do_stuff("Bob", { minimum:5, dollars:10 }); // Process Bob.
api.do_stuff("Eve", { minimum:5, dollars:800}); // Process Eve.

If you are using the same options a lot, set them as defaults.

var api = require("my_mod").defaults({ "minimum": 5 });

api.do_stuff("Bob", { dollars:10 }); // minimum will be 5
api.do_stuff("Eve", { dollars:800}); // minimum is still 5

Defaults can even inherit from other defaults.

var api = require("my_mod");

var fivers = api.defaults({ "minimum": 5}});
var rich = fivers.defaults({"dollars": 10});
var poor = fivers.defaults({"dollars": 800});

poor.do_stuff("Bob"); // dollars will be 10, minimum will be 5
rich.do_stuff("Eve"); // dollars will be 800, minimum is still 5

What you see

Defaulable wraps a CommonJS module.

Your original code:

// my_mod.js

// My code basically starts here
var DEFAULTS = { "minimum":0, "dollars":0 };

exports.do_stuff = function(person, opts) {
  opts = opts || {};

  console.log("Processing: " + person);
  console.log("  minimum = " + opts.minimum || DEFAULTS.minimum);
  console.log("  dollars = $" + opts.dollars || DEFAULTS.dollars);
}
// And obviously it ends here.

Your new code:

// my_mod.js

// Insert these lines at the top...
require('defaultable')(module,
  { "minimum": 0
  , "dollars": 0
  }, function(module, exports, DEFAULTS) { // The rest of your code follows unchanged.

// My code basically starts here (pretty much unmodified, but no hard-coded DEFAULTS)
exports.do_stuff = function(person, opts) {
  opts = opts || {};
  console.log("Processing: " + person);
  console.log("  minimum = " + opts.minimum || DEFAULTS.minimum);
  console.log("  dollars = $" + opts.dollars || DEFAULTS.dollars);
}
// Code ends here, just one more thing to append...

}) // defaultable

How it works

It's really simple.

Defaultable passes the initial defaults to you as DEFAULTS. Use module, module.exports, or exports as usual to build your module API.

Your API gets an additional .defaults() function, which will re-evaluate your code with new user-provided defaults.

Automatic defaults in require()

If you have multiple related modules, it can be nice for them to share defaults.

// main.js
require('defaultable')(module,
  { "minimum": 0
  , "dollars": 0
  }, function(module, exports, DEFS) {

var submod = require('./sub_mod').defaults(DEFS); // Bad!

})

For this situation, defaultable provides a wrapped require() function. It works just like before, however if the modules you load is itself defaultable, it will be initialized with the current defaults.

// main.js
require('defaultable')(module,
  { "minimum": 0
  , "dollars": 0
  }, function(module, exports, DEFS, require) {

var submod = require('./sub_mod'); // Good! Notice the "require" parameter above.

var legacy_mod = require('./legacy_mod'); // Still works.
var http = require('http');               // Still works.

})

If you do not want your module to inherit anything implicitly, use Defaultable's .def() function instead. This is useful for top-level modules of packages, for example.

// main.js -- The "main" file in package.json
require('defaultable').def(module,
  { "minimum": 0
  , "dollars": 0
  }, function(module, exports, DEFS) {

exports.check = function() {
  console.log("Dollars = " + dollars); // Always "0" for require(); still changeable via .defaults()
}

})