extend-me - npm Package Compare versions

Comparing version 1.0.2 to 1.1.0

index.js

@@ -16,15 +16,21 @@ 'use strict';
  * For example, if you wish to extend `BaseConstructor` to a new constructor with prototype overrides and/or additions, usage is:
+ *
  * ```javascript
  * extend.call(BaseConstructor, prototypeAdditions);`
  * ```
+ *
  * More elegantly, you can mix it in:
+ *
  * ```javascript
  * BaseConstructor.extend = extend
  * ```
+ *
  * and call it like this:
+ *
  * ```javascript
  * var ExtendedConstructor = BaseConstructor.extend(prototypeAdditions);
  * ```
- * To make `ExtendedConstructor` itself extensible, give it too an `extend` property as above, or simply include the special property `extendable: true` (see below) in the prototype additions, which attaches the `extend` property to the constructor for you.
  *
+ * This function (`extend()`) is added to the new extended object constructor as a property `.extend`, essentially making the object constructor itself easily "extendable." (Note: This is a property of each constructor and not a method of its prototype!)
+ *
  * @param {extendedPrototypeAdditionsObject} prototypeAdditions - Object with members to copy to new constructor's prototype. Most members will be copied to the prototype. Some members, however, have special meanings as explained in the {@link extendedPrototypeAdditionsObject|type definition} (and may or may not be copied to the prototype).
@@ -36,35 +42,45 @@ *
     function Constructor() {
+        if (prototypeAdditions && prototypeAdditions.preInitialize) {
+            prototypeAdditions.preInitialize.apply(this, arguments);
+        }
+
         initializePrototypeChain.apply(this, arguments);
 
-        if (prototypeAdditions.initializeOwn) {
-            prototypeAdditions.initializeOwn.apply(this, arguments);
+        if (prototypeAdditions && prototypeAdditions.postInitialize) {
+            prototypeAdditions.postInitialize.apply(this, arguments);
         }
     }
 
+    Constructor.extend = extend;
+
     var prototype = Constructor.prototype = Object.create(this.prototype);
     prototype.constructor = Constructor;
 
-    prototype.super = this.prototype;
-
     if (prototypeAdditions) {
         for (var key in prototypeAdditions) {
-            var value = prototypeAdditions[key];
-            switch (key) {
-                case 'initializeOwn':
-                    // already called above; not needed in prototype
-                    break;
-                case 'extendable':
-                    Constructor.extend = extend;
-                    break;
-                case 'aliases':
-                    for (var alias in value) {
-                        makeAlias(value[alias], alias);
-                    }
-                    break;
-                default:
-                    if (typeof value === 'string' && value[0] === '#') {
-                        makeAlias(value, key.substr(1));
-                    } else {
-                        prototype[key] = value;
-                    }
+            if (prototypeAdditions.hasOwnProperty(key)) {
+                var value = prototypeAdditions[key];
+                switch (key) {
+                    case 'initializeOwn':
+                        // already called above; not needed in prototype
+                        break;
+                    case 'aliases':
+                        for (var alias in value) {
+                            if (value.hasOwnProperty(alias)) {
+                                makeAlias(value[alias], alias);
+                            }
+                        }
+                        break;
+                    case '$$CLASS_NAME':
+                        if (extend.copyClassNames) {
+                            prototype[key] = value;
+                        }
+                        break;
+                    default:
+                        if (typeof value === 'string' && value[0] === '#') {
+                            makeAlias(value, key.substr(1));
+                        } else {
+                            prototype[key] = value;
+                        }
+                }
             }
@@ -80,3 +96,7 @@ }
 }
+extend.copyClassNames = true;
 
+extend.Base = function () {};
+extend.Base.extend = extend;
+
 /** @typedef {function} extendedConstructor
@@ -90,6 +110,6 @@ * @property prototype.super - A reference to the prototype this constructor was extended from.
  * @property {function} [initializeOwn] - Additional constructor code for new object. This method is added to the new constructor's prototype. Gets passed new object as context + same args as constructor itself. Called on instantiation after (all) the `initialize` function(s).
- * @property {boolean} [extendable] - Truthy value adds this function (`extend()`) as a property `.extend()` of the new extended object constructor, essentially making the object constructor itself easily "extensible" (i.e, able to create new constructors that inherit form this constructor). (Alternatively, even without doing this, you can always extend from any constructor by calling `extend.call(ConstructorToInheritFrom, {...})`.) (Not added to prototype.)
  * @property {object} [aliases] - Hash of aliases for prototype members in form `{ key: 'member', ... }` where `key` is the name of an alieas and `'member'` is the name of an existing member in the prototype. Each such key is added to the prototype as a reference to the named member. (The `aliases` object itself is *not* added to prototype.) Alternatively:
  * @property {string} [keys] - Arbitrary property names defined here with string values starting with a `#` character will alias the actual properties named in the strings (following the `#`). This is an alternative to providing an `aliases` hash, perhaps simpler (though subtler). (Use arbitrary identifiers here; don't use the name `keys`!)
  * @property {*} [arbitraryProperties] - Any additional arbitrary properties defined here will be added to the new constructor's prototype. (Use arbitrary identifiers here; don't use the name `aribitraryProperties`!)
