Roadmap

We do not plan to release v2 as "stable" until async/await hits node.js. Requiring babel to run your server is just not good developer experience. I do this right now, and I run into a host of problems. Writing your middleware with just promises or with co() or Bluebird.coroutine() everywhere isn't a good experience either. The current way to write middleware is ideal until async/await is native.

You can track v8's progress on async functions here: https://bugs.chromium.org/p/v8/issues/detail?id=4483. After v8 implements async functions, it will take some time for that v8 version to hit stable (6 weeks i think, not sure), then more time for that v8 version to hit node stable (i believe they plan to release a major version every 6 months).

Thus, once async functions hit v8, we have between 2-7 months to release Koa v2 as stable, but it'll probably just take us a day since not much other than the middeware signature has changed.

Don't be scared to use Koa v2 Alpha right now, though. People are already using it in production, and we don't foresee any major changes until we mark it stable.

Changes

The new middleware signature is:

// uses async arrow functions
app.use(async (ctx, next) => {
  try {
    await next() // next is now a function
  } catch (err) {
    ctx.body = { message: err.message }
    ctx.status = err.status || 500
  }
})

app.use(async ctx => {
  const user = await User.getById(this.session.userid) // await instead of yield
  ctx.body = user // ctx instead of this
})

You don't have to use asynchronous functions - you just have to pass a function that returns a promise. A regular function that returns a promise works too!

We don't know how much performance difference there will be, nor do many of the maintainers really care. Koa is as minimal as a framework can be and will not be your app's bottleneck.

New Features

Hopefully, Koa v2 will not have any new features as new features can be added to v1 as well. The only new features that will be added to Koa v2 will be breaking changes. Some possible features are:

• https://github.com/koajs/koa/issues/469
• https://github.com/koajs/koa/issues/281

Features for HTTP2 support can still go into Koa v1. The only problem is that if it's not in require('http') or require('https'), we're not going to include it in Koa. node-spdy is probably going to be the code that is merged into node.js.

Middleware

All of the current stable versions of middleware should be targeting koa v1. If it doesn't, let us know and we'll fix it.

Middleware may have an "alpha" version of the koa v2 version. These should NOT be marked as stable. If they do not exist, let us know and we'll create an alpha version so you can try it with koa v2. Better yet, make a PR!

Upgrading Middleware

You will have to convert your generators to async functions with the new middleware signature:

app.use(async ctx => {
  const user = await Users.getById(this.session.user_id)
  ctx.body = { message: 'some message' }
})

Upgrading your middleware may be a pain in the ass. One migration path is to update them one-by-one.

1. Wrap all your current middleware in koa-convert
2. Test
3. npm outdated to see which koa middleware is outdated
4. Update one outdated middleware, remove using koa-convert
5. Test
6. Repeat steps 3-5 until you're done

We have plans to create a migration bot #625 to make this process slightly better.

Updating Your Code

You should start refactoring your code now to ease migrating to Koa v2:

• Return promises everywhere!
• Do not use yield*
• Do not use yield {} or yield [].
  • Convert yield [] into yield Promise.all([])
  • Convert yield {} into yield Bluebird.props({})

You could also refactor your logic outside of Koa middleware functions. Create functions like function* someLogic(ctx) {} and call it in your middleware as const result = yield someLogic(this). Not using this will help migrations to the new middleware signature, which does not use this.

I currently use babel and use async functions + flow type outside of koa middleware. this will make my migration path in the future easier. I'm not sure if I plan to ever remove babel though since I really like flow type.

How You Can Help

• Documentation - we need a lot!
• Testing Koa v2 and its corresponding middleware
• Help create the migration bot https://github.com/koajs/koa/issues/625

Questions

• Should we transpile w/ babel before we publish? It might make performance better as it transpiles down to ES5, which V8 is more optimized with. Anyone wanna try benchmarking it?

es7 async functions are now supported when you enabled app.experimental = true. it uses https://github.com/thenables/composition. however, the last time i benchmarked it, it was significantly slower.

please provide feedback and maybe do some benchmarks and performance improvements so we can one day support es7 async functions by default without sacrificing anything :)

Frameworks

| Framework | Simultaneous Testing | Multiple Processes For Multiple Files | Global Error Handling | Builtin Babel | NPM Downloads/Month | | --- | :-: | :-: | :-: | :-: | :-: | | Mocha (current) | | | ✓ | | | | Ava | ✓ | ✓ | | ✓ | | | Jest | ✓ | ✓ | | ✓ | |

Request Libraries

| Request Library | Uses Promises | Builtin Response Testing | Response Testing Covers Common Use Cases | Reasonable Defaults For Testing | NPM Downloads/Month | | --- | :-: | :-: | :-: | :-: | :-: | | Superagent | | | | ✓ | | | Supertest (current) | | ✓ | | ✓ | | | Supertest-As-Promised | ✓ | ✓ | | ✓ | | | Assert-Request | ✓ | ✓ | ✓ | ✓ | | | Request | | | | ✓ | | | Request-Promise | ✓ | | | | | | Node-Fetch | ✓ | | | ✓ | | | Requisition | ✓ | | | ✓ | |

Notes

• (current) indicates that Koa currently uses it.
• If we use a framework with builtin babel support, we can easily use async/await in place of builtin response testing if the library supports promises.
• If a request library doesn't have reasonable defaults, we can easily create a wrapper that does.
• If the response testing doesn't cover common use cases, a custom helper assertion function can be used instead.

If anybody has any more columns or rows to add to either table, please leave a comment.

