doc: update README

and fix review

Author: popomore

README.md

@@ -20,53 +20,208 @@
 [download-image]: https://img.shields.io/npm/dm/egg-loader.svg?style=flat-square
 [download-url]: https://npmjs.org/package/egg-loader
 
-egg 文件加载器
+A core Plugable framework based on koa
 
-## 使用说明
+**Don't use it directly, see [egg]**
+
+## Usage
+
+Directory structure
+
+```
+├── package.json
+├── app.js (optional)
+├── agent.js (optional)
+├── app
+|   ├── router.js
+│   ├── controller
+│   │   └── home.js
+|   ├── extend (optional)
+│   |   ├── helper.js (optional)
+│   |   ├── filter.js (optional)
+│   |   ├── request.js (optional)
+│   |   ├── response.js (optional)
+│   |   ├── context.js (optional)
+│   |   ├── application.js (optional)
+│   |   └── agent.js (optional)
+│   ├── service (optional)
+│   ├── middleware (optional)
+│   │   └── response_time.js
+│   └── view (optional)
+|       ├── layout.html
+│       └── home.html
+├── config
+|   ├── config.default.js
+│   ├── config.prod.js
+|   ├── config.test.js (optional)
+|   ├── config.local.js (optional)
+|   ├── config.unittest.js (optional)
+│   └── plugin.js
+```
+
+Than you can start with code below
 
 ```js
-const app = koa();
-const Loader = require('egg-loader');
-const loader = new Loader({
-  baseDir: '/path/to/app',
-  eggPath: '/path/to/framework',
-  app: app,
+const Application = require('egg-core').Application;
+const app = new Application({
+  baseDir: '/path/to/app'
 });
-loader.loadPlugin();
-loader.loadConfig();
+app.ready(() => {
+  app.listen(3000);
+});
+```
+
+## EggLoader
+
+EggLoader will load file or directory easily, you can also custom your loader with low level API.
+
+### constructor
+
+- {String} baseDir - current directory of application
+- {Object} app - instance of egg application
+- {Object} plugins - merge plugins for test
+- {Logger} logger - logger instance，default is console
+
+### High Level API
+
+#### loadPlugin
+
+Load config/plugin.js
+
+#### loadConfig
+
+Load config/config.js and config/{serverEnv}.js
+
+#### loadController
+
+Load app/controller
+
+#### loadMiddleware
+
+Load app/middleware
+
+#### loadApplicationExtend
+
+Load app/extend/application.js
+
+#### loadContextExtend
+
+Load app/extend/context.js
+
+#### loadRequestExtend
+
+Load app/extend/request.js
+
+#### loadResponseExtend
+
+Load app/extend/response.js
+
+#### loadHelperExtend
+
+Load app/extend/helper.js
+
+#### loadCustomApp
+
+Load app.js
+
+#### loadCustomAgent
+
+Load agent.js
+
+#### loadService
+
+Load app/service
+
+### Low Level API
+
+#### getServerEnv()
+
+Get serverEnv for application, available serverEnv
+
+serverEnv | description
+---       | ---
+default   | default environment
+test      | system integration testing environment
+prod      | production environment
+local     | local environment on your own computer
+unittest  | unit test environment
+
+You can use this.serverEnv directly after instantiation.
+
+#### getEggPaths()
+
+Get the directory of the frameworks, a new framework born by extending egg, then you can use this function to get all frameworks.
+
+#### getLoadUnits()
+
+A loadUnit is a directory that can be loaded by EggLoader, it has the same structure.
+
+This function will get add loadUnits follow the order:
+
+1. plugin
+2. framework
+3. app
+
+loadUnit has a path and a type(app, framework, plugin).
+
+```js
+{
+  path: 'path/to/application',
+  type: 'app',
+}
 ```
 
-## API
+#### getAppname()
+
+Get appname from package.json
+
+#### loadFile(filepath)
+
+Load single file, will invork when export is function.
+
+#### loadToApp(directory, property, LoaderOptions)
+
+Load the files in directory to app.
 
-### options
+Invoke `this.loadToApp('$baseDir/app/controller', 'controller')`, then you can use it by `app.controller`.
 
-- baseDir: 应用根目录
-- eggPath: egg 本身的路径
-- plugins: 自定义插件配置
-- app: 任何基于 koa 实例化
+#### loadToContext(directory, property, LoaderOptions)
 
