Bugcore NPM | npm.io

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. 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

Quick Examples

Creation of a new class

var Class   = bugcore.Class;
var Obj     = bugcore.Obj;

var SomeClassConstructor = Class.extend(Obj, {});

Creation of a new class with an internal _constructor method

var SomeClassConstructor = Class.extend(Obj, {
    _constructor: function() {
        this._super(); // Call super constructor
    }
});

Creation of a new class with overridden equals and hashCode methods

/**
 * @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

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

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 framework

Download Source

The source is available for download from GitHub

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

npm install bugcore

For the web, simply include these scripts in your application

<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

var bugcore = require('bugcore');

var map     = new bugcore.Map();

In the browser:

<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

Command Classes

Concurrent Classes

Core Classes

Core Interfaces

Data Classes

Data Interfaces

Event Classes

Event Interfaces

Flow Classes

Match Classes

ObjectPathMatcher

Observable Classes

Observable Interfaces

Promise Classes

Promise Interfaces

IPromise

Proxy Classes

Proxy Interfaces

IProxy

Publisher Classes

Query Classes

Query Interfaces

State Classes

Stream Classes

Stream Interfaces

Throwable Classes

Trace Classes

Util Classes

Validator Classes

AddAtChange

TODO

AddChange

TODO

Change

TODO

ClearChange

TODO

PutChange

TODO

RemoveAtChange

TODO

RemoveChange

TODO

RemovePropertyChange

TODO

SetPropertyChange

TODO

Command

TODO

CommandBatch

TODO

CommandProcessor

TODO

Lock

TODO

LockMap

TODO

LockStriped

TODO

Semaphore

TODO

Class

Core class used to build other classes.

Class

/**
 * @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

Constructor Summary

Access	Signature
constructor	Class({Constructor} constructor, {Array.<Interface>} interfaces, {string} name, {Class} superclass)

Getters and Setters Summary

Access	Signature	Return Type
public	getConstructor()	{function(new:Constructor)}
public	getInterfaces()	{Array.<Interface>}
public	getName()	{string}
public	getSuperclass()	{Class}

Method Summary

Access	Signature	Return Type
public	alloc({*...} args)	{Constructor}
public	allocWithArray({Array.<*>} args)	{Constructor}
public	newInstance({*...} args)	{Constructor}
public	newInstanceWithArray({Array.<*>} args)	{Constructor}

Static Method Summary

Access	Signature	Return Type
static public	declare({Object.<string, *>} declaration)	{function(new:Constructor)}
static public	doesExtend({*} value, {function(new:Constructor)} constructor)	{boolean}
static public	doesImplement({*} value, {function(new:Implementable)} implementable)	{boolean}
static public	extend({function(new:Constructor)} constructor, {Object.<string, *>} declaration)	{function(new:Constructor)}
static public	implement({function(new:Constructor)} constructor, {function(new:Implementable)} implementable)	None

Class(constructor, interfaces, name, superclass)

Method

/**
 * @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`	{function(new:Constructor}	The Constructor of this class.
`interfaces`	{Array.<Interface>}	Any Interfaces that this Class implements.
`name`	{string}	The name of this Class.
`superclass`	{Class}	The superclass of this Class.

Examples

var myClass = new Class(constructor, interfaces, name, superclass);

Class#getConstructor()

Get the Class's Constructor function

Method

/**
 * @return {function(new:Constructor)}
 */
