Inheritance.js
Simple, lightweight extensions and helpers that make inheritance in JS a breeze, all with pure JavaScript, no extra libraries needed.
Includes support for AMD, CommonJS, and global inclusion via an HTML script tag.
Special Thanks to YouMightNotNeedjQuery.com. The functions
mix
,mixDeep
,mixPrototype
, andmixPrototypeDeep
were based largly off of their implementation of "Extend" and "Deep Extend".
Install
-
NPM:
$ npm install --save inheritance-js
-
Bower:
$ bower install --save inheritance-js
-
CDN (minified):
<script src="//npmcdn.com/inheritance-js@0.4.11/dist/inheritance.min.js"></script>
-
CDN (not minified):
<script src="//npmcdn.com/inheritance-js@0.4.11"></script>
- Download
Features
- Built with fully native, pure JavaScript! No extra libraries needed.
- Make any object inheritable with one function call.
- Make any object non-inheritable ("sealed") with one function call.
- Easily create object definitions containing...
- Object definition creation is made much more readable/maintainable.
- Mix multiple objects into one. (Almost same as jQuery/underscore/lodash
extend
). - Optional extensions/inheritance for native JavaScript objects (Full List of Native Object Extensions)
- Support for...
- AMD
- CommonJS
- Global HTML script tag
Documentation
Table of Contents
- Code Samples
- Including the Library in your project
- Functions
-
Functions Added to
Object
(These additions are optional)
Code Samples
Including the Library in your project
Note: If you don't want any native objects to be modified by this library, just use
inheritance.noexts.js
rather thaninheritance.js
.
Include as AMD Module
define([ 'inheritance' ], function(I) {
I.mix(...);
var MyObj = I.ObjectDefinition.create(...);P
...
});
Include as CommonJS Module
var I = require('inheritance');
I.mix(...);
var MyObj = I.ObjectDefinition.create(...);
...
Include via HTML Script Tag
<script type="text/javascript" src="inheritance.min.js" />
<script type="text/javascript">
I.mix(...);
// Notice that `ObjectDefinition` belongs to the `window` object, not the `I` namespace.
var MyObj = ObjectDefinition.create(...);
...
</script>
Functions
ObjectDefinition.create(objDef)
Creates a new object (I.E. "class") that can be inherited.
NOTE: The new object inherits the native JavaScript
Object
.
Parameters
Name | Type | Description |
---|---|---|
objDef |
Object | TODO |
Returns
-
Object
- The newly created, inheritable, object that inheritsObject
.
Usage
ObjectDefinition.createSealed(objDef)
Creates a new object (I.E. "class") that CANNOT be inherited.
NOTE: The new object inherits the native JavaScript
Object
.
Parameters
Name | Type | Description |
---|---|---|
objDef |
Object | TODO |
Returns
-
Object
- The newly created, non-inheritable, object that inheritsObject
.
Usage
TODO
inheritance(parent, objDefProps)
Creates a new object definition based upon the given objDefProps
that inherits the
given parent
.
Parameters
Name | Type | Description |
---|---|---|
parent | Object | The object to be inherited. |
*objDefProps | Object | An object containing all properties to be used in creating the new object definition that will inherit the given parent object. If this parameter isundefined or null , then a new child object definition is created. TODO: Add reference to the objDefProps spec
|
Returns
-
Object
- An object created from the givenobjDefProps
that inheritsparent
.
Usage
TODO
makeInheritable(obj, overwrite, ignoreOverwriteError)
Makes an object inheritable by adding a function called extend
as a "static" property
of the object. (I.E. Calling this function passing MyObject
as a parameter, creates
MyObject.extend
)
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object to make inheritable. |
*overwrite | Boolean | If true , then an existing extend property will be overwritten regardless of it's value. |
*ignoreOverwriteError | Boolean | If true , then no error will be thrown if obj.extend already exists and overwrite is not true . |
Returns
-
Object
- The modifiedobj
given.
Errors thrown
-
TypeError
- Ifobj
isundefined
ornull
. -
TypeError
- Ifobj.extend
already exists andoverwrite
is NOT equaltrue
.
Usage
TODO
seal(obj, overwrite, ignoreOverwriteError)
Makes an object sealed by adding a function called extend
as a "static" property
of the object that throws an error if it is ever called. Also adds a readonly
"static" property named sealed
to the object definition that is set to true
,
thus allowing for one to quickly determine whether or not an object's definition
is sealed without catching the error thrown by it's extend
function.
(I.E. Calling this function passing MyObject
as a parameter, creates
MyObject.extend
and MyObject.sealed
, where MyObject.sealed
will always be
true
)
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object to seal. |
*overwrite | Boolean | If true , then an existing extend property will be overwritten regardless of it's value. |
*ignoreOverwriteError | Boolean | If true , then no error will be thrown if obj.extend already exists and overwrite is not true . |
Returns
-
Object
- The modifiedobj
given.
Errors thrown
-
TypeError
- Ifobj
isundefined
ornull
. -
TypeError
- Ifobj.extend
already exists andoverwrite
is NOT equaltrue
.
Usage
TODO
mix(obj, mixins)
TODO
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object to mix into. NOTE: undefined and null are both VALID values for this parameter. If obj is undefined or null , then a new object will be created from the mixins given. |
mixins | Array | An array of objects whose properties should be mixed into the given obj .NOTE: The order of objects in this array does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- The mixed version ofobj
.
Usage
TODO
mixDeep(obj, mixins)
TODO
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object to deep mix into. NOTE: undefined and null are both VALID values for this parameter. If obj is undefined or null , then a new object will be created from the mixins given. |
mixins | Array | An array of objects whose properties should be deep mixed into the given obj .NOTE: The order of objects in this array does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- The deep mixed version ofobj
.
Usage
TODO
mixPrototype(obj, mixins)
TODO
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object containing the prototype to mix into. NOTE: undefined and null are both VALID values for this parameter. If obj is undefined or null , then a new object will be created from the mixins given. |
mixins | Array | An array of objects whose properties should be mixed into the prototype of the given obj .NOTE: The order of objects in this array does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- The mixed version ofobj
.
Errors thrown
-
TypeError
- Ifobj.prototype
does not exist.
Usage
TODO
mixPrototypeDeep(obj, mixins)
TODO
Parameters
Name | Type | Description |
---|---|---|
obj | Object | The object containing the prototype to deep mix into. NOTE: undefined and null are both VALID values for this parameter. If obj is undefined or null , then a new object will be created from the mixins given. |
mixins | Array | An array of objects whose properties should be deep mixed into the prototype of the given obj .NOTE: The order of objects in this array does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- The deep mixed version ofobj
.
Errors thrown
-
TypeError
- Ifobj.prototype
does not exist.
Usage
TODO
Object
Functions Added to Object.extend(objDefProps)
Creates a new object definition based upon the given objDefProps
and causes that new object definition to inherit this object.
NOTE: For a list of all native JavaScript objects that have this function added to them, see the wiki page. All of the other native JavaScript objects with this function work exactly as described here (I.E. this piece of documentation is not specific to
Object
).
Parameters
Name | Type | Description |
---|---|---|
objDefProps | Object | An object containing all properties to be used in creating the new object definition that will inherit the Object . If this parameter is undefined or null , then a new child object definition is created. TODO: Add reference to the objDefProps spec
|
Returns
-
Object
- An object created from the givenobjDefProps
that inheritsObject
.
Usage
var ChildObject = Object.extend({
// Child Definition Properties
});
Object.prototype.mix(...)
TODO
Parameters
Name | Type | Description |
---|---|---|
arguments | Object... | Mixin objects whose properties should be mixed into the Object .NOTE: The order of objects passed as arguments does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- TheObject
, mixed with the given mixin objects.
Usage
var obj = new Object();
obj.value0 = 42;
obj.value1 = "Fish fingers and custard";
obj.value2 = {
value0: 20,
value1: 21
}
obj.func0 = function() {
console.log('func0');
};
obj.func1 = function() {
console.log('func1');
};
var mixin0 = {
mixin0Var0: 0,
mixin0Var1: 0.1,
mixin0Func0: function() {
console.log('mixin0Func0');
},
mixin0Func1: function() {
console.log('mixin0Func1');
},
value2: {
value0: "Blah"
}
};
var mixin1 = {
mixin1Var0: 1,
mixin1Var1: 1.1,
value0: 24,
func0: function() {
console.log('func0 overridden by mixin1');
},
mixin0Func: function() {
console.log('mixin0Func overridden by mixin1');
}
};
var mixin2 = {
mixin2Var: 2,
mixin2Func: function() {
console.log('mixin2Func');
},
value0: 4400,
func0: function() {
console.log('func0 overridden by mixin2');
},
mixin0Var1: 2.1,
mixin0Func0: function() {
console.log('mixin0Func0 overridden by mixin2');
},
mixin1Var0: 2.2
};
// At this point, `obj` can be represented as follows:
// {
// value0: 42,
// value1: "Fish fingers and custard"
// func0: function() {...},
// func1: function() {...}
// }
var newObj = obj.mix(mixin0, mixin1, mixin2);
console.log('newObj.value0 = ' + newObj.value0); // newObj.value0 = 4400
console.log('newObj.value1 = ' + newObj.value1); // newObj.value1 = "Fish fingers and custard"
console.log('newObj.value2.value0 = ' + newObj.value2.value0) // newObj.value2.value0 = "Blah"
console.log('newObj.value2.value1 = ' + newObj.value2.value1) // newObj.value2.value1 = undefined
console.log('newObj.mixin0Var0 = ' + newObj.mixin0Var0); // newObj.mixin0Var0 = 0
console.log('newObj.mixin0Var1 = ' + newObj.mixin0Var1); // newObj.mixin0Var1 = 2.1
console.log('newObj.mixin1Var0 = ' + newObj.mixin1Var0); // newObj.mixin1Var0 = 1
console.log('newObj.mixin1Var1 = ' + newObj.mixin1Var1); // newObj.mixin1Var1 = 2.1
console.log('newObj.mixin2Var = ' + newObj.mixin2Var); // newObj.mixin2Var = 2
newObj.func0() // Prints "func0 overridden by mixin2"
newObj.func1() // Prints "func1"
newObj.mixin0Func0() // Prints "mixin0Func0 overridden by mixin2"
newObj.mixin0Func1() // Prints "mixin0Func1 overridden by mixin1"
newObj.mixin2Func() // Prints "mixin2Func"
Object.prototype.mixDeep(...)
TODO
Parameters
Name | Type | Description |
---|---|---|
arguments | Object... | Mixin objects whose properties should be deep mixed into the Object .NOTE: The order of objects in this array does matter! If there are properties present in multiple mixin objects, then the mixin with the largest index value overwrite any values set by the lower index valued mixin objects. |
Returns
-
Object
- TheObject
, deep mixed with the given mixin objects.
Usage
TODO
Contributing
See contribution documentation page for details.