1  'use strict';
  2  
  3  var util = require('util');
  4  var define = require('define-property');
  5  var CacheBase = require('cache-base');
  6  var Emitter = require('component-emitter');
  7  var isObject = require('isobject');
  8  var merge = require('mixin-deep');
  9  var pascal = require('pascalcase');
 10  var cu = require('class-utils');
 11  
 12  /**
 13   * Optionally define a custom `cache` namespace to use.
 14   */
 15  
 16  function namespace(name) {
 17    var Cache = name ? CacheBase.namespace(name) : CacheBase;
 18    var fns = [];
 19  
 20    /**
 21     * Create an instance of `Base` with the given `config` and `options`.
 22     *
 23     * ```js
 24     * // initialize with `config` and `options`
 25     * var app = new Base({isApp: true}, {abc: true});
 26     * app.set('foo', 'bar');
 27     *
 28     * // values defined with the given `config` object will be on the root of the instance
 29     * console.log(app.baz); //=> undefined
 30     * console.log(app.foo); //=> 'bar'
 31     * // or use `.get`
 32     * console.log(app.get('isApp')); //=> true
 33     * console.log(app.get('foo')); //=> 'bar'
 34     *
 35     * // values defined with the given `options` object will be on `app.options
 36     * console.log(app.options.abc); //=> true
 37     * ```
 38     *
 39     * @param {Object} `config` If supplied, this object is passed to [cache-base][] to merge onto the the instance upon instantiation.
 40     * @param {Object} `options` If supplied, this object is used to initialize the `base.options` object.
 41     * @api public
 42     */
 43  
 44    function Base(config, options) {
 45      if (!(this instanceof Base)) {
 46        return new Base(config, options);
 47      }
 48      Cache.call(this, config);
 49      this.is('base');
 50      this.initBase(config, options);
 51    }
 52  
 53    /**
 54     * Inherit cache-base
 55     */
 56  
 57    util.inherits(Base, Cache);
 58  
 59    /**
 60     * Add static emitter methods
 61     */
 62  
 63    Emitter(Base);
 64  
 65    /**
 66     * Initialize `Base` defaults with the given `config` object
 67     */
 68  
 69    Base.prototype.initBase = function(config, options) {
 70      this.options = merge({}, this.options, options);
 71      this.cache = this.cache || {};
 72      this.define('registered', {});
 73      if (name) this[name] = {};
 74  
 75      // make `app._callbacks` non-enumerable
 76      this.define('_callbacks', this._callbacks);
 77      if (isObject(config)) {
 78        this.visit('set', config);
 79      }
 80      Base.run(this, 'use', fns);
 81    };
 82  
 83    /**
 84     * Set the given `name` on `app._name` and `app.is*` properties. Used for doing
 85     * lookups in plugins.
 86     *
 87     * ```js
 88     * app.is('foo');
 89     * console.log(app._name);
 90     * //=> 'foo'
 91     * console.log(app.isFoo);
 92     * //=> true
 93     * app.is('bar');
 94     * console.log(app.isFoo);
 95     * //=> true
 96     * console.log(app.isBar);
 97     * //=> true
 98     * console.log(app._name);
 99     * //=> 'bar'
100     * ```
101     * @name .is
102     * @param {String} `name`
103     * @return {Boolean}
104     * @api public
105     */
106  
107    Base.prototype.is = function(name) {
108      if (typeof name !== 'string') {
109        throw new TypeError('expected name to be a string');
110      }
111      this.define('is' + pascal(name), true);
112      this.define('_name', name);
113      this.define('_appname', name);
114      return this;
115    };
116  
117    /**
118     * Returns true if a plugin has already been registered on an instance.
119     *
120     * Plugin implementors are encouraged to use this first thing in a plugin
121     * to prevent the plugin from being called more than once on the same
122     * instance.
123     *
124     * ```js
125     * var base = new Base();
126     * base.use(function(app) {
127     *   if (app.isRegistered('myPlugin')) return;
128     *   // do stuff to `app`
129     * });
130     *
131     * // to also record the plugin as being registered
132     * base.use(function(app) {
133     *   if (app.isRegistered('myPlugin', true)) return;
134     *   // do stuff to `app`
135     * });
136     * ```
137     * @name .isRegistered
138     * @emits `plugin` Emits the name of the plugin being registered. Useful for unit tests, to ensure plugins are only registered once.
139     * @param {String} `name` The plugin name.
140     * @param {Boolean} `register` If the plugin if not already registered, to record it as being registered pass `true` as the second argument.
141     * @return {Boolean} Returns true if a plugin is already registered.
142     * @api public
143     */
144  
145    Base.prototype.isRegistered = function(name, register) {
146      if (this.registered.hasOwnProperty(name)) {
147        return true;
148      }
149      if (register !== false) {
150        this.registered[name] = true;
151        this.emit('plugin', name);
152      }
153      return false;
154    };
155  
156    /**
157     * Define a plugin function to be called immediately upon init. Plugins are chainable
158     * and expose the following arguments to the plugin function:
159     *
160     * - `app`: the current instance of `Base`
161     * - `base`: the [first ancestor instance](#base) of `Base`
162     *
163     * ```js
164     * var app = new Base()
165     *   .use(foo)
166     *   .use(bar)
167     *   .use(baz)
168     * ```
169     * @name .use
170     * @param {Function} `fn` plugin function to call
171     * @return {Object} Returns the item instance for chaining.
172     * @api public
173     */
174  
175    Base.prototype.use = function(fn) {
176      fn.call(this, this);
177      return this;
178    };
179  
180    /**
181     * The `.define` method is used for adding non-enumerable property on the instance.
182     * Dot-notation is **not supported** with `define`.
183     *
184     * ```js
185     * // arbitrary `render` function using lodash `template`
186     * app.define('render', function(str, locals) {
187     *   return _.template(str)(locals);
188     * });
189     * ```
190     * @name .define
191     * @param {String} `key` The name of the property to define.
192     * @param {any} `value`
193     * @return {Object} Returns the instance for chaining.
194     * @api public
195     */
196  
197    Base.prototype.define = function(key, val) {
198      if (isObject(key)) {
199        return this.visit('define', key);
200      }
201      define(this, key, val);
202      return this;
203    };
204  
205    /**
206     * Mix property `key` onto the Base prototype. If base is inherited using
207     * `Base.extend` this method will be overridden by a new `mixin` method that will
208     * only add properties to the prototype of the inheriting application.
209     *
210     * ```js
211     * app.mixin('foo', function() {
212     *   // do stuff
213     * });
214     * ```
215     * @name .mixin
216     * @param {String} `key`
217     * @param {Object|Array} `val`
218     * @return {Object} Returns the `base` instance for chaining.
219     * @api public
220     */
221  
222    Base.prototype.mixin = function(key, val) {
223      Base.prototype[key] = val;
224      return this;
225    };
226  
227    /**
228     * Non-enumberable mixin array, used by the static [Base.mixin]() method.
229     */
230  
231    Base.prototype.mixins = Base.prototype.mixins || [];
232  
233    /**
234     * Getter/setter used when creating nested instances of `Base`, for storing a reference
235     * to the first ancestor instance. This works by setting an instance of `Base` on the `parent`
236     * property of a "child" instance. The `base` property defaults to the current instance if
237     * no `parent` property is defined.
238     *
239     * ```js
240     * // create an instance of `Base`, this is our first ("base") instance
241     * var first = new Base();
242     * first.foo = 'bar'; // arbitrary property, to make it easier to see what's happening later
243     *
244     * // create another instance
245     * var second = new Base();
246     * // create a reference to the first instance (`first`)
247     * second.parent = first;
248     *
249     * // create another instance
250     * var third = new Base();
251     * // create a reference to the previous instance (`second`)
252     * // repeat this pattern every time a "child" instance is created
253     * third.parent = second;
254     *
255     * // we can always access the first instance using the `base` property
256     * console.log(first.base.foo);
257     * //=> 'bar'
258     * console.log(second.base.foo);
259     * //=> 'bar'
260     * console.log(third.base.foo);
261     * //=> 'bar'
262     * // and now you know how to get to third base ;)
263     * ```
264     * @name .base
265     * @api public
266     */
267  
268    Object.defineProperty(Base.prototype, 'base', {
269      configurable: true,
270      get: function() {
271        return this.parent ? this.parent.base : this;
272      }
273    });
274  
275    /**
276     * Static method for adding global plugin functions that will
277     * be added to an instance when created.
278     *
279     * ```js
280     * Base.use(function(app) {
281     *   app.foo = 'bar';
282     * });
283     * var app = new Base();
284     * console.log(app.foo);
285     * //=> 'bar'
286     * ```
287     * @name #use
288     * @param {Function} `fn` Plugin function to use on each instance.
289     * @return {Object} Returns the `Base` constructor for chaining
290     * @api public
291     */
292  
293    define(Base, 'use', function(fn) {
294      fns.push(fn);
295      return Base;
296    });
297  
298    /**
299     * Run an array of functions by passing each function
300     * to a method on the given object specified by the given property.
301     *
302     * @param  {Object} `obj` Object containing method to use.
303     * @param  {String} `prop` Name of the method on the object to use.
304     * @param  {Array} `arr` Array of functions to pass to the method.
305     */
306  
307    define(Base, 'run', function(obj, prop, arr) {
308      var len = arr.length, i = 0;
309      while (len--) {
310        obj[prop](arr[i++]);
311      }
312      return Base;
313    });
314  
315    /**
316     * Static method for inheriting the prototype and static methods of the `Base` class.
317     * This method greatly simplifies the process of creating inheritance-based applications.
318     * See [static-extend][] for more details.
319     *
320     * ```js
321     * var extend = cu.extend(Parent);
322     * Parent.extend(Child);
323     *
324     * // optional methods
325     * Parent.extend(Child, {
326     *   foo: function() {},
327     *   bar: function() {}
328     * });
329     * ```
330     * @name #extend
331     * @param {Function} `Ctor` constructor to extend
332     * @param {Object} `methods` Optional prototype properties to mix in.
333     * @return {Object} Returns the `Base` constructor for chaining
334     * @api public
335     */
336  
337    define(Base, 'extend', cu.extend(Base, function(Ctor, Parent) {
338      Ctor.prototype.mixins = Ctor.prototype.mixins || [];
339  
340      define(Ctor, 'mixin', function(fn) {
341        var mixin = fn(Ctor.prototype, Ctor);
342        if (typeof mixin === 'function') {
343          Ctor.prototype.mixins.push(mixin);
344        }
345        return Ctor;
346      });
347  
348      define(Ctor, 'mixins', function(Child) {
349        Base.run(Child, 'mixin', Ctor.prototype.mixins);
350        return Ctor;
351      });
352  
353      Ctor.prototype.mixin = function(key, value) {
354        Ctor.prototype[key] = value;
355        return this;
356      };
357      return Base;
358    }));
359  
360    /**
361     * Used for adding methods to the `Base` prototype, and/or to the prototype of child instances.
362     * When a mixin function returns a function, the returned function is pushed onto the `.mixins`
363     * array, making it available to be used on inheriting classes whenever `Base.mixins()` is
364     * called (e.g. `Base.mixins(Child)`).
365     *
366     * ```js
367     * Base.mixin(function(proto) {
368     *   proto.foo = function(msg) {
369     *     return 'foo ' + msg;
370     *   };
371     * });
372     * ```
373     * @name #mixin
374     * @param {Function} `fn` Function to call
375     * @return {Object} Returns the `Base` constructor for chaining
376     * @api public
377     */
378  
379    define(Base, 'mixin', function(fn) {
380      var mixin = fn(Base.prototype, Base);
381      if (typeof mixin === 'function') {
382        Base.prototype.mixins.push(mixin);
383      }
384      return Base;
385    });
386  
387    /**
388     * Static method for running global mixin functions against a child constructor.
389     * Mixins must be registered before calling this method.
390     *
391     * ```js
392     * Base.extend(Child);
393     * Base.mixins(Child);
394     * ```
395     * @name #mixins
396     * @param {Function} `Child` Constructor function of a child class
397     * @return {Object} Returns the `Base` constructor for chaining
398     * @api public
399     */
400  
401    define(Base, 'mixins', function(Child) {
402      Base.run(Child, 'mixin', Base.prototype.mixins);
403      return Base;
404    });
405  
406    /**
407     * Similar to `util.inherit`, but copies all static properties, prototype properties, and
408     * getters/setters from `Provider` to `Receiver`. See [class-utils][]{#inherit} for more details.
409     *
410     * ```js
411     * Base.inherit(Foo, Bar);
412     * ```
413     * @name #inherit
414     * @param {Function} `Receiver` Receiving (child) constructor
415     * @param {Function} `Provider` Providing (parent) constructor
416     * @return {Object} Returns the `Base` constructor for chaining
417     * @api public
418     */
419  
420    define(Base, 'inherit', cu.inherit);
421    define(Base, 'bubble', cu.bubble);
422    return Base;
423  }
424  
425  /**
426   * Expose `Base` with default settings
427   */
428  
429  module.exports = namespace();
430  
431  /**
432   * Allow users to define a namespace
433   */
434  
435  module.exports.namespace = namespace;