From 65c130db5bdb9d971bb695966c9a22efd3b56d52 Mon Sep 17 00:00:00 2001 From: jongleberry Date: Tue, 7 Mar 2017 23:04:43 -0800 Subject: [PATCH] readme docs++ (#932) * Better expose documentation in overview readme * Add code examples for context, request and response * docs++ * fix indentation --- Readme.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 72 insertions(+), 5 deletions(-) diff --git a/Readme.md b/Readme.md index 5d2c2df..fb47dad 100644 --- a/Readme.md +++ b/Readme.md @@ -87,6 +87,78 @@ The middleware signature changed between v1.x and v2.x. The older signature is Please see the [Migration Guide](docs/migration.md) for more information on upgrading from v1.x and using v1.x middleware with v2.x. +## Context, Request and Response + +Each middleware receives a Koa `Context` object that encapsulates an incoming +http message and the corresponding response to that message. `ctx` is often used +as the parameter name for the context object. + +```js +app.use(async (ctx, next) => { await next(); }); +``` + +Koa provides a `Request` object as the `request` property of the `Context`. +Koa's `Request` object provides helpful methods for working with +http requests which delegate to an [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) +from the node `http` module. + +Here is an example of checking that a requesting client supports xml. + +```js +app.use(async (ctx, next) => { + ctx.assert(ctx.request.accepts('xml'), 406); + // equivalent to: + // if (!ctx.request.accepts('xml')) ctx.throw(406); + await next(); +}); +``` + +Koa provides a `Response` object as the `response` property of the `Context`. +Koa's `Response` object provides helpful methods for working with +http responses which delegate to a [ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) +. + +Koa's pattern of delegating to Node's request and response objects rather than extending them +provides a cleaner interface and reduces conflicts between different middleware and with Node +itself as well as providing better support for stream handling. The `IncomingMessage` can still be +directly accessed as the `req` property on the `Context` and `ServerResponse` can be directly +accessed as the `res` property on the `Context`. + +Here is an example using Koa's `Response` object to stream a file as the response body. + +```js +app.use(async (ctx, next) => { + await next(); + ctx.response.type = 'xml'; + ctx.response.body = fs.createReadStream('really_large.xml'); +}); +``` + +The `Context` object also provides shortcuts for methods on its `request` and `response`. In the prior +examples, `ctx.type` can be used instead of `ctx.request.type` and `ctx.accepts` can be used +instead of `ctx.request.accepts`. + +For more information on `Request`, `Response` and `Context`, see the [Request API Reference](docs/api/request.md), +[Response API Reference](docs/api/response.md) and [Context API Reference](docs/api/context.md). + +## Koa Application + +The object created when executing `new Koa()` is known as the Koa application object. + +The application object is Koa's interface with node's http server and handles the registration +of middleware, dispatching to the middleware from http, default error handling, as well as +configuration of the context, request and response objects. + +Learn more about the application object in the [Application API Reference](docs/api/index.md). + +## Documentation + + - [Usage Guide](docs/guide.md) + - [Error Handling](docs/error-handling.md) + - [Koa for Express Users](docs/koa-vs-express.md) + - [FAQ](docs/faq.md) + - [API documentation](docs/api/index.md) + ## Babel setup If you're not using `node v7.6+`, we recommend setting up `babel` with [`babel-preset-env`](https://github.com/babel/babel-preset-env): @@ -132,7 +204,6 @@ See [AUTHORS](AUTHORS). ## Community - - [API](docs/api/index.md) documentation - [Badgeboard](https://koajs.github.io/badgeboard) and list of official modules - [Examples](https://github.com/koajs/examples) - [Middleware](https://github.com/koajs/koa/wiki) list @@ -140,13 +211,9 @@ See [AUTHORS](AUTHORS). - [G+ Community](https://plus.google.com/communities/101845768320796750641) - [Reddit Community](https://www.reddit.com/r/koajs) - [Mailing list](https://groups.google.com/forum/#!forum/koajs) - - [Guide](docs/guide.md) - - [FAQ](docs/faq.md) - [中文文档](https://github.com/guo-yu/koa-guide) - __[#koajs]__ on freenode - - ## Backers Support us with a monthly donation and help us continue our activities.