bugcore

bugcore is a JavaScript library that provides a foundational architecture for object oriented JS

Usage no npm install needed!

<script type="module">
  import bugcore from 'https://cdn.skypack.dev/bugcore';
</script>

README


------------------------------------------------------------------------------------

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

npm version
Code Climate
NPM

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

Observable Classes

Observable Interfaces

Promise Classes

Promise Interfaces

Proxy Classes

Proxy Interfaces

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

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 ]

------------------------------------------------------------------------------------
### Class#getName()

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"

------------------------------------------------------------------------------------
### Class#getSuperclass()

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

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

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

Parameters

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

Returns

Examples

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

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

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

Parameters

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

Returns

Examples

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

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

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

Parameters

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

Returns

Examples

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

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

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

Examples

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

------------------------------------------------------------------------------------
### 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 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.
    }
});

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

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

------------------------------------------------------------------------------------
### Class.doesImplement(value, implementable)

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

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

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() {

    }
});

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

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

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

Getters and Setters Summary

Access Signature Return Type
public getClass() {Class}

Static Getters and Setters Summary

Access Signature Return Type
static public getClass() {Class}

Static Methods Summary

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

------------------------------------------------------------------------------------
### Constructor#getClass()

Get the Class for this instance.

Method

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

Parameters

  • None

Returns

  • {Class} - The Class of this instance.

Examples

//TODO BRN: Provide example of Class usage

------------------------------------------------------------------------------------
### Constructor.getClass()

Get the Class for this Constructor.

Method

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

Parameters

  • None

Returns

  • {Class} - The Class of this Constructor.

Examples

//TODO BRN: Provide example of Class usage

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

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

Parameters

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

Returns

Examples

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

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

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

Parameters

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

Returns

Examples

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

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

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

Parameters

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

Returns

Examples

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

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

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

Parameters

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

Returns

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

Class

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

Static Getters and Setters Summary

Access Signature Return Type
static public getInterface() {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({function(new:Implementable)} implementable, {string} name, {Interface} superinterface)

Getters and Setters Summary

Access Signature Return Type
public getImplementable() {function(new:Implementable)}
public getName() {string}
public getSuperinterface() {Interface}

Static Method Summary

Access Signature Return Type
static public declare({Object.<string, *>} declaration) {function(new:Implementable)}
static public extend({function(new:Implementable)} implementable, {Object.<string, *>} declaration) function(new:Implementable)

------------------------------------------------------------------------------------
### Interface(implementable, name, superinterface)

Constructor for a new Interface. This should not be used directly. Instead, use the 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} The Implementable of this Interface.
name {string} The name of this Interface.
superinterface {Interface} The superinterface of this Interface (optional).

Examples

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

------------------------------------------------------------------------------------
### Interface#getImplementable()

Get the Interface's Implementable function.

Method

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

Parameters

  • None

Returns

Examples

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

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

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

------------------------------------------------------------------------------------
### Interface#getName()

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"

------------------------------------------------------------------------------------
### Interface#getSuperinterface()

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

Method

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

Parameters

  • None

Returns

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

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

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

Parameters

Name Type Description
declaration {Object.<string, function(...):*>} An object that declares the methods of the new Interface.

Returns

Examples

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

------------------------------------------------------------------------------------
### Interface.extend(implementable, declaration)

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)} The Implementable of the Interface to extend.
declaration {Object.<string, function(...):*>} An object that declares the methods of the new Interface.

Returns

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

Interfaces

Constructor Summary

Access Signature
constructor _constructor()

Getters and Setters Summary

Access Signature Return Type
public getInternalId() {number}

Method Summary

Access Signature Return Type
public clone({boolean} deep) {*}
public equals({*} value) {boolean}
public hashCode() {number}

Static Method Summary

Access Signature Return Type
static public clone({A} value, {boolean} deep) {A}
static public equals({*} value1, {*} value2) {boolean}
static public 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();

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

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

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

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

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

/**
 * @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();

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

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

------------------------------------------------------------------------------------
### Obj.equals(value1, value2)

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

------------------------------------------------------------------------------------
### Obj.hashCode(value)

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({boolean=} deep) {*}

------------------------------------------------------------------------------------
### IClone#clone(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({*} value) {boolean}

------------------------------------------------------------------------------------
### IEquals#equals(value)

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 and 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() {number}

------------------------------------------------------------------------------------
### IHashCode#hashCode()

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

Interfaces

Constructor Summary

Access Signature
public _constructor({string} type, {*=} data, {string=} message, {Array.<(Throwable | Error)>=} causes)

Getters and Setters Summary

Access Signature Return Type
public getCauses() {Array.<(Throwable | Error)>}
public getData() {*}
public setData({*} data) None
public getMessage() {string}
public setMessage({string} message) None
public getStack() {string}
public getType() {string}

Method Summary

Access Signature Return Type
public addCause({(Throwable | Error)} cause) {*}
public toObject() {causes: Array.<(Throwable | 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.<(Throwable | 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.<(Throwable | 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

------------------------------------------------------------------------------------
### Throwable#addCause(cause)

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