-
-
-
-
-
-
-
-Function default
-
-
- default<DPType, DPCls>(theClass: DPCls, target: DPType, delegateFunc: DynamicProtoDelegate<DPType>, options?: IDynamicProtoOpts): void -
-
-
- -Type Parameters
--
-
-
-
DPType
- -
-
DPCls
--Parameters
--
-
-
-
theClass: DPCls
-This is the current class instance which contains the prototype for the current class
-
- -
-
target: DPType
-The current "this" (target) reference, when the class has been extended this.prototype will not be the 'theClass' value.
-
- -
-
delegateFunc: DynamicProtoDelegate<DPType>
-The callback function (closure) that will create the dynamic function
-
- -
-
-Optionaloptions: IDynamicProtoOptsAdditional options to configure how the dynamic prototype operates
-
Returns void
-
-
-
-
\ No newline at end of file
diff --git a/docs/typedoc/functions/default.html b/docs/typedoc/functions/default.html
new file mode 100644
index 0000000..ecf3db2
--- /dev/null
+++ b/docs/typedoc/functions/default.html
@@ -0,0 +1,25 @@
+Generated using TypeDoc
Function default
- default<DPType, DPCls>(theClass, target, delegateFunc, options?): void
Helper function when creating dynamic (inline) functions for classes, this helper performs the following tasks :-
+-
+
- Saves references to all defined base class functions +
- Calls the delegateFunc with the current target (this) and a base object reference that can be used to call all "super" functions. +
- Will populate the class prototype for all overridden functions to support class extension that call the prototype instance. +Callers should use this helper when declaring all function within the constructor of a class, as mentioned above the delegateFunc is +passed both the target "this" and an object that can be used to call any base (super) functions, using this based object in place of +super.XXX() (which gets expanded to _super.prototype.XXX()) provides a better minification outcome and also ensures the correct "this" +context is maintained as TypeScript creates incorrect references using super.XXXX() for dynamically defined functions i.e. Functions +defined in the constructor or some other function (rather than declared as complete typescript functions). +
Usage
+ +import dynamicProto from "@microsoft/dynamicproto-js";
class ExampleClass extends BaseClass {
constructor() {
dynamicProto(ExampleClass, this, (_self, base) => {
// This will define a function that will be converted to a prototype function
_self.newFunc = () => {
// Access any "this" instance property
if (_self.someProperty) {
...
}
}
// This will define a function that will be converted to a prototype function
_self.myFunction = () => {
// Access any "this" instance property
if (_self.someProperty) {
// Call the base version of the function that we are overriding
base.myFunction();
}
...
}
_self.initialize = () => {
...
}
// Warnings: While the following will work as _self is simply a reference to
// this, if anyone overrides myFunction() the overridden will be called first
// as the normal JavaScript method resolution will occur and the defined
// _self.initialize() function is actually gets removed from the instance and
// a proxy prototype version is created to reference the created method.
_self.initialize();
});
}
} +Type Parameters
Parameters
- theClass: DPCls
This is the current class instance which contains the prototype for the current class
+ - target: DPType
The current "this" (target) reference, when the class has been extended this.prototype will not be the 'theClass' value.
+ - delegateFunc: DynamicProtoDelegate<DPType>
The callback function (closure) that will create the dynamic function
+ Optionaloptions: IDynamicProtoOptsAdditional options to configure how the dynamic prototype operates
+
Returns void
Index
Properties
_df
-
diff --git a/docs/typedoc/interfaces/idynamicprotoopts.html b/docs/typedoc/interfaces/idynamicprotoopts.html
index 5da3732..7ea321d 100644
--- a/docs/typedoc/interfaces/idynamicprotoopts.html
+++ b/docs/typedoc/interfaces/idynamicprotoopts.html
@@ -1,83 +1,8 @@
-
-
-
-@microsoft/dynamicproto-js
-
- @microsoft/dynamicproto-js
Dynamic Proto JavaScript
- -Generates dynamic prototype methods for JavaScript objects (classes) by supporting method definition within their "class" constructor (like an instance version), this removes the need to expose internal properties on the instance (this) and the usage of ClassName.prototype.funcName() both of which result in better code minfication (smaller output) and therefore improved load times for your users.
The dynamically generated prototype methods support class inheritance of any type, which means you can extend from base classes that use instance or prototype defined methods, you also don't need to add the normal boiler plate code to handle detecting, saving and calling any previous instance methods that you are overriding as support for this is provided automatically.
+@microsoft/dynamicproto-js
Dynamic Proto JavaScript
Generates dynamic prototype methods for JavaScript objects (classes) by supporting method definition within their "class" constructor (like an instance version), this removes the need to expose internal properties on the instance (this) and the usage of ClassName.prototype.funcName() both of which result in better code minfication (smaller output) and therefore improved load times for your users.
The dynamically generated prototype methods support class inheritance of any type, which means you can extend from base classes that use instance or prototype defined methods, you also don't need to add the normal boiler plate code to handle detecting, saving and calling any previous instance methods that you are overriding as support for this is provided automatically.
So whether creating a new class or extending some other class/code, your resulting code, can be successfully extended via TypeScript or JavaScript.
-ES3 / IE8 support has been removed from Version 2.x.
-if you need to retain ES3 / IE8 support then you will need to use one of the 1.x versions which is now maintained on the old master branch
+if you need to retain ES3 / IE8 support then you will need to use one of the 1.x versions which is now maintained on the old master branch
The version 2.x is maintained on the default main branch
- - -Documentation
- -Github Documentation includes typedoc API references.
- - -Removing / Hiding internal properties from instance
- -By defining the properties / methods within the constructors closure, each instance can contain or define internal state in the form of properties which it does not have to expose publically as each defined "public" instance method has direct access to this define state within the context/scope of the closure method.
+The version 2.x is maintained on the default main branch
+Documentation
Github Documentation includes typedoc API references.
+Removing / Hiding internal properties from instance
By defining the properties / methods within the constructors closure, each instance can contain or define internal state in the form of properties which it does not have to expose publically as each defined "public" instance method has direct access to this define state within the context/scope of the closure method.
While this does require some additional CPU and memory at the point of creating each instance object this is designed to be as minimal as possible and should be outwayed by the following advantages :-
- Avoids polluting the instance (this) namespace with internal values that can cause issues with inheritence for base/super classes or even derived classes that extend your class.
- Smaller code as the internal properties and methods when defined within the instance can be minified.
- As the resulting generated code can be better minified this should result in a smaller minified result and therefore better load times for your users.
Basic Usage
import dynamicProto from "@microsoft/dynamicproto-js";
class ExampleClass extends BaseClass {
constructor() {
dynamicProto(ExampleClass, this, (_self, base) => {
// This will define a function that will be converted to a prototype function
_self.newFunc = () => {
// Access any "this" instance property
if (_self.someProperty) {
...
}
}
// This will define a function that will be converted to a prototype function
_self.myFunction = () => {
// Access any "this" instance property
if (_self.someProperty) {
// Call the base version of the function that we are overriding
base.myFunction();
}
...
}
_self.initialize = () => {
...
}
// Warnings: While the following will work as _self is simply a reference to
// this, if anyone overrides myFunction() the overridden will be called first
// as the normal JavaScript method resolution will occur and the defined
// _self.initialize() function is actually gets removed from the instance and
// a proxy prototype version is created to reference the created method.
_self.initialize();
});
}
}
+Basic Usage
- -import dynamicProto from "@microsoft/dynamicproto-js";
class ExampleClass extends BaseClass {
constructor() {
dynamicProto(ExampleClass, this, (_self, base) => {
// This will define a function that will be converted to a prototype function
_self.newFunc = () => {
// Access any "this" instance property
if (_self.someProperty) {
...
}
}
// This will define a function that will be converted to a prototype function
_self.myFunction = () => {
// Access any "this" instance property
if (_self.someProperty) {
// Call the base version of the function that we are overriding
base.myFunction();
}
...
}
_self.initialize = () => {
...
}
// Warnings: While the following will work as _self is simply a reference to
// this, if anyone overrides myFunction() the overridden will be called first
// as the normal JavaScript method resolution will occur and the defined
// _self.initialize() function is actually gets removed from the instance and
// a proxy prototype version is created to reference the created method.
_self.initialize();
});
}
}
-Build & Test this repo
-
+
-
+
Install all dependencies
+
- -npm install
npm install -g @microsoft/rush +Build & Test this repo
- --
-
Install all dependencies
-npm install
npm install -g @microsoft/rush -
-Navigate to the root folder and update rush dependencies
-
+rush update --
+
Navigate to the root folder and update rush dependencies
+
+rush update +
- Build, lint, create docs and run tests
-
+rush build
npm run test --
+
Build, lint, create docs and run tests
+
+rush build
npm run test +
If you are changing package versions or adding/removing any package dependencies, run
- - -rush update --purge --recheck --full
before building. Please check-in any files that change under common\ folder.Performance
- -The minified version of this adds a negligible amount of code and loadtime to your source code and by using this library, your generated code can be better minified as it removes most references of Classname.prototype.XXX methods from the generated code.
+Performance
The minified version of this adds a negligible amount of code and loadtime to your source code and by using this library, your generated code can be better minified as it removes most references of Classname.prototype.XXX methods from the generated code.
+Summary:
- ~2 KB minified (uncompressed)
Example usage and resulting minified code
In this first example of code that is typically emitted by TypeScript it contains several references to the Classname.prototype and "this" references, both of which cannot be minfied.
+
- -var NormalClass = /** @class */ (function () {
function NormalClass() {
this.property1 = [];
this.property1.push("Hello");
}
NormalClass.prototype.function1 = function () {
//...
doSomething();
};
NormalClass.prototype.function2 = function () {
//...
doSomething();
};
NormalClass.prototype.function3 = function () {
//...
doSomething();
};
return NormalClass;
}()); +Example usage and resulting minified code
- -In this first example of code that is typically emitted by TypeScript it contains several references to the Classname.prototype and "this" references, both of which cannot be minfied.
-var NormalClass = /** @class */ (function () {
function NormalClass() {
this.property1 = [];
this.property1.push("Hello");
}
NormalClass.prototype.function1 = function () {
//...
doSomething();
};
NormalClass.prototype.function2 = function () {
//...
doSomething();
};
NormalClass.prototype.function3 = function () {
//...
doSomething();
};
return NormalClass;
}()); -So the result would look something like this which represents a ~45% compression, note that the Classname.prototype appears several times.
-
+var NormalClass=(NormalClass.prototype.function1=function(){doSomething()},NormalClass.prototype.function2=function(){doSomething()},NormalClass.prototype.function3=function(){doSomething()},function(){this.property1=[],this.property1.push("Hello")}); -
+var NormalClass=(NormalClass.prototype.function1=function(){doSomething()},NormalClass.prototype.function2=function(){doSomething()},NormalClass.prototype.function3=function(){doSomething()},function(){this.property1=[],this.property1.push("Hello")}); +While in this example when using the dynamicProto helper to create the same resulting class and objects there are no references to Classname.prototype and only 1 reference to this.
-
+var DynamicClass = /** @class */ (function () {
function DynamicClass() {
dynamicProto(DynamicClass, this, function (_self, base) {
_self.property1 = [];
_self.property1.push("Hello()");
_self.function1 = function () {
//...
doSomething();
};
_self.function2 = function () {
//...
doSomething();
};
_self.function3 = function () {
//...
doSomething();
};
});
}
return DynamicClass;
}()); -
+var DynamicClass = /** @class */ (function () {
function DynamicClass() {
dynamicProto(DynamicClass, this, function (_self, base) {
_self.property1 = [];
_self.property1.push("Hello()");
_self.function1 = function () {
//...
doSomething();
};
_self.function2 = function () {
//...
doSomething();
};
_self.function3 = function () {
//...
doSomething();
};
});
}
return DynamicClass;
}()); +Which results in the following minified code which is much smaller and represents ~63% compression.
-
-var DynamicClass=function n(){dynamicProto(n,this,function(n,o){n.property1=[],n.property1.push("Hello()"),n.function1=function(){doSomething()},n.function2=function(){doSomething()},n.function3=function(){doSomething()}})}; -So when looking at the code for NormalClass and DynamicClass, both end up with 1 instance property called
+property1and the 3 functionsfunction1,function2andfunction3, in both cases the functions are defined ONLY on the "class" prototype andproperty1is defined on the instance. So anyone, whether using JavaScript or TypeScript will be able to "extend" either of class without any concerns about overloading instance functions and needing to save any previous method. And you are extending a 3rd party library you no longer have to worry about them changing the implementation asdynamicProto()handles converting overriden instance functions into prototype level ones. Yes, this means that if you don't override instance function it will continue to be an instance function.
- -var DynamicClass=function n(){dynamicProto(n,this,function(n,o){n.property1=[],n.property1.push("Hello()"),n.function1=function(){doSomething()},n.function2=function(){doSomething()},n.function3=function(){doSomething()}})}; +When to use
- -While this helper was created to support better minification for generated code via TypeScript code, it is not limited to only being used from within TypeScript, you can use the helper function directly in the same way as the examples above.
-As with including any additional code into your project there are trade offs that you need to make, including if you are looking at this helper, one of the primary items is the overall size of the additional code that you will be including vs the minification gains that you may obtained. This project endeavours to keep it's impact (bytes) as small as possible while supporting you to create readable and maintainable code that will create a smaller minified output.
-In most cases when creating JavaScript to support better minfication, when your code doesn't expose or provide a lot of public methods or only uses un-minifiable "names" less than 2 times, then you may not see enough potential gains to counteract the additional bytes required from the helper code. However, for any significant project you should.
+So when looking at the code for NormalClass and DynamicClass, both end up with 1 instance property called
+property1and the 3 functionsfunction1,function2andfunction3, in both cases the functions are defined ONLY on the "class" prototype andproperty1is defined on the instance. So anyone, whether using JavaScript or TypeScript will be able to "extend" either of class without any concerns about overloading instance functions and needing to save any previous method. And you are extending a 3rd party library you no longer have to worry about them changing the implementation asdynamicProto()handles converting overriden instance functions into prototype level ones. Yes, this means that if you don't override instance function it will continue to be an instance function.When to use
While this helper was created to support better minification for generated code via TypeScript code, it is not limited to only being used from within TypeScript, you can use the helper function directly in the same way as the examples above.
+As with including any additional code into your project there are trade offs that you need to make, including if you are looking at this helper, one of the primary items is the overall size of the additional code that you will be including vs the minification gains that you may obtained. This project endeavours to keep it's impact (bytes) as small as possible while supporting you to create readable and maintainable code that will create a smaller minified output.
+In most cases when creating JavaScript to support better minfication, when your code doesn't expose or provide a lot of public methods or only uses un-minifiable "names" less than 2 times, then you may not see enough potential gains to counteract the additional bytes required from the helper code. However, for any significant project you should.
So at the end of the day, if you are creating JS classes directly you should be able to create a simplier one-off solution that would result in smaller output (total bytes). This is how this project started, but, once we had several of these one-off solutions it made more sense to build it once.
- - -Performance optimizations (from v1.1)
- -To aid with execution performance from v1.1.0 (by default) the dynamically generated prototype functions will attempt to directly assign a top-level instance function (on first execution) of each function. This means that subsequent calls to that function will directly call the target instance function and avoid the dynamic function lookup process, this provides a minor performance improvement assists with identifying the called functions during profiling.
+Performance optimizations (from v1.1)
To aid with execution performance from v1.1.0 (by default) the dynamically generated prototype functions will attempt to directly assign a top-level instance function (on first execution) of each function. This means that subsequent calls to that function will directly call the target instance function and avoid the dynamic function lookup process, this provides a minor performance improvement assists with identifying the called functions during profiling.
To ensure that this does not break inheritance there are 3 prerequisites that must be true before this happens
- This check is only performed once per instance, per dynamic function
- The instance cannot already have an existing instance level function (duh!) -
- The dynamic proto function MUST be the FIRST prototype level function in the inherited class hierarchy.
-
-
- This simply means if a new class extends a class which is using dynamicProto() and it provides it's own prototype (class level in TypeScript terms) function, then we can't set an instance level as this would cause the class level function to never get called. +
- The dynamic proto function MUST be the FIRST prototype level function in the inherited class hierarchy.
+
-
+
- This simply means if a new class extends a class which is using dynamicProto() and it provides it's own prototype (class level in TypeScript terms) function, then we can't set an instance level as this would cause the class level function to never get called.
You can disable this default behavior by passing a new (optional) 4th argument to the dynamicProto(), the new 'options' argument is defined as an interface IDynamicProtoOpts to aid with any future options that may get exposed and has the following values
+You can disable this default behavior by passing a new (optional) 4th argument to the dynamicProto(), the new 'options' argument is defined as an interface IDynamicProtoOpts to aid with any future options that may get exposed and has the following values
+ +@@ -124,106 +86,102 @@ -Performance optimizations (from v1.1)
Description + +setInstFuncs Boolean Should the dynamic prototype attempt to set an instance function for instances that do not already have an function of the same name or have been extended by a class with a (non-dynamic proto) prototype function.
- - -Note:
-If ANY class in the hierarchy explicitly disables this behavior (passes options object with a value of
+setInstFuncs: false) to it's dynamicProto() calls, then that will block ALL functions for all classes, even if a base class explicitly passes an options with it set to true. This enables any class to explicitly disable this behavior should some unknown and unexpected issue occur, if you encounter something that requires this usage then please raised an issue (or provide a PR) so we can resolve for everyone.If ANY class in the hierarchy explicitly disables this behavior (passes options object with a value of
setInstFuncs: false) to it's dynamicProto() calls, then that will block ALL functions for all classes, even if a base class explicitly passes an options with it set to true. This enables any class to explicitly disable this behavior should some unknown and unexpected issue occur, if you encounter something that requires this usage then please raised an issue (or provide a PR) so we can resolve for everyone.Included NPM distribution formats
- -As part of the build / publish formats via NPM we include the following module formats:
+Included NPM distribution formats
As part of the build / publish formats via NPM we include the following module formats:
- dist/esm – Used as the "module" definition for npm, which keeps the bundle as an ES module file, suitable for other bundlers and inclusion as a < amd – Asynchronous Module Definition, used with module loaders like RequireJS -
- dist/node - Used as the "main" npm entry point for the utility, using the umd format with any third party modules located and included using the Node resolution algorithm +
- dist/node - Used as the "main" npm entry point for the utility, using the umd format with any third party modules located and included using the Node resolution algorithm
Other included formats
- --
+
- dist/cjs – CommonJS, suitable for Node and other bundlers script type=module> tag in modern browsers
- dist/iife – A self-executing function, suitable for inclusion as a <script> tag. (If you want to create a bundle for your application, you probably want to use this.)
- dist/umd – Universal Module Definition, works as amd, cjs and iife all in one
- dist/system – Native format of the SystemJS loader
- When you attempt to extend a base class which defines an abstract member (class) function you will get +
- When you attempt to extend a base class which defines an abstract member (class) function you will get
+
error TS2424: Class 'ABC' defines instance member function 'myFunction', but extended class 'XYZ' defines it as instance member property.+-
+
- The only solution for this is to define an empty 'Stub' method which stops the error, but also generates an unused prototype method in your final code that just takes up space. +
Other included formats
TypeScript Declaration Helper
- -When using TypeScript to create classes and automatically generate the declaration (*.d.ts) files for your classes you will run into one or more of the following issues :-
+TypeScript Declaration Helper
When using TypeScript to create classes and automatically generate the declaration (*.d.ts) files for your classes you will run into one or more of the following issues :-
-
-
-error TS2424: Class 'ABC' defines instance member function 'myFunction', but extended class 'XYZ' defines it as instance member property.- * The only solution for this is to define an empty 'Stub' method which stops the error, but also generates an unused prototype method in your final code that just takes up space.
+export abstract class ABC {
public myFunction(someArg:string): void {
}
public abstract myFunction2(theArg:string, ...): void;
}
export class XYZ extends ABC {
public myFunction2(theArg:string, ...): void {
// This stub is required otherwise it won't compile
// It's also extra unnecessary code in the final code
}
constructor() {
dynamicProto(XYZ, this, (self, base) => {
self.myFunction = (someArg) => {
// This implements a member function (on the prototype)
};
self.myFunction2 = (theArg:string, ...) => {
};
});
}
} -
+export abstract class ABC {
public myFunction(someArg:string): void {
}
public abstract myFunction2(theArg:string, ...): void;
}
export class XYZ extends ABC {
public myFunction2(theArg:string, ...): void {
// This stub is required otherwise it won't compile
// It's also extra unnecessary code in the final code
}
constructor() {
dynamicProto(XYZ, this, (self, base) => {
self.myFunction = (someArg) => {
// This implements a member function (on the prototype)
};
self.myFunction2 = (theArg:string, ...) => {
};
});
}
} +The above results in the following javascript output for XYZ class where the XYZ.prototype.myFunction2 is obsolete (as it gets replace), unnecessary (for the class to function) and uncompressable bloat for the code
-
+var XYZ = /** @class */ (function () {
function XYZ() {
dynamicProto(XYZ, this, (self, base) => {
// ... Removed for brevity ...
self.myFunction2 = (theArg:string, ...) => {
};
});
}
XYZ.prototype.myFunction2 = function () {
// This stub is required otherwise it won't compile
// It's also extra unnecessary code in the final code
};
return XYZ;
}()); -
+var XYZ = /** @class */ (function () {
function XYZ() {
dynamicProto(XYZ, this, (self, base) => {
// ... Removed for brevity ...
self.myFunction2 = (theArg:string, ...) => {
};
});
}
XYZ.prototype.myFunction2 = function () {
// This stub is required otherwise it won't compile
// It's also extra unnecessary code in the final code
};
return XYZ;
}()); +-
-
- When you are creating a class that you want users to be able to extend (using TypeScript), and you want all of the functions to be declared (in the *.d.ts) as member functions (not properties), so that the extendsion classes (using typescript) can just use the normal
superkeyword without forcing them to either use dynamicProto() or save / call the instance properties.-
+
- When you are creating a class that you want users to be able to extend (using TypeScript), and you want all of the functions to be declared (in the *.d.ts) as member functions (not properties), so that the extendsion classes (using typescript) can just use the normal
superkeyword without forcing them to either use dynamicProto() or save / call the instance properties. +- As with above the only solution (for dynamically generated declaration files) would be to defined Stub methods as above.
- When you are creating a class that you want users to be able to extend (using TypeScript), and you want all of the functions to be declared (in the *.d.ts) as member functions (not properties), so that the extendsion classes (using typescript) can just use the normal
-export class BaseClass {
// A Member function
public myFunction(someArg:string):void {
// Stub function
}
// A instance member property (which happens to be a function)
public propFunction: (theArgs:string) => void;
constructor() {
dynamicProto(BaseClass, this) (self) => {
// This will create (at runtime) a member functions
self.myFunction = (someArg:string) => {
};
self.propFunction = (theArgs:string) => {
};
});
}
}
export class NewClass extends BaseClass {
// This works as TS see's that the base class has a prototype
// function (not a property one)
public myFunction(someArg:string:void) {
super.myFunction(someArg);
}
public propFunction(theArgs:string): void {
// This doesn't work as you can't call super on properties
// Even though, when the base class is using dynamicProto()
// this WILL work!
super.propFunction(theArgs);
}
} -So in both of these cases the only workable solutions are either :-
+
+ +export class BaseClass {
// A Member function
public myFunction(someArg:string):void {
// Stub function
}
// A instance member property (which happens to be a function)
public propFunction: (theArgs:string) => void;
constructor() {
dynamicProto(BaseClass, this) (self) => {
// This will create (at runtime) a member functions
self.myFunction = (someArg:string) => {
};
self.propFunction = (theArgs:string) => {
};
});
}
}
export class NewClass extends BaseClass {
// This works as TS see's that the base class has a prototype
// function (not a property one)
public myFunction(someArg:string:void) {
super.myFunction(someArg);
}
public propFunction(theArgs:string): void {
// This doesn't work as you can't call super on properties
// Even though, when the base class is using dynamicProto()
// this WILL work!
super.propFunction(theArgs);
}
} +So in both of these cases the only workable solutions are either :-
- Define Stub member functions and live with the code bloat -
- Just don't use dynamicProto() and again live with the larger file size. +
- Just don't use dynamicProto() and again live with the larger file size.
So assuming that you do want to continue using dynamicProto() and don't want to deal with the additional code bloat, this project includes a simple rollup plugin included in the
+tools/rollupfolder that can be used to remove "tagged" stub code from the resulting output during packaging.So assuming that you do want to continue using dynamicProto() and don't want to deal with the additional code bloat, this project includes a simple rollup plugin included in the
tools/rollupfolder that can be used to remove "tagged" stub code from the resulting output during packaging.This is a Post processor that removes any code/comments (not just function) that are "tagged" from the resulting output, thus removing the Stub methods and the resulting code bloat from your final packaged code, but still leaving typescript declaration with the final (runtime) member function definition.
The plugin uses the following rules to identify and remove tagged code :-
- The function must be a instance member function (a prototype level function) where the generated JS looks like "
MyClass.prototype.methodName = function () { };" - The
tagnamemust appear either on the line before the function name (pre); on the closing line of the function (post) (NOTE: Not after as TypeScript can drop this from the final output) or within the stub function (enclosed).
+ +// @DynamicProtoStub
MyClass.prototype.methodName = function () {
};
MyClass.prototype.methodName = function () {
}; // @DymanicProtoStub
MyClass.prototype.methodName = function () {
// @DynamicProtoStub
};
MyClass.prototype.methodName = function () {
/* @DynamicProtoStub
* Some other comments
*/
}; - - The pre and post tagging comments must be defined using a single line comment "
// @DynamicProtoStub" only. - Enclosed tagging comments (within the function definition) may be defined using either single or multi-line comments. But the tagging comment MUST be the first comment within the function.
- The function may be prefixed by a typedoc comment of "
/** Description @param arg - arg details */" etc, which will be removed if the function is removed. However, it will not remove other prefixed single or multi-line comments.
- - The
tagnamemust be the first "element"/"word" of any comment with optional leading spaces or tabs only.-
+
- The
tagnamemust be the first "element"/"word" of any comment with optional leading spaces or tabs only. +- e.g. These would not match "
// - @DynamicProtoStub", "// This is the @DynamicProtoStub"
- - e.g. These would not match "
- Tagging comments may contains additional trailing content (after the tagName) and will also be removed
-
+
- Tagging comments may contains additional trailing content (after the tagName) and will also be removed
+
- "
// @DynamicProtoStub - Will be removed!"
- "
- If the stub function appears to contain any logic, specifically a closing bracket
}(including with a comment) will cause the function to not be matched and removed.
- - A final check is performed after removing all tagged functions for any remaining tags within the result and if any tags are detected it will cause the removal process to throw and fail the conversion. This ensures that if you expected a function to be removed that it has been removed.
-
+
- A final check is performed after removing all tagged functions for any remaining tags within the result and if any tags are detected it will cause the removal process to throw and fail the conversion. This ensures that if you expected a function to be removed that it has been removed.
+
- If your build is failing please check that the tagging comments conform to the above rules, failures normally occur because of unexpected formatting changes.
Some possible examples
-
+/**
* The typedoc comments
*/
// @DynamicProtoStub
public toBeRemoved():void {
}
// @DynamicProtoStub
public toBeRemoved():void {
}
/**
* This function does stuff
* @param args - used in the function
*/
public myFunction(args:string): void {
...
} // @DynamicProtoStub - Function will be removed
public myFunction2(): void {
...
} // @DynamicProtoStub - Function will be removed
/**
* This function does stuff
* @param args - used in the function
*/
public myFunction(args:string): void {
// @DynamicProtoStub - Function will be removed
}
public myFunction2(): void {
/* @DynamicProtoStub
* Function will be removed
*/
}
-
+/**
* The typedoc comments
*/
// @DynamicProtoStub
public toBeRemoved():void {
}
// @DynamicProtoStub
public toBeRemoved():void {
}
/**
* This function does stuff
* @param args - used in the function
*/
public myFunction(args:string): void {
...
} // @DynamicProtoStub - Function will be removed
public myFunction2(): void {
...
} // @DynamicProtoStub - Function will be removed
/**
* This function does stuff
* @param args - used in the function
*/
public myFunction(args:string): void {
// @DynamicProtoStub - Function will be removed
}
public myFunction2(): void {
/* @DynamicProtoStub
* Function will be removed
*/
}
+For clarification the following will NOT match or get removed
-
+
public myFunction3(): void {
}
// @DynamicProtoStub - This method will not be removed
// @DynamicProtoStub - This method will not be removed
public myFunction4(): void {
}
public myFunction4(): void {
/*
* @DynamicProtoStub
* This will fail because the tag is not the first
* "element"/"word" of any comment with optional
* leading spaces or tabs only.
*/
}
public myFunction4(): void {
// This is a stub
/* @DynamicProtoStub
* This will fail because the tagging comment is not
* the first comment within the function.
*/
}
-
- -
public myFunction3(): void {
}
// @DynamicProtoStub - This method will not be removed
// @DynamicProtoStub - This method will not be removed
public myFunction4(): void {
}
public myFunction4(): void {
/*
* @DynamicProtoStub
* This will fail because the tag is not the first
* "element"/"word" of any comment with optional
* leading spaces or tabs only.
*/
}
public myFunction4(): void {
// This is a stub
/* @DynamicProtoStub
* This will fail because the tagging comment is not
* the first comment within the function.
*/
}
+Adding to you own rollup.config.js
- -
+import dynamicRemove from "@microsoft/dynamicproto-js/tools/rollup/node/removedynamic";
const moduleRollupConfig = {
input: `${inputName}.js`,
output: {
file: `./dist/${format}/${outputName}.js`,
banner: banner,
format: format,
name: "OutputName-JS",
extend: true,
sourcemap: true
},
plugins: [
dynamicRemove(),
dynamicRemove({ tagname: "@MyTagName" }),
nodeResolve(),
uglify({
ie8: true,
toplevel: true,
compress: {
passes:3,
unsafe: true
},
output: {
preamble: banner,
webkit:true
}
})
]
};
-Adding to you own rollup.config.js
- -import dynamicRemove from "@microsoft/dynamicproto-js/tools/rollup/node/removedynamic";
const moduleRollupConfig = {
input: `${inputName}.js`,
output: {
file: `./dist/${format}/${outputName}.js`,
banner: banner,
format: format,
name: "OutputName-JS",
extend: true,
sourcemap: true
},
plugins: [
dynamicRemove(),
dynamicRemove({ tagname: "@MyTagName" }),
nodeResolve(),
uglify({
ie8: true,
toplevel: true,
compress: {
passes:3,
unsafe: true
},
output: {
preamble: banner,
webkit:true
}
})
]
};
+Not using Rollup?
- -Then let us know or simply take the embedded RegEx, and wrap it into your favorite tool and submit a PR.
+Not using Rollup?
Then let us know or simply take the embedded RegEx, and wrap it into your favorite tool and submit a PR.
It should be as simple as :-
- Load the TypeScript generated JS output source file @@ -231,22 +189,14 @@
- Write the new resulting file to the output path (or stream)
- Do the final check for any "remaining" tags, which represents a failed matching
Not using Rollup?
Version 2.x
- -Version 2.x is maintained on the default main branch
+Version 2.x
Version 2.x is maintained on the default main branch
- - -Breaking Changes from Version 1.x
- Removed ES3 / IE8 support
Browser Support
- --
+
- ES5 Compliant browsers
- ES3 Compliant browsers
Browser Support
@@ -260,7 +210,8 @@
- - -Browser Support
+ +Latest ✔ Latest ✔ 9+ Full ✔ @@ -268,21 +219,12 @@Browser Support
Latest ✔ Latest ✔ Previous Versions
- -- + + +Previous Versions
- - - -Version 1.x
- -Version 1.x is maintained on the master branch
- - -Browser Support (1.x)
- --
+
Version 1.x is maintained on the master branch
+Browser Support (1.x)
@@ -296,7 +238,8 @@
- - -Browser Support (1.x)
+ +Latest ✔ Latest ✔ 8+ Full ✔ @@ -304,20 +247,13 @@Browser Support (1.x)
Latest ✔ Latest ✔ ES3/IE8 Compatibility
- -Version 1.x ONLY, 2.x DOES NOT support ES3/IE8
+ + +ES3/IE8 Compatibility
Version 1.x ONLY, 2.x DOES NOT support ES3/IE8
As a library there are numerous users which cannot control the browsers that their customers use. As such we need to ensure that this library continues to "work" and does not break the JS execution when loaded by an older browser. While it would be ideal to just not support IE8 and older generation (ES3) browsers there are numerous large customers/users that continue to require pages to "work" and as noted they may or cannot control which browser that their end users choose to use.
As part of enabling ES3/IE8 support we have set the
tsconfig.jsonto ES3 anduglifysettings inrollup.config.jstransformations to support ie8. This provides a first level of support which blocks anyone from adding unsupported ES3 features to the code and enables the generated javascript to be validily parsed in an ES3+ environment.Ensuring that the generated code is compatible with ES3 is only the first step, JS parsers will still parse the code when an unsupport core function is used, it will just fail or throw an exception at runtime. Therefore, we also need to require/use polyfil implementations or helper functions to handle those scenarios.
- - -ES3/IE8 Features, Solutions, Workarounds and Polyfill style helper functions
- -This table does not attempt to include ALL of the ES3 unsupported features, just the currently known functions that where being used at the time or writing. You are welcome to contribute to provide additional helpers, workarounds or documentation of values that should not be used.
+ES3/IE8 Features, Solutions, Workarounds and Polyfill style helper functions
This table does not attempt to include ALL of the ES3 unsupported features, just the currently known functions that where being used at the time or writing. You are welcome to contribute to provide additional helpers, workarounds or documentation of values that should not be used.
+ +@@ -326,7 +262,8 @@ -ES3/IE8 Features, Solutions, Workarounds and Polyfill style helper functions
Usage + +Object.keys()Not provided by ES3 and not used N/A @@ -391,50 +328,10 @@ES3/IE8 Features, Solutions, Workarounds and Polyfill style helper functions
Not provided by ES3 and not used N/A Contributing
- -Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Application Insights.
- - -Trademarks
- -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.
- - -License
- - - - A final check is performed after removing all tagged functions for any remaining tags within the result and if any tags are detected it will cause the removal process to throw and fail the conversion. This ensures that if you expected a function to be removed that it has been removed.
+
- Tagging comments may contains additional trailing content (after the tagName) and will also be removed
+
- The
-
-
\ No newline at end of file
+Generated using TypeDoc
Contributing
Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Application Insights.
+Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.
+License
+
-
diff --git a/docs/typedoc/media/CONTRIBUTING.md b/docs/typedoc/media/CONTRIBUTING.md
new file mode 100644
index 0000000..d510f62
--- /dev/null
+++ b/docs/typedoc/media/CONTRIBUTING.md
@@ -0,0 +1,45 @@
+# Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to
+agree to a Contributor License Agreement (CLA) declaring that you have the right to,
+and actually do, grant us the rights to use your contribution. For details, visit
+https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need
+to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
+instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Welcome
+
+Welcome and thank you for your interest in contributing to DynamicProto-JS.
+
+We strongly welcome and encourage contributions to this project. If making a large change we request that you open an [issue][GitHubIssue] first.
+
+## Clone, Setup, Build & Test this repo
+1. Clone the repository and create a new branch
+
+2. Install all dependencies
+
+ ```sh
+ npm install
+ npm install -g @microsoft/rush
+ ```
+
+3. Navigate to the root folder and update rush dependencies
+
+ ```sh
+ rush update --recheck --full
+ ```
+
+4. Build, lint, create docs and run tests
+
+ ```sh
+ rush build
+ npm run test
+ ```
+
+If you are changing package versions or adding/removing any package dependencies, run
-
-
-
-
-
-
-
-
-
-
-
-set
-IDynamicProtoOpts | @microsoft/dynamicproto-js
set
-
-
-
-
-Interface IDynamicProtoOpts
Interface to define additional configuration options to control how the dynamic prototype functions operate.
-Hierarchy
--
-
- IDynamicProtoOpts
- Index
-
-
-
Properties
-Properties
-set
-set
-Should the dynamic prototype attempt to set an instance function for instances that do not already have an +
Interface IDynamicProtoOpts
Interface to define additional configuration options to control how the dynamic prototype functions operate.
+ Index
Properties
Properties
set
set
Should the dynamic prototype attempt to set an instance function for instances that do not already have an function of the same name or have been extended by a class with a (non-dynamic proto) prototype function.
-Optional use
-use
-When looking for base (super) functions if it finds a dynamic proto instances can it use the instance functions +
Optionaluse
use
When looking for base (super) functions if it finds a dynamic proto instances can it use the instance functions and bypass the prototype lookups. Defaults to true.
-
-
-
\ No newline at end of file
+Generated using TypeDoc
**```rush update --purge --recheck --full```**
before building. Please check-in any files that change under common\ folder. diff --git a/docs/typedoc/media/LICENSE b/docs/typedoc/media/LICENSE new file mode 100644 index 0000000..5ae193c --- /dev/null +++ b/docs/typedoc/media/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/typedoc/modules.html b/docs/typedoc/modules.html index 8d26258..72fabf6 100644 --- a/docs/typedoc/modules.html +++ b/docs/typedoc/modules.html @@ -1,61 +1,4 @@ -
-
-
-
-
-
\ No newline at end of file
+Generated using TypeDoc
@microsoft/dynamicproto-js
Index
Interfaces
Type Aliases
Functions
default
+
-
-
-
-
-
-
-
-
-
-Namespace default
Index
-Variables
-_df
-
-
\ No newline at end of file
diff --git a/docs/typedoc/variables/default._dfOpts.html b/docs/typedoc/variables/default._dfOpts.html
deleted file mode 100644
index 434d8ac..0000000
--- a/docs/typedoc/variables/default._dfOpts.html
+++ /dev/null
@@ -1,47 +0,0 @@
-Generated using TypeDoc
-
-
-
-
-
-
-Variable _dfOpts
-
-
\ No newline at end of file
diff --git a/gruntfile.js b/gruntfile.js
index 7472cc8..208c2d4 100644
--- a/gruntfile.js
+++ b/gruntfile.js
@@ -50,14 +50,15 @@ module.exports = function (grunt) {
dynamicproto: {
options: {
urls: [
- './lib/test/Selenium/Tests.html'
+ 'http://localhost:9005/lib/test/Selenium/Tests.html'
],
timeout: 300 * 1000, // 5 min
console: true,
summaryOnly: false,
httpBase: ".",
puppeteer: {
- headless: true,
+ debug: true,
+ headless: "new",
timeout: 30000,
ignoreHTTPErrors: true,
args: [
@@ -71,14 +72,15 @@ module.exports = function (grunt) {
rollup: {
options: {
urls: [
- './rollup/test/Selenium/Tests.html'
+ 'http://localhost:9005/rollup/test/Selenium/Tests.html'
],
timeout: 300 * 1000, // 5 min
console: true,
summaryOnly: false,
httpBase: ".",
puppeteer: {
- headless: true,
+ debug: true,
+ headless: "new",
timeout: 30000,
ignoreHTTPErrors: true,
args: [
@@ -113,8 +115,8 @@ module.exports = function (grunt) {
grunt.loadNpmTasks('grunt-run');
grunt.registerTask("default", ["ts:rollup", "ts:rolluptest", "ts:dynamicproto", "ts:dynamicprototest", "qunit:rollup", "qunit:dynamicproto"]);
grunt.registerTask("dynamicproto", ["eslint-ts:dynamicproto-fix", "ts:dynamicproto"]);
- grunt.registerTask("dynamicprototest", ["ts:dynamicproto", "ts:dynamicprototest", "qunit:dynamicproto"]);
- grunt.registerTask("rollup", ["ts:rollup", "ts:rolluptest", "qunit:rollup"]);
+ grunt.registerTask("dynamicprototest", ["ts:dynamicproto", "ts:dynamicprototest", "connect:server", "qunit:dynamicproto"]);
+ grunt.registerTask("rollup", ["ts:rollup", "ts:rolluptest", "connect:server", "qunit:rollup"]);
grunt.registerTask("lint", ["eslint-ts:dynamicproto"]);
grunt.registerTask("lint-fix", ["eslint-ts:dynamicproto-fix"]);
grunt.registerTask("serve", ["connect:server:keepalive"]);
diff --git a/lib/test/Selenium/Tests.html b/lib/test/Selenium/Tests.html
index f684fc5..54a9cfc 100644
--- a/lib/test/Selenium/Tests.html
+++ b/lib/test/Selenium/Tests.html
@@ -5,16 +5,16 @@
Generated using TypeDoc
Helper function when creating dynamic (inline) functions for classes, this helper performs the following tasks :-
--- Saves references to all defined base class functions
-- Calls the delegateFunc with the current target (this) and a base object reference that can be used to call all "super" functions.
-- Will populate the class prototype for all overridden functions to support class extension that call the prototype instance.
-Callers should use this helper when declaring all function within the constructor of a class, as mentioned above the delegateFunc is
-passed both the target "this" and an object that can be used to call any base (super) functions, using this based object in place of
-super.XXX() (which gets expanded to _super.prototype.XXX()) provides a better minification outcome and also ensures the correct "this"
-context is maintained as TypeScript creates incorrect references using super.XXXX() for dynamically defined functions i.e. Functions
-defined in the constructor or some other function (rather than declared as complete typescript functions).
-
- - -Usage
- - - -Typeparam
DPType This is the generic type of the class, used to keep intellisense valid
- -Typeparam
DPCls The type that contains the prototype of the current class
-