Would Koa be interested in an ES6 refactor via PR? Since we're using Babel, I could do it bit-by-bit. Just to name a few benefits- Readability via const, import/export instead of require, => functions, enhanced object literals, destructuring for things like const { req } = this...

// cc @jonathanong @tj

I understand that when I set this.body and all middleware finished executing the response is sent.

What I want is to send the response at some point and then execute some remaining actions.

Simply setting this.body and then doing yield next doesn't seem to do it - it doesn't seem to automatically send the response after the current middleware. I might be wrong, please correct me if this is the case.

This is the simplified code of what I've tried:

var router = require('koa-router');
router.get('/test', store, process);

function *store(next) {
  yield storeToDB(this.request.body);
  this.body = 'OK';
  // it seems like I need to do something here to send response, like res.send('OK') in express
  try { yield next; }
  catch(e) { console.log('processing error:', e); }
}

function *process() {
  yield processData(this.request.body);
}

The response is sent after process, not after store as I need.

I understand that some separate process can read from DB on some notifications or schedule, but I wanted to keep it simple yet...

closes https://github.com/koajs/koa/pull/530

please test this. if you guys wanna benchmark this, that would be helpful too!

• [ ] update docs
• [ ] add end-to-end testing w/ babel
• [x] publish and set koa-compose version
• [ ] add a warning to koa@1 about the middleware signature change

Some ideas how to better handle streams, the biggest problem being error handling.

As in https://github.com/koajs/koa/issues/180#issuecomment-32126654

// what you have to do currently
// ugly as fuck
app.use(function*(){
  var a = streamA().on('error', this.onerror);
  var b = streamB().on('error', this.onerror);
  this.body = a.pipe(b).pipe(streamC());
});

With multipipe.

// with `multipipe`
app.use(function*(){
  this.body = pipe(streamA(), streamB(), streamC());
});

// for fs leaks, also accept functions as this.body
// and call them when no other handler is set
// leaky as fuck
app.use(function*(){
  this.body = fs.createReadStream.bind(null, 'file.html');
});

We tried all possible google links about "koa flush headers early" and only could found two issues about "flushHeaders" function.

We tried that function but it doesn't work as expected. The expected behavior is:

1. call flushHeaders()
2. all headers that were set are sent over the internet to the client
3. if the server tries to set other headers it throws
4. when the body is set, it's streamed to the client

A basic use-case is to stream "preload" headers for alerting the client to download CSS and font files, so they will be ready by the time slow api and db calls are finished.

For some reason we were able to do this with express and can't figure out how to do it with Koa. Probably just missing documentation, it will help a lot! Thanks.

Assert-request is a promise-based utility I created to replace supertest. Supertest often leads to a custom .end function checking things like a header not existing. In addition, .expect is messy because it tries to be a single function to assert everything. As you can see by looking through the diff, assert-request leads to much cleaner code.

If you're worried about this getting unpublished, NPM recently changed the unpublish feature after left-pad (you first have to contact support and they will check if anything will break because it's gone). If you're worried about this not being maintained, first of all I plan to maintain this, and second of all you can always fork it. The code base is well tested, and IMO well written.

i think this is enough for custom status.

var koa = require('koa');
var app = koa();

app.statuses['700'] = 'Custom Status';

app.use(function* () {
  this.status = 700;
});

app.listen(3000);

curl http://127.0.0.1:3000/ -i
HTTP/1.1 700 Custom Status
X-Powered-By: koa
Content-Type: text/plain; charset=utf-8
Content-Length: 13
Date: Wed, 01 Oct 2014 12:27:11 GMT
Connection: keep-alive

Custom Status

Hi all, there is no bug issues report for a long time. And nodejs will enable generator by default on 4.0.0.

So can we release the koa 1.0.0 after nodejs 4.0.0 publish?

Bumps json5 from 2.2.1 to 2.2.3.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Fixes #1646

Description

Allow context creation an overridable Koa option.

Checklist

• [x] I have ensured my pull request is not behind the main or master branch of the original repository.
• [x] I have rebased all commits where necessary so that reviewing this pull request can be done without having to merge it first.
• [x] I have written a commit message that passes commitlint linting.
• [x] I have ensured that my code changes pass linting tests.
• [x] I have ensured that my code changes pass unit tests.
• [x] I have described my pull request and the reasons for code changes along with context if necessary.

Bumps jest from 28.1.3 to 29.3.1.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

There are examples in the documentation that show that it is not necessary to return a result of the next middleware. If the developers follow this example for writing packages, then it will be impossible to do this things:

app.use(async (ctx, next) => {
  const result = await next();
  if(result instanceof CustomError){
    ctx.body = "something wrong";
    ctx.status = 500;
    return;
  }
  if(!result && typeof result === "object"){
    ctx.body = result; // response with json
  }
})

app.use(async (ctx, next) => {
  // example code from external package
  await next();
  // the result is lost
});

app.use(async ctx => {
  if(ctx.request.charset !== 'utf-8') // some logic
    return new CustomError();

  return { ok: true }
});

Actually, I see this use case as extremely convenient. Why not allow something to be returned for processing? And, for example, consider it as the body of the response. It doesn't matter whether it is a string, an object or a stream, just treat it as a response.

Checklist

• [x] I have searched through GitHub issues for similar issues.
• [x] I have completely read through the README and documentation.

Describe the feature

Support HTTP Trailer headers that come after the response body:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Trailer

Checklist

• [x] I have searched through GitHub issues for similar issues.
• [x] I have completely read through the README and documentation.

Bumps eslint-plugin-promise from 5.2.0 to 6.1.1.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.