-### methods
+Load the files in directory to context, it will bind the context.
 
-基础方式
+```
+// define service in app/service/query.js
+module.exports = class Query {
+  constructor(ctx) {
+    // get the ctx
+  }
+
+  get() {}
+};
+
+// use the service in app/controller/home.js
+module.exports = function*() {
+  this.body = this.service.query.get();
+};
+```
 
-- loadFile: 加载单文件，
-- loadDirs: 获取需要加载的所有目录，按照 egg > 插件 > 框架 > 应用的顺序加载。
+#### loadExtend(name, target)
+
+Loader app/extend/xx.js to target, example
+
+```js
+this.loadExtend('application', app);
+```
 
-业务方法
+### LoaderOptions
 
-- getAppname: 获取应用名
-- loadServerEnv: 加载环境变量
-- loadConfig: 加载: config
-- loadPlugin: 加载插件
-- loadApplication: 加载 extend/application.js 到 app
-- loadRequest: 加载 extend/request.js 到 app.request
-- loadResponse: 加载 extend/response.js 到 app.response
-- loadContext: 加载 extend/context.js 到 app.context
-- loadHelper: 加载 extend/helper.js，到 app.Helper.prototype，需要定义 app.Helper 才会加载
-- loadService: 加载 app/service 到 app.service
-- loadProxy: 加载 app/proxy 到 app.proxy
-- loadMiddleware: 加载中间件
-- loadController: 加载 app/controller 到 app.controller
-- loadAgent: 加载 agent.js 进行自定义
-- loadApp: 加载 app.js 进行自定义
+- {String|Array} directory - directories to load
+- {Object} target: attach object from loaded files,
+- {String} ignore - ignore the files when load
+- {Function} initializer - custom file exports
+- {Boolean} lowercaseFirst - determine whether the fist letter is lowercase
+- {Boolean} override: determine whether override the property when get the same name
+- {Boolean} call - determine whether invoke when exports is function
+- {Object} inject - an object that be the argument when invoke the function
 
+[egg]: https://github.com/eggjs/egg

lib/egg_loader.js

