diff --git a/README.md b/README.md index 57a468a..585c031 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,16 @@ -# Release v2.1.6 +# Release v3.0.0 -# [v3.0.0](new-api.md) has *BREAKING* changes and is not compatible for inheirtance with *ANY* v2.\*.\* Generators. +# v3.0.0 has *BREAKING* changes and is not compatible for inheirtance with *ANY* v2.\*.\* Generators. ## Table of Contents * [ Generator ](#generator) * [ Generator.generate(create) ](#generate) * [ Generator.isGenerator(test) ](#is-generator) - * [ Generator.toGenerator(constructor) ](#to-generator) + * [ Generator.toGenerator(constructor, create) ](#to-generator) * [ Class: Generation ](#class-generation) - * [ Generation.name ](#generation-name) - * [ Generation.proto ](#generation-proto) + * [ new Generation() ](#generation-create) * [ Generation.definePrototype([descriptor,] properties) ](#generation-define-prototype) - * [ Generation.create() ](#generation-create) * [ Generation.generate(create) ](#generation-generate) * [ Generation.isCreation(test) ](#generation-is-creation) * [ Generation.isGeneration(test) ](#generation-is-generation) @@ -35,8 +33,8 @@ $ npm install generate-js ## Generator.generate(create) -* *create* `Function` Create method that gets called when creating a new object that inherits from [Generation.proto](#generation-proto). -* *return*: `Generation` A new [Generation](#class-generation) that inherits from [Generation](#class-generation). +* *create* `Function` Constructor that with inherit form [Generation](#class-generation). +* *return*: `Constructor` The inputed `create` function. Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation). @@ -63,12 +61,13 @@ var Person = Generator.generate( Returns `true` if *test* object inherits from [Generation](#class-generation), `false` otherwise. -## Generator.toGenerator(constructor) +## Generator.toGenerator(constructor, create) * *constructor* `Function` An constructor to be generatorized. -* *return*: `Generation` A new [Generation](#class-generation) that who's create method is equivalent to calling `new constructor();`. +* *create* `Function` Constructor that with inherit form [Generation](#class-generation) and *constructor*. +* *return*: `Constructor` The inputed `create` function. -Returns a new [Generation](#class-generation) that is equivalent to *constructor*. +Returns a new [Generation](#class-generation) that inherits from [Generation](#class-generation) and *constructor*. *NOTE*: Some native constructors can *NOT* be generatorized. @@ -78,14 +77,20 @@ Example: var Generator = require('generate-js'), events = require('events'); -var EventEmitter = Generator.toGenerator(events.EventEmitter); +var EventEmitter = Generator.toGenerator(events.EventEmitter, function EventEmitter() { + events.EventEmitter.call(this); //call the super constructor +}); -// EventEmitter.create() same as new events.EventEmitter(); +// new EventEmitter() same as new events.EventEmitter(); // new generators can inherit all the abilities of EventEmitter like so. var MyNewGenerator = EventEmitter.generate( /* create method */ - function MyNewGenerator() {} + function MyNewGenerator() { + EventEmitter.call(this); //call the super constructor + + // your code + } ); ``` @@ -95,17 +100,25 @@ var MyNewGenerator = EventEmitter.generate( A new Generation that inherits from the Generation that generated it using the [Generation.generate(create)](#generation-generate) method. - -## Generation.name -* *name* `String` The name of the create method. + +## new Generation() + +* *return*: `Creation` A new [Creation](#class-creation) that is an instance of *this* [Generation](#generation). -Name of *this* [Generation](#class-generation). +Creates a new [Creation](#class-creation) that is an instance of *this* [Generation](#generation). - -## Generation.proto -* *proto* `Object` Prototype inheritance for [Creations](#class-creation) created by *this* [Generation](#class-generation). +Example: +```javascript +var jim = new Person('Jim', 10, 'male'); -Generation.proto inherits from previous Generation's protos all the way up to Generation.proto which is equal to [Creation](class-creation). +jim.name // 'Jim' +jim.age // 10 +jim.sex // 'male' + +jim.sayHello(); // prints out: 'Hello, my name is Jim. What is yours?' +jim.sayBye(); // prints out: 'Goodbye.' + +``` ## Generation.definePrototype([descriptor,] properties) @@ -114,7 +127,7 @@ Generation.proto inherits from previous Generation's protos all the way up to Ge * *configurable* `Boolean` States weather or not properties will be *configurable*, defaults to `false`. * *enumerable* `Boolean` States weather or not properties will be *enumerable*, defaults to `false`. * *writable* `Boolean` States weather or not properties will be *writable*, defaults to `false`. -* *properties* `Object` An object who's properties will be attached to *this* [Generation's proto](#generation-proto). +* *properties* `Object` An object who's properties will be attached to *this* [Generation.prototype](#generation). * *return*: `Generation` *This* [Generation](#class-generation). Defines shared properties for all [Creations](#class-creation) created by *this* [Generation](#class-generation). @@ -171,31 +184,11 @@ Person.definePrototype( ``` - -## Generation.create() - -* *return*: `Creation` A new [Creation](#class-creation) that inherits from *this* [Generation.proto](#generation-proto). - -Creates a new [Creation](#class-creation) that inherits from *this* [Generation.proto](#generation-proto). - -Example: -```javascript -var jim = Person.create('Jim', 10, 'male'); - -jim.name // 'Jim' -jim.age // 10 -jim.sex // 'male' - -jim.sayHello(); // prints out: 'Hello, my name is Jim. What is yours?' -jim.sayBye(); // prints out: 'Goodbye.' - -``` - ## Generation.generate(create) -* *create* `Function` Create method that gets called when creating a new object that inherits from *this* [Generation.proto](#generation-proto). -* *return*: `Generation` A new [Generation](#class-generation) that inherits from *this* [Generation](#class-generation). +* *create* `Function` Constructor that with inherit form [Generation](#class-generation). +* *return*: `Constructor` The inputed `create` function. Returns a new [Generation](#class-generation) that inherits from *this* [Generation](#class-generation). @@ -204,9 +197,7 @@ Example: var Student = Person.generate( /* create method */ function Student(name, age, sex, studentId) { - // 'supercreate' method is only available in this create method scope. - // NOTE: if the 'supercreate' method is not called implicitly it will be called with no arguments. - this.supercreate(name, age, sex); + Person.call(this, name, age, sex); this.studentId = studentId || 'A0000000000'; } ); @@ -222,7 +213,7 @@ Student.definePrototype( } ); -var sarah = Student.create('Sarah', 17, 'female', 'A0123456789'); +var sarah = new Student('Sarah', 17, 'female', 'A0123456789'); sarah.name // 'Sarah' sarah.age // 17 @@ -248,12 +239,12 @@ Returns `true` if *test* inherits from *this* [Generation](#class-generation), ` * *test* `Object` An Object to be tested. * *return*: `Boolean` `true` or `false`. -Returns `true` if *test* inherits from *this* [Generation.proto](#generation-proto), `false` otherwise. +Returns `true` if *test* is an instance of *this* [Generation](#generation), `false` otherwise. ## Class: Creation -A new Creation that inherits from a [Generation's proto](#generation-proto) that created it using the [Generation.create()](#generation-create) method. +A instance [Generation](#generation) that created it using the [new Generation()](#generation-create). ## Creation.defineProperties([descriptor,] properties) diff --git a/generate.js b/generate.js index 649d46d..c285121 100644 --- a/generate.js +++ b/generate.js @@ -4,14 +4,6 @@ */ (function GeneratorScope() { - - // Variables - var Creation = {}, - Generation = {}, - Generator = {}; - - // Helper Methods - /** * Assert Error function. * @param {Boolean} condition Whether or not to throw error. @@ -31,7 +23,8 @@ function assertTypeError(test, type) { if (typeof test !== type) { throw new TypeError('Expected \'' + type + - '\' but instead found \'' + typeof test + '\''); + '\' but instead found \'' + + typeof test + '\''); } } @@ -120,233 +113,208 @@ return obj; } - // Creation Class + + + var Creation = { + /** + * Defines properties on this object. + * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. + * @param {Object} properties An object who's properties will be attached to this object. + * @return {Object} This object. + */ + defineProperties: function defineProperties(descriptor, + properties) { + defineObjectProperties(this, descriptor, + properties); + return this; + }, + + /** + * returns the prototype of `this` Creation. + * @return {Object} Prototype of `this` Creation. + */ + getProto: function getProto() { + return Object.getPrototypeOf(this); + }, + + /** + * returns the prototype of `this` super Creation. + * @return {Object} Prototype of `this` super Creation. + */ + getSuper: function getSuper() { + return Object.getPrototypeOf(this.constructor.prototype); + } + }; + + var Generation = { + /** + * Returns true if 'generator' was generated by this Generator. + * @param {Generator} generator A Generator. + * @return {Boolean} true or false. + */ + isGeneration: function isGeneration(generator) { + assertTypeError(generator, 'function'); + + var _ = this; + + return _.prototype.isPrototypeOf(generator.prototype); + }, + + /** + * Returns true if 'object' was created by this Generator. + * @param {Object} object An Object. + * @return {Boolean} true or false. + */ + isCreation: function isCreation(object) { + var _ = this; + return object instanceof _; + }, + /** + * Generates a new generator that inherits from `this` generator. + * @param {Generator} ParentGenerator Generator to inherit from. + * @param {Function} create Create method that gets called when creating a new instance of new generator. + * @return {Generator} New Generator that inherits from 'ParentGenerator'. + */ + generate: function generate(construct) { + assertTypeError(construct, 'function'); + + var _ = this; + + defineObjectProperties( + construct, { + configurable: false, + enumerable: false, + writable: false + }, { + prototype: Object.create(_.prototype) + } + ); + + defineObjectProperties( + construct, { + configurable: false, + enumerable: false, + writable: false + }, + Generation + ); + + defineObjectProperties( + construct.prototype, { + configurable: false, + enumerable: false, + writable: false + }, { + constructor: construct, + generator: construct, + } + ); + + return construct; + }, + + /** + * Defines shared properties for all objects created by this generator. + * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. + * @param {Object} properties An object who's properties will be attached to this generator's prototype. + * @return {Generator} This generator. + */ + definePrototype: function definePrototype(descriptor, + properties) { + defineObjectProperties(this.prototype, + descriptor, + properties); + return this; + } + }; + + function Generator() {} + defineObjectProperties( - Creation, { + Generator, { configurable: false, enumerable: false, writable: false }, { - /** - * Defines properties on this object. - * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. - * @param {Object} properties An object who's properties will be attached to this object. - * @return {Object} This object. - */ - defineProperties: function defineProperties(descriptor, - properties) { - defineObjectProperties(this, descriptor, - properties); - return this; - }, - - /** - * returns the prototype of `this` Creation. - * @return {Object} Prototype of `this` Creation. - */ - getProto: function getProto() { - return Object.getPrototypeOf(this); - }, - - /** - * returns the prototype of `this` super Creation. - * @return {Object} Prototype of `this` super Creation. - */ - getSuper: function getSuper() { - return Object.getPrototypeOf(this.generator) - .proto; - // return Object.getPrototypeOf(Object.getPrototypeOf(this)); - } + prototype: Generator.prototype } ); - // Generation Class defineObjectProperties( - Generation, { + Generator.prototype, { configurable: false, enumerable: false, writable: false - }, { - name: 'Generation', + }, + Creation + ); - proto: Creation, + defineObjectProperties( + Generator, { + configurable: false, + enumerable: false, + writable: false + }, + Generation + ); + defineObjectProperties( + Generator, { + configurable: false, + enumerable: false, + writable: false + }, { /** - * Creates a new instance of this Generator. - * @return {Generator} Instance of this Generator. + * Returns true if 'generator' was generated by this Generator. + * @param {Generator} generator A Generator. + * @return {Boolean} true or false. */ - create: function create() { - var _ = this, - newObj = Object.create(_.proto); - - _.__supercreate(newObj, arguments); - - return newObj; - }, - - __supercreate: function __supercreate(newObj, args) { - var _ = this, - superGenerator = Object.getPrototypeOf(_), - supercreateCalled = false; - - newObj.supercreate = function supercreate() { - - supercreateCalled = true; - - if (Generation.isGeneration(superGenerator)) { - superGenerator.__supercreate(newObj, - arguments); - } - }; - - _.__create.apply(newObj, args); - - if (!supercreateCalled) { - newObj.supercreate(); - } - - delete newObj.supercreate; + isGenerator: function isGenerator(generator) { + return this.isGeneration(generator); }, - __create: function () {}, - /** * Generates a new generator that inherits from `this` generator. * @param {Generator} ParentGenerator Generator to inherit from. * @param {Function} create Create method that gets called when creating a new instance of new generator. * @return {Generator} New Generator that inherits from 'ParentGenerator'. */ - generate: function generate(create) { - var _ = this; - - assertError(Generation.isGeneration(_) || _ === - Generation, - 'Cannot call method \'generate\' on non-Generations.' - ); + toGenerator: function toGenerator(extendFrom, create) { + assertTypeError(extendFrom, 'function'); assertTypeError(create, 'function'); - var newGenerator = Object.create(_), - newProto = Object.create(_.proto); - defineObjectProperties( - newProto, { + create, { configurable: false, enumerable: false, writable: false }, { - generator: newGenerator + prototype: Object.create(extendFrom.prototype), } ); defineObjectProperties( - newGenerator, { + create, { configurable: false, enumerable: false, writable: false - }, { - name: getFunctionName(create), - proto: newProto, - __create: create - } + }, + Generation ); - return newGenerator; - }, - - /** - * Returns true if 'generator' was generated by this Generator. - * @param {Generator} generator A Generator. - * @return {Boolean} true or false. - */ - isGeneration: function isGeneration(generator) { - var _ = this; - return _.isPrototypeOf(generator); - }, - - /** - * Returns true if 'object' was created by this Generator. - * @param {Object} object An Object. - * @return {Boolean} true or false. - */ - isCreation: function isCreation(object) { - var _ = this; - return _.proto.isPrototypeOf(object); - }, - - /** - * Defines shared properties for all objects created by this generator. - * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. - * @param {Object} properties An object who's properties will be attached to this generator's prototype. - * @return {Generator} This generator. - */ - definePrototype: function definePrototype(descriptor, - properties) { - defineObjectProperties(this.proto, descriptor, - properties); - return this; - }, - - /** - * Generator.toString method. - * @return {String} A string representation of this generator. - */ - toString: function toString() { - return '[' + (this.name || 'generation') + - ' Generator]'; - } - } - ); - - // Generator Class Methods - defineObjectProperties( - Generator, { - configurable: false, - enumerable: false, - writable: false - }, { - /** - * Generates a new generator that inherits from `this` generator. - * @param {Generator} ParentGenerator Generator to inherit from. - * @param {Function} create Create method that gets called when creating a new instance of new generator. - * @return {Generator} New Generator that inherits from 'ParentGenerator'. - */ - generate: function generate(create) { - return Generation.generate(create); - }, - - /** - * Returns true if 'generator' was generated by this Generator. - * @param {Generator} generator A Generator. - * @return {Boolean} true or false. - */ - isGenerator: function isGenerator(generator) { - return Generation.isGeneration(generator); - }, - - /** - * [toGenerator description] - * @param {Function} constructor A constructor function. - * @return {Generator} A new generator who's create method is `constructor` and inherits from `constructor.prototype`. - */ - toGenerator: function toGenerator(constructor) { - - assertTypeError(constructor, 'function'); - - var newGenerator = Object.create(Generation), - newProto = Object.create(constructor.prototype); - defineObjectProperties( - newProto, { + create.prototype, { configurable: false, enumerable: false, writable: false }, { - generator: newGenerator + constructor: construct, + generator: construct, } ); defineObjectProperties( - newProto, { + create.prototype, { configurable: false, enumerable: false, writable: false @@ -354,26 +322,13 @@ Creation ); - defineObjectProperties( - newGenerator, { - configurable: false, - enumerable: false, - writable: false - }, { - name: getFunctionName(constructor), - proto: newProto, - __create: constructor - } - ); - - return newGenerator; + return create; } } ); - Object.freeze(Creation); - Object.freeze(Generation); Object.freeze(Generator); + Object.freeze(Generator.prototype); // Exports if (typeof define === 'function' && define.amd) { diff --git a/new.js b/new.js deleted file mode 100644 index 62a783d..0000000 --- a/new.js +++ /dev/null @@ -1,347 +0,0 @@ -/** - * @name generate.js - * @author Michaelangelo Jong - */ - -(function GeneratorScope() { - /** - * Assert Error function. - * @param {Boolean} condition Whether or not to throw error. - * @param {String} message Error message. - */ - function assertError(condition, message) { - if (!condition) { - throw new Error(message); - } - } - - /** - * Assert TypeError function. - * @param {Boolean} condition Whether or not to throw error. - * @param {String} message Error message. - */ - function assertTypeError(test, type) { - if (typeof test !== type) { - throw new TypeError('Expected \'' + type + - '\' but instead found \'' + - typeof test + '\''); - } - } - - /** - * Returns the name of function 'func'. - * @param {Function} func Any function. - * @return {String} Name of 'func'. - */ - function getFunctionName(func) { - if (func.name !== void(0)) { - return func.name; - } - // Else use IE Shim - var funcNameMatch = func.toString() - .match(/function\s*([^\s]*)\s*\(/); - func.name = (funcNameMatch && funcNameMatch[1]) || ''; - return func.name; - } - - /** - * Returns true if 'obj' is an object containing only get and set functions, false otherwise. - * @param {Any} obj Value to be tested. - * @return {Boolean} true or false. - */ - function isGetSet(obj) { - var keys, length; - if (obj && typeof obj === 'object') { - keys = Object.getOwnPropertyNames(obj) - .sort(); - length = keys.length; - - if ((length === 1 && (keys[0] === 'get' && typeof obj.get === - 'function' || - keys[0] === 'set' && typeof obj.set === 'function' - )) || - (length === 2 && (keys[0] === 'get' && typeof obj.get === - 'function' && - keys[1] === 'set' && typeof obj.set === 'function' - ))) { - return true; - } - } - return false; - } - - /** - * Defines properties on 'obj'. - * @param {Object} obj An object that 'properties' will be attached to. - * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties on 'properties'. - * @param {Object} properties An object who's properties will be attached to 'obj'. - * @return {Generator} 'obj'. - */ - function defineObjectProperties(obj, descriptor, properties) { - var setProperties = {}, - i, - keys, - length, - - p = properties || descriptor, - d = properties && descriptor; - - properties = (p && typeof p === 'object') ? p : {}; - descriptor = (d && typeof d === 'object') ? d : {}; - - keys = Object.getOwnPropertyNames(properties); - length = keys.length; - - for (i = 0; i < length; i++) { - if (isGetSet(properties[keys[i]])) { - setProperties[keys[i]] = { - configurable: !!descriptor.configurable, - enumerable: !!descriptor.enumerable, - get: properties[keys[i]].get, - set: properties[keys[i]].set - }; - } else { - setProperties[keys[i]] = { - configurable: !!descriptor.configurable, - enumerable: !!descriptor.enumerable, - writable: !!descriptor.writable, - value: properties[keys[i]] - }; - } - } - Object.defineProperties(obj, setProperties); - return obj; - } - - - - var Creation = { - /** - * Defines properties on this object. - * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. - * @param {Object} properties An object who's properties will be attached to this object. - * @return {Object} This object. - */ - defineProperties: function defineProperties(descriptor, - properties) { - defineObjectProperties(this, descriptor, - properties); - return this; - }, - - /** - * returns the prototype of `this` Creation. - * @return {Object} Prototype of `this` Creation. - */ - getProto: function getProto() { - return Object.getPrototypeOf(this); - }, - - /** - * returns the prototype of `this` super Creation. - * @return {Object} Prototype of `this` super Creation. - */ - getSuper: function getSuper() { - return Object.getPrototypeOf(this.constructor.prototype); - } - }; - - var Generation = { - /** - * Returns true if 'generator' was generated by this Generator. - * @param {Generator} generator A Generator. - * @return {Boolean} true or false. - */ - isGeneration: function isGeneration(generator) { - assertTypeError(generator, 'function'); - - var _ = this; - - return _.prototype.isPrototypeOf(generator.prototype); - }, - - /** - * Returns true if 'object' was created by this Generator. - * @param {Object} object An Object. - * @return {Boolean} true or false. - */ - isCreation: function isCreation(object) { - var _ = this; - return object instanceof _; - }, - /** - * Generates a new generator that inherits from `this` generator. - * @param {Generator} ParentGenerator Generator to inherit from. - * @param {Function} create Create method that gets called when creating a new instance of new generator. - * @return {Generator} New Generator that inherits from 'ParentGenerator'. - */ - generate: function generate(construct) { - assertTypeError(construct, 'function'); - - var _ = this; - - defineObjectProperties( - construct, { - configurable: false, - enumerable: false, - writable: false - }, { - prototype: Object.create(_.prototype) - } - ); - - defineObjectProperties( - construct, { - configurable: false, - enumerable: false, - writable: false - }, - Generation - ); - - defineObjectProperties( - construct.prototype, { - configurable: false, - enumerable: false, - writable: false - }, { - constructor: construct, - generator: construct, - } - ); - - return construct; - }, - - /** - * Defines shared properties for all objects created by this generator. - * @param {Object} descriptor Optional object descriptor that will be applied to all attaching properties. - * @param {Object} properties An object who's properties will be attached to this generator's prototype. - * @return {Generator} This generator. - */ - definePrototype: function definePrototype(descriptor, - properties) { - defineObjectProperties(this.prototype, - descriptor, - properties); - return this; - } - }; - - function Generator() {} - - defineObjectProperties( - Generator, { - configurable: false, - enumerable: false, - writable: false - }, { - prototype: Generator.prototype - } - ); - - defineObjectProperties( - Generator.prototype, { - configurable: false, - enumerable: false, - writable: false - }, - Creation - ); - - defineObjectProperties( - Generator, { - configurable: false, - enumerable: false, - writable: false - }, - Generation - ); - - defineObjectProperties( - Generator, { - configurable: false, - enumerable: false, - writable: false - }, { - /** - * Returns true if 'generator' was generated by this Generator. - * @param {Generator} generator A Generator. - * @return {Boolean} true or false. - */ - isGenerator: function isGenerator(generator) { - return this.isGeneration(generator); - }, - - /** - * Generates a new generator that inherits from `this` generator. - * @param {Generator} ParentGenerator Generator to inherit from. - * @param {Function} create Create method that gets called when creating a new instance of new generator. - * @return {Generator} New Generator that inherits from 'ParentGenerator'. - */ - toGenerator: function toGenerator(extendFrom, create) { - assertTypeError(extendFrom, 'function'); - assertTypeError(create, 'function'); - - defineObjectProperties( - create, { - configurable: false, - enumerable: false, - writable: false - }, { - prototype: Object.create(extendFrom.prototype), - } - ); - - defineObjectProperties( - create, { - configurable: false, - enumerable: false, - writable: false - }, - Generation - ); - - defineObjectProperties( - create.prototype, { - configurable: false, - enumerable: false, - writable: false - }, { - constructor: construct, - generator: construct, - } - ); - - defineObjectProperties( - create.prototype, { - configurable: false, - enumerable: false, - writable: false - }, - Creation - ); - - return create; - } - } - ); - - Object.freeze(Generator); - Object.freeze(Generator.prototype); - - // Exports - if (typeof define === 'function' && define.amd) { - // AMD - define(function () { - return Generator; - }); - } else if (typeof module === 'object' && typeof exports === 'object') { - // Node/CommonJS - module.exports = Generator; - } else { - // Browser global - window.GeneratorF = Generator; - } - -}()); diff --git a/package.json b/package.json index 2850bc9..3c0d366 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "generate-js", - "version": "2.1.6", + "version": "3.0.0", "description": "An easy to use prototypal inheritance model and generator.", "main": "generate.js", "scripts": {