'use strict';
|
|
var util = require('util');
|
var define = require('define-property');
|
var CacheBase = require('cache-base');
|
var Emitter = require('component-emitter');
|
var isObject = require('isobject');
|
var merge = require('mixin-deep');
|
var pascal = require('pascalcase');
|
var cu = require('class-utils');
|
|
/**
|
* Optionally define a custom `cache` namespace to use.
|
*/
|
|
function namespace(name) {
|
var Cache = name ? CacheBase.namespace(name) : CacheBase;
|
var fns = [];
|
|
/**
|
* Create an instance of `Base` with the given `config` and `options`.
|
*
|
* ```js
|
* // initialize with `config` and `options`
|
* var app = new Base({isApp: true}, {abc: true});
|
* app.set('foo', 'bar');
|
*
|
* // values defined with the given `config` object will be on the root of the instance
|
* console.log(app.baz); //=> undefined
|
* console.log(app.foo); //=> 'bar'
|
* // or use `.get`
|
* console.log(app.get('isApp')); //=> true
|
* console.log(app.get('foo')); //=> 'bar'
|
*
|
* // values defined with the given `options` object will be on `app.options
|
* console.log(app.options.abc); //=> true
|
* ```
|
*
|
* @param {Object} `config` If supplied, this object is passed to [cache-base][] to merge onto the the instance upon instantiation.
|
* @param {Object} `options` If supplied, this object is used to initialize the `base.options` object.
|
* @api public
|
*/
|
|
function Base(config, options) {
|
if (!(this instanceof Base)) {
|
return new Base(config, options);
|
}
|
Cache.call(this, config);
|
this.is('base');
|
this.initBase(config, options);
|
}
|
|
/**
|
* Inherit cache-base
|
*/
|
|
util.inherits(Base, Cache);
|
|
/**
|
* Add static emitter methods
|
*/
|
|
Emitter(Base);
|
|
/**
|
* Initialize `Base` defaults with the given `config` object
|
*/
|
|
Base.prototype.initBase = function(config, options) {
|
this.options = merge({}, this.options, options);
|
this.cache = this.cache || {};
|
this.define('registered', {});
|
if (name) this[name] = {};
|
|
// make `app._callbacks` non-enumerable
|
this.define('_callbacks', this._callbacks);
|
if (isObject(config)) {
|
this.visit('set', config);
|
}
|
Base.run(this, 'use', fns);
|
};
|
|
/**
|
* Set the given `name` on `app._name` and `app.is*` properties. Used for doing
|
* lookups in plugins.
|
*
|
* ```js
|
* app.is('foo');
|
* console.log(app._name);
|
* //=> 'foo'
|
* console.log(app.isFoo);
|
* //=> true
|
* app.is('bar');
|
* console.log(app.isFoo);
|
* //=> true
|
* console.log(app.isBar);
|
* //=> true
|
* console.log(app._name);
|
* //=> 'bar'
|
* ```
|
* @name .is
|
* @param {String} `name`
|
* @return {Boolean}
|
* @api public
|
*/
|
|
Base.prototype.is = function(name) {
|
if (typeof name !== 'string') {
|
throw new TypeError('expected name to be a string');
|
}
|
this.define('is' + pascal(name), true);
|
this.define('_name', name);
|
this.define('_appname', name);
|
return this;
|
};
|
|
/**
|
* Returns true if a plugin has already been registered on an instance.
|
*
|
* Plugin implementors are encouraged to use this first thing in a plugin
|
* to prevent the plugin from being called more than once on the same
|
* instance.
|
*
|
* ```js
|
* var base = new Base();
|
* base.use(function(app) {
|
* if (app.isRegistered('myPlugin')) return;
|
* // do stuff to `app`
|
* });
|
*
|
* // to also record the plugin as being registered
|
* base.use(function(app) {
|
* if (app.isRegistered('myPlugin', true)) return;
|
* // do stuff to `app`
|
* });
|
* ```
|
* @name .isRegistered
|
* @emits `plugin` Emits the name of the plugin being registered. Useful for unit tests, to ensure plugins are only registered once.
|
* @param {String} `name` The plugin name.
|
* @param {Boolean} `register` If the plugin if not already registered, to record it as being registered pass `true` as the second argument.
|
* @return {Boolean} Returns true if a plugin is already registered.
|
* @api public
|
*/
|
|
Base.prototype.isRegistered = function(name, register) {
|
if (this.registered.hasOwnProperty(name)) {
|
return true;
|
}
|
if (register !== false) {
|
this.registered[name] = true;
|
this.emit('plugin', name);
|
}
|
return false;
|
};
|
|
/**
|
* Define a plugin function to be called immediately upon init. Plugins are chainable
|
* and expose the following arguments to the plugin function:
|
*
|
* - `app`: the current instance of `Base`
|
* - `base`: the [first ancestor instance](#base) of `Base`
|
*
|
* ```js
|
* var app = new Base()
|
* .use(foo)
|
* .use(bar)
|
* .use(baz)
|
* ```
|
* @name .use
|
* @param {Function} `fn` plugin function to call
|
* @return {Object} Returns the item instance for chaining.
|
* @api public
|
*/
|
|
Base.prototype.use = function(fn) {
|
fn.call(this, this);
|
return this;
|
};
|
|
/**
|
* The `.define` method is used for adding non-enumerable property on the instance.
|
* Dot-notation is **not supported** with `define`.
|
*
|
* ```js
|
* // arbitrary `render` function using lodash `template`
|
* app.define('render', function(str, locals) {
|
* return _.template(str)(locals);
|
* });
|
* ```
|
* @name .define
|
* @param {String} `key` The name of the property to define.
|
* @param {any} `value`
|
* @return {Object} Returns the instance for chaining.
|
* @api public
|
*/
|
|
Base.prototype.define = function(key, val) {
|
if (isObject(key)) {
|
return this.visit('define', key);
|
}
|
define(this, key, val);
|
return this;
|
};
|
|
/**
|
* Mix property `key` onto the Base prototype. If base is inherited using
|
* `Base.extend` this method will be overridden by a new `mixin` method that will
|
* only add properties to the prototype of the inheriting application.
|
*
|
* ```js
|
* app.mixin('foo', function() {
|
* // do stuff
|
* });
|
* ```
|
* @name .mixin
|
* @param {String} `key`
|
* @param {Object|Array} `val`
|
* @return {Object} Returns the `base` instance for chaining.
|
* @api public
|
*/
|
|
Base.prototype.mixin = function(key, val) {
|
Base.prototype[key] = val;
|
return this;
|
};
|
|
/**
|
* Non-enumberable mixin array, used by the static [Base.mixin]() method.
|
*/
|
|
Base.prototype.mixins = Base.prototype.mixins || [];
|
|
/**
|
* Getter/setter used when creating nested instances of `Base`, for storing a reference
|
* to the first ancestor instance. This works by setting an instance of `Base` on the `parent`
|
* property of a "child" instance. The `base` property defaults to the current instance if
|
* no `parent` property is defined.
|
*
|
* ```js
|
* // create an instance of `Base`, this is our first ("base") instance
|
* var first = new Base();
|
* first.foo = 'bar'; // arbitrary property, to make it easier to see what's happening later
|
*
|
* // create another instance
|
* var second = new Base();
|
* // create a reference to the first instance (`first`)
|
* second.parent = first;
|
*
|
* // create another instance
|
* var third = new Base();
|
* // create a reference to the previous instance (`second`)
|
* // repeat this pattern every time a "child" instance is created
|
* third.parent = second;
|
*
|
* // we can always access the first instance using the `base` property
|
* console.log(first.base.foo);
|
* //=> 'bar'
|
* console.log(second.base.foo);
|
* //=> 'bar'
|
* console.log(third.base.foo);
|
* //=> 'bar'
|
* // and now you know how to get to third base ;)
|
* ```
|
* @name .base
|
* @api public
|
*/
|
|
Object.defineProperty(Base.prototype, 'base', {
|
configurable: true,
|
get: function() {
|
return this.parent ? this.parent.base : this;
|
}
|
});
|
|
/**
|
* Static method for adding global plugin functions that will
|
* be added to an instance when created.
|
*
|
* ```js
|
* Base.use(function(app) {
|
* app.foo = 'bar';
|
* });
|
* var app = new Base();
|
* console.log(app.foo);
|
* //=> 'bar'
|
* ```
|
* @name #use
|
* @param {Function} `fn` Plugin function to use on each instance.
|
* @return {Object} Returns the `Base` constructor for chaining
|
* @api public
|
*/
|
|
define(Base, 'use', function(fn) {
|
fns.push(fn);
|
return Base;
|
});
|
|
/**
|
* Run an array of functions by passing each function
|
* to a method on the given object specified by the given property.
|
*
|
* @param {Object} `obj` Object containing method to use.
|
* @param {String} `prop` Name of the method on the object to use.
|
* @param {Array} `arr` Array of functions to pass to the method.
|
*/
|
|
define(Base, 'run', function(obj, prop, arr) {
|
var len = arr.length, i = 0;
|
while (len--) {
|
obj[prop](arr[i++]);
|
}
|
return Base;
|
});
|
|
/**
|
* Static method for inheriting the prototype and static methods of the `Base` class.
|
* This method greatly simplifies the process of creating inheritance-based applications.
|
* See [static-extend][] for more details.
|
*
|
* ```js
|
* var extend = cu.extend(Parent);
|
* Parent.extend(Child);
|
*
|
* // optional methods
|
* Parent.extend(Child, {
|
* foo: function() {},
|
* bar: function() {}
|
* });
|
* ```
|
* @name #extend
|
* @param {Function} `Ctor` constructor to extend
|
* @param {Object} `methods` Optional prototype properties to mix in.
|
* @return {Object} Returns the `Base` constructor for chaining
|
* @api public
|
*/
|
|
define(Base, 'extend', cu.extend(Base, function(Ctor, Parent) {
|
Ctor.prototype.mixins = Ctor.prototype.mixins || [];
|
|
define(Ctor, 'mixin', function(fn) {
|
var mixin = fn(Ctor.prototype, Ctor);
|
if (typeof mixin === 'function') {
|
Ctor.prototype.mixins.push(mixin);
|
}
|
return Ctor;
|
});
|
|
define(Ctor, 'mixins', function(Child) {
|
Base.run(Child, 'mixin', Ctor.prototype.mixins);
|
return Ctor;
|
});
|
|
Ctor.prototype.mixin = function(key, value) {
|
Ctor.prototype[key] = value;
|
return this;
|
};
|
return Base;
|
}));
|
|
/**
|
* Used for adding methods to the `Base` prototype, and/or to the prototype of child instances.
|
* When a mixin function returns a function, the returned function is pushed onto the `.mixins`
|
* array, making it available to be used on inheriting classes whenever `Base.mixins()` is
|
* called (e.g. `Base.mixins(Child)`).
|
*
|
* ```js
|
* Base.mixin(function(proto) {
|
* proto.foo = function(msg) {
|
* return 'foo ' + msg;
|
* };
|
* });
|
* ```
|
* @name #mixin
|
* @param {Function} `fn` Function to call
|
* @return {Object} Returns the `Base` constructor for chaining
|
* @api public
|
*/
|
|
define(Base, 'mixin', function(fn) {
|
var mixin = fn(Base.prototype, Base);
|
if (typeof mixin === 'function') {
|
Base.prototype.mixins.push(mixin);
|
}
|
return Base;
|
});
|
|
/**
|
* Static method for running global mixin functions against a child constructor.
|
* Mixins must be registered before calling this method.
|
*
|
* ```js
|
* Base.extend(Child);
|
* Base.mixins(Child);
|
* ```
|
* @name #mixins
|
* @param {Function} `Child` Constructor function of a child class
|
* @return {Object} Returns the `Base` constructor for chaining
|
* @api public
|
*/
|
|
define(Base, 'mixins', function(Child) {
|
Base.run(Child, 'mixin', Base.prototype.mixins);
|
return Base;
|
});
|
|
/**
|
* Similar to `util.inherit`, but copies all static properties, prototype properties, and
|
* getters/setters from `Provider` to `Receiver`. See [class-utils][]{#inherit} for more details.
|
*
|
* ```js
|
* Base.inherit(Foo, Bar);
|
* ```
|
* @name #inherit
|
* @param {Function} `Receiver` Receiving (child) constructor
|
* @param {Function} `Provider` Providing (parent) constructor
|
* @return {Object} Returns the `Base` constructor for chaining
|
* @api public
|
*/
|
|
define(Base, 'inherit', cu.inherit);
|
define(Base, 'bubble', cu.bubble);
|
return Base;
|
}
|
|
/**
|
* Expose `Base` with default settings
|
*/
|
|
module.exports = namespace();
|
|
/**
|
* Allow users to define a namespace
|
*/
|
|
module.exports.namespace = namespace;
|
