Comparing version 2.5.0 to 2.6.0
14
index.js
@@ -28,2 +28,4 @@ 'use strict'; | ||
* | ||
* @this Base class being extended from (i.e., its constructor function object). | ||
* | ||
* @param {string} [extendedClassName] - This is simply added to the prototype as $$CLASS_NAME. Useful for debugging because all derived constructors appear to have the same name ("Constructor") in the debugger. | ||
@@ -108,2 +110,6 @@ * | ||
if (typeof this.postExtend === 'function') { | ||
this.postExtend(prototype); | ||
} | ||
return Constructor; | ||
@@ -161,2 +167,10 @@ } | ||
/** | ||
* Optional static method is called with new "class" (constructor) after extending. | ||
* This permits miscellaneous tweaking and cleanup of the new class. | ||
* @method postExtend | ||
* @param {object} prototype | ||
* @memberOf Base | ||
*/ | ||
/** @typedef {function} extendedConstructor | ||
@@ -163,0 +177,0 @@ * @property prototype.super - A reference to the prototype this constructor was extended from. |
{ | ||
"name": "extend-me", | ||
"version": "2.5.0", | ||
"version": "2.6.0", | ||
"main": "index.js", | ||
@@ -31,3 +31,2 @@ "description": "A class extender", | ||
"gulp-util": "^3.0.7", | ||
"jsdoc": "^3.3.3", | ||
"multipipe": "^0.2.1", | ||
@@ -34,0 +33,0 @@ "run-sequence": "^1.1.4", |
103
README.md
@@ -0,23 +1,11 @@ | ||
# extend-me | ||
A class extender | ||
### Update history | ||
## Require/include | ||
#### v2.5.0 | ||
* Added `parent(/*optional*/ancestorConstructorName)` to constructor to get the parent class's constructor or the named ancestor class's constructor. | ||
* Now resets returned constructor's `name` to `extendedClassName` OR `prototypeAdditions.$$CLASS_NAME` in the prototype OR `prototypeAdditions.name` | ||
#### v2.4.0 | ||
Previously, on instantiation, the `preInitialize` and `postInitialize` methods were called if and only if they were defined on the subclass's (extended object's) own prototype. This has been changed so that the "top" such methods on the prototype chain are now called, whether defined on the extended class or on an ancestor class. As before, these methods are called before and after the `initialize` cascade, respectively. Unlike `initialize`, however, there is no cascade; only the top most method is ever called. | ||
This was an oversight and the workaround has been to forward the calls by redefining new methods with these names whose sole function was to forward the call to `this.super`. This change is backwards compatible with that workaround; it will simply call the forwarding method as before. However, it is now safe to remove the forwarding methods altogether and the call will be made for you. | ||
This can be considered a breaking change because previously without the workarounds, such ancestor methods were not executed. If you were dependent on this unlikely scenario, you can restore that behavior by defining new methods with these names as no-ops. | ||
### Require/include | ||
Node.js / Browserify: | ||
```javascript | ||
var Base = require('extend-me').Base; | ||
var newClass = Base.extend(extendedClassName, prototype); | ||
var extend = require('extend-me'); | ||
``` | ||
@@ -35,14 +23,30 @@ | ||
### Syntax | ||
## Syntax | ||
### First establish a base class | ||
1. Use either the provided `extend.Base` (which provides `super` support): | ||
```javascript | ||
var newClass = Base.extend(extendedClassName, prototypeAdditions); | ||
var Base = extend.Base; | ||
``` | ||
2. Roll your own base class: | ||
```javascript | ||
var MyBase() { ... } | ||
MyBase.extend = extend; | ||
``` | ||
* `Base` could also be any descendant class (previously extended in this way). | ||
* `extendedClassName` _Optional._ This value if provided is copied to the prototype as `$$CLASS_NAME` and is useful in debugging to identify the derived class, the name of which is otherwise (unfortunately) not displayed by the debugger. Could also be useful in your code (something not easily available in standard JavaScript). | ||
* `prototypeAdditions` _Required._ The members (properties and methods) of this object are added to the new constructor's prototype. Getter/setter literal syntax is not supported but you can use `defineProperty`'s {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty|descriptor objects}. These are recognized with duck-typing. See API doc for details. | ||
### Then extend it | ||
### Usage | ||
```javascript | ||
var MyClass = Base.extend(extendedClassName, prototypeAdditions); | ||
``` | ||
where: | ||
* `Base` is the base class being extended from. This could also be any descendant class (any class previously extended in this way). | ||
* `extendedClassName` _Optional._ This value, if provided, is copied to the prototype as `$$CLASS_NAME` and is useful in debugging to identify the derived class, the name of which is otherwise (unfortunately) not displayed by the debugger. Could also be useful in your code. You can also name a class by including `$$CLASS_NAME` or simply `name` in `prototypeAdditions`. | ||
* `prototypeAdditions` _Required._ A prototype object for the new class. The members of this object are added to the new constructor's prototype. | ||
## Usage | ||
```javascript | ||
@@ -93,8 +97,8 @@ var MyClass = Base.extend({ | ||
### Constructors | ||
## Constructors | ||
You may optionally supply an `initialize` method to be called as your constructor. | ||
It will be called on object instantiation with the same parameters as passed to the actual constructor. | ||
You may optionally supply an `initialize` method to be called as your practical constructor. | ||
It will be called upon object instantiation with the same parameters as passed to the actual constructor. | ||
## Initialization Chain | ||
### Initialization Chain | ||
@@ -117,19 +121,54 @@ There may be `initialize` methods at each level of inheritance. | ||
## Super | ||
## `Base` | ||
You can reference the immediate ancestor in the prototype chain with the `super` | ||
(a getter on `Base`'s prototype), as shown in the example above. | ||
A base class is provided in `extend.Base`. This base class contains the methods described below. | ||
Use of `Base` is not required, however, as you can also create your own base class simply by adding `extend` to it (see [Syntax](#syntax) above). | ||
### API documentation | ||
```js | ||
function MyBase() {} | ||
MyBase.extend = extend; | ||
The following methods are available in the prototype of `extend.Base`. | ||
### `super` | ||
Reference to the immediate ancestor in the prototype chain. Implemented as a getter on the `Base`'s prototype. See example above. | ||
### `superMember(memberName)` | ||
Find member on prototype chain beginning with super class. | ||
### `superMethod(methodName)` | ||
Find method on prototype chain beginning with super class. | ||
### `callSuperMethod(methodName, arg1, arg2, arg3, ...)` | ||
Find method on prototype chain beginning with super class and call it with remaining args. | ||
## API documentation | ||
Detailed API docs can be found [here](http://joneit.github.io/extend-me/extend-me.html). | ||
### Demo | ||
## Demo | ||
A demo can be found [here](http://joneit.github.io/extend-me/demo.html). | ||
### Submodules | ||
## Update history | ||
### v2.6.0 | ||
* Added `postExtend`, an optional static method of the base "class" (constructor). When defined, it is called at the end of `extend()` with the new "class" (new constructor) as its sole parameter. This permits miscellaneous tweaking and cleanup of the new class. | ||
### v2.5.0 | ||
* Added `parent(/*optional*/ancestorConstructorName)` to constructor to get the parent class's constructor or the named ancestor class's constructor. | ||
* Now resets returned constructor's `name` to `extendedClassName` OR `prototypeAdditions.$$CLASS_NAME` in the prototype OR `prototypeAdditions.name` | ||
### v2.4.0 | ||
Previously, on instantiation, the `preInitialize` and `postInitialize` methods were called if and only if they were defined on the subclass's (extended object's) own prototype. This has been changed so that the "top" such methods on the prototype chain are now called, whether defined on the extended class or on an ancestor class. As before, these methods are called before and after the `initialize` cascade, respectively. Unlike `initialize`, however, there is no cascade; only the top most method is ever called. | ||
This was an oversight and the workaround has been to forward the calls by redefining new methods with these names whose sole function was to forward the call to `this.super`. This change is backwards compatible with that workaround; it will simply call the forwarding method as before. However, it is now safe to remove the forwarding methods altogether and the call will be made for you. | ||
This can be considered a breaking change because previously without the workarounds, such ancestor methods were not executed. If you were dependent on this unlikely scenario, you can restore that behavior by defining new methods with these names as no-ops. | ||
## Submodules | ||
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. |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
17357
15
190
172