Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix styling of Koa vs Express docs #1068

Merged
merged 2 commits into from
Dec 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/api/context.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Context

A Koa Context encapsulates node's `request` and `response` objects
A Koa Context encapsulates Node's `request` and `response` objects
into a single object which provides many helpful methods for writing
web applications and APIs.
These operations are used so frequently in HTTP server development
Expand Down Expand Up @@ -35,7 +35,7 @@ app.use(async ctx => {

Node's `response` object.

Bypassing Koa's response handling is __not supported__. Avoid using the following node properties:
Bypassing Koa's response handling is __not supported__. Avoid using the following Node properties:

- `res.statusCode`
- `res.writeHead()`
Expand Down Expand Up @@ -128,7 +128,7 @@ Koa uses [http-errors](https://github.com/jshttp/http-errors) to create errors.
### ctx.assert(value, [status], [msg], [properties])

Helper method to throw an error similar to `.throw()`
when `!value`. Similar to node's [assert()](http:https://nodejs.org/api/assert.html)
when `!value`. Similar to Node's [assert()](http:https://nodejs.org/api/assert.html)
method.

```js
Expand Down
4 changes: 2 additions & 2 deletions docs/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Koa requires __node v7.6.0__ or higher for ES2015 and async function support.

You can quickly install a supported version of node with your favorite version manager:
You can quickly install a supported version of Node with your favorite version manager:

```bash
$ nvm install 7
Expand Down Expand Up @@ -40,7 +40,7 @@ app.listen(3000);
## Cascading

Koa middleware cascade in a more traditional way as you may be used to with similar tools -
this was previously difficult to make user friendly with node's use of callbacks.
this was previously difficult to make user friendly with Node's use of callbacks.
However with async functions we can achieve "true" middleware. Contrasting Connect's implementation which
simply passes control through series of functions until one returns, Koa invoke "downstream", then
control flows back "upstream".
Expand Down
4 changes: 2 additions & 2 deletions docs/api/request.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Request

A Koa `Request` object is an abstraction on top of node's vanilla request object,
A Koa `Request` object is an abstraction on top of Node's vanilla request object,
providing additional functionality that is useful for every day HTTP server
development.

Expand All @@ -9,7 +9,7 @@
### request.header

Request header object. This is the same as the [`headers`](https://nodejs.org/api/http.html#http_message_headers) field
on node's [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
on Node's [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage).

### request.header=

Expand Down
4 changes: 2 additions & 2 deletions docs/api/response.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Response

A Koa `Response` object is an abstraction on top of node's vanilla response object,
A Koa `Response` object is an abstraction on top of Node's vanilla response object,
providing additional functionality that is useful for every day HTTP server
development.

Expand All @@ -21,7 +21,7 @@

### response.status

Get response status. By default, `response.status` is set to `404` unlike node's `res.statusCode` which defaults to `200`.
Get response status. By default, `response.status` is set to `404` unlike Node's `res.statusCode` which defaults to `200`.

### response.status=

Expand Down
2 changes: 1 addition & 1 deletion docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
## What custom properties do the Koa objects have?

Koa uses its own custom objects: `ctx`, `ctx.request`, and `ctx.response`.
These objects abstract node's `req` and `res` objects with convenience methods and getters/setters.
These objects abstract Node's `req` and `res` objects with convenience methods and getters/setters.
Generally, properties added to these objects must obey the following rules:

- They must be either very commonly used and/or must do something useful
Expand Down
20 changes: 10 additions & 10 deletions docs/koa-vs-express.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Koa vs Express

Philosophically, Koa aims to "fix and replace node", whereas Express "augments node".
Philosophically, Koa aims to "fix and replace Node", whereas Express "augments Node".
Koa uses promises and async functions to rid apps of callback hell and simplify error handling.
It exposes its own `ctx.request` and `ctx.response` objects instead of node's `req` and `res` objects.
It exposes its own `ctx.request` and `ctx.response` objects instead of Node's `req` and `res` objects.

Express, on the other hand, augments node's `req` and `res` objects with additional properties and methods
Express, on the other hand, augments Node's `req` and `res` objects with additional properties and methods
and includes many other "framework" features, such as routing and templating, which Koa does not.

Thus, Koa can be viewed as an abstraction of node.js's `http` modules, where as Express is an application framework for node.js.
Thus, Koa can be viewed as an abstraction of Node.js's `http` modules, where as Express is an application framework for Node.js.

| Feature | Koa | Express | Connect |
|------------------:|-----|---------|---------|
Expand All @@ -18,10 +18,10 @@
| JSONP | | ✓ | |


Thus, if you'd like to be closer to node.js and traditional node.js-style coding, you probably want to stick to Connect/Express or similar frameworks.
Thus, if you'd like to be closer to Node.js and traditional Node.js-style coding, you probably want to stick to Connect/Express or similar frameworks.
If you want to get rid of callbacks, use Koa.

As result of this different philosophy is that traditional node.js "middleware", i.e. functions of the form `(req, res, next)`, are incompatible with Koa. Your application will essentially have to be rewritten from the ground, up.
As result of this different philosophy is that traditional Node.js "middleware", i.e. functions of the form `(req, res, next)`, are incompatible with Koa. Your application will essentially have to be rewritten from the ground, up.

## Does Koa replace Express?

Expand All @@ -34,7 +34,7 @@
Typically many middleware would
re-implement similar features, or even worse incorrectly implement them,
when features like signed cookie secrets among others are typically application-specific,
not middleware specific.
not middleware-specific.

## Does Koa replace Connect?

Expand Down Expand Up @@ -75,18 +75,18 @@

For example, instead of a "body parsing" middleware, you would instead use a body parsing function.

### Koa abstracts node's request/response
### Koa abstracts Node's request/response

Less hackery.

Better user experience.

Proper stream handling.

### Koa routing (third party libraries support)

Since Express comes with its own routing, but Koa does not have
any in-built routing, there are third party libraries available such as
any built-in routing, there are third party libraries available such as
koa-router and koa-route.
Similarly, just like we have helmet for security in Express, for Koa
we have koa-helmet available and the list goes on for Koa available third
Expand Down