@@ -118,7 +118,7 @@ class EggLoader {
   /**
    * Get all framework directories.
    *
-   * You can extend Application of egg, the extrypoint is options.app,
+   * You can extend Application of egg, the entrypoint is options.app,
    *
    * loader will find all directories from the prototype of Application,
    * you should define `Symbol.for('egg#eggPath')` property.

lib/mixin/config.js

@@ -4,6 +4,8 @@ const debug = require('debug')('egg-loader:config');
 const fs = require('fs');
 const path = require('path');
 const extend = require('extend');
+const assert = require('assert');
+
 
 module.exports = {
 
@@ -33,7 +35,7 @@ module.exports = {
     //           framework config.{env}
     for (const filename of names) {
       for (const unit of this.getLoadUnits()) {
-        const config = this._loadConfig(unit.path, filename, appConfig);
+        const config = this._loadConfig(unit.path, filename, appConfig, unit.type);
 
         if (!config) {
           continue;
@@ -58,16 +60,15 @@ module.exports = {
     ];
     const target = {};
     for (const filename of names) {
-      const config = this._loadConfig(this.options.baseDir, filename);
+      const config = this._loadConfig(this.options.baseDir, filename, undefined, 'app');
       extend(true, target, config);
     }
     return target;
   },
 
-  _loadConfig(dirpath, filename, extraInject) {
-    const pluginPaths = this.orderPlugins ? this.orderPlugins.map(plugin => plugin.path) : [];
-    const isPlugin = pluginPaths.indexOf(dirpath) > -1;
-    const isApp = dirpath === this.options.baseDir;
+  _loadConfig(dirpath, filename, extraInject, type) {
+    const isPlugin = type === 'plugin';
+    const isApp = type === 'app';
 
     let filepath = path.join(dirpath, 'config', filename);
     // let config.js compatible
@@ -80,14 +81,12 @@ module.exports = {
       return null;
     }
 
-    // delete coreMiddleware when app and plugin
     if (isPlugin || isApp) {
-      delete config.coreMiddleware;
+      assert(!config.coreMiddleware, 'Can not define coreMiddleware in app or plugin');
     }
-    // delete middleware and proxy when it's not app
     if (!isApp) {
-      delete config.middleware;
-      delete config.proxy;
+      assert(!config.middleware, 'Can not define middleware in framework or plugin');
+      assert(!config.proxy, 'Can not define proxy in framework or plugin');
     }
 
     return config;

test/fixtures/app-core-middleware/config/config.default.js

@@ -0,0 +1 @@
+exports.coreMiddleware = [];

test/fixtures/app-core-middleware/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "coreMiddleware"
+}

test/fixtures/plugin/node_modules/d/config/config.js

@@ -0,0 +1 @@
+exports.middleware = [];

test/fixtures/plugin/plugin-middleware/config/config.default.js

@@ -0,0 +1,5 @@
+{
+  "eggPlugin": {
+    "name": "middleware"
+  }
+}

test/fixtures/plugin/plugin-middleware/package.json

@@ -0,0 +1 @@
+exports.proxy = {};

test/fixtures/plugin/plugin-proxy/config/config.default.js

@@ -0,0 +1,5 @@
+{
+  "eggPlugin": {
+    "name": "proxy"
+  }
+}

test/fixtures/plugin/plugin-proxy/package.json

@@ -1,6 +1,7 @@
 'use strict';
 
 const should = require('should');
+const utils = require('./utils');
 const Loader = require('./utils').Loader;
 
 describe('test/load_config.test.js', function() {
@@ -48,12 +49,39 @@ describe('test/load_config.test.js', function() {
     should.not.exists(loader.config.pluginA);
   });
 
-  it('should delete config.middleware and config.proxy', function() {
-    const loader = new Loader('plugin');
-    loader.loadConfig();
-    should.not.exists(loader.config.proxy);
-    loader.config.coreMiddleware.should.not.containEql('d');
-    loader.config.appMiddleware.should.not.containEql('d');
+  it('should throw when plugin define middleware', function() {
+    const loader = new Loader('plugin', {
+      plugins: {
+        middleware: {
+          enable: true,
+          path: utils.getFilepath('plugin/plugin-middleware'),
+        },
+      },
+    });
+    (function() {
+      loader.loadConfig();
+    }).should.throw('Can not define middleware in framework or plugin');
+  });
+
+  it('should throw when plugin define proxy', function() {
+    const loader = new Loader('plugin', {
+      plugins: {
+        proxy: {
+          enable: true,
+          path: utils.getFilepath('plugin/plugin-proxy'),
+        },
+      },
+    });
+    (function() {
+      loader.loadConfig();
+    }).should.throw('Can not define proxy in framework or plugin');
+  });
+
+  it('should throw when app define coreMiddleware', function() {
+    const loader = new Loader('app-core-middleware');
+    (function() {
+      loader.loadConfig();
+    }).should.throw('Can not define coreMiddleware in app or plugin');
   });
 
   it('should read appinfo from the function of config', function() {

test/load_config.test.js

@@ -82,6 +82,8 @@ describe('test/load_extend.test.js', function() {
   });
 
   it('should throw when syntax error', function() {
+    const file = utils.getFilepath('load_context_syntax_error/app/extend/context.js');
+    const reg = new RegExp(`${file} error: Unexpected token`);
     (function() {
       const app = koa();
       app.coreLogger = console;
@@ -90,7 +92,7 @@ describe('test/load_extend.test.js', function() {
       });
       loader.loadConfig();
       loader.load();
-    }).should.throw(/load_context_syntax_error\/app\/extend\/context\.js error: Unexpected token \)/);
+    }).should.throw(reg);
   });
 
   it('should extend symbol', function() {

test/load_extend.test.js

@@ -8,6 +8,7 @@ const should = require('should');
 const pedding = require('pedding');
 const path = require('path');
 const Loader = require('../lib/loader');
+const utils = require('./utils');
 const dirBase = path.join(__dirname, 'fixtures/load_dirs');
 
 describe('test/loader.test.js', () => {
@@ -179,12 +180,14 @@ describe('test/loader.test.js', () => {
 
   it('should contain syntax error filepath', () => {
     const app = { model: {} };
+    const file = utils.getFilepath('load_dirs/syntax_error/error.js');
+    const reg = new RegExp(`load file: ${file}, error:`);
     (function() {
       new Loader({
         directory: path.join(dirBase, 'syntax_error'),
         target: app.model,
       }).load();
-    }).should.throw(/load file: .*?test\/fixtures\/load_dirs\/syntax_error\/error\.js, error:/);
+    }).should.throw(reg);
   });
 
   it('should throw when directory contains dot', () => {