diff --git a/.publishrc b/.publishrc index 3679485..ac38751 100644 --- a/.publishrc +++ b/.publishrc @@ -8,6 +8,6 @@ "gitTag": true }, "confirm": false, - "publishTag": "alpha", + "publishTag": "latest", "prePublishScript": "npm run build" } diff --git a/README.md b/README.md index 212bb64..8b692c5 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,146 @@ -JPEX - Javascipt Protoype Extension -=================================== -[![Build Status](https://travis-ci.org/jackmellis/jpex.svg?branch=master)](https://travis-ci.org/jackmellis/jpex) + +![Jpex](https://jpex-js.github.io/dist/jpex.svg) +=========== +Easy Dependency Injection +-------------------------- + +[![Build Status](https://travis-ci.org/jpex-js/jpex.svg?branch=master)](https://travis-ci.org/jackmellis/jpex) [![npm version](https://badge.fury.io/js/jpex.svg)](https://badge.fury.io/js/jpex) [![Code Climate](https://codeclimate.com/github/jackmellis/jpex/badges/gpa.svg)](https://codeclimate.com/github/jackmellis/jpex) [![Test Coverage](https://codeclimate.com/github/jackmellis/jpex/badges/coverage.svg)](https://codeclimate.com/github/jackmellis/jpex/coverage) Jpex is a Class wrapper and Inversion of Control framework. -Jpex makes it easy to create an Object-Oriented-style application in Node. It wraps up a lot of the prototypical quirks of Javascript so you can focus on creating purposeful classes. This is an intentional move away from static functions and modules in favour of providing all complex objects in the form of class instances. +*This the 2.0 of Jpex. For version 1, please refer to the [v1](https://github.com/jpex-js/jpex/blob/1.x/docs/index.md) docs* -The second purpose of Jpex is to make dependency injection extremely easy. You shouldn't ever have to `require` a module within your application (other than Jpex itself), but you also shouldn't have to worry about manually injecting dependencies into every class. -Nobody wants to call a function with 20 parameters in a specific order. -It's not readable, maintainable, or fun. Proper dependency injection should be automagical and the caller shouldn't care what the callee depends on. +## Getting Started -Usage ------ -Easy: require, extend, and instantiate! +### Install +Jpex is available on [npm](https://www.npmjs.com/package/jpex): +`npm install jpex --save` + +You can then include Jpex in your commonJs project: ```javascript -var jpex = require('jpex'); +var Jpex = require('jpex'); +Jpex.extend(...); +``` +Which works out-of-the-box with *node*, *webpack* and *browserify* + +Jpex also comes with a pre-built js file which can be included as a script tag on your page: +``` + + +``` -var MyClass = jpex.extend(function($log){ - this.thing = 'hello'; - $log('My Class instantiated'); +You can also download the source code from [github](https://github.com/jpex-js/jpex) + +------ + +### Registering Services +Services and factories are small modules or functions that provide a reusable or common piece of functionality. In Jpex, you can register **factories**: +```javascript +Jpex.register.factory('myFactory', function(){ + return {}; +}); +``` +**services**: +```javascript +Jpex.register.service('myService', function(){ + this.method = function(){ + ... + }; }); +``` +and **constants**: +```javascript +Jpex.register.constant('myConstant', 'foo'); +``` + +------ + +### Using Factories +Once registered, you can request any factory when creating a new Jpex class: +```javascript +var Class = Jpex.extend(function(myFactory, myService, myConstant){ + myService.method(); + myConstant === 'foo'; +}); + +new Class(); // creates an instance of Class using the above constructor function. +``` -var instance = new MyClass(); +You can also request a factory from Jpex directly: +```javascript +var myService = Jpex.$resolve('myService'); +var myConstant = Jpex.$resolve('myConstant'); + +myService.method(); +myConstant === 'foo'; ``` -There is much more that can be done with Jpex. Checkout the full documentation at https://github.com/jackmellis/jpex/blob/master/docs/index.md + +And finally, you can request a dependency from within another factory: +```javascript +Jpex.register.constant('myConstant', 'foo'); + +Jpex.register.factory('myFactory', function(myConstant){ + return { + injectedValue : myConstant + }; +}); + +Jpex.register.service('myService', function(myFactory){ + this.method = function(){ + return myFactory.injectedValue; + }; +}); + +Jpex.$resolve('myService').method(); // returns 'foo'! +``` + +------- + +### Extend & Instantiate +You can `extend` Jpex to create a whole new *class* with its own constructor and factories. You can also extend an extended class and so on. Each extended class inherits its parent's properties and factories. +```javascript +var Class = Jpex.extend(function(inheritedService){ + // ... +}); + +var SubClass = Class.extend({ + constructor : function(inheritedService){ + ... + }, + invokeParent : true, // will fire off the parent constructor + methods : { + methodA : function(){ + // ... + } + } +}); +``` +you can invoke a Jpex class with the `new` keyword. This will create a new instance of the class: +```javascript +var instance = new SubClass(); + +instance.methodA(); +``` + +------ + +### Plugins +There are several [plugins](/plugins) available that add extra functionality to Jpex. The most fundamental are [jpex-node](https://www.npmjs.com/package/jpex-node) and [jpex-web](https://www.npmjs.com/package/jpex-web) that add some useful default factories to your node or web application: +```javascript +Jpex.use(require('jpex-node')); +Jpex.$resolve('$fs'); +Jpex.$resolve('$promise'); + +// or +Jpex.use(require('jpex-web')); +Jpex.$resolve('$window'); + +// etc. +``` + +For more information, see the full documentation at [https://jpex-js.github.io](https://jpex-js.github.io) diff --git a/docs/changelog.md b/changelog.md similarity index 100% rename from docs/changelog.md rename to changelog.md diff --git a/docs/api/defaults/copy.md b/docs/api/defaults/copy.md deleted file mode 100644 index 6975e32..0000000 --- a/docs/api/defaults/copy.md +++ /dev/null @@ -1,40 +0,0 @@ -$copy -===== -The $copy factory allows you to create a copy any object. It can be used as a function, or as an object which contains shallow and deep copy functions. - -The shallow copy will copy an object but will not create copies of its properties. So if an object has a property `x` which is an object itself, the copied object will have the exact same instance of x. - -The deep copy will copy an object and then copy all of that object's properties. - -The extend method takes any number of arguments and will deep copy the properties of the last arguments onto the first argument. i.e. `$copy.extend(a, b, c)` will copy the properties of `b` onto `a` and then `c` onto `a`. If `b` and `c` have the same property, `c`'s property wins. -There are a couple of rules to keep in mind: -If two objects have the same property, and the type of that property is an *object*, its properties will be combined. i.e. if `b.x.foo` is set and `c.x.bah` is set, then `a.x` will get both properties `foo` and `bah`. -If two objects have the same property, and the type of that property is an *array*, its elements will be concatenated. i.e. if `b.x = [1, 2, 3]` and `c.x = [4, 5]` then `a.x` will be `[1,2,3,4,5]`. - -```javascript -var obj = { x : [1, 2, 3] }; -var shallow, deep, extended; - -shallow = $copy(obj); -// or -shallow = $copy.shallow(obj); // same as above - -shallow !== obj; -shallow.x === obj.x; - -deep = $copy.deep(obj); - -deep !== obj; -deep.x !== obj.x; -deep.x[0] === obj.x[0]; - -extended = $copy.extend(0, 1); // 1 - -extended = $copy.extend({}, obj); // { x : [1,2,3] } - -extended = $copy.extend({}, obj, {y : 'why'}); // { x : [1,2,3], y : 'why' } - -extended = $copy.extend({}, {x : 'first'}, {x : 'second'}); // { x : 'second' } - -extended = $copy.extend({}, {x : [1, 2, 3]}, {x : [4, 5, 6]}); // { x : [1, 2, 3, 4, 5, 6]} -``` diff --git a/docs/api/defaults/error.md b/docs/api/defaults/error.md deleted file mode 100644 index d68d5ba..0000000 --- a/docs/api/defaults/error.md +++ /dev/null @@ -1,46 +0,0 @@ -$error -======= -The $error service allows for a convenient way to organise and throw errors in your application. You can create custom error types which will be held against the $error service, meaning you can hold a library of errors for later use. -*For usage examples and best practices, as well as error handling, see the [Error Handling](../../errorhandling.md) section.* - - -$error ------- -*(message, arguments...)* -This will throw the default error using the provided parameters (based on `$error.default`). -```javascript -try{ - $error('Something went wrong'); -}catch(e){ - ... -} -``` - -$error.Error ------------- -This is a standard error (based on the Error class). This is also the default error type. All defined errors have the same properties available: -###$error.Error.create -Creates an instance of the error with the provided parameters, but does not throw it. -###$error.Error.throw -Creates and throws an error with the provided parameters. - - -$error.define -------------- -*(name, constructorFunction)* -You can define new error types using $error's `define` function. The error type is automatically attached to the $error object. -The constructor function can take any arguments, but the first argument will always be the message. The message property of the error instance will automatically be assigned. -```javascript -$error.define('CustomError', function(message, code){ - this.code = code; -}); - -$error.CustomError.throw(); -``` - -$error.default --------------- -This is the default error that will be thrown when calling $error directly. It can be set to any custom error class. -```javascript -$error.default = $error.CustomError; -``` \ No newline at end of file diff --git a/docs/api/defaults/fs.md b/docs/api/defaults/fs.md deleted file mode 100644 index 818a190..0000000 --- a/docs/api/defaults/fs.md +++ /dev/null @@ -1,13 +0,0 @@ -$fs -=== - -$fs is a wrapper around node's File System module (fs). It includes only the asynchronous methods (`readFileSync` etc. are not included). -Any method that would normally take a callback has been converted into a promise (with the exception of fs.watch). - -```javascript -var MyClass = jpex.extend(function($fs){ - $fs.readFile('files/file', 'utf8') - .then(function(data){}) - .catch(function(err){}); -}); -``` \ No newline at end of file diff --git a/docs/api/defaults/log.md b/docs/api/defaults/log.md deleted file mode 100644 index 2cf572a..0000000 --- a/docs/api/defaults/log.md +++ /dev/null @@ -1,14 +0,0 @@ -$log -==== -This is a wrapper for the console functions - -```javascript -var MyClass = jpex.extend(function($log){ - $log('I am console.log'); - $log.log('I am also console.log'); - $log.warn('I am console.warn'); - $log.error('I am console.error'); -}); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/defaults/promise.md b/docs/api/defaults/promise.md deleted file mode 100644 index 0b6b963..0000000 --- a/docs/api/defaults/promise.md +++ /dev/null @@ -1,44 +0,0 @@ -$promise -======== -This wraps up the native `Promise` class, without the need for the `new` keyword. - -$promise --------- -| Parameter | Type | Default | -|---------------|---------------|-----------| -| function | Function | | -Calling $promise will create a new Promise with the provided constructor function. -The function takes two parameters: resolve and reject. -```javascript -return $promise(function(resolve, reject){ - resolve(123); -}); -``` - -$promise.resolve ----------------- -Returns a resolved promise. -```javascript -return $promise.resolve(123); -``` - -$promise.reject ---------------- -Returns a rejected promise. -```javascript -return $promise.reject().catch(...); -``` - -$promise.all ------------- -Accepts an array of promises and resolves once all promises have been resolved. -```javascript -$promise.all([$promise(...), $promise.resolve(), 123]); -``` - -$promise.race -------------- -Accepts an array of promises and resolves when any of the promises has been resolved. -```javascript -$promise.race([$promise(...), $promise.resolve(), 123]); -``` \ No newline at end of file diff --git a/docs/api/defaults/resolve.md b/docs/api/defaults/resolve.md deleted file mode 100644 index b1c7f15..0000000 --- a/docs/api/defaults/resolve.md +++ /dev/null @@ -1,13 +0,0 @@ -$resolve -======= -The $resolve factory allows you to load a dependency after instantiating your class. Although use cases are limited, it does allow for variants of lazy loading and unit testing. - -```javascript -var fs = $resolve('$fs'); -var path = $resolve('path'); -var p = $resolve('$ipromise'); -``` -It is also possible to provide additional named parameters to the resolver: -```javascript -$resolve('someService', {myFactory : {}}); -``` diff --git a/docs/api/defaults/timers.md b/docs/api/defaults/timers.md deleted file mode 100644 index c1196b5..0000000 --- a/docs/api/defaults/timers.md +++ /dev/null @@ -1,45 +0,0 @@ -$timers -======= -These are just wrappers for the `setTimeout`, `setInterval`, `setImmediate`, and `process.nextTick` functions. - -$timeout --------- -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Callback | Function | | -| Timeout | Integer | 0 | -$timeout is the equivalent of the setTimeout function. The callback function is called after the value of Timeout has passed. The callback function is only called once. - -$interval ---------- -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Callback | Function | | -| Interval | Integer | 0 | -$interval is the equivalent of the setInterval function. $interval is like $timeout except that the callback function is called repeatedly. - -$immediate ----------- -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Callback | Function | | -$immediate calls the callback function on the next available event loop. Unlike $tick, $immediate will not block IO operations. - -$tick ------ -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Callback | Function | | -$tick calls the callback on the next tick. This will block IO operations until the following event loop. - - -```javascript -var MyClass = jpex.extend(function($timeout, $interval, $immediate, $tick){ - $timeout(function(){}, 250); - $interval(function(){}, 250); - $immediate(function(){}); - $tick(function(){}); -}); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/defaults/typeof.md b/docs/api/defaults/typeof.md deleted file mode 100644 index 625db21..0000000 --- a/docs/api/defaults/typeof.md +++ /dev/null @@ -1,17 +0,0 @@ -$typeof -======= -$typeof provides a function that returns the type of any object. The possible values are: -- string -- number -- boolean -- function -- array -- object -- date -- regexp -- null -- undefined - -```javascript -var t = $typeof('hw'); // 'string' -``` diff --git a/docs/api/factories/constant.md b/docs/api/factories/constant.md deleted file mode 100644 index 8667cab..0000000 --- a/docs/api/factories/constant.md +++ /dev/null @@ -1,19 +0,0 @@ -Constant -======== -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Value | Any | | - -Returns a constant value. This is useful for passing a static object into classes, such as a database connection. - -```javascript -var MyClass = jpex.extend(function(db){ - db.retrieveSomeStuff(); -}); -MyClass.Register.Constant('db', returnDatabaseObjectFromSomewhere()); - -new MyClass(); -``` - -If your register a factory or service as a singleton, after the first time it is resolved, it is re-registered as a cosntant. \ No newline at end of file diff --git a/docs/api/factories/enum.md b/docs/api/factories/enum.md deleted file mode 100644 index 9a65408..0000000 --- a/docs/api/factories/enum.md +++ /dev/null @@ -1,21 +0,0 @@ -Enum -==== -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Value | Array[String] | | - -Pass in an array of strings and it creates an enumerable object with properties, the values of which are a 0-based value. Once registered, the resulting enum is frozen, meaning the injected value cannot be amended. - -```javascript -var MyClass = jpex.extend(function(myEnum, $log){ - $log(myEnum.Apple); - $log(myEnum.Banana); -}); - -MyClass.Register.Enum('myEnum', ['Apple', 'Banana']); - -new MyClass(); -// 0 -// 1 -``` \ No newline at end of file diff --git a/docs/api/factories/errortype.md b/docs/api/factories/errortype.md deleted file mode 100644 index facf2ce..0000000 --- a/docs/api/factories/errortype.md +++ /dev/null @@ -1,17 +0,0 @@ -ErrorType -========= -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Constructor | Function | Optional | - -The *ErrorType* factory will register a new error type against the class. It can then be accessed via the $error factory. - -```javascript -var ParentClass = Jpex.extend(function($error){ - $error.ParentError.throw(); -}); -ParentClass.Register.ErrorType('ParentError', function(){ - this.code = 123; -}); -``` diff --git a/docs/api/factories/factory.md b/docs/api/factories/factory.md deleted file mode 100644 index dc41c07..0000000 --- a/docs/api/factories/factory.md +++ /dev/null @@ -1,44 +0,0 @@ -Factory -======= -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Dependencies | Array[String] | null | -| Function | Function | | - -These are functions that return an object that is then injected into the class instance. Think angular Factories. -As with classes, if you omit the dependencies parameter, the dependencies are extracted from the function function. -Factories are inherited, so you can register a factory on a parent class and use it in a child class. In fact, this is the whole idea: Factories are common, reusable modules that you expect to be used by your class and its children. -```javascript -var MyClass = jpex.extend(function(myFactory){ - myFactory.doSomething(); -}); - -MyClass.Register.Factory('myFactory', function($log){ - return { - doSomething : function(){ - $log('Do Something!'); - } - }; -}); - -new MyClass(); -``` - -All main factories (except *Enum* and *ErrorType*) return a chainable object that allows you to specify additional options. -####interface -Specify which interfaces the factory implements -```javascript -MyClass.Register.Factory('myFactory', () => {}).interface('iFactory').interface(['multiple', 'interfaces']); -``` - -####lifecycle -Specify the lifecycle of the factory. The lifecycle property is an object with the following methods: -- application -- class -- instance -- none -More information can be found in the [lifecycles](./lifecycles.md) section. -```javascript -MyClass.Register.Factory('myFactory'), function(){...}).lifecycle.class(); -``` \ No newline at end of file diff --git a/docs/api/factories/file.md b/docs/api/factories/file.md deleted file mode 100644 index 7f8e825..0000000 --- a/docs/api/factories/file.md +++ /dev/null @@ -1,22 +0,0 @@ -File -==== -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Path | String | | - -This will attempt to load the provided path when injected. Once loaded, the result is returned as is, there is no additional processing, just the object in the file. If Path is a relative path, it will be resolved in relation to the current working directory. - -```javascript -var MyClass = jpex.extend(function(file1, file2, file3){ - file1.doSomething(); - file2.sameAsFile1(); - file3.isJson; -}); - -MyClass.Register.File('file1', 'files/jsfile'); -MyClass.Register.File('file2', 'files/jsfile.js'); -MyClass.Register.File('file3', 'files/jsonfile.json'); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/factories/folder.md b/docs/api/factories/folder.md deleted file mode 100644 index 802c9ca..0000000 --- a/docs/api/factories/folder.md +++ /dev/null @@ -1,22 +0,0 @@ -Folder -====== -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Path | String | | - -If a dependency can't be found in the registered factories, it will attempt to find the dependency in any registered folders. -This can be an expensive process so should be avoided if possible. Once the dependency has been found in a folder, the resulting location will be cached. - -```javascript -var MyClass = jpex.extend(function(jsfile, jsonfile){ - file1.doSomething(); - file3.isJson; -}); - -MyClass.Register.Folder('files'); - -new MyClass(); -``` - - -There is also an extended version of folders [here](https://github.com/jackmellis/jpex/blob/master/jpex-folder/readme.md) \ No newline at end of file diff --git a/docs/api/factories/interface.md b/docs/api/factories/interface.md deleted file mode 100644 index 1536983..0000000 --- a/docs/api/factories/interface.md +++ /dev/null @@ -1,97 +0,0 @@ -Interface -========= -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Function | Function | | -| Implements | String/Array | | - -Interfaces are a sort of contract for your dependencies. It defines how how a module should be structured and what properties and methods it should have. -For details on usage and practices, see the [Interfaces](../../interfaces.md) section. - -i ---- -The constructor function takes a single parameter, an *interface utility* which provides a number of methods for defining your interface. -###string -This will define a string-type. This can also be declared using a string literal. -```javascript -MyClass.Register.Interface('foo', i => ({ a : i.string, b : ''})); -``` -###number -This will define a numeric type. This can also be declared by writing any numeric value -```javascript -MyClass.Register.Interface('foo', i => ({a : i.number, b : 2})) -``` -###boolean -This will define a boolean type. This can also be declared with a true/false -```javascript -MyClass.Register.Interface('foo', i => ({a : i.boolean, b : true})) -``` -###null -This will define a null type. This can also be declared with null -```javascript -MyClass.Register.Interface('foo', i => ({a : i.null, b : null})) -``` -###function -This will define a function type. This can also be declared by writing any function -```javascript -MyClass.Register.Interface('foo', i => ({a : i.function, b : function(){}})) -``` -If you want to ensure the function has certain properties against it, you can use the `functionWith` method. -###object -This will define an empty object. This can also be declared using an object literal. -```javascript -MyClass.Register.Interface('foo', i => i.object); -``` -If you declare an object with properties, these will also be type checked: -```javascript -MyClass.Register.Interface('foo', i => ({ - a : { - b : { - c : i.string - } - } -})); -``` -###array -This will define an empty array. This can also be declared using an array literal. -```javascript -MyClass.Register.Interface('foo', i => ({a : i.array, b : []})); -``` -To specify the type of elements the array can hold, use the `arrayOf` method or create a single element of that type. -```javascript -MyClass.Register.Interface('foo', i => [i.number]); -``` -###arrayOf -This will define an array that must be a specific type. You can enter multiple types. -```javascript -MyClass.Register.Interface('foo' i => i.arrayOf(i.string, i.number)); -``` - -###functionWith -This will define a function that must also have certain properties attached to it. The parameter must be an object. -```javascript -MyClass.Register.Interface('foo' i => i.functionWith({a : i.object})); -``` -###any -This will create a property of any type as long as it is defined. -```javascript -MyClass.Register.Interface('foo' i => ({a : i.any()})); -``` -###either -This defines a property that can be of several types. -```javascript -MyClass.Register.Interface('foo' i => ({a : i.either(i.string, i.array)})); -``` - -Implements ----------- -The implements property allows you to define another interface that this interface uses. This allows you to create an inheritence structure. When resolving an interface, all the implemented interfaces must be validated. -```javascript -MyClass.Register.Interface('foo' i => ({a : i.string})); -MyClass.Register.Interface('bah' i => ({b : i.number}), 'foo'); -``` -This is the same as: -```javascript -MyClass.Register.Interface('bah' i => ({b : i.number})).interface('foo'); -``` \ No newline at end of file diff --git a/docs/api/factories/lifecycles.md b/docs/api/factories/lifecycles.md deleted file mode 100644 index 8f744fb..0000000 --- a/docs/api/factories/lifecycles.md +++ /dev/null @@ -1,121 +0,0 @@ -Life Cycles -=========== -The life cycle of a factory determines how often a new instance is created. - -*Life cycles replace the singleton parameter of factories which has now been deprecated. `Factory(n, fn, true)` should now be written as `Factory(n, fn).lifecycle.application()`.* - -application ------------ -This option means that after the first time a facory has been created, the same instance will be used throughout the entire application. -```javascript -var MyClass = Jpex.extend(function(myFactory){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.application(); - -new MyClass(); // will create an instance of myFactory -new MyClass(); // will reuse the same instance - -var SubClass = MyClsss.extend(); - -new SubClass(); // will also reuse the same instance -``` - -Keep in mind that an application lifecycle does not mean the factory is global. It is only accesable relative to where it was registered. -```javascript -var ClassA = Jpex.extend(function(myFactory){...}); -var ClassB = Jpex.extend(function(myFactory){...}); - -ClassA.Register.Factory('myFactory', function(){...}).lifecycle.application(); - -new ClassA(); // creates an instance of myFactory -new ClassB(); // myFactory is not accessable to ClassB as they are on a different heirarchy tree -``` - -It is also important to keep in mind that if an application-level factory depends on another factory, it will only calculate the dependency once. -```javascript -var MasterClass = Jpex.extend(); -MasterClass.Register.Constant('myConstant', 'master'); -MasterClass.Register.Factory('myFactory', function(myConstant){return myConstants;}); - -var ClassA = MasterClass.extend(function(myFactory){}); -ClassA.Register.Constant('myConstant', 'A'); - -var ClassB = MasterClass.extend(function(myFactory){}); -ClassB.Register.Constant('myConstant', 'B'); - -// The first class to get instantiated will determine what myFactory will resolve to... -new ClassA(); // 'A' -new ClassB(); // 'A' -new Master(); // 'A' -``` - -And finally, if you re-declare a factory in a child class, this will be used instead of the original. -```javascript -var MyClass = Jpex.extend(function(myFactory){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.application(); - -new MyClass(); // will create an instance of myFactory - -var SubClass = MyClsss.extend(); -SubClass.Register.Factory('myFactory', function(){...}); - -new SubClass(); // will use its own declaration of myFactory -``` - -class ------ -For a class-level life cycle, the same factory instance will be used every time you create a new class instance. However, if you create a child class, it will use a different instance of the factory. -```javascript -var MyClass = Jpex.extend(function(myFactory){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.class(); - -new MyClass(); // will create an instance of myFactory -new MyClass(); // will reuse the same instance - -var SubClass = MyClsss.extend(); - -new SubClass(); // will create another instance of myFactory -new SubClass(); // will reuse the same instance -``` - -instance --------- -This will create a new factory instance every time you instantiate a class. -```javascript -var MyClass = Jpex.extend(function(myFactory){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.instance(); - -new MyClass(); // will create an instance of myFactory -new MyClass(); // will create another instance of myFactory -``` -However, unlike *none*, it will use the instance to resolve all of the class instance's factories. -```javascript -var MyClass = Jpex.extend(function(a, b, c){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.instance(); -MyClass.Register.Factory('a', function(myFactory){return myFactory;}) -MyClass.Register.Factory('b', function(myFactory){return myFactory;}) -MyClass.Register.Factory('c', function(myFactory){return myFactory;}) - -new MyClass(); //a b and c will all be the same instance of myFactory -``` - -none ----- -This will create a new factory instance every time it is requested. -```javascript - -var MyClass = Jpex.extend(function(a, b, c){...}); - -MyClass.Register.Factory('myFactory', function(){...}).lifecycle.none(); -MyClass.Register.Factory('a', function(myFactory){return myFactory;}) -MyClass.Register.Factory('b', function(myFactory){return myFactory;}) -MyClass.Register.Factory('c', function(myFactory){return myFactory;}) - -new MyClass(); //a b and c will all be different instances of myFactory -new MyClass(); // this will create another 3 instances of myFactory -``` -Note that if you invoke the class's parent, it *will* share the same factory instance with it. \ No newline at end of file diff --git a/docs/api/factories/named-params.md b/docs/api/factories/named-params.md deleted file mode 100644 index 7fbee55..0000000 --- a/docs/api/factories/named-params.md +++ /dev/null @@ -1,17 +0,0 @@ -Named Parameters -================ -Named parameters take precedence over anything else and are essential to quickly mocking out dependencies in unit tests or injecting variable values such as a *request* object or the user's *session*. -When instantiating a class, you can provide a single object with any number dependencies. If a class already has a factory defined, a named parameter of the same name will overwrite it. - -```javascript -var MyClass = jpex.extend(function(custom, fs){ - custom('string'); -}); - -new MyClass({ - custom : function(val){}, - fs : {} -}); -``` - -Named parameters are especially useful for unit testing, as you can quickly create a mock dependency that will replace an existing factory. \ No newline at end of file diff --git a/docs/api/factories/node_module.md b/docs/api/factories/node_module.md deleted file mode 100644 index d509985..0000000 --- a/docs/api/factories/node_module.md +++ /dev/null @@ -1,18 +0,0 @@ -node_module -=========== -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | - -If a dependency can't be found within any registered factories, Jpex will attempt to load the dependency from node_modules. This includes anything in the node_modules folder and global modules like fs and path. -To avoid the overhead of checking all factories and folders before resorting to this method, you can manually register a node_module. -```javascript -var MyClass = jpex.extend(function(fs, path){ - path.resolve('/'); - fs.readFile(); -}); - -MyClass.Register.node_module('fs'); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/factories/service.md b/docs/api/factories/service.md deleted file mode 100644 index 9742143..0000000 --- a/docs/api/factories/service.md +++ /dev/null @@ -1,30 +0,0 @@ -Service -======= -| Parameter | Type | Default | -|---------------|---------------|-----------| -| Name | String | | -| Dependencies | Array[String] | null | -| Function | Function | | - -Services are simple classes that are instantiated and the instance returned when injected. -It is also possible to register another Jpex class as a service, meaning that you can inject classes into each other. - -```javascript -var MyClass = jpex.extend(function(myService){ - myService.doSomething(); -}); - -MyClass.Register.Service('myService', function($log){ - this.doSomething = function(){ - $log('Do Something!'); - }; -}); - -new MyClass(); - -var LinkedClass = jpex.extend(function(myClass){ - -}); - -LinkedClass.Register.Service('myClass', MyClass); // injects MyClass as a dependency of Linked Class -``` \ No newline at end of file diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index e810db5..0000000 --- a/docs/api/index.md +++ /dev/null @@ -1,39 +0,0 @@ -API -=== -Jpex ----- -The following static properties and methods are available on the Jpex class object and any class that inherits it. -[extend](./jpex/extend.md) -[Register](./jpex/register.md) -[NamedParameters](./jpex/namedparameters.md) -[InvokeParent](./jpex/invokeparent.md) - -Factories ---------- -Factories are small modules that can be injected into a class or another factory. -[Factory](./factories/factory.md) -[Constant](./factories/constant.md) -[Service](./factories/service.md) -[File](./factories/file.md) -[Folder](./factories/folder.md) -[Enum](./factories/enum.md) -[Interface](./factories/interface.md) -[node_module](./factories/node_module.md) -[named parameters](./factories/named-params.md) - -[Factory Lifecycles](./factories/lifecycles.md) - -Default factories ------------------ -Jpex comes with several default factories that can be injected into your classes. -[$log](./defaults/log.md) -[$timeout](./defaults/timers.md#$timeout) -[$interval](./defaults/timers.md#$interval) -[$immediate](./defaults/timers.md#$immediate) -[$tick](./defaults/timers.md#$tick) -[$promise](./defaults/promise.md) -[$fs](./defaults/fs.md) -[$error](./defaults/error.md) -[$typeof](./defaults/typeof.md) -[$copy](./defaults/copy.md) -[$resolve](./defaults/resolve.md) diff --git a/docs/api/jpex/extend.md b/docs/api/jpex/extend.md deleted file mode 100644 index f0f29e2..0000000 --- a/docs/api/jpex/extend.md +++ /dev/null @@ -1,102 +0,0 @@ -Jpex.Extend -====== -*Object* -The extend function creates a new class using the original as its parent and the function as a constructor. You can then extend the new class and so on. - -Note that you don't have to pass arguments into the new command, these are automatically injected. - -Extend can be called in 3 ways: with no parameters, with a constructor function, and with an [options](#extend-options) object: - -```javascript -var MyClass1 = jpex.extend(); - -var MyClass2 = MyClass1.extend(function(myService, myFactory, $timeout){ - // Class constructor -}); - -var MyClass3 = jpex.extend({ - invokeParent : true, - dependencies : ['myService', 'myFactory', '$timeout'], - constructor : function(myService, myFactory, $timeout){ - // Class constructor - }, - prototype : { - someFn : function(){} - }, - static : { - staticProperty : {} - } -}); -``` - -*Keep in mind that the constructor parameters are injected rather than passed in directly. So calling `new MyClass2(service, factory)` would not instantiate the class with those parameters. If you wanted to pass a parameters into your Class you would need to use [named parameters](../factories/named-params.md) e.g. `new MyClass2({mySerivce : service, myFactory : factory})`* - -Extend options --------------- - -###constructor -*function(dependency1, ...)* -The constructor function that will be called when the class is instantiated. - -###dependencies -*Array[String | Object]* -Dependencies to be resolved and injected into the constructor. If omitted, the dependencies are extracted from the constructor function. -Often the dependencies option isn't required, but there may be some use cases such as [object dependencies](../../di.md#object-dependencies) or dependencies that are not valid parameter names. -It is also possible to make dependencies [optional](../../di.md#optional-dependencies). - -###bindToInstance -*Boolean | String* -If *true*, the bindToInstance option will attach all injected dependencies to the instance (e.g. `this.$promise`). If bindToInstance is a string, it will create a property of that name on the instance and attach the dependencies to that. -```javascript -var MyClass = jpex.extend({ - dependencies : ['myService'], - bindToInstance : 'tmp' -}); - -var instance = new MyClass(); -instance.tmp.myService; -``` - -###prototype -*Object* -Adds functions to the class prototype. This is the same as directly adding properties to the prototype after creating the class. The prototype is inherited (it becomes the prototype of the child class's prototype). - -###invokeParent -*Boolean | String* -*Defaults to false if there is a constructor function, or true if there isn't* -Determines whether the parent constructor should be called before calling the class constructor. Any dependencies shared between the parent and child classes will be passed up the invocation chain, if the parent uses any different dependencies these will be resolved. -If invokeParent is set to `'after'` the parent will be called after the main constructor. -```javascript -var ParentClass = jpex.extend(function($log){ - $log('Parent Class'); -}); - -var ChildClass = ParentClass.extend({ - constructor : function($log){ - $log('Child Class'); - }, - invokeParent : true -}); -new ChildClass(); - -// Console would read -// Parent Class -// Child Class - -var BabyClass = ChildClass.extend({ - constructor : function($log){ - $log('Baby Class'); - }, - invokeParent : 'after' -}); - -new BabyClass(); - -// Console would read -// Baby Class -// Parent Class -// Child Class -``` - -###Static -Adds static properties to the newly created class, this is the same as doing `MyClass.something = x`. Static properties are inherited. diff --git a/docs/api/jpex/invokeparent.md b/docs/api/jpex/invokeparent.md deleted file mode 100644 index 4517858..0000000 --- a/docs/api/jpex/invokeparent.md +++ /dev/null @@ -1,11 +0,0 @@ -Jpex.InvokeParent -============ -*(instance, arguments, namedParameters)* -Although you can automatically [invoke the parent](./extend.md#invokeparent), it's also possible to invoke it manually. The third argument allows you to inject custom parameters into the parent or overwrite one of the dependencies in *arguments* -```javascript -var MyClass = jpex.extend(function(myFactory, myService){ - MyClass.invokeParent(this, arguments, {someDependency : 'foo'}); -}); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/jpex/namedparameters.md b/docs/api/jpex/namedparameters.md deleted file mode 100644 index fbcffd3..0000000 --- a/docs/api/jpex/namedparameters.md +++ /dev/null @@ -1,14 +0,0 @@ -Jpex.NamedParameters -=============== -*(arguments)* -This will take an array of values that correspond to the class's dependencies and returns an object with key value pairs. -Essentially this reconstructs your class's dependencies into an object. -The values in the arguments array must be in the same order as the dependencies declared for the class. The normal usage would be to pass in the `arguments` keyword in your class's constructor method. -```javascript -var MyClass = jpex.extend(function(myFactory, myService){ - var namedParameters = MyClass.NamedParameters(arguments); - // returns {myFactory : ..., myService : ...}; -}); - -new MyClass(); -``` \ No newline at end of file diff --git a/docs/api/jpex/register.md b/docs/api/jpex/register.md deleted file mode 100644 index 906d83e..0000000 --- a/docs/api/jpex/register.md +++ /dev/null @@ -1,23 +0,0 @@ -Jpex.Register -======== -The Register property contains methods for registering a factory or service against a class. Once registered, the factory can be injected into the constructor of the class or any class that inherits from it. -```javascript -Jpex.Register('myFactory', function(){ - return {}; -}); - -var ChildClass = Jpex.extend(function(myFactory){ - ... -}); -``` - -Register contains the following methods: -[Factory](../factories/factory.md) -[Constant](../factories/constant.md) -[Service](../factories/service.md) -[File](../factories/file.md) -[Folder](../factories/folder.md) -[Enum](../factories/enum.md) -[node_module](../factories/node_module.md) - -The Register function itself is just a shortcut for `Register.Factory();` \ No newline at end of file diff --git a/docs/di.md b/docs/di.md deleted file mode 100644 index 127afc5..0000000 --- a/docs/di.md +++ /dev/null @@ -1,135 +0,0 @@ -Dependency Injection -===================== -Overview --------- -Dependency Injection is, simply, the process of injecting dependencies into a module. In a normal nodejs module, you would use `require()` to load anything you need: -```javascript -module.exports = function(){ - var path = require('path'); - var fs = require('fs'); - var util = require('../utils'); - ... -}; -``` -However, this means that your code is tightly coupled and you also have to understand how all of these modules are set up, where they live in the file system, etc. It also makes your code harder to test as you're not only testing the code itself, but the modules it requires. -Dependency Injection is a way to abstract this part of the application to a separate process. You could manually inject your dependencies like so: -```javascript -module.exports = function(path, fs, util){ - ... -}; -``` -and in your calling code: -```javascript -require('./myModule')(require('path'), require('fs'), require('../utils')); -``` -but all you're doing is shifting the point at which you couple your dependencies. Your calling code shouldn't care what dependencies are used in your module. But similarly, your module shouldn't care where the dependencies come from or how they're constructed. - -Using Jpex, the internal resolver handles all of this for you. Any modules or factories you depend on are automatically worked out, created, and injected into your module. The module doesn't care where they come from, and the caller doesn't care what the module needs. -```javascript -module.exports = Jpex.extend(function(path, fs, util){ - ... -}); - -require('./myModule')(); -``` - -Declaring dependencies ----------------------- -There are 2 ways to declare a dependency: in a dependency array, or in a constructor function: -```javascript -Jpex.extend({dependencies:['path']}); -Jpex.extend(function(path){}); -``` -If you declare dependencies in the constructor, Jpex uses string parsing to extract the list of dependencies. In a web-facing app, this would cause issues when files are minified, however, it is extremely uncommon for node files to be minified so it's rarely an issue to rely on this method. - -Registering Factories ---------------------- -There are 3 common ways to resolve a dependency: -- [Register a factory](./api/index.md#factories) -- [Load from node modules](./api/factories/node_module.md) -- [Use Jpex's predefined defaults](./api/index.md#default-factories) -```javascript -Jpex.Register('myFactory', function(){ - return; -}); - -var MyClass = Jpex.extend(function(myFactory, express, $log){ - myFactory // factory - express // loaded from node_modules - $log // predefined factory -}); -``` - -Resolving Dependencies ----------------------- -When you create an instance of a class it attempts to resolve all its dependencies. Jpex will attempt to resolve a dependency in this order: - -1. [Named parameters](./api/factories/named-params.md) -2. [Factories](./api/factories/factory.md) registered against the class -3. Factories registered against parent classes -4. [Predefined factories](./api/index.md#default-factories) -5. [Folders](./api/factories/folder.md) registered against the class and its parents -6. [Node modules](./api/factories/node_module.md) - -If a dependency resolves to a factory that also has dependencies, these will also be resolved, and so on. - - -Enhanced Features ------------------ -###Object Dependencies -An advanced feature is the ability to pass properties into a factory from your class declaration. -In your factory you add a dependency to the special *$options* key. -You can then access the object from your factory. This means you can use a single factory for multiple purposes. -```javascript -var MyClass = jpex.extend({ - dependencies : [{myFactory : 'bob'}, {myFactory : 'steve'}], - constructor : function(a, b){ - a.sayHello(); // hello bob - b.sayHello(); // hello steve - } -}); - -MyClass.Register.Factory('myFactory', function($options){ - return { - sayHello : function(){ - return 'hello ' + $options; - } - }; -}); - -new MyClass(); -``` - -###Optional Dependencies -Dependencies can be made optional by wrapping them in underscores. Normally if a require dependency cannot be resolved, an error is thrown. If an optional dependency cannot be found, it will fail silently and return *undefined*. -```javascript -var MyClass = jpex.extend(function(_doesNotExist_, _failsToResolve_, _doesExist_, $log){ - $log(_doesNotExist_); - $log(_failsToResolve_); - $log(_doesExist_); -}); - -MyClass.Register.Factory('failsToResolve', function(doesNotExist){ - return {}; -}); - -MyClass.Register.Factory('doesExist', function(){ - return {}; -}); - -new MyClass(); -// undefined -// undefined -// {} -``` - -###Ancestoral Dependencies -Sometimes you may want to overwrite a factory but still have a reference to the original version. Ancestoral dependencies allow you to inject a dependency defined only on parent classes. This is useful when creating a new factory that enhances the original factory. -To make a dependency Ancesetoral, prefix the name with a ^. -```javascript -MyClass.Register.Factory('$log', ['^$log'], function($log){ - return function(message){ - $log('Enhanced message: ' + message); - }; -}, true); -``` diff --git a/docs/errorhandling.md b/docs/errorhandling.md deleted file mode 100644 index 19ccd52..0000000 --- a/docs/errorhandling.md +++ /dev/null @@ -1,92 +0,0 @@ -Error Handling -============== -Throwing Errors ---------------- -The [$error](./api/defaults/error.md) service allows for a convenient way to organise and throw errors in your application. You can create custom error types which will be held against the $error service, meaning you can hold a library of errors for later use. - -There are number of ways to throw an error using $error: -```javascript -$error('throws a default error type'); -$error.CustomError.throw('throws a custom error type'); -throw $error.CustomError.create('creates an error but has to be thrown manually'); -throw new $error.CustomError('instantiated and thrown manually'); -``` - -###Error Types -$error contains the following default error types: -###Error -This is just a standard error (based on the Error class) which takes a message parameter. - - -Defining Errors ---------------- -###The Hard Way -You can define new error types using $error's `define` function. Define takes 2 parameters: the name of the error, and an optional constructor function. The error type is automatically attached to the $error object. -The constructor function can take any arguments, but the first argument will always be the message. The message property of the error instance will automatically be assigned. -```javascript -$error.define('CustomError', function(message, code){ - this.code = code; -}); - -$error.CustomError.throw(); -``` - -####Caveat: Inheritence -If you were to inject $error into your class or factory and define new error types on it, this would mutate the original $error object used by all classes you have inherited from. This runs the risk of exposing errors you don't want to expose to parent classes, or overwriting error types used by third parties or completely separate classes. - -In order to support inheritence you would need to re-register the $error factory on any class that defines new errors. The $error class in the background uses the *$errorFactory* service, which simply returns the $error instance. The important thing to note is that while $error is a singleton, $errorFactory is not, so it is recreated every time you inject it. -To add new error types to $error without polluting parent classes, you would need to overwrite the $errorFactory service using an ancestral dependency. Then overwrite the $error service to return the newest version of $errorFactory: -```javascript -var ParentClass = Jpex.extend(); -ParentClass.Register.Factory('$errorFactory', '^$errorFactory', function($errorFactory){ - $errorFactory.define('ParentError'); - return $errorFactory; -}); -ParentClass.Register.Factory('$error', function($errorFactory){ - return $errorFactory; -}); - -var MyClass = ParentClass.extend(); - -MyClass.Register.Factory('$errorFactory', '^$errorFactory', function($errorFactory){ - $errorFactory.define('ChildError'); - return $errorFactory; -}); -MyClass.Register.Factory('$error', function($errorFactory){ - return $errorFactory; -}, true); - -// ParentClass would have access to $error.ParentError only - -// MyClass would have access to $error.ParentError and $error.ChildError. -``` - -These steps feel a little convoluted just for defining an error type that may never get used. That's why there is also a shortcut for this: - -###The Easy Way -The [ErrorType](./api/factories/errortype.md) factory will register a new error type for you. It will automatically handle all of the re-registering, making it nice and easy to create an Error specific to your class: -```javascript -var ParentClass = Jpex.extend(); -ParentClass.Register.ErrorType('ParentError'); - -var MyClass = ParentClass.extend(); -MyClass.Register.ErrorType('ChildError'); -``` - -Handling Errors ---------------- -When an error is thrown in your application, Jpex will attempt to handle it using $errorHandler. $errorHandler should be a function that takes a single parameter of the error. The $errorHandler factory is not defined by default, so if Jpex cannot find it, it will just allow the error to bubble up through the application stack. -```javascript -Jpex.Register.Factory('$errorHandler', function($log){ - return function(e){ - $log.error('An error has been caught'); - throw e; - }; -}); - -var MyClass = Jpex.extend(function($error, $errorHandler){ - $error('This will be caught by $errorHandler'); - - $errorHandler('Pass this straight to $errorHandler'); -}); -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 5f588a2..0000000 --- a/docs/index.md +++ /dev/null @@ -1,23 +0,0 @@ -JPEX - Javascipt Protoype Extension -=================================== - -Overview --------- -Jpex makes it easy to create an Object-Oriented-style application in Node. It wraps up a lot of the prototypical quirks of Javascript so you can focus on creating purposeful classes. This is an intentional move away from static functions and modules in favour of providing all complex objects in the form of class instances. - -The second purpose of Jpex is to make dependency injection extremely easy. You shouldn't ever have to `require` a module within your application (other than Jpex itself), but you also shouldn't have to worry about manually injecting dependencies into every class. -Nobody wants to call a function with 20 parameters in a specific order. -It's not readable, maintainable, or fun. Proper dependency injection should be automagical and the caller shouldn't care what the callee depends on. - - -Topics ------- -[Dependency Injection](./di.md) -[Inheritence](./inheritence.md) -[Interfaces](./interfaces.md) -[Error Handling](./errorhandling.md) -[Creating Jpex Plugins](./plugins.md) - -[API](./api/index.md) - -[Change Log](./changelog.md) diff --git a/docs/inheritence.md b/docs/inheritence.md deleted file mode 100644 index f393801..0000000 --- a/docs/inheritence.md +++ /dev/null @@ -1,22 +0,0 @@ -Inheritence -=========== -Jpex supports class inheritence via the [extend](./api/jpex/extend.md) function. This method is avaialble on all classes that inherit from Jpex and the result is a new class. Classes can be extended any number of times and support javascript's `instanceof` property. -```javascript -var ClassA = Jpex.extend(); -var ClassB = ClassA.extend(); -var ClassC = ClassA.extend(); - -ClassA instanceof Jpex // true - -ClassB instanceof ClassA // true -ClassB instanceof Jpex // true - -ClassC instanceof ClassA // true -ClassC instanceof Jpex // true -ClassC instanceof ClassB // false -``` - -Each time you extend from a class, any [static](./api/jpex/extend.md#static) properties are inherited as well as any methods attached to the [prototype](./api/jpex/extend.md#prototype). -[Factories](./api/index.md#default-factories) are also inherited. When a dependency is resolved, Jpex looks for a factory registered on the current class, then it looks for factories registered on the parent class, then that class's parent and so on until it finds a registered dependency. -This means that if a parent class has a factory, you can overwrite it in a child class. The parent class will still use the original definition, but the child will use the new definition. - diff --git a/docs/interfaces.md b/docs/interfaces.md deleted file mode 100644 index cd123a5..0000000 --- a/docs/interfaces.md +++ /dev/null @@ -1,106 +0,0 @@ -Interfaces -========== - -Interfaces are a sort of contract for your dependencies. It defines how how a module should be structured and what properties and methods it should have. -Any factories that implement an interfacr must adhere to the interface's pattern. This means that you can guarentee that a dependency will always have certian methods available. -If a factory does not match the interface when resolved, an error is thrown describing the properties that must be addressed. - -```javascript -var MyClass = Jpex.extend(function(iFactory){...}); -var ChildClass = MyClass.extend(function(iFactory){...}) - -MyClass.Register.Interface('iFactory', function(i){ return {a : i.string, b : i.number, c : i.array};}); - -MyClass.Register.Service('myFactory', function(){ - this.a = 'string'; - this.b = 4; - this.c = []; -}).interface('iFactory'); - -// When ChildClass overrides this factory, if it does not have the same format it will throw an error -ChildClass.Register.Factory('myFactory', function(){ - return {}; -}).interface('iFactory'); - -new MyClass(); // okay -new ChildClass(); // error - myFactory does not match interface pattern. -``` - -Implementing Interfaces ------------------------ -When registering a factory you can set which interfaces it implements. -```javascript -MyClass.Register.Factory('myFactory', function(){...}, true).interface('iService'); -``` -Then when you want to inject your factory you can use the interface to find, validate, and inject the factory. -```javascript -var ChildClass = MyClass.extend(function(iService){...}); -``` -You can still inject the factory directly and it will ignore the interface validation. -```javascript -var ChildClass = MyClass.extend(function(myFactory){...}); -``` - - -Declaring with Named Parameters -------------------------------- -When you pass in [named parameters](./api/factories/named-params.md) you can either pass in the interface name, or a factory that implements the interface, and it will be picked up by the class. The named parameter will have to meet the interface requirements in order to be accepted. -```javascript -new MyClass({iService : {}, factoryThatImplementsAnInterface : {}}); -``` - -Jpex Class Interfaces ---------------------- -When you declare a class, you can optionally provide an *Interface* option. This doesn't do anything on its own, but if you register a class as a service for another class, it will use this property to determine what the class implements. -```javascript -var ServiceClass = Jpex.extend({ - interface : 'iService' -}); - -MyClass.Register.Service('myService', ServiceClass); - -MyClass.Register.Factory('usesMyService', function(iService){...}); -``` -Alternatively you can still provide your own interface options to the `Service` function: -```javascript -MyClass.Register.Service('myService', ServiceClass).interface('iService'); -``` - -Interface Derivitives ---------------------- -As you can *nest* interfaces, you may have a factory that implements a higher-order interface than what you want. The factory will still be valid as its interface implements the requested interface. -```javascript -MyClass.Register.Interface('IEnumerable', function(i){return i.array;}); -MyClass.Register.Interface('IList', function(i){ - var arr = []; - arr.Add = i.function; - arr.Remove = i.function; -}, 'IEnumerable'); - -MyClass.Register.Factory('List', function(){ - var arr = []; - arr.Add = function(){...}; - arr.Remove = function(){...}; -}).interface('IList'); - -MyClass.Register.Factory('lister', function(IEnumerable){...}); -``` -Because the *List* factory implements *IList*, it is implied that it must also implement *IEnumerable*, so if you inject IEnumerable into your class, it will decide that *List* is an acceptable implementer. It will validate that *List* implements *IEnumerable*, but it will not check that it implements *IList* because it is not interested in any features beyond what *IEnumerable* exposes. - -Notes / Caveats ---------------- -Javascript is neither a compiled nor a typed language, so interfaces are not a natural or easy fit. Jpex works just fine without interfaces so what is the benifit of wedging them into the framework? -- Maintainability - - With interfaces it is easy to interchange dependencies. The implementation of a logging service can quickly be swapped with another and you can guarantee that the same methods will be available. You may also have different factories depending on the environment etc. - -- Decoupling - - It's good practice not to tightly couple your application. This is what Jpex is all about. Although it may seem trivial to use iMyService instead of myService, it means you are putting an extra step between the implementation and the caller. - -- Unit Testing - - This is a huge plus for using interfaces. The jpexmocks library in particular has methods for completely mocking out a factory or class based on the interface it implements, meaning you can unit test a class or module without having to manually create a mock version of every dependency it uses. - -If there are multiple factories that implement the same interface, the Dependency Injection process has to guess which one to use. It will use the factory closest to the class that's being instantiated. It is often better to have many interfaces than a few generic ones as this will ensure that the correct factory gets picked up. - diff --git a/docs/plugins.md b/docs/plugins.md deleted file mode 100644 index e51da75..0000000 --- a/docs/plugins.md +++ /dev/null @@ -1,71 +0,0 @@ -Creating Plugins -================ -It's fairly easy to create an add-on component for Jpex. - -Format ------- -Generally, a plugin should be a node_modules-installable that returns a parameter-less function. You can then `require` jpex and its libraries. -It's important after setting your plugin up, that you also apply it to the Jpex class itself. Most setup functions are only run the first time Jpex is required. - -Adding Factory Types --------------------- -Most out-of-the-box factory types are all just wrappers around the main Factory type of the Constant type. -To add a new factory type, require the `jpex/factories` module. This contains a `factories` object and an `apply` method. The apply method will bind all of the factories to the Jpex class. -```javascript -module.exports = function(){ - var factorySetup = require('jpex/factories'); - - factorySetup.factories.MyNewFactory = function(name, param){ - return this.Register.Factory(name, () => dosomething); - }; - - // Apply to the Jpex class - factorySetup.apply(require('jpex')); -}; -``` - -Adding Default Factories ------------------------- -All of the default factories are held in `jpex/defaults`. This module contains a `defaults` array and an `apply` method. -To add a new default factory, simply add a function to the array that takes a Class as the only parameter. -```javascript -module.exports = function(){ - var defaultsSetup = reqire('jpex/defaults'); - - defaultsSetup.defaults.push(function(Class){ - Class.Register.Factory('$plugin', function(){}); - }); - - // Apply to the Jpex class - defaultsSetup.apply(require('jpex')); -}; -``` - -Adding static methods/properties --------------------------------- -This is nice and simple. `jpex/class/static` contains a `methods` and a `properties` object. These are applied to the Jpex class and then inherited by subsequent classes. -```javascript -module.exports = function(){ - var staticSetup = require('jpex/class/statc'); - - staticSetup.methods.Test = function(){}; - staticSetup.properties.Prop = {}; - - // Apply to the Jpex class - staticSetup.apply(require('jpex')); -}; -``` - -Adding Private properties -------------------------- -These properties are added to every new class that is created. The properties should be functions that return a value. -```javascript -module.exports = function(){ - var privateSetup = require('jpex/class/privates'); - - privateSetup.properties._privateArray = () => {return [];}; - - // Apply to the Jpex class - privateSetup.apply(require('jpex')); -}; -``` diff --git a/package.json b/package.json index afc76ce..e02a4ec 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "jpex", - "version": "2.0.0-alpha.3", + "version": "2.0.0", "description": "Javascript Prototype Extension", "main": "src/index.js", "directories": { @@ -26,7 +26,7 @@ "bugs": { "url": "https://github.com/jackmellis/jpex/issues" }, - "homepage": "https://github.com/jackmellis/jpex#readme", + "homepage": "https://jpex-js.github.io", "devDependencies": { "eslint": "^3.15.0", "jasmine": "^2.5.3",