inheritance-js

Inheritance.js

 

WARNING: This project has been deprecated and will be removed from NPM and Bower in about 6 months (Feb, 2017)! This project started out as an experiment/learning tool for me, but I ultimately found that the approach taken in the project is VERY inefficient. I'm truly very sorry for any inconvenience this may cause. I recommend as a replacement that you use the native inheritance functionality of JavaScript, it's fast, and really actually not that hard to pick up; or just use ES6 classes. Trying to turn the prototypal inheritance into classical inheritance is really not worth it in JavaScript. It's better to embrace how the language works naturally, once you do, you'll never regret it. I will remove the library from NPM and Bower in about 6 months. If anyone would like to take over the project, just let me know.

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, and mixPrototypeDeep 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.12/dist/inheritance.min.js"></script>
• CDN (not minified): <script src="//npmcdn.com/inheritance-js@0.4.12"></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...
  • mixins (deep)
  • private properties
  • static properties
  • static constant properties
  • private static properties
  • getters (via get keyword)
  • setters (via set keyword)
• 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

Changelog

Table of Contents

• Code Samples
• Including the Library in your project
  • Include as AMD Module
  • Include as CommonJS Module
  • Include via HTML Script Tag
• Functions
  • ObjectDefinition.create
  • ObjectDefinition.createSealed
  • inheritance
  • makeInheritable
  • seal
  • mix
  • mixDeep
  • mixPrototype
  • mixPrototypeDeep
• Functions Added to Object (These additions are optional)
  • Object.extend
  • Object.prototype.mix
  • Object.prototype.mixDeep

Code Samples

• Create New Object Definition (I.E. "Class") [JSbin] [JSFiddle]

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 than inheritance.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 inherits Object.

Usage

• JSbin
• JSFiddle

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

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 given objDefProps that inherits parent.

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 modified obj given.

Errors thrown

• TypeError - If obj is undefined or null.
• TypeError - If obj.extend already exists and overwrite is NOT equal true.

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 modified obj given.

Errors thrown

• TypeError - If obj is undefined or null.
• TypeError - If obj.extend already exists and overwrite is NOT equal true.

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

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

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

Errors thrown

• TypeError - If obj.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 of obj.

Errors thrown

• TypeError - If obj.prototype does not exist.

Usage

TODO

Functions Added to Object

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 given objDefProps that inherits Object.

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 - The Object, 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 - The Object, deep mixed with the given mixin objects.

Usage

TODO

Contributing

See contribution documentation page for details.