getConstructor: function() {

Parameters

None

Returns

{function(new:Constructor)} - The Class's Constructor function.

Examples

/** @type {function(new:MyClassConstructor)} */
var MyClassConstructor  = Class.extend(Obj, {});

/** @type {Class} */
var MyClass             = MyClassConstructor.getClass();

console.log(MyClassConstructor === MyClass.getConstructor());   // true

Class#getInterfaces()

Get the Class's implemented Interfaces

Method

/**
 * @return {Array.<Interface>}
 */
getInterfaces: function() {

Parameters

None

Returns

{Array.<Interface>} - The Class's implemented Interfaces.

Examples

var MyInterface         = Interface.declare({
    myMethod: function() {}
});
var MyClassConstructor  = Class.extend(Obj, {
    myMethod: function() {}
});

Class.implement(MyClassConstructor, MyInterface);

var MyClass = MyClassConstructor.getClass();
MyClass.getInterfaces();                            // [ MyInterface ]

Get the Class's name (if one was supplied)

Method

/**
 * @return {string}
 */
getName: function() {

Parameters

None

Returns

{string} - The Class's name.

Examples

var MyClassConstructor  = Class.extend(Obj, {
    _name: "MyClass"
});

var MyClass = MyClassConstructor.getClass();
MyClass.getName();                         // "MyClass"

Get the Class's superclass (if there is one)

Method

/**
 * @return {Class}
 */
getSuperclass: function() {

Parameters

None

Returns

{Class} - The Class's superclass.

Examples

Extended Class

var MyClassConstructor  = Class.extend(Obj, {});

var MyClass = MyClassConstructor.getClass();
console.log(MyClass.getSuperclass() === Obj.getClass());    // true

Declared Class

var MyBaseClassConstructor  = Class.declare({});

var MyBaseClass = MyBaseClassConstructor.getClass();
MyBaseClass.getSuperclass();                                // null

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

/**
 * @param {...} args
 * @return {Constructor}
 */
alloc: function(args) {

Parameters

Name	Type	Description
`args`	{...}	Any number of arguments of any type.

Returns

{Constructor} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var BaseBallClass   = BaseBall.getClass();
var myBaseBall      = BaseBallClass.alloc("arg1", "arg2");

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

/**
 * @param {Array.<*>=} args
 * @return {Constructor}
 */
allocWithArray: function(args) {

Parameters

Name	Type	Description
`args`	{Array.<*>}	An array of args to apply to the constructor.

Returns

{Constructor} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var BaseBallClass   = BaseBall.getClass();
var myBaseBall      = BaseBallClass.allocWithArray(["arg1", "arg2"]);

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

/**
 * @param {*...} args
 * @return {Constructor}
 */
newInstance: function(args) {

Parameters

Name	Type	Description
`args`	{*...}	Any number of arguments of any type.

Returns

{Constructor} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var BaseBallClass   = BaseBall.getClass();
var myBaseBall      = BaseBallClass.newInstance("arg1", "arg2");

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

/**
 * @param {Array.<*>=} args
 * @return {Constructor}
 */
newInstanceWithArray: function(args) {

Parameters

Name	Type	Description
`args`	{Array.<*>}	An array of args to apply to the constructor and init methods.

Returns

{Constructor} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var BaseBallClass   = BaseBall.getClass();
var myBaseBall      = BaseBallClass.newInstanceWithArray(["arg1", "arg2"]);

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 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

/**
 * @static
 * @param {Object.<string, *>} declaration
 * @return {function(new:Constructor)}
 */
Class.declare = function(declaration) {

Parameters

Name	Type	Description
`declaration`	{Object.<string, *>}	An object that declares the methods of the new class.

Returns

{function(new:Constructor)} - The newly created class's constructor.

Examples

var LowestLevelObject = Class.declare({
    _constructor: function() {
        // No need to call this._super, this is the lowest level.
    }
});

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

/**
 * @static
 * @param {*} value
 * @param {function(new:Constructor)} constructor
 * @return {boolean}
 */
Class.doesExtend = function(value, constructor) {

Parameters

Name	Type	Description
`value`	{*}	The value to determine if it extends the given Constructor's Class
`constructor`	{function(new:Constructor)}	The Constructor used to check if the value extends it's Class

Returns

{boolean} - Whether or not the value extends the given Constructor's Class

Examples

var BaseBall = Class.extend(Ball, {});
var myBaseBall = new BaseBall();

Class.doesExtend(myBaseBall, Ball);         //true
Class.doesExtend(myBaseBall, BaseBall);     //true

This method is used to determine if a value implements a particular Implementable's Interface.

Method

/**
 * @static
 * @param {*} value
 * @param {function(new:Implementable)} implementable
 * @return {boolean}
 */
Class.doesImplement = function(value, implementable) {

Parameters

Name	Type	Description
`value`	{*}	The value to determine if it implements the given Implementable's Interface
`constructor`	{function(new:Constructor)}	The Constructor used to check if the value extends it's Class

Returns

{boolean} - Whether or not the value implements the given Implementable's Interface

Examples

var IBall   = Interface.declare({});
var Ball    = Class.declare({});
Class.implement(Ball, IBall);

var myBall  = new Ball();

Class.doesImplement(myBall, IBall);         //true

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

Method

/**
 * @static
 * @param {function(new:Constructor)} constructor
 * @param {Object.<string, *>} declaration
 * @return {function(new:Constructor)}
 */
Class.extend = function(constructor, declaration) {

Parameters

Name	Type	Description
`constructor`	{function(new:Constructor)}	The constructor of the class to extend.
`declaration`	{Object.<string, *>}	An object that declares the methods of the new class.

Returns

{function(new:Constructor)} - The newly created class's constructor.

Examples

var BaseBall = Class.extend(Ball, {

    _constructor: function(diameter) {
        this._super(); // Call super constructor
        this.diameter = diameter;
    }

    throwBall: function() {

    }
});

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

/**
 * @static
 * @param {function(new:Constructor)} constructor
 * @param {function(new:Implementable)} implementable
 */
Class.implement = function(constructor, implementable) {

Parameters

Name	Type	Description
`constructor`	{function(new:Constructor)}	The Constructor of the Class to implement the Interface.
`implementable`	{function(new:Implementable)}	The Implementable of the Interface to implement.

Returns

None

Examples

Implement an Interface

var IBall   = Interface.declare({
    throwBall: function() {}
});

var Ball    = Class.declare({
    throwBall: function() {
        // Implementation of method
    }
});

Class.implement(Ball, IBall);

Constructor

Represents the base instantiable constructor function of all classes declared in the BugCore system using [Class.declare](#Class-declare)

Class

/**
 * @constructor
 */
var Constructor = function() {

Getters and Setters Summary

Access	Signature	Return Type
public	[getClass](#Constructor_getClass)()	{[Class](#Class)}

Static Getters and Setters Summary

Access	Signature	Return Type
static public	[getClass](#Constructor-getClass)()	{[Class](#Class)}

Static Methods Summary

Access	Signature	Return Type
static public	[alloc](#Constructor-alloc)({*...} args)	{[Constructor](#Constructor)}
static public	[allocWithArray](#Constructor-allocWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)	{[Constructor](#Constructor)}
static public	[newInstance](#Constructor-newInstance)({*...} args)	{[Constructor](#Constructor)}
static public	[newInstanceWithArray](#Constructor-newInstanceWithArray)({[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>} args)	{[Constructor](#Constructor)}

Get the [Class](#Class) for this instance.

Method

/**
 * @return {Class}
 */
getClass: function() {

Parameters

None

Returns

{[Class](#Class)} - The Class of this instance.

Examples

//TODO BRN: Provide example of Class usage

Get the [Class](#Class) for this Constructor.

Method

/**
 * @static
 * @return {Class}
 */
Constructor.getClass = function() {

Parameters

None

Returns

{[Class](#Class)} - The Class of this Constructor.

Examples

//TODO BRN: Provide example of Class usage

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

/**
 * @static
 * @param {*...}
 * @return {Constructor}
 */
Constructor.alloc = function() {

Parameters

Name	Type	Description
`args`	{...}	Any number of arguments of any type.

Returns

{[Constructor](#Constructor)} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var myBaseBall      = BaseBall.alloc("arg1", "arg2");

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

/**
 * @static
 * @param {Array.<*>} args
 * @return {Constructor}
 */
Constructor.allocWithArray = function(args) {

Parameters

Name	Type	Description
`args`	{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}	An array of args to apply to the constructor.

Returns

{[Constructor](#Constructor)} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var myBaseBall      = BaseBall.allocWithArray(["arg1", "arg2"]);

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

/**
 * @static
 * @param {*...}
 * @return {Constructor}
 */
Constructor.newInstance = function() {

Parameters

Name	Type	Description
`args`	{*...}	Any number of arguments of any type.

Returns

{[Constructor](#Constructor)} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var myBaseBall      = BaseBall.newInstance("arg1", "arg2");

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

/**
 * @static
 * @param {Array.<*>} args
 * @return {Constructor}
 */
Constructor.newInstanceWithArray = function(args) {

Parameters

Name	Type	Description
`args`	{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<*>}	An array of args to apply to the constructor and init methods.

Returns

{[Constructor](#Constructor)} - The new instance

Examples

var BaseBall        = Class.extend(Ball, {});
var myBaseBall      = BaseBall.newInstanceWithArray(["arg1", "arg2"]);

Func

Implementable

Represents the base function of all interfaces declared in the BugCore system using [Interface.declare](#Interface-declare)

Class

/**
 * @constructor
 */
var Implementable = function() {};

Static Getters and Setters Summary

Access	Signature	Return Type
static public	[getInterface](#Implementable-getInterface)()	{[Interface](#Interface)}

Implementable.getInterface()

Get the Interface for this Implementable.

Method

/**
 * @static
 * @return {Interface}
 */
Implementable.getInterface = function() {

Parameters

None

Returns

{Interface} - The Interface of this Implementable.

Examples

var MyImplementable = Interface.declare({
    interfaceMethod: function() {

    }
});
var MyInterface = MyImplementable.getInterface();

Interface

Core class used to build interfaces.

Class

/**
 * @constructor
 * @param {function(new:Implementable)} implementable
 * @param {string} name
 * @param {Interface} superinterface
 */
var Interface = function(implementable, name, superinterface) {

Constructor Summary

Access	Signature
constructor	[Interface](#Interface_constructor)({function(new:[Implementable](#Implementable))} implementable, {string} name, {[Interface](#Interface)} superinterface)

Getters and Setters Summary

Access	Signature	Return Type
public	[getImplementable](#Interface_getImplementable)()	{function(new:[Implementable](#Implementable))}
public	[getName](#Interface_getName)()	{string}
public	[getSuperinterface](#Interface_getSuperinterface)()	{[Interface](#Interface)}

Static Method Summary

Access	Signature	Return Type
static public	[declare](#Interface-declare)({[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)	{function(new:[Implementable](#Implementable))}
static public	[extend](#Implementable-extend)({function(new:[Implementable](#Implementable))} implementable, {[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, *>} declaration)	function(new:[Implementable](#Implementable))

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

/**
 * @constructor
 * @param {function(new:Implementable)} implementable
 * @param {string} name
 * @param {Interface} superinterface
 */
var Interface = function(implementable, name, superinterface) {

Parameters

Name	Type	Description
`implementable`	{function(new:[Implementable](#Implementable)}	The Implementable of this Interface.
`name`	{string}	The name of this Interface.
`superinterface`	{[Interface](#Interface)}	The superinterface of this Interface (optional).

Examples

var myInterface = new Interface(implementable, name, superinterface);

Get the Interface's Implementable function.

Method

/**
 * @return {function(new:Implementable)}
 */
getImplementable: function() {

Parameters

None

Returns

{function(new:[Implementable](#Implementable))} - The Interface's Implementable function.

Examples

/** @type {function(new:MyInterfaceImplementable)} */
var MyInterfaceImplementable  = Interface.declare({});

/** @type {Interface} */
var MyInterface            = MyInterfaceImplementable.getInterface();

console.log(MyInterfaceImplementable === MyInterface.getImplementable());   // true

Get the Interface's name (if one was supplied)

Method

/**
 * @return {string}
 */
getName: function() {

Parameters

None

Returns

{string} - The Interface's name.

Examples

var MyInterfaceImplementable  = Interface.declare({
    _name: "MyInterface"
});

var MyInterface = MyInterfaceImplementable.getInterface();
MyInterface.getName();                         // "MyInterface"

Get the Interface's superinterface (if there is one)

Method

/**
 * @return {Interface}
 */
getSuperinterface: function() {

Parameters

None

Returns

{[Interface](#Interface)} - The Interface's superinterface.

Examples

Extended Interface

var MyInterfaceImplementable  = Interface.extend(SomeInterfaceImplementable, {});

var MyInterface = MyInterfaceImplementable.getInterface();
console.log(MyInterface.getSuperinterface() === SomeInterfaceImplementable.getInterface());    // true

Declared Interface

var MyBaseInterfaceImplementable  = Interface.declare({});

var MyBaseInterface = MyBaseInterfaceImplementable.getInterface();
MyBaseInterface.getSuperinterface();                                // null

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

/**
 * @static
 * @param {Object.<string, function(...):*>} declaration
 * @return {function(new:Implementable)}
 */
Interface.declare = function(declaration) {

Parameters

Name	Type	Description
`declaration`	{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, function(...):*>}	An object that declares the methods of the new Interface.

Returns

{function(new:[Implementable](#Implementable))} - The newly created Interface's Implementable.

Examples

var MyImplementable = Interface.declare({
    foo: function() {},
    bar: function() {}
});

This method is used to extend and existing interface.

Method

/**
 * @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`	{function(new:[Implementable](#Implementable))}	The Implementable of the Interface to extend.
`declaration`	{[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).<string, function(...):*>}	An object that declares the methods of the new Interface.

Returns

{function(new:[Implementable](#Implementable))} - The newly created Interface's Implementable.

Examples

var IBall = Interface.declare({
    throwBall: function() {

    }
});
var IBaseBall = Class.extend(IBall, {
    hitBall: function() {

    }
});

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

/**
 * @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	[_constructor](#Obj__constructor)()

Getters and Setters Summary

Access	Signature	Return Type
public	[getInternalId](#Obj_getInternalId)()	{number}

Method Summary

Access	Signature	Return Type
public	[clone](#Obj_clone)({boolean} deep)	{*}
public	[equals](#Obj_equals)({*} value)	{boolean}
public	[hashCode](#Obj_hashCode)()	{number}

Static Method Summary

Access	Signature	Return Type
static public	[clone](#Obj-clone)({A} value, {boolean} deep)	{A}
static public	[equals](#Obj-equals)({} value1, {} value2)	{boolean}
static public	[hashCode](#Obj-hashCode)({*} value)	{number}

Obj#_constructor()

Method

/**
 * @constructs
 */
_constructor: function() {

Parameters

None

Examples

var myObj = new Obj();

Obj#getInternalId()

Method

/**
 * @return {number}
 */
getInternalId: function() {

Parameters

None

Returns

{number} - The unique internal id for this instance. Unique only to this JS runtime.

Examples

var myObj       = new Obj();
var internalId  = myObj.getInternalId();

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

/**
 * @param {boolean=} deep
 * @return {*}
 */
clone: function(deep) {

Parameters

Name	Type	Description
`deep`	{boolean=}	Whether or not to perform a deep clone. Optional - default: false

Returns

{*} - A clone of the instance.

Examples

var myObj               = new Obj();
var shallowCloneObj     = myObj.clone();     //shallow clone
var deepCloneObj        = myObj.clone(true); //deep clone

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

/**
 * @param {*} value
 * @return {boolean}
 */
equals: function(value) {

Parameters

Name	Type	Description
`value`	{*}	The value to compare to for equality.

Returns

{boolean} - Whether or not the instance is equal to the value parameter.

Examples

Two different instances are not equal

var obj1   = new Obj();
var obj2   = new Obj();
obj1.equals(obj2);      //false

An instance is equal to itself

var obj1   = new Obj();
obj1.equals(obj1);      //true

Clones are not equal unless the 'equals' method is overridden

var obj         = new Obj();
var objClone    = obj.clone();
obj.equals(objClone);      //false

var obj         = new Obj();
var objClone    = obj.clone(true);
obj.equals(objClone);      //false

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

/**
 * @return {number}
 */
hashCode: function() {

Parameters

None

Returns

{number} - The hash code of this instance.

Examples

Get hash code of instance

var obj         = new Obj();
var hashCode    = obj.hashCode();

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

/**
 * @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 Array will create a new Array with the same values in the same order.

Parameters

Name	Type	Description
`value`	{A}	The value to clone.
`deep`	{boolean=}	Whether or not to perform a deep clone. Optional - default: false

Returns

{A} - A clone of the value.

Examples

var myObj               = new Obj();
var shallowCloneObj     = Obj.clone(myObj);         //shallow clone

var myObj               = new Obj();
var deepCloneObj        = Obj.clone(myObj, true);   //deep clone

var myString            = "abc123";
var cloneString         = Obj.clone(myString);      //"abc123"

Checks value1 and value2 for equality.

If value1 implements IEquals, the value1.equals() method will be used to perform the equality check. Otherwise === is used to compare the two values.

Notes

Two Date instances of the same time are considered equal

Method

/**
 * @static
 * @param {*} value1
 * @param {*} value2
 * @return {boolean}
 */
Obj.equals = function(value1, value2) {

Parameters

Name	Type	Description
`value1`	{*}	The value to compare value2 to for equality.
`value2`	{*}	The value to compare value1 to for equality.

Returns

{boolean} - Whether or not the two values are equal.

Examples

Two different instances are not equal

var obj1   = new Obj();
var obj2   = new Obj();
Obj.equals(obj1, obj2);         //false

An instance is equal to itself

var obj1   = new Obj();
Obj.equals(obj1, obj1);         //true

Strings of the same value are equal

var string1 = "mystring";
var string2 = "mystring";
Obj.equals(string1, string2)    //true

Undefined and null are not equal

var undefinedValue  = undefined;
var nullValue       = null;
Obj.equals(undefinedValue, nullValue) //false

Two Dates of the same time are equal

var time    = Date.now();
var date1   = new Date(time);
var date2   = new Date(time);
Obj.equals(date1, date2)        //true

Returns the hashCode of the value. If the value implements IHashCode, then the value.hashCode() method will be used to generate the hash code.

Method

/**
 * @static
 * @param {*} value
 * @return {number}
 */
Obj.hashCode = function(value) {

Parameters

Name	Type	Description
`value`	{*}	The value to generate a hash code for..

Returns

{number} - The hash code of the value.

Examples

Get hash code of an instance.

var myObj       = new Obj();
var hashCode    = Obj.hashCode(myObj);

Get hash code of a string.

var myString    = "abc123";
var hashCode    = Obj.hashCode(myString);

IClone

The base interface for cloning. If your Class can be cloned, you should implement this interface.

Interface

/**
 * @interface
 */
var IClone = Interface.declare({

Method Summary

Access	Signature	Return Type
public	[clone](#IClone_clone)({boolean=} deep)	{*}

This method returns a clone of the instance that implements this interface. Implementations should respect the deep clone flag.

Notes

Implementations should respect the deep flag.
Immutable values need not be cloned on a deep clone.

Method

/**
 * @param {boolean=} deep
 * @return {*}
 */
clone: function(deep) {}

Parameters

Name	Type	Description
`deep`	{boolean=}	Whether or not to perform a deep clone. Optional - default: false

Returns

{*} - A clone of the instance.

IEquals

The base interface for equality checks. If your Class can be compared for equality against another, you should implement this interface.

Notes

This interfaces must be implemented along with the the IHashCode interface if you want your Class to work properly with the bugcore data classes.
If two instances are equal, they should return the same hash code.

Interface

/**
 * @interface
 */
var IEquals = Interface.declare({

Method Summary

Access	Signature	Return Type
public	[equals](#IEquals_equals)({*} value)	{boolean}

This method returns true if the instance that implements this interface is equal to the given value. Returns false if the given value does not equal the instance.

Notes

Implementations should handle any value passed in as a parameter.

Method

/**
 * @param {*} value
 * @return {boolean}
 */
equals: function(value) {}

Parameters

Name	Type	Description
`value`	{*}	The value to compare the instance against for equality.

Returns

{boolean} - Returns true if the instance is equal to the given value. False if not.

IHashCode

The base interface for generating a hash code for an instance. Used in tandem with the IEquals interface for storing values in [HashStore](#HashStore) and [HashTable](#HashTable).

Notes

This interfaces must be implemented along with the the IEquals interface if you want your Class to work properly with the bugcore data classes.
If two instances are equal, they should return the same hash code.
If two instances are not they can still return the same hash code. However, this should be avoided to a degree as it will hurt the performance of HashTable and HashStore
Equal hash codes does not guarantee equality.

Interface

/**
 * @interface
 */
var IHashCode = Interface.declare({

Method Summary

Access	Signature	Return Type
public	[hashCode](#IHashCode_hashCode)()	{number}

This method returns a hash code for the current instance.

Notes

Implementations should try to generate a relatively unique hash code for the given instance.
If two instances are equal, they should return the same hash code.

Method

/**
 * @return {number}
 */
hashCode: function() {}

Parameters

None

Returns

{number} - The hash code for the instance.

Throwable

The root throwable class of the bugcore system. Has support for more complex stack traces including cause chains.

Class

/**
 * @class
 * @extends {Obj}
 * @implements {IObjectable}
 */
var Throwable = Class.extend(Obj, {

Extends

[Obj](#Obj)

Interfaces

[IObjectable](#IObjectable)

Constructor Summary

Access	Signature
public	[_constructor](#Throwable__constructor)({string} type, {*=} data, {string=} message, {[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<([Throwable](#Throwable) \| [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))>=} causes)

Getters and Setters Summary

Access	Signature	Return Type
public	[getCauses](#Throwable_getCauses)()	{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<([Throwable](#Throwable) \| [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))>}
public	[getData](#Throwable_getData)()	{*}
public	[setData](#Throwable_setData)({*} data)	None
public	[getMessage](#Throwable_getMessage)()	{string}
public	[setMessage](#Throwable_setMessage)({string} message)	None
public	[getStack](#Throwable_getStack)()	{string}
public	[getType](#Throwable_getType)()	{string}

Method Summary

Access	Signature	Return Type
public	[addCause](#Throwable_addCause)({([Throwable](#Throwable) \| [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))} cause)	{*}
public	[toObject](#Throwable_toObject)()	{causes: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<([Throwable](#Throwable) \| [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))>, data: *, message: string, type: string}

Throwable#_constructor(type, data, message, causes)

Method

/**
 * @constructs
 * @param {string} type
 * @param {*=} data
 * @param {string=} message
 * @param {Array.<(Throwable | Error)>=} causes
 */
_constructor: function(type, data, message, causes) {

Parameters

Name	Type	Description
`type`	{string}	The type of throwable.
`data`	{*=}	Any extra data to pass along with this throwable.
`message`	{string=}	A message to add to this throwable. (optional - default: "")
`causes`	{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<([Throwable](#Throwable) \| [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))>=}	An array of other throwables or js errors that caused this throwable. (optional - default: [])

Examples

Simple throwable

var myThrowable = new Throwable("MyThrowable", {}, "Something bad happened");
throw myThrowable;

Throwable with cause

try {
    somethingWillGoWrong();
} catch (error) {
    var myThrowable     = new Throwable("SomethingWentWrong", {}, "Something went wrong in the somethingWillGoWrong function", [error]);
    throw throwable;
}

Throwable#getCauses()

Get the causes of the Throwable.

Method

/**
 * @return {Array.<(Throwable | Error)>}
 */
getCauses: function() {

Parameters

None

Returns

{[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).<([Throwable](#Throwable) | [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))>} - An array of other Throwables or JS Errors that caused this Throwable.

Examples

try {
    somethingWillGoWrong();
} catch (error) {
    var myThrowable     = new Throwable("SomethingWentWrong", {}, "Something went wrong in the somethingWillGoWrong function", [error]);
    var causes          = myThrowable.getCauses();  // [error]
}

Throwable#getData()

Get the data of the Throwable.

Method

/**
 * @return {*}
 */
getData: function() {

Parameters

None

Returns

{*} - An array of other Throwables or JS Errors that caused this Throwable.

Examples

var data            = "some data";
var myThrowable     = new Throwable("ThrowableType", data, "some message");

myThrowable.getData() === data;     //true

Throwable#setData(data)

Set the data of the Throwable.

Method

/**
 * @param {*} data
 */
setData: function(data) {

Parameters

Name	Type	Description
`data`	{*}	The data to set on the Throwable.

Returns

None

Examples

var data            = "some data";
var myThrowable     = new Throwable("ThrowableType");
myThrowable.setData(data);

myThrowable.getData() === data;     //true

Throwable#getMessage()

Get the message of the Throwable.

Method

/**
 * @return {string}
 */
getMessage: function() {

Parameters

None

Returns

{string} - The message included with the Throwable.

Examples

var message         = "some message";
var myThrowable     = new Throwable("ThrowableType", null, message);

myThrowable.getMessage() === message;     //true

Throwable#setMessage(message)

Set the message of the Throwable.

Method

/**
 * @param {string} message
 */
setMessage: function(message) {

Parameters

Name	Type	Description
`message`	{string}	The message to set on the Throwable.

Returns

None

Examples

var message         = "some message";
var myThrowable     = new Throwable("ThrowableType");
myThrowable.setMessage(message);

myThrowable.getMessage() === message;     //true

Throwable#getStack()

Get the stack trace of the Throwable.

Method

/**
 * @return {string}
 */
getStack: function() {

Parameters

None

Returns

{string} - The stack trace of the Throwable.

Examples

//TODO

Throwable#getType()

Get the type of the Throwable.

Method

/**
 * @return {string}
 */
getType: function() {

Parameters

None

Returns

{string} - The type of the Throwable.

Examples

var myThrowable     = new Throwable("ThrowableType");

myThrowable.getType() === "ThrowableType";     //true

Add a cause to the Throwables list of causes.

Notes

All causes will be included in the stack of the throwable.

Method

/**
 * @param {(Throwable | Error)} cause
 */
addCause: function(cause) {

bugcore framework object oop

bugpack

@infinitebrahmanuniverse/nolb-bug @everything-registry/sub-chunk-1272 gulp-recipe gulp-elf classpack bitpack

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

10 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

11 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago

12 years ago