Skip to content

Commit

Permalink
docs: fixed grammatical and spelling errors (#4424)
Browse files Browse the repository at this point in the history
  • Loading branch information
vyasriday committed Aug 18, 2020
1 parent 95776d6 commit 064cc7a
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 21 deletions.
28 changes: 14 additions & 14 deletions docs/source/en/intro/egg-and-koa.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@ title: Egg and Koa

## Asynchronous Programming Model

Node.js is an asynchronous world, asynchronous programming models in official API support are all in callback form ,it brings many problems. For example:
Node.js is an asynchronous world, asynchronous programming models in official API support are all in callback form,it brings many problems. For example:

- [callback hell](http://callbackhell.com/): Notorious "callback hell"。
- [release zalgo](https://oren.github.io/#/articles/zalgo/): Asynchronous functions may call callback function response data synchronously which would bring inconsistency.

The community has provided many solutions for the problems, the winner is Promise, it is built into ECMAScript 2015. On the basis of Promise, and with the ability of Generator to switch context, we can write asynchronous code in synchronous way with [co] and other third party libraries. Meanwhile [async function], the official solution has been published in ECMAScript 2017 and landed in Node.js 8.
The community has provided many solutions for the problems and the winner is Promise. It is built into ECMAScript 2015. On the basis of Promise, and with the ability of Generator to switch context, we can write asynchronous code in a synchronous way with [co] and other third-party libraries. Meanwhile [async function], the official solution has been published in ECMAScript 2017 and landed in Node.js 8.

### Async Function

Expand Down Expand Up @@ -41,7 +41,7 @@ The middleware in Koa is different from Express, Koa use the onion model:

![](https://raw.githubusercontent.com/koajs/koa/a7b6ed0529a58112bac4171e4729b8760a34ab8b/docs/middleware.gif)

All the requests will be executed twice during one middleware. Compared to Express middleware, it is very easy to implement post-processing logic. You can obviously feel the advantage of Koa middleware model by comparing the compress middleware implementing in Koa and Express.
All the requests will be executed twice during one middleware. Compared to Express middleware, it is very easy to implement post-processing logic. You can obviously feel the advantage of Koa middleware model by comparing the compress middleware implementatio in Koa and Express.

- [koa-compress](https://github.com/koajs/compress/blob/master/lib/index.js) for Koa.
- [compression](https://github.com/expressjs/compression/blob/master/index.js) for Express.
Expand All @@ -50,7 +50,7 @@ All the requests will be executed twice during one middleware. Compared to Expre

Unlike that there are only two objects `Request` and `Response` in Express, Koa has one more, `Context` object in one HTTP request(it is `this` in Koa 1, while it is the first parameter for middleware function in Koa 2). We can mount all the related properties in one request to this object. Such as [traceId](https://github.com/eggjs/egg-tracer/blob/1.0.0/lib/tracer.js#L12) that runs through the whole request lifetime (which will be called anywhere afterward) could be mounted. It is more semantic other than request and response.

At the same time Request and Response are mounted to Context object. Just like Express, the two objects provide lots of easy ways to help developing. For example:
At the same time Request and Response are mounted to the Context object. Just like Express, the two objects provide lots of easy ways to help developing. For example:

- `get request.query`
- `get request.hostname`
Expand All @@ -59,7 +59,7 @@ At the same time Request and Response are mounted to Context object. Just like E

### Exception Handling

Another enormous advantage for writing asynchronous code in synchronous way is that it is quite at ease to handle exception. You can catch all the exceptions thrown in the codes followed the convention with `try catch`. We can easily write a customized exception handling middleware.
Another enormous advantage for writing asynchronous code in a synchronous way is that it is quite easy to handle the exception. You can catch all the exceptions thrown in the codes followed the convention with `try catch`. We can easily write a customized exception handling middleware.

```js
async function onerror(ctx, next) {
Expand Down Expand Up @@ -111,15 +111,15 @@ More about extension, please check [Exception](../basics/extend.md) section.

### Plugin

As is known to all, Many middlewares are imported to provide different kind of features in Express and Koa. Eg, [koa-session](https://github.com/koajs/session) provides the Session support, [koa-bodyparser](https://github.com/koajs/bodyparser) help to parse request body. Egg has provided a powerful plugin mechanism to make it easier to write stand alone features.
As is known to all, Many middlewares are imported to provide different kinds of features in Express and Koa. Eg, [koa-session](https://github.com/koajs/session) provides the Session support, [koa-bodyparser](https://github.com/koajs/bodyparser) help to parse request body. Egg has provided a powerful plugin mechanism to make it easier to write stand-alone features.

One plugin can include:

- extend:extend the context of base object, provide utility and attributes.
- middleware:add one or more middlewares, provide pre or post processing logic for request.
- middleware:add one or more middlewares, provide pre or post-processing logic for request.
- config:configure the default value in different environments.

Stand alone module plugin can provide rich features with high maintenancability. You can almost forget the configuration as the plugin supports configuring the default value in different environments.
A stand-alone module plugin can provide rich features with high maintainability. You can almost forget the configuration as the plugin supports configuring the default value in different environments.

[egg-security](https://github.com/eggjs/egg-security) is a typical example.

Expand All @@ -131,17 +131,17 @@ More about plugin, please check [Plugin](../basics/plugin.md) section.

When Egg 1.x released, the Node.js LTS version did not support async function,so Egg 1.x was based on Koa 1.x. On the basis of this, Egg had added fully async function support. Egg is completely compatible with middlewares in Koa 2.x, all applications could write with `async function`.

- The underlying is based on Koa 1.x, asynchronous solution is based on generator function wrapped by [co].
- Official plugin and core of Egg are written in generator function, keep supporting Node.js LTS version, use [co] when necessary to be compatiable with async function.
- The underlying is based on Koa 1.x, asynchronous solution is based on the generator function wrapped by [co].
- Official plugin and the core of Egg are written in generator function, keep supporting Node.js LTS version, use [co] when necessary to be compatible with async function.
- Application developers can choose either async function (Node.js 8.x+) or generator function (Node.js 6.x+).

#### Egg 2.x

When Node.js 8 became LTS version, async function could be used in Node.js without any performance problem. Egg released 2.x based on Koa 2.x, the framework and built-in plugins were all written by async function, and Egg 2.x still kept compatibility with generator function and all the usages in Egg 1.x, applications based on Egg 1.x can migrate to Egg 2.x only by upgrading to Node.js 8.
When Node.js 8 became LTS version, an async function could be used in Node.js without any performance problem. Egg released 2.x based on Koa 2.x, the framework and built-in plugins were all written by async function, and Egg 2.x still kept compatibility with generator function and all the usages in Egg 1.x, applications based on Egg 1.x can migrate to Egg 2.x only by upgrading to Node.js 8.

- The underlying will be based on Koa 2.x, asynchronous solution will be based on async function.
- Official plugin and core of egg will be written in async function.
- Recommend user to transfer business layer to async function.
- The underlying will be based on Koa 2.x, the asynchronous solution will be based on async function.
- The official plugin and core of egg will be written in an async function.
- Recommend the user to transfer the business layer to async function.
- Only support Node.js 8+.

[co]: https://github.com/tj/co
Expand Down
10 changes: 5 additions & 5 deletions docs/source/en/intro/index.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
title: What is Egg?
---

**Egg is born for building enterprise application and framework**,we hope Egg will give birth to more application framework to help developers and developing team reduce development and maintenance costs.
**Egg is born for building enterprise application and framework**,we hope Egg will give birth to more application framework to help developers and developing teams reduce development and maintenance costs.

## Design principles

Since we know well that enterprise applications need to consider how to balance the differences between different teams, seeking common ground while reserving differences in the pursuit of clarifying specification and cooperation, we focus on providing core features for Web development and a flexible and extensible plugin mechanism instead of giant bazaar mode which is popular in common Web frameworks (with integrated such as database, template engine, front-end framework and other functions). We will not make technical selection because default technical selection makes the scalability of the framework too poor to meet a variety of custom requirements. With the help of Egg, it is very easy for architects and technical leaders to build their own framework which is suitable for their business scenarios based on existing technology stack .
Since we know well that enterprise applications need to consider how to balance the differences between different teams, seeking common ground while reserving differences in the pursuit of clarifying specification and cooperation, we focus on providing core features for Web development and a flexible and extensible plugin mechanism instead of giant bazaar mode which is popular in common Web frameworks (with integrated such as database, template engine, front-end framework and other functions). We will not make a technical selection because default technical selection makes the scalability of the framework too poor to meet a variety of custom requirements. With the help of Egg, it is very easy for architects and technical leaders to build their own framework which is suitable for their business scenarios based on the existing technology stack .

The plugin mechanism of Egg is very extensible, **one purpose for one plugin**(Eg: [Nunjucks] is encapsulated into [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks), and MySQL is encapsulated into [egg-mysql](https://github.com/eggjs/egg-mysql)). Aggregating the plugins and customizing the configurations according to their own business scenarios greatly reduces the development cost.

Egg is a convention-over-configuration framework, follows the [Loader](../advanced/loader.md) to do the development, it helps to reduce the cost of learning. Developers no longer work as 'nails'. The cost of communication is very high for a team without convention. it is easy to get fault without convention. However convention is not equal to diffcult extension, instead, Egg does well in extension part, you can build your own framework according to team convention. [Loader](../advanced/loader.md) can help load different default configuration in different environment, Egg default convention can also be covered by your own.
Egg is a convention-over-configuration framework, follows the [Loader](../advanced/loader.md) to do the development, it helps to reduce the cost of learning. Developers no longer work as 'nails'. The cost of communication is very high for a team without convention. It is easy to get fault without convention. However convention is not equal to difficult extension, instead, Egg does well in extension part, you can build your own framework according to team convention. [Loader](../advanced/loader.md) can help load different default configuration in a different environment, Egg default convention can also be covered by your own.

## Differences Between Community Framework

[Express] is well used in Node.js community, it is easy and extensible, fit personal project a lot. However, without default convention, standard mvc model has lots of strange impl which would lead to misunderstandings. Egg's teamwork cost is really low by following convention convention-over-configuration.
[Express] is well used in the Node.js community, it is easy and extensible, fits personal projects a lot. However, without default convention, the standard mvc model has lots of strange impl which would lead to misunderstandings. Egg's teamwork cost is really low by following convention convention-over-configuration.

[Sails] is a framework that also follows convention-over-configuration,it does well in extensible work. Compared with Egg, [Sails] supports blueprint REST API, [WaterLine] , Frontend integration, WebSocket and so on, all of these are provided by [Sails]. Egg does not provide these functions, it only has integration of different functional extensions, such as egg-blueprint, egg-waterline, if you use sails-egg to integrate these extensions, [Sails] can be replaced.
[Sails] is a framework that also follows convention-over-configuration,it does well in extensible work. Compared with Egg, [Sails] supports blueprint REST API, [WaterLine] , Frontend integration, WebSocket and so on, all of these are provided by [Sails]. Egg does not provide these functions, it only has the integration of different functional extensions, such as egg-blueprint, egg-waterline, if you use sails-egg to integrate these extensions, [Sails] can be replaced.

## Features

Expand Down
4 changes: 2 additions & 2 deletions docs/source/en/intro/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ class NewsController extends Controller {
module.exports = NewsController;
```

And also add config.
And also add config.

```js
// config/config.default.js
Expand Down Expand Up @@ -391,7 +391,7 @@ it is inevitable that we need to manage configurations.
Egg provides a powerful way to manage them in a merged configuration file.

- Environment-specific configuration files are well supported, e.g. config.local.js, config.prod.js, etc.
- Configurations could be set wherever convenient for Applications/Plugins/Framesworks, and Egg will be careful to merge and load them.
- Configurations could be set wherever convenient for Applications/Plugins/Frameworks, and Egg will be careful to merge and load them.
- For more information on merging, see [Configurations](../basics/config.md).

```js
Expand Down

0 comments on commit 064cc7a

Please sign in to comment.