defaultable.js

// Defaultable APIs
//
// Copyright 2011 Jason Smith, Jarrett Cruger and contributors
//
//    Licensed under the Apache License, Version 2.0 (the "License");
//    you may not use this file except in compliance with the License.
//    You may obtain a copy of the License at
//
//        http://www.apache.org/licenses/LICENSE-2.0
//
//    Unless required by applicable law or agreed to in writing, software
//    distributed under the License is distributed on an "AS IS" BASIS,
//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//    See the License for the specific language governing permissions and
//    limitations under the License.

module.exports = good_args(defaultable);
module.exports.def   = good_args(fresh_defaultable);
module.exports.merge = merge_obj;

var path_lib = require('path');
var real_require = require;


function fresh_defaultable(_mod, _defs, _definer) {
  var mod = defaultable.apply(this, arguments);
  mod.defaults._defaultable.fresh = true;
  return mod;
}


function defaultable(real_module, initial_defs, definer, real_require) {
  if(!real_module || !real_module.exports)
    throw new Error('Need to provide the module, with .exports object');

  if(!is_obj(initial_defs))
    throw new Error('Defaults must be an object');

  // use real_module.id if filename not available (running on couchdb)
  var mod_dir = path_lib.dirname(real_module.filename || real_module.id);
  var mod_require = real_module.require || real_require || workaround_require;

  workaround_require._defaultable = true;
  function workaround_require(path) {
    if(/^\.\//.test(path) || /^\.\.\//.test(path))
      path = path_lib.resolve(mod_dir, path);

    try       {
      return real_require(path)
    } catch(er) {
      // This CouchDB workaround really belongs in CouchDB. CouchDB errors look like this:
      //   ["error","invalid_require_path","Must require a JavaScript string, not: object"]
      if(er[0] !== "error" || er[1] !== "invalid_require_path"
      || er[2] !== "Must require a JavaScript string, not: object")
        throw er;

      try        { return real_require(path + '/index') }
      catch(er2) { throw er                             } // Nope, throw the original error.
    }
  }

  var defaulter = make_defaulter({});
  real_module.exports = defaulter(initial_defs);
  return real_module.exports;

  function make_defaulter(old_defs) {
    defaulter._defaultable = {};
    return defaulter;

    function defaulter(new_defs) {
      var faux_exports = {};
      var faux_module = {"exports":faux_exports};
      var final_defs = merge_obj(new_defs || {}, old_defs);

      require._defaultable = true;
      function require(path) {
        var mod = mod_require.call(real_module, path);
        if(mod.defaults && typeof mod.defaults === 'function' && mod.defaults._defaultable && !mod.defaults._defaultable.fresh)
          return mod.defaults(final_defs);
        return mod;
      }

      definer(faux_module, faux_exports, final_defs, require);

      var api = faux_module.exports;
      if(('defaults' in api) && !api.defaults._defaultable)
        throw new Error('defaultable modules may not export a label called "defaults"');
      else
        api.defaults = make_defaulter(final_defs);

      return api;
    }
  }
}


// Recursively merge higher-priority values into previously-set lower-priority ones.
function merge_obj(high, low) {
  if(!is_obj(high))
    throw new Error('Bad merge high-priority');
  if(!is_obj(low))
    throw new Error('Bad merge low-priority');

  var keys = [];
  function add_key(k) {
    if(!~ keys.indexOf(k))
      keys.push(k);
  }

  _each(_keys(high), add_key);
  _each(_keys(low), add_key);

  var result = {};
  _each(keys, function (key) {
    var high_val = high[key];
    var low_val = low[key];

    if(is_obj(high_val) && is_obj(low_val))
      result[key] = merge_obj(high_val, low_val);
    else if (key in high)
      result[key] = high[key];
    else if (key in low)
      result[key] = low[key];
    else
      throw new Error('Unknown key type: ' + key);
  })

  return result;
}


//
// Utilities
//

/**
 * Added for browser compatibility
 */

function _keys(obj) {
  if(Object.keys) return Object.keys(obj);
  var keys = [];
  for(var k in obj){
    if(obj.hasOwnProperty(k)) keys.push(k);
  }
  return keys;
}

function _each(obj, fn) {
  for (var i = 0, len = obj.length; i < len; i++) {
    fn(obj[i]);
  }
}

function isArray(obj) {
  if(Array.isArray)
    return Array.isArray(obj);
  return toString.call(obj) === '[object Array]';
}

function good_args(func) {
  // Make a function validate its parameters.
  return good;

  function good(_Mod, _Defs, _Definer) {
    var args = Array.prototype.slice.call(arguments);
    var m0dule = { 'exports': {} };

    if(args.length == 1)
      return func(m0dule, {}, args[0]);
    else if(args.length == 2)
      return func(m0dule, args[0], args[1]);
    else if(args.length > 2)
      return func.apply(this, args);
    else
      throw new Error('Unknown arguments: ' + JSON.stringify(args));
  }
}

function is_obj(val) {
  return val && !isArray(val) && (typeof val === 'object')
}