+ * @property {string} [$$CLASS_NAME] - This is simply copied to the prototype. Useful for debugging purposes because all derived constructors appear to have the same name ("Constructor") in the debugger. This property is ignored when `extend.classnames` is set to `false`.
  */
@@ -96,0 +116,0 @@

package.json

 {
   "name": "extend-me",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "main": "index.js",
@@ -5,0 +5,0 @@ "description": "Yet another Backbone-like class extender",

README.md

 # extend-me
 Yet another Backbone-like class extender
 
+**Version 2.0 has a breaking changes:**
+1. `this.super` has been removed as it suffered the "grandchild" problem; use `YourBaseClass.prototype` instead.
+2. The `.initializeOwn` method has been renamed to `.postInitialize`.
+
 ## Synopsis
 
 ```javascript
-var extend = require('extend-me');
+var Base = require('extend-me').Base;
 
-function Parabola() {}
+var Parabola = Base.extend({
+    initialize: function (a, b) {
+        this.a = a;
+        this.b = b;
+    },
+    calculate: function(x) {
+        return this.a * Math.pow(x, 2) + (this.b * x);
+    }
+});
 
-Parabola.extend = extend;
-
-Parabola.initialize = function (a, b) { this.a = a; this.b = b; };
-Parabola.prototype.func = function(x) { return this.a * Math.pow(x, 2) + (this.b * x); };
-
 var ParabolaWithIntercept = Parabola.extend({
@@ -20,14 +27,38 @@ initialize: function(a, b, c) {
     },
-    func: function(x) {
-        return this.super.pow.apply(this, arguments) + this.c;
+    calculate: function(x) {
+        var y = Parabola.prototype.calculate.apply(this, arguments);
+        return y + this.c;
     }
-}
+});
 
+var parabola = new ParabolaWithIntercept(3, 2, 1),
+    y = ParabolaWithIntercept(-3); // yields 22
 ```
 
-\[See the note [Regarding submodules](https://github.com/openfin/rectangular#regarding-submodules)
-for important information on cloning this repo or re-purposing its build template.\]
+### Constructors
 
+The `initialize` methods at each level of inheritance are the constructors.
+Instantiating a derived class will automatically call `initialize` on all ancestor
+classes that implement it, starting with the most distant ancestor all the way to
+and inclucing the derived class in question.
+
+If you intend to instantiate the base class (`Parabola` in the above) directly
+(_i.e.,_ it is not "abstract"), include the following in the constructor:
+
+```javascript
+function Parabola() {
+    this.initialize.apply(this, arguments);
+}
+```
+
+To add initialization code to be executed before or after this chain of `initialize`
+calls, you an define methods `preInitialize` and `postInitialize`.
+
 ## API documentation
 
 Detailed API docs can be found [here](http://openfin.github.io/extend-me/extend-me.html).
+
+## Regarding the git submodule `jsdoc-template`
+
+See the note [Regarding submodules](https://github.com/openfin/rectangular#regarding-submodules)
+for important information on cloning this repo or re-purposing its build template.

No alert changes

Improved metrics

Total package byte prevSize

10473

increased by16.96%

Lines of code

124

increased by15.89%

Number of lines in readme file

64

increased by93.94%

No dependency changes