bugcore
Version:
bugcore is a JavaScript library that provides a foundational architecture for object oriented JS
2,239 lines (1,475 loc) • 102 kB
Markdown
<br />
------------------------------------------------------------------------------------
# bugcore
bugcore is a JavaScript library that provides a foundational architecture for
object oriented JS. It is designed to work both within node js as well as
directly in the browser.
bugcore provides a basic class model based on John Resig's [simple JavaScript
inheritance](http://ejohn.org/blog/simple-javascript-inheritance/). In addition
the library provides many basic data models and utility classes for common
object oriented patterns.
If the library is missing something you need, please let us know!
NOTE: This documentation is still being written. If you click on a link and it
doesn't go anywhere, it's likely because that portion of the docs hasn't been
written yet. If there are parts of the docs you'd like us to focus on, feel
free to ask!
## Build Status
[](http://badge.fury.io/js/bugcore)<br />
[](https://codeclimate.com/github/airbug/bugcore)<br />
[](https://nodei.co/npm/bugcore/)
## Quick Examples
Creation of a new class
```javascript
var Class = bugcore.Class;
var Obj = bugcore.Obj;
var SomeClassConstructor = Class.extend(Obj, {});
```
Creation of a new class with an internal _constructor method
```javascript
var SomeClassConstructor = Class.extend(Obj, {
_constructor: function() {
this._super(); // Call super constructor
}
});
```
Creation of a new class with overridden equals and hashCode methods
```javascript
/**
* @class
* @extends {Obj}
*/
var SomeClassConstructor = Class.extend(Obj, {
/**
* @constructs
* @param {number} a
* @param {number} b
*/
_constructor: function(a, b) {
this._super(); // Call super constructor
/**
* @private
* @type {number}
*/
this.a = a;
/**
* @private
* @type {string}
*/
this.b = b
},
/**
* @override
* @param {*} value
* @return {boolean}
*/
equals: function(value) {
if (Class.doesExtend(value, SomeClass)) {
return (Obj.equals(value.a, this.a) && Obj.equals(value.b, this.b));
}
return false;
},
/**
* @override
* @return {number}
*/
hashCode: function() {
if (!this._hashCode) {
this._hashCode = Obj.hashCode("[SomeClass]" +
Obj.hashCode(this.a) + Obj.hashCode(this.b));
}
return this._hashCode;
},
});
```
Use of a Map
```javascript
var myMap = new bugcore.Map();
myMap.put("key1", "value1");
myMap.put("key2", "value2");
myMap.get("key1"); // "value1"
myMap.get("key2"); // "value2"
```
Use of a Map with instances as keys
```javascript
var myMap = new bugcore.Map();
// SomeClass is from the above example that uses overridden equals and hashCode methods
var instance1 = new SomeClass(123, "abc");
var instance2 = new SomeClass(123, "abc");
myMap.put(instance1, "value");
myMap.put(instance2, "value2");
//hash codes and equality checks are equal therefore the two instances are considered
//the same key even though they are separate instances in memory
myMap.getCount(); // 1
myMap.get(instance1) // "value2"
myMap.get(instance2) // "value2"
```
## Dependencies
bugcore is dependent upon the [bugpack](https://github.com/airbug/bugpack) framework
## Download Source
The source is available for download from [GitHub](https://github.com/airbug/bugcore)
From the web, you can download the packaged scripts here
https://s3.amazonaws.com/public-airbug/bugcore-0.3.27.js
https://s3.amazonaws.com/public-airbug/bugcore-0.3.27.min.js
## Install
For node js, you can install using Node Package Manager [npm](https://www.npmjs.org/package/bugcore)
npm install bugcore
For the web, simply include these scripts in your application
```html
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugpack-0.2.2.min.js"></script>
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugcore-0.3.27.min.js"></script>
```
## Usage
In node js:
npm will install the bugpack dependency
```javascript
var bugcore = require('bugcore');
var map = new bugcore.Map();
```
In the browser:
```html
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugpack-0.2.2.js"></script>
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugcore-0.3.27.js"></script>
<script type="text/javascript">
var map = new bugcore.Map();
</script>
```
## Documentation
### Change Classes
* [`AddAtChange`](#AddAtChange)
* [`AddChange`](#AddChange)
* [`Change`](#Change)
* [`ClearChange`](#ClearChange)
* [`PutChange`](#PutChange)
* [`RemoveAtChange`](#RemoveAtChange)
* [`RemoveChange`](#RemoveChange)
* [`RemovePropertyChange`](#RemovePropertyChange)
* [`SetPropertyChange`](#SetPropertyChange)
### Command Classes
* [`Command`](#Command)
* [`CommandBatch`](#CommandBatch)
* [`CommandProcessor`](#CommandProcessor)
### Concurrent Classes
* [`Lock`](#Lock)
* [`LockMap`](#LockMap)
* [`LockStriped`](#LockStriped)
* [`Semaphore`](#Semaphore)
### Core Classes
* [`Class`](#Class)
* [`Constructor`](#Constructor)
* [`Func`](#Func)
* [`Implementable`](#Implementable)
* [`Interface`](#Interface)
* [`Obj`](#Obj)
### Core Interfaces
* [`IClone`](#IClone)
* [`IEquals`](#IEquals)
* [`IHashCode`](#IHashCode)
### Data Classes
* [`BidiMap`](#BidiMap)
* [`Collection`](#Collection)
* [`Collections`](#Collections)
* [`DependencyGraph`](#DependencyGraph)
* [`Document`](#Document)
* [`DualMap`](#DualMap)
* [`DualMultiMap`](#DualMultiMap)
* [`DualMultiSetMap`](#DualMultiSetMap)
* [`Graph`](#Graph)
* [`GraphEdge`](#GraphEdge)
* [`GraphNode`](#GraphNode)
* [`HashStore`](#HashStore)
* [`HashStoreNode`](#HashStoreNode)
* [`HashTable`](#HashTable)
* [`HashTableNode`](#HashTableNode)
* [`List`](#List)
* [`Map`](#Map)
* [`MultiListMap`](#MultiListMap)
* [`MultiMap`](#MultiMap)
* [`MultiSetMap`](#MultiSetMap)
* [`Pair`](#Pair)
* [`Queue`](#Queue)
* [`ReferenceGraph`](#ReferenceGraph)
* [`Set`](#Set)
* [`Stack`](#Stack)
* [`Striped`](#Striped)
* [`Tree`](#Tree)
* [`TreeNode`](#TreeNode)
* [`UnorderedPair`](#UnorderedPair)
* [`Url`](#Url)
* [`WeightedList`](#WeightedList)
* [`WeightedListNode`](#WeightedListNode)
### Data Interfaces
* [`IArrayable`](#IArrayable)
* [`ICollection`](#ICollection)
* [`IIterable`](#IIterable)
* [`IIterator`](#IIterator)
* [`IList`](#IList)
* [`IMap`](#IMap)
* [`IObjectable`](#IObjectable)
* [`ISet`](#ISet)
### Event Classes
* [`Event`](#Event)
* [`EventDispatcher`](#EventDispatcher)
* [`EventListener`](#EventListener)
* [`EventPropagator`](#EventPropagator)
* [`EventQuery`](#EventQuery)
* [`EventQueryBuilder`](#EventQueryBuilder)
* [`EventQueryListener`](#EventQueryListener)
* [`EventReceiver`](#EventReceiver)
### Event Interfaces
* [`IEventDispatcher`](#IEventDispatcher)
* [`IEventPropagator`](#IEventPropagator)
* [`IEventReceiver`](#IEventReceiver)
### Flow Classes
* [`Flow`](#Flow)
* [`Flows`](#Flows)
* [`ForEachParallel`](#ForEachParallel)
* [`ForEachSeries`](#ForEachSeries)
* [`ForInParallel`](#ForInParallel)
* [`ForInSeries`](#ForInSeries)
* [`If`](#If)
* [`IterableParallel`](#IterableParallel)
* [`IterableSeries`](#IterableSeries)
* [`Iteration`](#Iteration)
* [`IterableFlow`](#IterableFlow)
* [`Parallel`](#Parallel)
* [`Series`](#Series)
* [`Task`](#Task)
* [`WhileParallel`](#WhileParallel)
* [`WhileSeries`](#WhileSeries)
### Match Classes
* [`ObjectPathMatcher`](#ObjectPathMatcher)
### Observable Classes
* [`Observable`](#Observable)
* [`ObservableArray`](#ObservableArray)
* [`ObservableCollection`](#ObservableCollection)
* [`ObservableList`](#ObservableList)
* [`ObservableMap`](#ObservableMap)
* [`ObservableObject`](#ObservableObject)
* [`ObservableSet`](#ObservableSet)
* [`Observation`](#Observation)
* [`ObservationPropagator`](#ObservationPropagator)
* [`Observer`](#Observer)
### Observable Interfaces
* [`IObservable`](#IObservable)
* [`IObservationPropagator`](#IObservationPropagator)
### Promise Classes
* [`Deferred`](#Deferred)
* [`FinallyHandler`](#FinallyHandler)
* [`FulfilledHandler`](#FulfilledHandler)
* [`Handler`](#Handler)
* [`Promise`](#Promise)
* [`Promises`](#Promises)
* [`RejectedHandler`](#RejectedHandler)
* [`Resolver`](#Resolver)
### Promise Interfaces
* [`IPromise`](#IPromise)
### Proxy Classes
* [`Proxy`](#Proxy)
* [`ProxyMethod`](#ProxyMethod)
* [`ProxyObject`](#ProxyObject)
* [`ProxyProperty`](#ProxyProperty)
### Proxy Interfaces
* [`IProxy`](#IProxy)
### Publisher Classes
* [`Publisher`](#Publisher)
* [`PublisherMessage`](#PublisherMessage)
* [`PublisherSubscription`](#PublisherSubscription)
### Query Classes
* [`Query`](#Query)
* [`QueryBuilder`](#QueryBuilder)
* [`WhereCondition`](#WhereCondition)
* [`WhereConditionBuilder`](#WhereConditionBuilder)
### Query Interfaces
* [`ICondition`](#ICondition)
* [`IConditionBuilder`](#IConditionBuilder)
### State Classes
* [`StateEvent`](#StateEvent)
* [`StateMachine`](#StateMachine)
### Stream Classes
* [`ArraySupplier`](#ArraySupplier)
* [`CollectConsumer`](#CollectConsumer)
* [`Consumer`](#Consumer)
* [`EachOperation`](#EachOperation)
* [`FilterOperation`](#FilterOperation)
* [`IterableSupplier`](#IterableSupplier)
* [`MapOperation`](#MapOperation)
* [`ReduceConsumer`](#ReduceConsumer)
* [`Stream`](#Stream)
* [`Supplier`](#Supplier)
* [`Suppliers`](#Suppliers)
### Stream Interfaces
* [`IConsumer`](#IConsumer)
* [`IStreamable`](#IStreamable)
* [`IStreamOperation`](#IStreamOperation)
* [`ISupplier`](#ISupplier)
### Throwable Classes
* [`ArgumentBug`](#ArgumentBug)
* [`Bug`](#Bug)
* [`Exception`](#Exception)
* [`MappedParallelException`](#MappedParallelException)
* [`MappedThrowable`](#MappedThrowable)
* [`ParallelException`](#ParallelException)
* [`Throwable`](#Throwable)
### Trace Classes
* [`Trace`](#Trace)
* [`Tracer`](#Tracer)
### Util Classes
* [`ArgUtil`](#ArgUtil)
* [`ArrayUtil`](#ArrayUtil)
* [`Config`](#Config)
* [`DateUtil`](#DateUtil)
* [`HashUtil`](#HashUtil)
* [`HtmlUtil`](#HtmlUtil)
* [`IdGenerator`](#IdGenerator)
* [`LiteralUtil`](#LiteralUtil)
* [`MathUtil`](#MathUtil)
* [`ObjectUtil`](#ObjectUtil)
* [`Properties`](#Properties)
* [`PropertiesChain`](#PropertiesChain)
* [`StackTraceUtil`](#StackTraceUtil)
* [`StringUtil`](#StringUtil)
* [`TypeUtil`](#TypeUtil)
* [`UuidGenerator`](#UuidGenerator)
* [`WeightedRandomizer`](#WeightedRandomizer)
### Validator Classes
* [`ValidationMachine`](#ValidationMachine)
* [`Validator`](#Validator)
* [`ValidatorGroup`](#ValidatorGroup)
* [`ValidatorProcessor`](#ValidatorProcessor)
<br /><a name="AddAtChange" />
## AddAtChange
TODO
<br /><a name="AddChange" />
## AddChange
TODO
<br /><a name="Change" />
## Change
TODO
<br /><a name="ClearChange" />
## ClearChange
TODO
<br /><a name="PutChange" />
## PutChange
TODO
<br /><a name="RemoveAtChange" />
## RemoveAtChange
TODO
<br /><a name="RemoveChange" />
## RemoveChange
TODO
<br /><a name="RemovePropertyChange" />
## RemovePropertyChange
TODO
<br /><a name="SetPropertyChange" />
## SetPropertyChange
TODO
<br /><a name="Command" />
## Command
TODO
<br /><a name="CommandBatch" />
## CommandBatch
TODO
<br /><a name="CommandProcessor" />
## CommandProcessor
TODO
<br /><a name="Lock" />
## Lock
TODO
<br /><a name="LockMap" />
## LockMap
TODO
<br /><a name="LockStriped" />
## LockStriped
TODO
<br /><a name="Semaphore" />
## Semaphore
TODO
<br /><a name="Class"></a>
## Class
Core class used to build other classes.
__Class__
```javascript
/**
* @constructor
* @param {function(new:Constructor)} constructor
* @param {Array.<Interface>} interfaces
* @param {string} name
* @param {Class} superclass
*/
var Class = function(constructor, interfaces, name, superclass) {
```
[View code](https://github.com/airbug/bugcore/blob/v0.3.12/libraries/bugcore/js/src/core/Class.js)
__Constructor Summary__
Access | Signature
--- | ---
constructor | <code>[Class](#Class_constructor)({[Constructor](#Constructor)} constructor, {[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<[Interface](#Interface)>} interfaces, {string} name, {[Class](#Class)} superclass)</code>
__Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[getConstructor](#Class_getConstructor)()</code> | <code>{function(new:[Constructor](#Constructor))}</code>
public | <code>[getInterfaces](#Class_getInterfaces)()</code> | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<[Interface](#Interface)>}</code>
public | <code>[getName](#Class_getName)()</code> | <code>{string}</code>
public | <code>[getSuperclass](#Class_getSuperclass)()</code> | <code>{[Class](#Class)}</code>
__Method Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[alloc](#Class_alloc)({*...} args)</code> | <code>{[Constructor](#Constructor)}</code>
public | <code>[allocWithArray](#Class_allocWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)</code> | <code>{[Constructor](#Constructor)}</code>
public | <code>[newInstance](#Class_newInstance)({*...} args)</code> | <code>{[Constructor](#Constructor)}</code>
public | <code>[newInstanceWithArray](#Class_newInstanceWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)</code> | <code>{[Constructor](#Constructor)}</code>
__Static Method Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[declare](#Class-declare)({[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)</code> | <code>{function(new:[Constructor](#Constructor))}</code>
static public | <code>[doesExtend](#Class-doesExtend)({*} value, {function(new:[Constructor](#Constructor))} constructor)</code> | <code>{boolean}</code>
static public | <code>[doesImplement](#Class-doesImplement)({*} value, {function(new:[Implementable](#Implementable))} implementable)</code> | <code>{boolean}</code>
static public | <code>[extend](#Class-extend)({function(new:[Constructor](#Constructor))} constructor, {[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)</code> | <code>{function(new:[Constructor](#Constructor))}</code>
static public | <code>[implement](#Class-implement)({function(new:[Constructor](#Constructor))} constructor, {function(new:[Implementable](#Implementable))} implementable)</code> | None
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_constructor"></a>
### Class(constructor, interfaces, name, superclass)
__Method__
```javascript
/**
* @constructor
* @param {function(new:Constructor)} constructor
* @param {Array.<Interface>} interfaces
* @param {string} name
* @param {Class} superclass
*/
var Class = function(constructor, interfaces, name, superclass) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`constructor` | <code>{function(new:[Constructor](#Constructor)}</code> | The Constructor of this class.
`interfaces` | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<[Interface](#Interface)>}</code> | Any Interfaces that this Class implements.
`name` | <code>{string}</code> | The name of this Class.
`superclass` | <code>{[Class](#Class)}</code> | The superclass of this Class.
__Examples__
```js
var myClass = new Class(constructor, interfaces, name, superclass);
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_getConstructor"></a>
### Class#getConstructor()
Get the Class's Constructor function
__Method__
```javascript
/**
* @return {function(new:Constructor)}
*/
getConstructor: function() {
```
__Parameters__
* None
__Returns__
* <code>{function(new:[Constructor](#Constructor))}</code> - The Class's Constructor function.
__Examples__
```javascript
/** @type {function(new:MyClassConstructor)} */
var MyClassConstructor = Class.extend(Obj, {});
/** @type {Class} */
var MyClass = MyClassConstructor.getClass();
console.log(MyClassConstructor === MyClass.getConstructor()); // true
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_getInterfaces"></a>
### Class#getInterfaces()
Get the Class's implemented Interfaces
__Method__
```javascript
/**
* @return {Array.<Interface>}
*/
getInterfaces: function() {
```
__Parameters__
* None
__Returns__
* <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<[Interface](#Interface)>}</code> - The Class's implemented Interfaces.
__Examples__
```javascript
var MyInterface = Interface.declare({
myMethod: function() {}
});
var MyClassConstructor = Class.extend(Obj, {
myMethod: function() {}
});
Class.implement(MyClassConstructor, MyInterface);
var MyClass = MyClassConstructor.getClass();
MyClass.getInterfaces(); // [ MyInterface ]
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_getName" />
### Class#getName()
Get the Class's name (if one was supplied)
__Method__
```javascript
/**
* @return {string}
*/
getName: function() {
```
__Parameters__
* None
__Returns__
* <code>{string}</code> - The Class's name.
__Examples__
```javascript
var MyClassConstructor = Class.extend(Obj, {
_name: "MyClass"
});
var MyClass = MyClassConstructor.getClass();
MyClass.getName(); // "MyClass"
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_getSuperclass" />
### Class#getSuperclass()
Get the Class's superclass (if there is one)
__Method__
```javascript
/**
* @return {Class}
*/
getSuperclass: function() {
```
__Parameters__
* None
__Returns__
* <code>{[Class](#Class)}</code> - The Class's superclass.
__Examples__
Extended Class
```javascript
var MyClassConstructor = Class.extend(Obj, {});
var MyClass = MyClassConstructor.getClass();
console.log(MyClass.getSuperclass() === Obj.getClass()); // true
```
Declared Class
```javascript
var MyBaseClassConstructor = Class.declare({});
var MyBaseClass = MyBaseClassConstructor.getClass();
MyBaseClass.getSuperclass(); // null
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_alloc" />
### Class#alloc()
This method allocates and returns a new instance of this Class that has only been constructed. It passes all
arguments through to the constructor.
__Method__
```javascript
/**
* @param {...} args
* @return {Constructor}
*/
alloc: function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{...}</code> | Any number of arguments of any type.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var BaseBallClass = BaseBall.getClass();
var myBaseBall = BaseBallClass.alloc("arg1", "arg2");
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_allocWithArray" />
### Class#allocWithArray()
This method allocates and returns a new instance of this Class that has only been constructed. It uses an array
as the arguments to apply to the constructor.
__Method__
```javascript
/**
* @param {Array.<*>=} args
* @return {Constructor}
*/
allocWithArray: function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}</code> | An array of args to apply to the constructor.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var BaseBallClass = BaseBall.getClass();
var myBaseBall = BaseBallClass.allocWithArray(["arg1", "arg2"]);
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_newInstance" />
### Class#newInstance()
This method returns a new instance of this Class that has been both constructed and initialized. It passes all
arguments through to both the constructor as well as the init methods.
__Method__
```javascript
/**
* @param {*...} args
* @return {Constructor}
*/
newInstance: function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{*...}</code> | Any number of arguments of any type.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var BaseBallClass = BaseBall.getClass();
var myBaseBall = BaseBallClass.newInstance("arg1", "arg2");
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class_newInstanceWithArray" />
### Class#newInstanceWithArray()
This method returns a new instance of this Class that has been both constructed and initialized. It uses an array
as the arguments to apply to both the constructor and the init methods.
__Method__
```javascript
/**
* @param {Array.<*>=} args
* @return {Constructor}
*/
newInstanceWithArray: function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}</code> | An array of args to apply to the constructor and init methods.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var BaseBallClass = BaseBall.getClass();
var myBaseBall = BaseBallClass.newInstanceWithArray(["arg1", "arg2"]);
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class-declare" />
### Class.declare(declaration)
This method is used to declare a low level base class in the bugcore system. Most of the
time you should not use this method to declare new classes unless you are sure of what
you are doing. Instead use the [Class.extend](#Class-extend) method and extend Obj. By
using this method, it will exclude many of the base methods that the rest of the bugcore
system depends upon, including hashCode, equals, _internalId, and clone
__Method__
```javascript
/**
* @static
* @param {Object.<string, *>} declaration
* @return {function(new:Constructor)}
*/
Class.declare = function(declaration) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`declaration` | <code>{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>}</cod> | An object that declares the methods of the new class.
__Returns__
* <code>{function(new:[Constructor](#Constructor))}</code> - The newly created class's constructor.
__Examples__
```javascript
var LowestLevelObject = Class.declare({
_constructor: function() {
// No need to call this._super, this is the lowest level.
}
});
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class-doesExtend" />
### Class.doesExtend(value, constructor)
This method is used to determine if a value extends a particular Constructor's Class. Instances of Classes are
considered to extend their own Class.
__Method__
```javascript
/**
* @static
* @param {*} value
* @param {function(new:Constructor)} constructor
* @return {boolean}
*/
Class.doesExtend = function(value, constructor) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`value` | <code>{*}</code> | The value to determine if it extends the given Constructor's Class
`constructor` | <code>{function(new:[Constructor](#Constructor))}</code> | The Constructor used to check if the value extends it's Class
__Returns__
* <code>{boolean}</code> - Whether or not the value extends the given Constructor's Class
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var myBaseBall = new BaseBall();
Class.doesExtend(myBaseBall, Ball); //true
Class.doesExtend(myBaseBall, BaseBall); //true
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class-doesImplement" />
### Class.doesImplement(value, implementable)
This method is used to determine if a value implements a particular Implementable's Interface.
__Method__
```javascript
/**
* @static
* @param {*} value
* @param {function(new:Implementable)} implementable
* @return {boolean}
*/
Class.doesImplement = function(value, implementable) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`value` | <code>{*}</code> | The value to determine if it implements the given Implementable's Interface
`constructor` | <code>{function(new:[Constructor](#Constructor))}</code> | The Constructor used to check if the value extends it's Class
__Returns__
* <code>{boolean}</code> - Whether or not the value implements the given Implementable's Interface
__Examples__
```javascript
var IBall = Interface.declare({});
var Ball = Class.declare({});
Class.implement(Ball, IBall);
var myBall = new Ball();
Class.doesImplement(myBall, IBall); //true
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class-extend" />
### Class.extend(constructor, declaration)
This method is used to extend another Class. It accepts the Class's Constructor as a parameter
and the declaration for the new Class.
__Notes__
* The declaration can include methods and default properties for the new Class.
* If you're creating a low level Class, it is best practice to extend [Obj](#Obj)
__Method__
```javascript
/**
* @static
* @param {function(new:Constructor)} constructor
* @param {Object.<string, *>} declaration
* @return {function(new:Constructor)}
*/
Class.extend = function(constructor, declaration) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`constructor` | <code>{function(new:[Constructor](#Constructor))}</code> | The constructor of the class to extend.
`declaration` | <code>{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>}</code> | An object that declares the methods of the new class.
__Returns__
* <code>{function(new:[Constructor](#Constructor))}</code> - The newly created class's constructor.
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {
_constructor: function(diameter) {
this._super(); // Call super constructor
this.diameter = diameter;
}
throwBall: function() {
}
});
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Class-implement" />
### Class.implement(constructor, implementable)
This method marks a Class as implementing an Interface. When calling this method it will add the
Implementable's Interface to the Class's list of Interfaces. It will also validate that the
given Class actually implements all of the methods of the Interface. If the Class does not
this method will throw an Error.
__Method__
```javascript
/**
* @static
* @param {function(new:Constructor)} constructor
* @param {function(new:Implementable)} implementable
*/
Class.implement = function(constructor, implementable) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`constructor` | <code>{function(new:[Constructor](#Constructor))}</code> | The Constructor of the Class to implement the Interface.
`implementable` | <code>{function(new:[Implementable](#Implementable))}</code> | The Implementable of the Interface to implement.
__Returns__
* None
__Examples__
Implement an Interface
```javascript
var IBall = Interface.declare({
throwBall: function() {}
});
var Ball = Class.declare({
throwBall: function() {
// Implementation of method
}
});
Class.implement(Ball, IBall);
```
<br /><a name="Constructor" />
## Constructor
Represents the base instantiable constructor function of all classes declared in the
BugCore system using [Class.declare](#Class-declare)
__Class__
```javascript
/**
* @constructor
*/
var Constructor = function() {
```
__Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[getClass](#Constructor_getClass)()</code> | <code>{[Class](#Class)}</code>
__Static Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[getClass](#Constructor-getClass)()</code> | <code>{[Class](#Class)}</code>
__Static Methods Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[alloc](#Constructor-alloc)({*...} args)</code> | <code>{[Constructor](#Constructor)}</code>
static public | <code>[allocWithArray](#Constructor-allocWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)</code> | <code>{[Constructor](#Constructor)}</code>
static public | <code>[newInstance](#Constructor-newInstance)({*...} args)</code> | <code>{[Constructor](#Constructor)}</code>
static public | <code>[newInstanceWithArray](#Constructor-newInstanceWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)</code> | <code>{[Constructor](#Constructor)}</code>
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor_getClass" />
### Constructor#getClass()
Get the [Class](#Class) for this instance.
__Method__
```javascript
/**
* @return {Class}
*/
getClass: function() {
```
__Parameters__
* None
__Returns__
* <code>{[Class](#Class)}</code> - The Class of this instance.
__Examples__
```js
//TODO BRN: Provide example of Class usage
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor-getClass" />
### Constructor.getClass()
Get the [Class](#Class) for this Constructor.
__Method__
```javascript
/**
* @static
* @return {Class}
*/
Constructor.getClass = function() {
```
__Parameters__
* None
__Returns__
* <code>{[Class](#Class)}</code> - The Class of this Constructor.
__Examples__
```js
//TODO BRN: Provide example of Class usage
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor-alloc" />
### Constructor.alloc()
This method allocates and returns a new instance of the class represented by this Constructor. The new instance
has only been constructed and not initialized. The method passes all arguments through to the constructor.
__Method__
```javascript
/**
* @static
* @param {*...}
* @return {Constructor}
*/
Constructor.alloc = function() {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{...}</code> | Any number of arguments of any type.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var myBaseBall = BaseBall.alloc("arg1", "arg2");
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor-allocWithArray" />
### Constructor.allocWithArray()
This method allocates and returns a new instance of the class represented by this Constructor. The new instance has only been
constructed and not initialized. This method uses an array as the arguments to apply to the constructor.
__Method__
```javascript
/**
* @static
* @param {Array.<*>} args
* @return {Constructor}
*/
Constructor.allocWithArray = function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}</code> | An array of args to apply to the constructor.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var myBaseBall = BaseBall.allocWithArray(["arg1", "arg2"]);
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor-newInstance" />
### Constructor.newInstance()
This method allocates and returns a new instance of the class represented by this Constructor. The new instance
has been both constructed and initialized. This method passes all arguments through to both the constructor as
well as the init methods.
__Method__
```javascript
/**
* @static
* @param {*...}
* @return {Constructor}
*/
Constructor.newInstance = function() {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{*...}</code> | Any number of arguments of any type.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var myBaseBall = BaseBall.newInstance("arg1", "arg2");
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Constructor-newInstanceWithArray" />
### Constructor.newInstanceWithArray()
This method allocates and returns a new instance of the class represented by this Constructor. The new instance
has been both constructed and initialized. This method uses an array as the arguments to apply to both the
constructor and the init methods.
__Method__
```javascript
/**
* @static
* @param {Array.<*>} args
* @return {Constructor}
*/
Constructor.newInstanceWithArray = function(args) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`args` | <code>{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}</code> | An array of args to apply to the constructor and init methods.
__Returns__
* <code>{[Constructor](#Constructor)}</code> - The new instance
__Examples__
```javascript
var BaseBall = Class.extend(Ball, {});
var myBaseBall = BaseBall.newInstanceWithArray(["arg1", "arg2"]);
```
<br /><a name="Func" />
## Func
<br /><a name="Implementable" />
## Implementable
Represents the base function of all interfaces declared in the BugCore system
using [Interface.declare](#Interface-declare)
__Class__
```javascript
/**
* @constructor
*/
var Implementable = function() {};
```
__Static Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[getInterface](#Implementable-getInterface)()</code> | <code>{[Interface](#Interface)}</code>
<br />
------------------------------------------------------------------------------------
<br />
<a name="Implementable-getInterface"></a>
### Implementable.getInterface()
Get the [Interface](#Interface) for this Implementable.
__Method__
```javascript
/**
* @static
* @return {Interface}
*/
Implementable.getInterface = function() {
```
__Parameters__
* None
__Returns__
* <code>{[Interface](#Interface)}</code> - The Interface of this Implementable.
__Examples__
```js
var MyImplementable = Interface.declare({
interfaceMethod: function() {
}
});
var MyInterface = MyImplementable.getInterface();
```
<br /><a name="Interface" />
## Interface
Core class used to build interfaces.
__Class__
```javascript
/**
* @constructor
* @param {function(new:Implementable)} implementable
* @param {string} name
* @param {Interface} superinterface
*/
var Interface = function(implementable, name, superinterface) {
```
__Constructor Summary__
Access | Signature
--- | --- | ---
constructor | <code>[Interface](#Interface_constructor)({function(new:[Implementable](#Implementable))} implementable, {string} name, {[Interface](#Interface)} superinterface)</code>
__Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[getImplementable](#Interface_getImplementable)()</code> | <code>{function(new:[Implementable](#Implementable))}</code>
public | <code>[getName](#Interface_getName)()</code> | <code>{string}</code>
public | <code>[getSuperinterface](#Interface_getSuperinterface)()</code> | <code>{[Interface](#Interface)}</code>
__Static Method Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[declare](#Interface-declare)({[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)</code> | <code>{function(new:[Implementable](#Implementable))}</code>
static public | <code>[extend](#Implementable-extend)({function(new:[Implementable](#Implementable))} implementable, {[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)</code> | <code>function(new:[Implementable](#Implementable))</code>
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface_constructor" />
### Interface(implementable, name, superinterface)
Constructor for a new Interface. This should not be used directly. Instead, use the
[Interface.declare](#Interface-declare) method to create a new Interface.
__Method__
```javascript
/**
* @constructor
* @param {function(new:Implementable)} implementable
* @param {string} name
* @param {Interface} superinterface
*/
var Interface = function(implementable, name, superinterface) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`implementable` | <code>{function(new:[Implementable](#Implementable)}</code> | The Implementable of this Interface.
`name` | <code>{string}</code> | The name of this Interface.
`superinterface` | <code>{[Interface](#Interface)}</code> | The superinterface of this Interface (optional).
__Examples__
```js
var myInterface = new Interface(implementable, name, superinterface);
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface_getImplementable" />
### Interface#getImplementable()
Get the Interface's Implementable function.
__Method__
```javascript
/**
* @return {function(new:Implementable)}
*/
getImplementable: function() {
```
__Parameters__
* None
__Returns__
* <code>{function(new:[Implementable](#Implementable))}</code> - The Interface's Implementable function.
__Examples__
```javascript
/** @type {function(new:MyInterfaceImplementable)} */
var MyInterfaceImplementable = Interface.declare({});
/** @type {Interface} */
var MyInterface = MyInterfaceImplementable.getInterface();
console.log(MyInterfaceImplementable === MyInterface.getImplementable()); // true
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface_getName" />
### Interface#getName()
Get the Interface's name (if one was supplied)
__Method__
```javascript
/**
* @return {string}
*/
getName: function() {
```
__Parameters__
* None
__Returns__
* <code>{string}</code> - The Interface's name.
__Examples__
```javascript
var MyInterfaceImplementable = Interface.declare({
_name: "MyInterface"
});
var MyInterface = MyInterfaceImplementable.getInterface();
MyInterface.getName(); // "MyInterface"
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface_getSuperinterface" />
### Interface#getSuperinterface()
Get the Interface's superinterface (if there is one)
__Method__
```javascript
/**
* @return {Interface}
*/
getSuperinterface: function() {
```
__Parameters__
* None
__Returns__
* <code>{[Interface](#Interface)}</code> - The Interface's superinterface.
__Examples__
Extended Interface
```javascript
var MyInterfaceImplementable = Interface.extend(SomeInterfaceImplementable, {});
var MyInterface = MyInterfaceImplementable.getInterface();
console.log(MyInterface.getSuperinterface() === SomeInterfaceImplementable.getInterface()); // true
```
Declared Interface
```javascript
var MyBaseInterfaceImplementable = Interface.declare({});
var MyBaseInterface = MyBaseInterfaceImplementable.getInterface();
MyBaseInterface.getSuperinterface(); // null
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface-declare" />
### Interface.declare(declaration)
This method is used to declare a low level base Interface in the bugcore system. Unlike Class.declare
this method should be freely used to declare basic interfaces that extend no other Interface.
__Method__
```javascript
/**
* @static
* @param {Object.<string, function(...):*>} declaration
* @return {function(new:Implementable)}
*/
Interface.declare = function(declaration) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`declaration` | <code>{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, function(...):*>}</code> | An object that declares the methods of the new Interface.
__Returns__
* <code>{function(new:[Implementable](#Implementable))}</code> - The newly created Interface's Implementable.
__Examples__
```javascript
var MyImplementable = Interface.declare({
foo: function() {},
bar: function() {}
});
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Interface-extend" />
### Interface.extend(implementable, declaration)
This method is used to extend and existing interface.
__Method__
```javascript
/**
* @static
* @param {function(new:Implementable)} implementable
* @param {Object.<string, function(..):*>} declaration
* @return {function(new:Implementable)}
*/
Interface.extend = function(implementable, declaration) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`implementable` | <code>{function(new:[Implementable](#Implementable))}</code> | The Implementable of the Interface to extend.
`declaration` | <code>{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, function(...):*>}</code> | An object that declares the methods of the new Interface.
__Returns__
* <code>{function(new:[Implementable](#Implementable))}</code> - The newly created Interface's Implementable.
__Examples__
```javascript
var IBall = Interface.declare({
throwBall: function() {
}
});
var IBaseBall = Class.extend(IBall, {
hitBall: function() {
}
});
```
<br /><a name="Obj" />
## Obj
The root class of all other classes in the bugcore library. Provides basic functionality such as hash code support,
equality checks and clone support.
__Class__
```javascript
/**
* @class
* @extends {Constructor}
* @implements {IClone}
* @implements {IEquals}
* @implements {IHashCode}
*/
var Obj = Class.declare(/** @lends {Obj.prototype} */{
```
__Extends__
* [`Constructor`](#Constructor)
__Interfaces__
* [`IClone`](#IClone)
* [`IEquals`](#IEquals)
* [`IHashCode`](#IHashCode)
__Constructor Summary__
Access | Signature
--- | ---
constructor | <code>[_constructor](#Obj__constructor)()</code>
__Getters and Setters Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[getInternalId](#Obj_getInternalId)()<code> | <code>{number}</code>
__Method Summary__
Access | Signature | Return Type
--- | --- | ---
public | <code>[clone](#Obj_clone)({boolean} deep)</code> | <code>{\*}</code>
public | <code>[equals](#Obj_equals)({\*} value)</code> | <code>{boolean}</code>
public | <code>[hashCode](#Obj_hashCode)() | <code>{number}</code>
__Static Method Summary__
Access | Signature | Return Type
--- | --- | ---
static public | <code>[clone](#Obj-clone)({A} value, {boolean} deep)</code> | <code>{A}</code>
static public | <code>[equals](#Obj-equals)({\*} value1, {\*} value2)</code> | <code>{boolean}</code>
static public | <code>[hashCode](#Obj-hashCode)({\*} value)</code> | <code>{number}</code>
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj__constructor" />
### Obj#_constructor()
__Method__
```javascript
/**
* @constructs
*/
_constructor: function() {
```
__Parameters__
* None
__Examples__
```js
var myObj = new Obj();
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj_getInternalId" />
### Obj#getInternalId()
__Method__
```javascript
/**
* @return {number}
*/
getInternalId: function() {
```
__Parameters__
* None
__Returns__
* <code>{number}</code> - The unique internal id for this instance. Unique only to this JS runtime.
__Examples__
```js
var myObj = new Obj();
var internalId = myObj.getInternalId();
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj_clone" />
### Obj#clone(deep)
By default the clone method will use the instance's Class to instantiate a new instance.
It will also iterate through the instance's properties and attempt to clone all properties
that are not functions. If a deep clone is being performed, then the clone method will
attempt to create a deep copy of each property. If a shallow clone is being performed
then a reference to the property value will be set on the new instance.
__Notes__
* _internalId is not cloned for deep or shallow clones. Therefore the clone instance
is unique from that of the original.
__Method__
```javascript
/**
* @param {boolean=} deep
* @return {*}
*/
clone: function(deep) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`deep` | <code>{boolean=}</code> | Whether or not to perform a deep clone. Optional - default: false
__Returns__
* <code>{\*}</code> - A clone of the instance.
__Examples__
```js
var myObj = new Obj();
var shallowCloneObj = myObj.clone(); //shallow clone
var deepCloneObj = myObj.clone(true); //deep clone
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj_equals" />
### Obj#equals(value)
By default, the equality check will compare this instances _internalId to the value parameter.
__Notes__
* If two instances are equal, they should return the same hash code.
__Method__
```javascript
/**
* @param {*} value
* @return {boolean}
*/
equals: function(value) {
```
__Parameters__
Name | Type | Description
--- | --- | ---
`value` | <code>{\*}</code> | The value to compare to for equality.
__Returns__
* <code>{boolean}</code> - Whether or not the instance is equal to the value parameter.
__Examples__
Two different instances are not equal
```js
var obj1 = new Obj();
var obj2 = new Obj();
obj1.equals(obj2); //false
```
An instance is equal to itself
```js
var obj1 = new Obj();
obj1.equals(obj1); //true
```
Clones are not equal unless the 'equals' method is overridden
```js
var obj = new Obj();
var objClone = obj.clone();
obj.equals(objClone); //false
```
```js
var obj = new Obj();
var objClone = obj.clone(true);
obj.equals(objClone); //false
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj_hashCode" />
### Obj#hashCode()
Returns the objects hashCode. The generation of the hashCode is only run once and
then cached.
__Notes__
* If two instances are equal, they should return the same hash code.
* Equal hash codes is not a guarantee of equality.
* A hash code should not change for an instance over the lifespan of the instance.
* Generation of hash codes should be done only using immutable values.
__Method__
```javascript
/**
* @return {number}
*/
hashCode: function() {
```
__Parameters__
* None
__Returns__
* <code>{number}</code> - The hash code of this instance.
__Examples__
Get hash code of instance
```js
var obj = new Obj();
var hashCode = obj.hashCode();
```
<br />
------------------------------------------------------------------------------------
<br />
<a name="Obj-clone" />
### Obj.clone(value, deep)
Clones the value parameter.
If the value implements IClone the clone() method will be called to perform a clone of
the value. If the value is a basic value such as a number or string it will simply be
passed through.
__Method__
```javascript
/**
* @static
* @param {A} value
* @param {boolean=} deep
* @return {A}
* @template A
*/
Obj.clone = function(value, deep) {
```
__Notes__
* If the value implements IClone, the clone() method will be used to clone the value.
* Cloning an object literal will create a new object literal and set references to all
iterable property values of the original object.
* Cloning a Date will create a new Date instance with the same time.
* Cloning an