bugcore is a JavaScript library that provides a foundational architecture for object oriented JS
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.
The library is extremely robust and makes up the foundation of our architecture for airbug so check out the docs for an overview of the full power of what the code has to offer. If the library is missing something you need, please let us know!
Latest Version 0.2.1
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!
Creation of a new class
var Class = bugcore.Class;
var Obj = bugcore.Obj;
var SomeClass = Class.extend(Obj, {});
Creation of a new class with a constructor
var SomeClass = 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 SomeClass = 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"
bugcore is dependent upon the bugpack framework
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.2.1.js
https://s3.amazonaws.com/public-airbug/bugcore-0.2.1.min.js
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.1.11.min.js"></script>
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugcore-0.2.1.min.js"></script>
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.1.11.js"></script>
<script type="text/javascript" src="https://s3.amazonaws.com/public-airbug/bugcore-0.2.1.js"></script>
<script type="text/javascript">
var map = new bugcore.Map();
</script>
Core class used to build other classes.
Class
/**
* @constructor
*/
var Class = function() {
Getters and Setters Summary
public getConstructor() :function(new:Constructor)public getInterfaces() :Array.<Interface>public getSuperclass() :ClassStatic Method Summary
static declare(Object declaration) :function(new:Constructor)static extend(function(new:Constructor) constructor, Object declaration) :function(new:Constructor)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} declaration
* @return {function(new:Constructor)}
*/
Class.declare = function(declaration) {
Parameters
declaration {Object} - 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.
}
});
Method
/**
* @static
* @param {function(new:Constructor)} constructor
* @param {Object} declaration
* @return {function(new:Constructor)}
*/
Class.extend = function(constructor, declaration) {
Parameters
constructor {function(new:Constructor)} - The constructor of the class to extend.declaration {Object} - 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() {
}
});
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
Static Getters and Setters Summary
Get the Class for this instance.
Method
/**
* @return {Class}
*/
getClass: function() {
Parameters
Returns
{Class} - The Class of this instance.Examples
//TODO BRN: Provide example of Class usage
Get the Class for this Constructor.
Method
/**
* @static
* @return {Class}
*/
Constructor.getClass = function() {
Parameters
Returns
{Class} - The Class of this Constructor.Examples
//TODO BRN: Provide example of Class usage
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
Getters and Setters Summary
Method Summary
Static Method Summary
static clone(A value, boolean deep) :Astatic equals(* value1, * value2) :booleanstatic hashCode(* value) :numberMethod
/**
* @constructs
*/
_constructor: function() {
Parameters
Examples
var myObj = new Obj();
Method
/**
* @return {number}
*/
getInternalId: function() {
Parameters
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
Method
/**
* @param {boolean=} deep
* @return {*}
*/
clone: function(deep) {
Parameters
deep {boolean=} - Whether or not to perform a deep clone. Optional - default: falseReturns
{*} - 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.
Method
/**
* @param {*} value
* @return {boolean}
*/
equals: function(value) {
Parameters
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
Method
/**
* @return {number}
*/
hashCode: function() {
Parameters
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
Parameters
value {A} - The value to clone.deep {boolean=} - Whether or not to perform a deep clone. Optional - default: falseReturns
{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
Method
/**
* @static
* @param {*} value1
* @param {*} value2
* @return {boolean}
*/
Obj.equals = function(value1, value2) {
Parameters
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
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);
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
Getters and Setters Summary
public getCauses() :Array.<(Throwable | Error)>public getData() :*public setData(* data)public getMessage() :stringpublic setMessage(string message)public getStack() :stringpublic getType() :stringMethod Summary
public addCause((Throwable | Error) cause) :*public toObject() :{ causes: Array.<Throwable>, data: *, message: string, type: string}Method
/**
* @constructs
* @param {string} type
* @param {*=} data
* @param {string=} message
* @param {Array.<(Throwable | Error)>=} causes
*/
_constructor: function(type, data, message, causes) {
Parameters
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;
}
Get the causes of the Throwable.
Method
/**
* @return {Array.<(Throwable | Error)>}
*/
getCauses: function() {
Parameters
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]
}
Add a cause to the Throwables list of causes.
Notes
Method
/**
* @param {(Throwable | Error)} cause
*/
addCause: function(cause) {
Parameters
cause {(Throwable | Error)} - The cause to add to the Throwable's array of causes.Returns
Examples
Add multiple causes to a single throwable
var myThrowable = new Throwable("MultipleCauses", {}, "Several things went wrong");
//We want this to complete the looping even if a throwable occurs.
for (var i = 0; i < 10; i++) {
try {
somethingMightGoWrong();
} catch (error) {
myThrowable.addCause(error);
}
}
The root class of several of the data objects. A collection represents a group of items.
Notes
Class
/**
* @class
* @extends {Obj}
* @implements {IArrayable}
* @implements {ICollection.<I>}
* @implements {IIterable}
* @template I
*/
var Collection = Class.extend(Obj, /** @lends {Collection.prototype} */{
Extends
Interfaces
Constructor Summary
Getters and Setters Summary
Method Summary
public add(I item):booleanpublic addAll((ICollection.<I> | Array.<I>) items)public clear()public contains(* value):booleanpublic containsAll((ICollection.<*> | Array.<*>) values):booleanpublic containsEqual((ICollection.<*> | Array.<*>) values):booleanpublic forEach(function(I) func)public getCount():numberpublic getValueArray():Array.<I>public getValueCount(* value):numberpublic isEmpty():booleanpublic iterator():IIteratorpublic map(function fn, Object context):ICollectionpublic remove(* value):booleanpublic removeAll((ICollection.<*> | Array.<*>) values)public retainAll((ICollection.<*> | Array.<*>) values)public toArray():Array.<I>Method
/**
* @constructs
* @param {(ICollection.<I>; | Array.<I>)=} items
*/
_constructor: function(items) {
Parameters
items {(ICollection.<I> | Array.<I>)=} - Starting items to add to the Collection (Optional)Examples
No parameters
var myCollection = new Collection();
Array parameter
var items = [
"item1",
"item2"
];
var myCollection = new Collection(values);
Other Collection parameter
var itemsCollection = new Collection([
"item1",
"item2"
]);
var myCollection = new Collection(itemsCollection);
Method
/**
* @return {HashStore}
*/
getHashStore: function() {
Parameters
Returns
{HashStore} - The underlying HashStore that supports this CollectionExamples
var myCollection = new Collection();
var hashStore = myCollection.getHashStore();
Adds an item to the collection
Method
/**
* @param {I} item
* @return {boolean}
*/
add: function(item) {
Parameters
item {I} - The item to add to the collectionReturns
{boolean} - Whether or not the item was added to the collection.Examples
var myCollection = new Collection();
var myItem = "myItem";
var result = myCollection.add(myItem); // true
Adds an Array or Collection of items to the Collection
Method
/**
* @param {(ICollection.<I> | Array.<I>)} items
*/
addAll: function(items) {
Parameters
items {(ICollection.<I> | Array.<I>)} - The items to add to the collection. Can either be an Array or another Collection.Returns
Examples
Add an array of items.
var myCollection = new Collection();
var myItems = [
"item1",
"item2"
];
myCollection.addAll(myItems);
Add a Collection of items.
var myCollection = new Collection();
var itemsCollection = new Collection([
"item1",
"item2"
]);
myCollection.addAll(itemsCollection);
Removes all of the items from this collection.
Method
/**
*
*/
clear: function() {
Parameters
Returns
Examples
Empty the Collection
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.getCount(); // 2
myCollection.clear();
myCollection.getCount(); // 0
Checks the Collection to see if it contains a value.
Method
/**
* @param {*} value
* @return {boolean}
*/
contains: function(value) {
Parameters
value {*} - The value that we're checking if the collection contains.Returns
{boolean}Examples
Value not contained
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.contains("item3"); // false
Value contained
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.contains("item2"); // true
Checks the Collection to see if it contains all of the values in the given argument. If ALL of the values are contained by the collection, this method will return true. Otherwise, false.
Notes
Method
/**
* @param {(ICollection.<*> | Array.<*>)} values
* @return {boolean}
*/
containsAll: function(values) {
Parameters
values {(ICollection.<*> | Array.<*>)} - The values that we're checking to see if the collection contains all of them.Returns
{boolean}Examples
Values not contained
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsAll(["item3"]); // false
Partial values contained are not a match.
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsAll(["item2", "item3"]); // false
Values contained
var myCollection = new Collection([
"item1",
"item2",
"item3"
]);
myCollection.containsAll(["item2", "item3"]); // true
Exact match is true
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsAll(["item1", "item2"]); // true
Multiple elements are ignored. Match is true.
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsAll(["item1", "item2", "item2"]); // true
Empty collections are contained by any collection
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsAll([]); // true
Checks the Collection to see if it contains exactly the values in the given argument. If the collection contains the exact same values as the collection given in the parameter, this method will return true. Otherwise, false.
Method
/**
* @param {(ICollection.<*> | Array.<*>)} values
* @return {boolean}
*/
containsEqual: function(values) {
Parameters
values {(ICollection.<*> | Array.<*>)} - The values that we're checking to see if the collection contains exactly.Returns
{boolean}Examples
Values not contained at all
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsEqual(["item3"]); // false
Partial values contained are not a match.
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsEqual(["item2", "item3"]); // false
Values contained but not an exact match
var myCollection = new Collection([
"item1",
"item2",
"item3"
]);
myCollection.containsEqual(["item2", "item3"]); // false
Exact match is true
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.containsEqual(["item1", "item2"]); // true
Exact match out of order is true
var myCollection = new Collection([
"item2",
"item1"
]);
myCollection.containsEqual(["item1", "item2"]); // true
Multiple elements are considered
var myCollection = new Collection([
"item1",
"item2",
"item2"
]);
myCollection.containsEqual(["item1", "item2"]); // false
forEach executes the provided function once for each element of the Collection.
Notes
Method
/**
* @param {function(I)} func
*/
forEach: function(func) {
Parameters
func {function(I)} - The function to execute for each itemReturns
Examples
Execute for each item
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.forEach(function(item) {
console.log(item); // item1 on first pass, item2 on second
});
Partial values contained are not a match.
var myCollection = new Collection([]);
myCollection.forEach(function(item) {
console.log(item); // never executed
});
Returns the number of items in the collection.
Method
/**
* @return {number}
*/
getCount: function() {
Parameters
Returns
{number} - The number of items in the Collection.Examples
Empty Collection
var myCollection = new Collection([]);
myCollection.getCount(); //0
Starts with 2 items
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.getCount() //2
Returns an Array of the Collection's values.
Notes
Method
/**
* @return {Array.<I>}
*/
getValueArray: function() {
Parameters
Returns
{Array.<I>} - An Array of the Collection's values.Examples
Empty Collection
var myCollection = new Collection([]);
myCollection.getValueArray(); // []
Starts with 2 items (order of items shown in examples is not indicative of real world results)
var myCollection = new Collection([
"item1",
"item2"
]);
myCollection.getValueArray() // ["item1", "item2"]
Manipulation of Collection after array is returned. (order of items shown in examples is not indicative of real world results)
var myCollection = new Collection([
"item1",
"item2"
]);
var myValueArray = myCollection.getValueArray();
myCollection.add("item3") // ["item1", "item2"]
console.log(myCollection.getValueArray()) // ["item1", "item2", "item3"]
console.log(myValueArray) // ["item1", "item2"]
The root event class for all other events in the bugcore system.
Notes
Class
/**
* @class
* @extends {Obj}
*/
var Event = Class.extend(Obj, /** @lends {Event.prototype} */{
Extends
Constructor Summary
Getters and Setters Summary
public getBubbles() :booleanpublic setBubbles(boolean bubbles)public getCurrentTarget() :*public setCurrentTarget(* currentTarget)public getData() :*public getTarget(): *public setTarget(* target)public getType() :stringMethod Summary
Method
/**
* @constructs
* @param {string} type
* @param {*=} data
*/
_constructor: function(type, data) {
Parameters
type {string} - The type of this eventdata {*=} - Any data to pass along with this Event (Optional)Examples
Simple instantiation
var myEvent = new Event("MyEvent");
Dispatching an event
var myDispatcher = new EventDispatcher();
myDispatcher.dispatchEvent(new Event("MyEvent", {my: "data"}));
Whether or not this Event bubbles
Notes
Method
/**
* @return {boolean}
*/
getBubbles: function() {
Parameters
Returns
{boolean} - Whether or not this event bubblesExamples
var myEvent = new Event();
myEvent.getBubbles(); // true
Returns whether or not propagation of this event has stopped.
Notes
stopPropagation()]("#Event_stopPorpagation"]Method
/**
* @return {boolean}
*/
isPropagationStopped: function() {
Parameters
Returns
{boolean} - Whether or not propagation of this event has stopped.Examples
var myEvent = new Event();
myEvent.isPropagationStopped(); // false;
myEvent.stopPropagation();
myEvent.isPropagationStopped(); // true;
Utility class for determining the data type of values.
Class
/**
* @constructor
*/
var TypeUtil = function() {
Static Method Summary
static isArray(* value) :booleanstatic isBoolean(* value) :booleanstatic isDate(* value) :booleanstatic isFunction(* value) :booleanstatic isNull(* value) :booleanstatic isNumber(* value) :booleanstatic isObject(* value) :booleanstatic isString(* value) :booleanstatic isUndefined(* value) :booleanstatic toType(* value) :stringDetermines if the given value is an array.
Method
/**
* @static
* @param {*} value
* @return {boolean}
*/
TypeUtil.isArray = function(value) {
Parameters
value {*} - The value to check for the type of arrayReturns
{boolean} - Whether or not the value is an array.Examples
Array literal is an array
var myArray = [];
TypeUtil.isArray(myArray); //true
Instance of Array is an array
var myArray = new Array();
TypeUtil.isArray(myArray); //true
Instance of Collection is NOT an array
var myCollection = new Collection();
TypeUtil.isArray(myCollection); //false
number is NOT an array
var myNumber = 123;
TypeUtil.isArray(myNumber); //false
FAQs
bugcore is a JavaScript library that provides a foundational architecture for object oriented JS
The npm package bugcore receives a total of 62 weekly downloads. As such, bugcore popularity was classified as not popular.
We found that bugcore demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.