Koa: Koa 2.0.0

[jonathanong]

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?

[fengmk2]

Should let user to do that, not koa itself.

[tejasmanohar]

@fengmk2 Maybe I'm missing something, but I don't think making the user transpile through Babel here is an adequate solution... wouldn't that require the user to modify what's in node_modules/ (/ fork koa and add babel transpiling in prepublish etc)?

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?
I think we should transpile for more reasons than performance (though that is a potential one). We can play with even more features this way, and there are quite useful / nice features in Babel that are hidden behind --harmony-x flags or entirely non-existent in Node 4.x.x.

[jonathanong]

yeah you can't expect users to transpile any of their node modules

[tejasmanohar]

Agreed. Personally, I think we should use Babel. Then, we don't require Node 4.x.x+ either- we just require an ES6 engine to _use_ Koa (not to install / require etc) @jonathanong. Maybe not everyone is using Node 4.x.x because apps using Koa don't _have to_ use a Node version that has any ES6 natively if we transpile, right? They could just be transpiling with Babel (or something else) themselves?

Basically, I think we should allow the user to _decide_ how they want to run their app using our module. If we ship it as is without transpiling, then the user must use Node 4.x.x, but if we transpile and ship, they can use that, Babel, or something else- no restrictions as long as their engine is ES5+ and their application somehow supports ES6 (since generators). _That_ is giving the user options.

But either way, asking users to transpile the module itself if they don't want to use Node 4.x.x isn't really _reasonable_ (asking them to transpile it, that is. just saying only node 4.x.x is _suboptimal_, imo, but still _reasonable_).

[yanickrochon]

I personally don't transpile. I can see the benefit, but in most case it just adds overhead for only a little benefit (code readability... which most dev don't need anyhow).

As far as I'm concerned, the 2.0 version should just be 4.x+ compatible, period. Devs can just stick with the 1.x branch for their existing applications. Everything is just fine. One of my project is still using a 0.21.0 version, and I don't see any reason to upgrade it. I started this project back when Node 0.11 was released, been using the --harmony flag then, and still using it with Node 0.12.7 at the moment.

Bottom line is, I don't see why 2.0 should be BC. I sure don't have any problem with it.

[tj]

+1 for 4.x only. To me there's nothing overly compelling enough to really make anyone feel like they _have_ to upgrade if they can't quite yet, just a signature change etc. If the perf thing proves out then maybe that'll be worth it, but still a little weird.

[travisjeffery]

+1 to 4.x only too. with koa < 1.x people had to run recent/certain versions of node to have generators and that worked out alright/didn't seem to be an issue there.

[chentsulin]

+1 for 4.x only. koa is significant project which using new coming features to achieve great develop experience, so it needs move forward to the next steps.

[tejasmanohar]

@chentsulin Babel vs Node 4.x.x isn't about being able to use new features or not.

[chentsulin]

@tejasmanohar but support only Node 4.x.x will encourage people to upgrade, not just stay on 0.12. support from 0.x to 4 always be a nightmare to project maintainers. (maybe just like IE 6 ~ 11?)

If I does not use koa one year ago, I will stay on 0.10 for a long time.

[yanickrochon]

@tejasmanohar what @chentsulin said is not really related to the use of Babel or not, but more about if Koa should be BC or not. My take is that, it should not and people should move forward.

That being said and in regards to the use of a transpiler, I don't like all the features in Babel... This is my choice, my opinion. I also do not use _any_ project which are coded in CoffeeScript either. I may be an extremist on this matter, but I really don't like to have dependencies I don't really need nor use in my project. (And I have seen bugs and bad implementations being produced by transpilers that could have been trivial to avoid otherwise.)

My problem with using a transpiler is that it is opiniated. As everyone agree to be Node 4.x+ for version 2.0, all necessary optimizations are already there without using any development flags or a transpiler. As for code readability is concerned, there's not much Babel can add on top of that. Koa is supposed to be lightweight anyway. I haven't seen any valuable objective arguments to justify such dependency.

[tejasmanohar]

Ah, I see. Yeah, I don't think Koa 2.0 needs to be BC either.

[felixfbecker]

+1 for Node 4.x requirement

[thelinuxlich]

+1 for Node 4.x requirement!

[cesarandreu]

+1 for Node 4.x requirement.

Koa only works on node.js anyway, right? So it's not like other engines are at a loss. Any Node 4.x is LTS, so I'd expect people to be able to upgrade sooner or later.

[mike-marcacci]

I'm all for the node 4.x requirement, but I do have a note about babel compatibility:

I've been using the branch from #533 on a brand-new project over the past week, and I discovered that because it uses native, uncompiled es6, I had to be careful what babel transformers are used on _my_ code. Just as one example, if the "es6.class" transformer is enabled (which isn't necessary in 4.x, but is nonetheless on by default) the Koa class can't be extended by babel-compiled code and throws compile-time errors.

This is really a babel issue if it's an issue at all, and I've opted to explicitly declare my transformations in my package.json to avoid it, but I'm sure others will encounter this use case.

These are my babel configs that work seamlessly with the latest Koa.

...
  "babel": {
    "whitelist": [
      "strict",
      "regenerator",
      "es6.modules",
      "es6.arrowFunctions",
      "es6.destructuring",
      "es6.spread",
      "es7.asyncFunctions"
    ]
  }
...

[yanickrochon]

How is Babel currently being used in Koa? Why is it listed as a devDependency?

[tejasmanohar]

@yanickrochon I assume it's listed as a dev dependency because you need it (or another transpiler of sorts) to develop on the experimental portion with ES7 async functions and all that jazz. :notes:

That said, doesn't look like it's actually being used to transpile anything in the scripts etc but rather only in usage by a developer. Maybe @jonathanong can shed some light here?

[jonathanong]

oh yeah it was part of the experimental tests. i removed the tests in the async-function branch but not babel yet.

[jonathanong]

also, i'm not changing the stance on the node 4.x compatibility. i just know people care about performance and the usage of es6 features slows performance (due to VM not optimizing yet). using babel to transpile to ES5 _may_ improve performance (as well as being very easy), but i would want to benchmark that before doing that.

[yanickrochon]

Dev for 2.0 doesn't have to have an RC just yet and may as well be a proof of concept. Angular 2.0 has been in alpha for ages... lol... so Koa 2.0 doesn't have to be released next month. At some point, all these new ES6 features will be optimized.

Also, as a thought; is co still relevant, or will still be relevant in 2.0?

[jonathanong]

yeah we'll leave it in for now for function* (ctx, next) {} middleware. i don't see a reason not to unless anyone has objections.

[felixfbecker]

Old middleware will not work anyway and will require koa-convert. I think we should remove co and instead let koa-convert take care of converting legacy, generator-based, context-as-this middleware. Might add performance, but the question should be _why should we leave it in_ if old middleware won't work anyway.

[thelinuxlich]

Arrow functions are optimized in Node 4

[jonathanong]

should we remove co from koa, guys? this means that all your generator functions should look like this if you don't use babel:

app.use(co.wrap(function* (ctx, next) {
  yield next()
})

we're going to eventually remove co anyways... could be v2 or v3.

[dead-horse]

remove co after node LTS support async await ?

[tejasmanohar]

:+1: for after Node LTS supports async/await

[felixfbecker]

That's gonna be ages.

[tejasmanohar]

@felixfbecker Well, part of the question is would you rather use _co#wrap_. I'd guess 1.5 - 2 yrs till async/await is in Node LTS but may be completely wrong... all this Babel hype has made us immune to time!

[thelinuxlich]

I prefer to use Babel so I can choose between co or bluebird

[yanickrochon]

There's already a proposal which I think have merits. Since co _has been_ Promise-based for a while now, I think Koa should drop it as dependency and move to a Promise solution. The advantage of using promises is quite evident and should not have a negative impact in most cases. Also, old middlewares can use co.wrap if they need to be re-used, until they migrate to be 2.0 compatible. To me, since there is a solution that not only works but is clean means that there's no problem in dropping co in favour of Promise or async/await (using a transpiler for now).

Furthermore, Generators have always been "hacky". It does not promote good usage of the design pattern :)

[jonathanong]

@thelinuxlich

I prefer to use Babel so I can choose between co or bluebird

this should be irrelevant if you do app.use(function* (ctx, next) {}) right

[thelinuxlich]

@jonathanong how so? If I use async/await keywords I will need Babel anyway, right?

[gyson]

@jonathanong

• Is function* (ctx, next) {} a valid middleware or just a shortcut for co.wrap(function* (ctx, next) {}) with app.use?
• Should koa-compose and koa-router support it ?
• Could koa-* middleware return function* (ctx, next) {} ?

[fundon]

I found some interesting things with koa-compose

e.g:

const middleware = compose([
  function *one(ctx, next) {
    // maybe will return something
  },
  function *two(ctx, next) {
    // maybe will return something
  }
])

// now, `yield middleware(ctx, next)` is a Promise Instance
app.use(function *(ctx, next) {
   const result = yield (yield middleware(ctx, next))
   // do something for result
})

[matthewmueller]

Haven't been really following this discussion too much, but I feel like I'm missing the benefits of these changes. Is it just "new-ness"? The API seems more confusing now:

app.use((ctx, next) => {
  const start = new Date;
  return next().then(() => {
    const ms = new Date - start;
    console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
  });
});

Don't take this to sound negative, just curious for the reasoning behind these changes.

[mike-marcacci]

Hey @matthewmueller, it's taking advantage of the es7 syntax, which is much less of a hack than using generators:

app.use(async (ctx, next) => {
  const start = new Date;
  await next();
  const ms = new Date - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

[madbence]

@mike-marcacci it should be async (ctx, next) => ...

[mike-marcacci]

correct :)

[tj]

Mentioned somewhere else, but I think we should wait to upgrade middleware until async/await is native, otherwise we'll just be going through them all over again to upgrade. Plus doing it now is confusing in the sense that it makes it seem like people should be migrating, even though 2.0 is not a thing yet (IMO shouldn't be until async/await).

Other than async/await there's not really anything new, so the less pain for migration the better. Requiring Babel will just make Koa go vaporware, at least I certainly wouldn't want to use Babel for server code.

[tejasmanohar]

@tj I kinda agree with you that maybe v2 shouldn't be released as "stable" until async/await is in V8 if we've decided not to use Babel to transpile the module's code (though I think that's fine and means we can release v2 stable-y earlier)... reason for this is it's kind a regression to switch out promises / .then()ables for co / generators / yield since we lose the serially (top -> bottom) processed code /readability benefits for managing async flow that exist in v1.

UPDATE: basically, writing koa 2 middleware without async/await is harder, less readable, and a regression in terms of what co / koa v1 / yield provide- imo

[magicdawn]

at least I certainly wouldn't want to use Babel for server code.

:+1:

[omsmith]

I'd say on my end, I've made the updates I've submitted, since I made them locally to give it all a go - so may as well submit them.

Perhaps the middlewares/tooling which have released new versions (koajs/compose, koajs/rewrite, koajs/route) should unpublish the major bumps and republish with an -alpha suffix? If 2.0 is being tip-toed around for the time being then not much point in releasing them all as latest when koa itself hasn't done so.

Personally, I do prefer the promise interface, even without async/await (although obviously the new syntax will make it nicer to consume), just to remove confusion in thinking this is what generators "actually do".

[yanickrochon]

I too understand the wait, but really like the Promise implementation. Did not like it at first, but really got to appreciate things like

function getSomeValue(key) {
  return valueCache[key] || (valueCache[key] = new Promise((resolve, reject) => {
    // do some async processing
    // then resolve(value); or reject(Error)
  }));
}

My question, however is: "What is the ETA for native async/await?" If the answer is "next year, or something", then we should really consider releasing Koa 3.0 _then_ and start migrating essential middlewares right now. :smile:

[mike-marcacci]

The tc39 page still has the spec in "DRAFT" but with the expectation that it will move to "FINISHED" this month.

Once it's finalized, it obviously has to be implemented in V8 before it can make its way to node, so the beginning of 2016 is the earliest I'd bet on.

[ljharb]

fwiw, the arrow function spec did _not_ move to stage 4 ("finished") this week - it's still stage 3.

[tejasmanohar]

@mike-marcacci Early 2016 seems a bit too hopeful.

[mike-marcacci]

@tejasmanohar, you're definitely right - just emphasizing that "next year, or something" is definitely the answer to @yanickrochon's question

[tejasmanohar]

Moreover, maybe it's just me, but I don't see how using co in Koa v1 is better than using Babel for async/await in Koa v2 (and official middleware). Someone explain?

If we don't use async/await through Babel in Koa v2 stuff, then what's the improvement to warrant a new version? Also, what are the real downsides of transpiling syntax on the server?

UPDATE: We don't have to use Babel or force anyone to use Babel in Koa itself but what about the official middleware. I don't see a reason not to use Babel there until async/await hits stable Node?

[yanickrochon]

To me, the real improvement over co is stack trace. Just by replacing parts of my apps with promises made a real difference on maintenance cost.

As for Babel, AFAIC, this is just a matter of semantic as it really doesn't offer much than that. I personally don't care much about it. I also noticed that arrow functions are slightly slower than "legacy" functions, but I haven't really made a benchmark on that one.

[thelinuxlich]

Pff, forget the past, release Koa 2 now :)

[tejasmanohar]

I'm not concerned with the perf aspect of Babel or even using Babel in the core... it's more about whether or not to use Babel for _async/await_ in official middleware in the Koa.js org. We should probably vote on a universal policy for this, as if we release Koa@2, users will expect the popular official middleware to be upgraded and follow a standard.

And, I'm not the only one noticing this... @coderhaoxin, @fengmk2, and @matthewmueller have all brought up concerns about the new Promise-based middleware in issues on other repos in the org. Without async/await, this feels like a regression of the async control flow benefits from Koa@1 with yield... almost feels like callbacks from a readability perspective. See here, here, and here.

So... I'll start the poll. +1 for Babel in official middleware for me. I don't wanna include Babel in the core or make users of Koa use Babel (like require hooks), but I think that's a fair, opinionated choice for the official middleware as they're merely clients of Koa 2, not Koa itself.

[elgerlambert]

Could be a while before async/await is implemented in v8 (comment made 3 weeks ago):

I should also note that async is a particularly tricky feature that will require
deep knowledge of V8's innards. We expect this to be a multi-quarter project. In
particular, it ties in closely with generators, around which there currently are
various open questions in the V8 implementation. We have some plans for tackling
that next year, but not before we have finished ES6. To be honest, we would
prefer not to open that can right now, since ES6 already is producing a lot of
churn. - https://codereview.chromium.org/1423663006/

Here's a different issue on the same topic: https://code.google.com/p/v8/issues/detail?id=4483

[menems]

Hi,

I don't think you have to use babel on official middleware, unless thoses middleware are already es5 transpiled for end user. Users have to choose if they want async support with babel or use promise style as long as async has official support on node core.

Some people prefer use promise catch pattern than try/catch.

koa1: generator
koa2: promise ( async with babel)
koa3: native async

I think it's a not a bad idea to release a koa2

[yanickrochon]

I think that _requiring_ Babel will only cause harm to Koa as it should be a matter of choice for a project only. Forcing Babel (i.e. extra non essential dependencies) is a big :-1: for me.

As for promises regressing to a callback-like style, I disagree. The big issue with callbacks was the indentation problem, where the flow could easily get lost through the layers of callbacks, where people had to fragment code to keep it clean. With Promises, the control can easily be vertical and simple through chaining, and usually only require one level of indentation for many, many asynchronous requests within the same workflow. Hardly the same as with callbacks.

Also, the advantage of promises is the lack of try... catch in code (that I particularly find ugly) and is encapsulated in a more elegant way using promises.

My guess is that async/await will take a bit lot longer than a few months to implement (as suggested by @elgerlambert 's comment. The implementation will need to get around the stack trace problem that arise when using yield with co right now and produce a real call stack on error, among other things. Bottom line is, I would not be surprised to see this feature implemented only after the second quarter of 2016 in an unstable version of Node.

[matthewmueller]

Thanks for the information guys. Yah, I think we should wait as well.

I'm -1 on the promise implementation (without await/async) for 2 reasons:

1) It requires a change in all middleware (there are 1000's of koa middleware modules at this point, public and private)
2) Aesthetically, I think it's really hard to say that the promise implementation is nicer than the generator implementation. There are more tokens and more indentation.

I agree with the others that I don't think it's reasonable to force everyone to use babel-node, it's also tangibly slower to recompile than node.

I do think the ctx stuff is nice, but I'd rather wait until async/await than force everyone to update their middleware twice.

[mattstyles]

Requiring end-users to transpile, and to transpile selected dependencies, is proper weird.

Publishing transpiled modules isnt a problem, then its just a matter of which coding style is preferred or performance. Of course, having a decent stack trace is necessary too.

If maintainers like the async/await style and it looks like (for the time being) es5 transpiled code would be most performant then surely pre-compilation is the way to go no? Just dont force that transpilation on to the end-user, who should be able to include a few middleware, attach them to koa and node server to get going.

[omsmith]

async/await wouldn't force an additional iteration. The signature stays the same, so churning through all the middleware wouldn't have to happen again (though more complex middleware might opt to use the new syntax to simplify things).

[tejasmanohar]

I agree with the others that I don't think it's reasonable to force everyone to use babel-node, it's also tangibly slower to recompile than node.

If we transpile official middleware that's making use of async/await before publishing to NPM, the end user doesn't need to use Babel. Async/await are just handlers of promises. It's about what's used in the official middleware. @matthewmueller

[yanickrochon]

I could live with middleware being developped with Babel (as a dev-dependency), and transpiled to ES2015 before being published to npm.

• src the Babel implementation
• dist the transpiled code

and refer to dist/*.js in package.json for the main module. Thus making middlewares ready for async/await while being available for Koa 2.

[matthewmueller]

async/await wouldn't force an additional iteration

yah, the 2nd iteration is certainly optional, but people will probably want to upgrade their middleware again. i guess i just don't see any downside in waiting until async/await.

If we transpile official middleware that's making use of async/await before publishing to NPM, the end user doesn't need to use Babel. Async/await are just handlers of promises. It's about what's used in the official middleware.

just becomes harder to tweak and fix bugs you discover in your node modules, since it's compiled javascript. not as bad as coffeescript's compiled output, but still can be confusing.

---

Personally, I wouldn't mind supporting both promises and generators, but it seemed like folks wanted to support one or the other.

[targos]

To prevent the need of an update when async/await is native and keep backward compatibility, the middlewares could be exported like this (assuming src contains the source and lib the transpiled code):

module.exports = asyncSupported() ? require('./src') : require('./lib');

[tejasmanohar]

+1 for what @targos said

[monder]

-1 on babel forced for everybody.
+1 for releasing v2 with promise based middlewares. Fully agree with @menems .
Most of the middleware do not require processing before and after request at the same time, so the cases as @matthewmueller mentioned are few, and it will be just the replacement of yield* next with return next().
Project based middleware and request handling with Promises looks more structural either starting with

next()
.then(() => {
  // code
}).then(() => {

or ending

}).then(() => {
  // code
}).then(() => {
  return next()
});

[dead-horse]

I'm -1 on change middlewares that use lots of generator functions to promise implementation. Don't want to maintain tow different branches for all the middlewares. Actually our inner web framework are still base on koa 1.x until async/await is native, it is not friendly for koa's users to migrate at this stage.

Maybe we should set the latest tag to 1.x (and all the middlewares support koa@2 too) until we have a conclusion with this issue. IMO we should make sure most of the frequently-used middlewares are default to support koa@2(using async-await with babel or promise implementation) before we finally announce koa@2.

[tj]

Replacing with promise-based ones seems really pointless to me since we'll just be doing it again later, back to the old yield code more or less. I don't see a huge reason to rush 2.0, I'd rather not taint the user experience and confuse people with something that isn't permanent. 2.0 has almost no new features, the reason for the bump was for async/await, so doing a 2.0 without async/await native is a bust IMO

[tejasmanohar]

+1. No point releasing 2.0 w/o async/await _somehow_ (whether that's Babel, native, etc.). IMO- (Native async/await >) Babel async/await > Generators > Promise-based middleware w/o await.

[jonathanong]

yeah latest should be 1.x for a while. i haven't looked at how to publish "latest" on npm yet.

i don't see a rush with converting all the middleware to async/await or promises since you could always just use koa-convert or something. there's been a bunch of PRs but i've been more-or-less "meh" about them. some are fine since you don't NEED async functions to write it, but for others, it's easier to just use koa-convert.

[yanickrochon]

With Koa 1.x, I get things like these

TypeError: You may only yield a function, promise, generator, array, or object, but the following object was passed: "undefined"
      at next (/home/yanick/dev/.../node_modules/koa/node_modules/co/index.js:101:25)
      at onFulfilled (/home/yanick/dev/.../node_modules/koa/node_modules/co/index.js:69:7)
      at process._tickDomainCallback (node.js:411:9)

I roughly have an idea where this is coming from, but it would make my life heck lot easier with a proper stack trace. If async/await doesn't get rid of that issue, screw that AFAIC.

[dead-horse]

I'll set my koa middlewares default to support koa 1.x, and a dist-tag koa2 point to the version that support koa 2.x.

$ npm view koa-bodyparser dist-tags
{ latest: '2.0.1', koa2: '3.0.0' }

Add some notifications in the readme, then change koa's latest tag to 1.x ?

[aheckmann]

doing a 2.0 without async/await native is a bust IMO

Agree.

[tejasmanohar]

Perhaps the middlewares/tooling which have released new versions (koajs/compose, koajs/rewrite, koajs/route) should _unpublish_ the major bumps and republish with an -alpha suffix?

:+1: @omsmith - except _s/unpublish/deprecate_

[mattstyles]

Yeah I'd be happy to republish to try not to confuse the ecosystem

On Sat, Nov 21, 2015 at 5:31 PM, Tejas Manohar [email protected]
wrote:

Perhaps the middlewares/tooling which have released new versions (koajs/compose, koajs/rewrite, koajs/route) should _unpublish_ the major bumps and republish with an -alpha suffix?

:+1: @omsmith - except s/unpublish/deprecate

Reply to this email directly or view it on GitHub:
https://github.com/koajs/koa/issues/533#issuecomment-158663665

[mattstyles]

Although, having said that surely a section at the top of the readme would suffice to explain which version hits which version of Koa

On Sat, Nov 21, 2015 at 5:33 PM, null [email protected] wrote:

Yeah I'd be happy to republish to try not to confuse the ecosystem
On Sat, Nov 21, 2015 at 5:31 PM, Tejas Manohar [email protected]
wrote:

Perhaps the middlewares/tooling which have released new versions (koajs/compose, koajs/rewrite, koajs/route) should _unpublish_ the major bumps and republish with an -alpha suffix?

:+1: @omsmith - except s/unpublish/deprecate

Reply to this email directly or view it on GitHub:
https://github.com/koajs/koa/issues/533#issuecomment-158663665

[tejasmanohar]

No reason to rush this. As @tj said, there are very few _actual improvements_ in Koa v2. If the overall consensus is no Babel for transpiling modules in this org (seems to be), then I vote we

• Pause a Koa@2 release
• Set Koa 1.x version as npm latest everywhere (in all Koajs/* middleware, too)
• Move v2 to a non-master branch and put v1 on master (like Express).
  
  
  
  • This is because _async/await_ is pretty far off from Node... First, it needs to be finalized in the ES2016 spec. Then, implemented in V8. Then... node. Would be surprised if it happened anytime before Q2 2016 (wild guess). Keeping v2 stuff on master for Koa + official middleware is confusing to newcomers, especially since the docs/ don't match up yet (which will obviously have to be fixed before we release v2 as well).
  
  
  • Add a notice to v1/master README about Koa 2
  
  
• Start updating docs/ for Koa 2 on its non-master branch

Side note: I now see the -1 on Babel argument. One of the negative sides of Koa v1 pre-Node@4 was the requirement of using _--harmony_ flags; we were longing for the features required to be in Node stable. Now that they are- if we introduce Babel and jump to async/await early, though we're not playing with as much risk as _--harmony_, it's still an extra step and yet another thing to push people away from using Koa in production. Koa v2 also provides no significant benefit to those who don't use async/await through Babel right now so transpiling doesn't solve much in the big picture.

[navaru]

I've upgraded a few projects from babel 5.x to 6.x mostly for performance issues, for a larger project initial load time took ~12s, not it takes ~4s. From my experience, introducing babel as a dependency is a terrible choice.

As mentioned above _Generators have always been "hacky"_, well babel is a "hacky" choice as well, async/await are implemented using generators, so we only get a nicer syntax by introducing more complexity.

I agree with @tejasmanohar

[magicdawn]

-1 on babel server code.

And I prefer this over ctx. I think we don't need to surrender to the arrow function. I use arrow function in small piece work, like Array.prototype.forEach / map , since it does not provide this binding, and our middlewares are not doing small piece work. So I don't use it in middlewares. that's it.

[tejasmanohar]

On that note, would someone with access to NPM please change @latest to koa v1.x? :)

$ npm -v
3.4.1

$ npm dist-tags ls koa
npm latest: 2.0.0-alpha.3

I've done this with koa-route. Ideally, as @stephenmathieson mentioned in https://github.com/koajs/route/issues/42, you should be able to npm install koa koa-route (same for all other official middleware- I'll have a look through the rest of them I have access to later today).

// cc @jonathanong @tj @fengmk2 @dead-horse @juliangruber (just tagging the most active people from this thread that have access- for some reason, @koajs/owners doesn't work for me- guess only owners can do that.)

[dead-horse]

If we make a conclusion here, I'll make these changes later. any suggestions ?

• [ ] create a branch v2.x from master.
• [ ] set v1.x to default branch.
• [ ] change latest tag in npm point to koa@1
• [ ] make all the middlewares' latest tag support koa@1, and add a tag named koa2 to support koa@2.

[tejasmanohar]

:+1: - thx, @dead-horse

My Votes-

• [x] create a branch v2.x from master.
• [ ] set v1.x to default branch.
• [x] change latest tag in npm point to koa@1
• [x] make all the middlewares' latest tag support koa@1, and add a tag named koa2 to support koa@2.

Additions -

• [x] set v1.x code to master
• [x] make all middleware's master reflect version compatible with koa v1.x

Questions-

1. Why do you prefer setting v1.x to default branch to just moving v1.x code to master? This is nicer, as most people assume master reflects the current stable ("latest") afaik.

UPDATE: I guess ^ is valid if you want to avoid rewriting git history. Yeah... probably best.

Everyone else- please vote :smile:

[fundon]

Or create next tag for koa v2.x on npm.

[yanickrochon]

I wondered the same thing about 2.0 being master.... it should've been a next branch with a 2.0-alpha* tags all along.

[tejasmanohar]

I'm cool w/ next branch

[jedahan]

+1 for master being v1.x right now, next branch being created for v2.x, and using tags for actual version numbers, from either branch.

[tejasmanohar]

thanks for knocking this out, @dead-horse.

next question- should we continue accepting PRs for making official middleware v1 -> v2? I think it's a waste of a release for even the middleware (not sure koa core) until we have async/await. we'll have to update this all again once await is out, document this without await, and manage issues with/without await and for v1 until v2 is released stable and decently adopted. premature, imo.

[yanickrochon]

My take on this is that some middleware can upgrade easily to Koa 2. Some of them do not rely on any asynchronous call, and having them compatible without koa-convert is just fine right now.

No need to wait for async/await if the middleware doesn't even need it. Besides, I personally prefer a Promise implementation as it does not force me to use await all the way down a function stack.

[ljharb]

@yanickrochon Whether you use await or async is irrelevant, since they're just sugar for nested Promise thens and a Promise-returning function, respectively. If you're using Promises, you're compatible with others' use of async/await. If you're using async functions, you're compatible with others' use of Promises. This seems like it's solely a question of whether the project should use babel to transpile a specific kind of syntax sugar for Promises, a decision which has no impact on consumers of the project.

[zackify]

What's the status on koa 2 being stable?

[jonathanong]

it's pretty stable... you're free to use it and report any bugs to us.

we're just not in a rush to release it and update all the middleware until async functions are native in v8

[zackify]

I figured it was. I am using it now with babel, but I'm only using
promises. Think I should go back to 1.x or stay on 2.0?

On Thu, Dec 3, 2015 at 3:01 PM jongleberry [email protected] wrote:

it's pretty stable... you're free to use it and report any bugs to us.

we're just not in a rush to release it until async functions are native in
v8

—
Reply to this email directly or view it on GitHub
https://github.com/koajs/koa/issues/533#issuecomment-161766762.

[jonathanong]

totally up to you :) i'm sticking with 1.x until i have time to update my middleware, though it could be as simple as wrapping every middleware with koa-convert

[mike-marcacci]

For what it's worth I'm using it with async and babel in a live (but only internal) project. Babel's a pain in the ass but if your team is comfortable working with it (ie, it's already part of your front-end development efforts) then you'll be fine on 2.0.

However, if you're looking to introduce these new features to a team that's unfamiliar with the extra step, or if you already depend on a lot of existing koa middleware, I'd recommend sticking to 1.x.

[zackify]

@mike-marcacci I've had zero problems with babel, but that's a discussion for another thread :) the thing we should all worry about is using something that will not actually become a standard.

[mattstyles]

We're using v2 on a number of internal projects and will probably roll it into client work early next year.

They are small services and we have a team used to the Babel transpile step on the client so that awkward step isn't a problem for us. Some of our common modules are already promise based so from that point v2 makes perfect sense for us. 

Haven't encountered any major problems from using it, and it's been very easy for less experienced devs to pick up and help create cracking services which is a nice bonus.

On Thu, Dec 3, 2015 at 8:13 PM, Mike Marcacci [email protected]
wrote:

For what it's worth I'm using it with async and babel in a live (but only internal) project. Babel's a pain in the ass but if your team is comfortable working with it (ie, it's already part of your front-end development efforts) then you'll be fine on 2.0.

However, if you're looking to introduce these new features to a team that's unfamiliar with the extra step, or if you already depend on a lot of existing koa middleware, I'd recommend sticking to 1.x.

Reply to this email directly or view it on GitHub:
https://github.com/koajs/koa/issues/533#issuecomment-161769846

[mike-marcacci]

I wouldn't be too worried about the stability too much here: Koa 2.0-alpha doesn't really bring any feature changes, just interface changes. If another drastic change makes its way into the "production-ready" 2.0 version of Koa, upgrading your app from 2.0-alpha wouldn't be substantially different from upgrading a 1.x app.

[yanickrochon]

I personally find it quite sad that everyone want to stick with yield... oh, sorry, await (i.e. yield wrapped in ES6 syntax). The great advantage of using Promise is that you don't need to specify if a function is async or not; you just return a Promise if it is, or whatever otherwise. I often found myself requiring to make functions async just because, down in my call stack, some function was async... This is totally unnecessary with promises.

A few months ago, I saw a lot of Promise advocates, but they are somehow quiet nowadays.

[ljharb]

@yanickrochon an async function is just one that statically returns a Promise. it's not about "needing" to specify, it's about "getting" to - since everything should return one anyways, to make future sync/async refactors a nonbreaking change.

[mike-marcacci]

Well, I'm not 100% sure I agree with the "everything should be a promise" prescription... but to correct your point @yanickrochon, you don't need to make a function async just because it calls one... an async function simply returns a promise; when you return inside your async function, it resolves the promise with the return value. Functions b and c are equivalent:

async function a() {
    return 'a';
}

async function b() {
    var r = await a();
    return r + 'b';
}

function c() {
    return a().then(function(r) {
        return r + 'b';
    });
}

[yanickrochon]

@mike-marcacci can you call b in a function that is _not_ declared as async? Or is it required to have all the functions in the call stack to be declared as such?

In the case of c, the caller is not required to be async (i.e. it can call c() and simply ignore it's returned value).

[omsmith]

Like he noted, async functions just return promises.

function d() {
  return (Math.random() % 2 ? b : c)().then (r => r + 'c');
}

[mike-marcacci]

Yep - note how a is an async function which is called in regular function c. Each of the 3 functions immediately return a Promise which can be:

• yield'ed to to co or koa
• chained with .then()
• await'ed in an ES2016 async function
• ignored

This is why there's no real need to use babel with koajs 2. In fact, async/await is just syntactic sugar: it introduces very little in terms of language features. It's also important to remember that since this is just sugar, all the old Promise tricks continue to work:

async function d() {

    // these are executed in parallel
    var results = await Promise.all([
        a(),
        b()
    ]);

    return results.map(r => r + 'd');
}

[ljharb]

(JS is single-threaded, nothing is executed in parallel - they're executed concurrently)

For posterity, the above function looks like this in ES6:

function d() {
    return Promise.resolve().then(() => Promise.all([
        a(),
        b()
    ]).then(results => results.map(r => r + 'd'));
}

[yanickrochon]

@mike-marcacci alright, thx for the precision.

[madbence]

@ljharb why is that Promise.resolve() needed in d? to me it seems unnecessary. but there is definitely a missing ) somewhere :wink:

[ljharb]

@madbence it's required so that the a and b invocations happen on the next tick, not the current tick - and so that if they throw exceptions, those exceptions reject the returned Promise rather than causing a synchronous exception to be thrown.

[madbence]

:+1: thanks!

[rsilvestre]

There is some thing I don't understand.

Why we don't use generator anymore in version 2.x ???

Is it possible to have a clear roadmap !!!

[tj]

@rsilvestre generators were/are just a hack, async/await is designed specifically for waiting on promises, so they're the long-term solution which is great, that will help reduce fragmentation in the community as a whole.

[rsilvestre]

@tj thank you for your answer, but I still think a roadmap could be interesting.

[tj]

Agreed! I guess we mostly don't have one because there isn't much of a roadmap, a few small issues and the async/await thing which is the only real big change in 2.x

[greim]

I worry the current plan of action puts a damper on the growth of the Koa community over the next year or two. Somebody will shoehorn shitty "async/await support" into Express or Hapi, people will rally around it because "Koa with its generators is self-admittedly hacky, and they're not adding async/await support for a long time". Koa will then miss the opportunity to be the tool of choice once promises really do start seeping into the roots of the Node.js world.

I personally think Koa should move to 2.x ASAP and start building the community around it. Which yes means publishing transpiled code, but that isn't a bad thing. I'd even go so far as letting 0.12-ers in on the action. It isn't Koa's job to encourage Node users to upgrade their Nodes, after all. Let them continue using --harmony if they want. A Babel transpilation pipeline can then easily be set up to accept async/await code as input, and produce generator-ified code as output, which is what gets published.

If someday native async/await has sufficiently penetrated the planetary install base of Node.js, then all you have to do is modify/drop your transpilation hook.

My two cents anyway :)

[tj]

@greim I think that's totally fine for early adopters that want to use the 2.x alphas, but I wouldn't feel great doing server-side transpilation for the 2.0 personally. I agree it's important to be ready to flick the switch right when that time comes. Open to suggestions there I just think it's really awkward to say 2.0 is ready but you have to transpile it, as a user myself I would be turned off by that.

[mugli]

@tj Why is it bad to transpile code on server-side but not on client-site? I'm asking because I don't see anybody complaining about using Babel on client-side projects, even in libraries.

[greim]

Just to clarify though, whoever owns Koa npm publish rights would be the only ones who would ever actually transpile code. Pre-transpiled code would then ship to npm and people would run it natively without needing babel or having transpilers in their dep tree or anything.

Which if you're targeting 4.x engines, the transpilation could be pretty shallow; mainly just a transform of async/await to some generator-based facsimile, since Babel 6 pipelines can be micro-managed to only change minimal stuff. (It becomes a "cat" operation if you turn everything off.)

Sorry if I'm over-explaining and everyone already knows this. Just wanted to clarify my stance as definitely not requiring _users_ to do transpilations themselves.

[tj]

@mugli it's not bad really, it's just not ideal, especially since the vast majority of node developers don't do this (unless they were using CoffeeScript etc).

@greim developers using Koa for their app would still need to transpile, that's the part I'm not too fond of. I think it's fine for middleware developers or people who want to commit to it at that level. Unfortunately it's a little tricky to figure out how the community would respond, there's just us small minority that chimes in on issues.

[greim]

Strictly speaking devs using Koa don't need to transpile, they just have to return promises. co.wrap() and similar could assist here, or people could chain then()s or whatever. Lots of people (myself included) would opt to transpile their own server-side code, but it seems like no concern of Koa's.

[tj]

For sure, they can do that already without Babel involved at all. I just don't think it's too sane to release the official 2.0 when the UX is worse than 1.x due to using promises (without transpilation involved). Maybe it wouldn't turn people off, it's hard to say. We've already seen people converting middleware to use promises, which is a step backwards, they would be converted yet-again when async/await is native.

[tj]

I guess what I mean is there's no reason to use 2.x unless you want the nicer solution, which is async/await. Without native async/await you don't even get the nice solution, which to me is a regression. Babel mitigates that but transpiling is not an elegant solution for a major bump that is supposed to be nicer than the 1.x releases.

[greim]

I get what you're saying. Koa is wedged in a sort-of not ideal spot I think since there will be an opportunity cost for waiting, because the world has a tendency to move on.

[tj]

Yep! I definitely agree with you there, it's a tricky call. I suppose maybe the ideal case is we have a bit of tooling to convert middleware and apps to async/await on day one. No waiting for people to upgrade manually, just a little GH bot or something.

[Globik]

@ljharb and what, function d returns a result? Say, var a= d(); console.log(a)? Or is it false? Correct is a.then(function(syntaticsugar){just gimme a syntatic sugar!!!!})???

[ljharb]

@Globik function d returns a Promise (like every async function, since that's all its sugar for) - so d().then(value => doSomething(value)) for example, or in another async function, await d() would be sufficient.

[nelix]

Its standard practice when releasing libs that use babel (react components for example) to run babel in prepublish.
Most people don't run babel on node_modules because that would be very slow, and it would also break many libraries (via use strict mostly). It's also a configuration nightmare as many libs have different babel plugin needs.

People using koa 2 would need to transpile, but they can do it via node-babel or require('babel/register'); which is much easier than whats involved with publishing modules that use babel.

Since Koa is basically express with generators, has anyone considered naming koa with async/await something else? Like koa-await, then maybe they can be merged for release 3 when the idea is more stable?

[tejasmanohar]

Since Koa is basically express with generators, has anyone considered naming koa with async/await something else? Like koa-await, then maybe they can be merged for release 3 when the idea is more stable?

I strongly suggest against forking. Koa uses generators for what we desire in async/await. It's hacky. Once async/await is native, I don't think it's much questionable whether we should move Koa to it or not :) - Without async/await, it seems the general consensus is Promise-based Koa is meh.

[tejasmanohar]

People using koa 2 would need to transpile, but they can do it via node-babel or require('babel/register'); which is much easier than whats involved with publishing modules that use babel.

On a side note, this is unrelated to Koa itself, but Babel's been talked about a few times here (especially _how_ to use it). Don't use Babel require hooks in production due to performance (and general reliability issues). It's ok for tests, small scripts, etc., but I'm sure you wouldn't want your production application to waste resources live transpiling the application from ES6+ -> ES5 implementations.

[tejasmanohar]

More on topic, should we close this issue if it's been decided not to transpile and instead, wait on Node.js stable to have async/await to release Koa v2 stable + as npm dist-tag latest. The original question posted by @jonathanong was-

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?

... kinda deviated :P

[mugli]

Yeah, confused here too about what has been decided.

[greim]

Don't use Babel require hooks in production due to performance (and general reliability issues).

What are the performance bottlenecks and reliability issues? Are there benchmarks or is this just speculation? Koa has always been bleeding edge and non-mainstream, so in my view it doesn't make sense to be ultra-conservative.

[mattstyles]

There probably arent any performance bottlenecks since the code that is executing is the same stuff from a build-time transpile, it doesnt matter when the transpile happens, just that it does. Start up times will be slower as the transpile happens then, after that it is cached, and is start-up time super critical? not usually.

Memory is a different story though, babel eats through it.

[ljharb]

The other concern is testing. If you're doing realtime transpilation in production, then you didn't run your tests against the exact code being run in production. It's considered a very poor practice to ship anything except final compiler output to a production environment.

[tejasmanohar]

@mattstyles Yeah, memory is one point- in general it's probably not something to dedicate resources to in production-, but I agree with @ljharb. You should ship final/static code to production, not variable code.

[mattstyles]

Oh yeah, I totally agree, I wasnt saying you should. :+1:

[greim]

You should ship final/static code to production, not variable code.

I actually agree with this, and similarly an npm module should only ship code that runs directly on it's target engine. But that doesn't argue against against using pre-publish or pre-test/deploy transpilation.

[ljharb]

of course. but "pre-publish" should be done by every module, and "pre-test/deploy" should be done on app code (but _never_ inside of node_modules, which should always be a black box)

[yanickrochon]

Exactly. The point is that, Koa should always be published as node-ready, and should _never_ have to install babel as a dependency.

I personally care less about using Babel inside Koa, as long as when I'm doing npm install koa, Babel does not get pulled as well.

Also, all tests should be made against transpiled code, not inside a Babel container. As I wrote a few weeks ago, I did come across a bug in a module, introduced by a transpiler. The module looked fine reading the source code, but the transpiled one had a wrong loop condition (also, that loop was not optimized at all).

[greim]

@ljharb @yanickrochon - Agreed on all points. Koa 2 could ship without itself violating any of those constraints, or transpiling or depending on Babel in any way. The decision to not ship is rather based on the fact that in order to use Koa, you'd have to do one of:

• Transpile your app
• Wrap your middleware in co or similar
• Revert to .then() everywhere

All of which are worse than the current generator-based approach. At least that's the consensus of the thread. Personally I'd rather Koa 2 ship and let _me_ worry about whether transpiling my own code is sub-optimal.

[ljharb]

I don't think that needs to be the case. Whether koa is using async/await or not, async/await is just sugar over nested promise thens. Users of koa will _never_ be either forced to use async/await, nor prevented from using it, as long as babel is run pre-publish. All they have to do is provide a promise-returning function where an async function is expected.

[greim]

All they have to do is provide a promise-returning function where an async function is expected.

But (again speaking for the consensus of the thread, not myself) all of the ways of returning promises suck, except for async/await, which depends on transpilation at the moment, which sucks. So, impasse.

[tj]

Regardless of middleware pre-compiling you'd still need to transpile for your app, or use promises, which is pretty meh compared to just using generators. Like I've said I don't think we need to rush it, you can use the 2.0 alpha's anyway, not like it changes anything by putting a 2.0 label on it. I think that just sets up a whole mess load of issues when we make it official, it has already caused a lot of confusion so I think it would be worth the wait personally.

[yanickrochon]

@greim see, I personally don't mind Promise-based implementations and really don't care for the async/await. I'll use it when it's available and, really, everything will just be compatible anyway, so refactoring code is just for aesthetics. It's all a matter of opinion, and you can't just change the nature of Koa, introducing Babel (which does differ slightly from ES6, too), and force chocke that on other users who do not use it. This is the whole point of this thread.

And @tj is right, even though I'd prefer to have it sooner, and I do appreciate all the efforts some people put to make their middlewares Koa 2.0 compatible, we do not need to rush this. Koa 1.x is just fine still and it is the general consensus to wait for the native implementation of async/await.

I'm just one of those who like C over C++ just as I prefer JavaScript over Babel/CoffeeScript and all those "higher level" JS syntax. And I believe many people in here feel the same way.

[greim]

we do not need to rush this

I somewhat disagree, but I've already beat that horse to death above :)

[iksose]

@mike-marcacci , @mattstyles any chance of a repo or gist of sample usage of babel 6 w/ koa2?

[tejasmanohar]

@iksose haven't touched the project in a bit, but i was using it here

[mike-marcacci]

Hi @iksose, I just went ahead and open sources a spin-off of an internal project where we use Koa 2.0-alpha with babel: AuthX. There's not much in the way of docs but feel free to peruse the source and try it out.

The ES6/7 stuff lives in the src directory and gets compiled into dist by gulp or run directly via server.js.

[mattstyles]

@iksose this is the source file with the async stuff and my build script is in the package.

This example is only one file but its trivial to extend that to many files.

I do almost exactly the same for client JS but use browserify with the babel transform to create a bundle for the browser.

If I want to pre-compile a module then you just add your build script as a pre-publish script (example ) and ignore your built stuff from git and your source stuff from npm using .gitignore and .npmignore.

It's pretty easy to add this in and if you restrict your transforms then the file size change is small, but, it is _another_ step in the process and I can understand why maintainers are steering clear.

[iksose]

thanks for the awesome leads

[jonathanong]

i've upgraded the description for this issue. let me know if you have any questions and be sure to mention me because i always unsubscribe.

also, please don't make new issues about koa v2 unless it's a bug or something. thanks :)

[felixfbecker]

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.

Why this?

[jonathanong]

i should add that it's one way to help migrate, not that it's required.

[timjacobi]

async/await will likely not make it into ES2016

https://twitter.com/bterlson/status/692489384654999552

[tejasmanohar]

sadface :(

this just shows us why the new naming system (es6 -> es2015) is terribly confusing for developers (+ the impact babel had on the community). async/await may very well reach stage 4 though, which seems to mean that at least some engines will implement it (based on this)... whether that'll be behind a flag or not and moreover, considered "stable", that's another question.

still, i don't think we should release koa v2 until async/await (or similar, non-hacky + superior solution) is stable native. anyhow, maybe it'll make the spec for ES2017… :P

[ljharb]

What "makes it" into the publication is irrelevant. Only "stage 4" matters. The instant it hits stage 4, it will have already been shipped in two browsers, and will rapidly be shipped in the rest of the engines.

[tejasmanohar]

@ljharb interesting. by any chance, do you know if v8/node allows "stage 4" features w/o flags (like --harmony) before they're in the publication? if so, awesome! :D

[ljharb]

Absolutely. Stage 3 features tend to get shipped without flags too. Publication doesn't matter.

[jonathanong]

anyone against publishing koa v2 with a next tag? we can move any other breaking changes to v3. we will still maintain v1.x and v2.x.

i've just had a bad experience with other libraries like babel-eslint that used prerelease versions like 5.0.0-alpha10 for a long time.

[tejasmanohar]

@jonathanong personally, i'd like to see some resolution on the following PRs before we release koa v2 w/ the next tag

• https://github.com/koajs/koa/pull/612
• https://github.com/koajs/koa/pull/614
• https://github.com/koajs/koa/pull/605

other than that, no objections

[dead-horse]

@jonathanong we can publish koa@2 without preprelease version, just follow semver, and keep v2 with a next tag? We can both use v1 and v2 with semver range.

[netfishx]

@dead-horse +1

[jonathanong]

yeah we just have to port the latest commits from master to v2.x then we can publish

[PlasmaPower]

@jonathanong but node still doesn't have async/await support builtin right?

[dead-horse]

@PlasmaPower the latest tag is still point at 1.x

[PlasmaPower]

@dead-horse what would be the change when we "publish" then?

[tejasmanohar]

@PlasmaPower we wouldn't write -beta/alpha in the release title. it's "stable" enough. that's the only practical difference, right @jonathanong?

[PlasmaPower]

@tejasmanohar ah, okay. Makes sense.

[jonathanong]

npm install koa would install v1.x and npm outdated wouldn't mark it as outdated. but npm install koa@2 should work

[PlasmaPower]

@llambda yeah, but we were planning to wait for async/await to release 2.0 as default.

[ide]

@jonathanong can I convince you to release Koa 2 before async/await land in Node? At this point the pros are starting to outweigh the cons and the cons are going away.

Pros:

• Development effort gets consolidated on Koa 2, including work by middleware authors
• Koa middleware becomes less fragmented since there is one recommended way to do things
  
  
  
  • Right now several middleware projects need to maintain Koa 1 and Koa 2 versions
  
  
  • Avoid the stagnation & fragmentation of Gulp 3 & 4 for example.
  
  
• Koa 2 is a better way to write code instead of using generators for flow control

Cons:

• If you do want to use async/await, which the docs show, then you need to add a transpilation step to your build pipeline
  
  
  
  • And if you don't have a build pipeline you need to add one (this is the top obstacle in my mind)
  
  

Other thoughts:

• Koa's audience has been early adopters. These are the people using modern JS and Babel and Node 5.
• When Node <N> with async/await support comes out like a year (??) from now, people on any prior version of Node aren't going to be able to use async/await without upgrading anyway
  
  
  
  • Basically, I'm not sure that asking people to upgrade to Node <N> is easier than asking people to use Babel or write Promises
  
  
• Babel 6 is more stable now
• Async functions are at Stage 3 and are used by many people and big projects in production
• Transpilation is optional since you can use Promises directly anyway
• koa-convert makes migration of most middleware quite easy. The migration from Koa 1 -> 2 is good as far as migration paths go.
• Koa 1 is still on npm (obviously). It's still alive and this is about rallying behind Koa 2 and moving forward together.

[PlasmaPower]

@ide A big problem is then the transition will often be generators -> promises -> async/await instead of just generators -> async/await.

[jonathanong]

@ide yep that's the plan but we're not gonna mark is as latest. We just need to finish cherry picking commits from master (see PR)

[jonathanong]

@PlasmaPower I don't see why you would ever actually write anything in promises. You can always use koa-convert or bluebird.coroutine with koa v2 until async/await is in node

[tejasmanohar]

I'm 100% for releasing Koa 2 as stable (no beta flag) but not as npm latest. The real problem with releasing Koa 2 on npm latest (and pointing to it on git master / the default branch) is how confusing getting the serial control flow that was in Koa 1 in Koa 2 because there are simply too many options. Bluebird coroutines, co, async/await via Babel, etc. - just to name a few -, and this causes people who aren't familiar with these tools to say "well, which one should I use?". It's _extremely_ easy to migrate Koa 1 middleware to Koa 2 with async/await where necessary (most work out-of-the-box with koa-convert) but popularizing "handling Promises somehow" in Koa 2 with a bunch of different options is going to make this migration harder when native async/await reaches Node IMO.

[ljharb]

@jonathanong you may not see it, but some do actually prefer Promises to things like async/await - I, for one, would definitely use koa2 with normal promises.

[tejasmanohar]

@ljharb Just curious- why? In parallel to the middleware stack, Koa 1's most prominent feature was readability gained by the "serial" control flow w/ co.

[ljharb]

@tejasmanohar i like async function but await only works for serial code, and most of my promise chains aren't a.then(b).then(c), they involve more Promise.alls and more parallelization. plus i abhor try/catch.

[PlasmaPower]

@ljharb There's always let [a, b] = await Promise.all([a, b]). Also, even if you aren't using async for your main function, it can often be useful deeper in the chain where there is less branching.

[fl0w]

Isnt await* equivalent to Promise.all?

[ljharb]

@fl0w that was never part of the official proposal and isn't supported by babel latest anymore.

[PlasmaPower]

@fl0w I'm not sure that's supported by much.

[PlasmaPower]

yield* was there because it made sense if you were actually outputting values, that doesn't make very much sense for promises especially given that Promise.all exists.

[ljharb]

@PlasmaPower it's subjective. personally i don't like it. the real question is, how many people will a) want to use koa 2, b) want to use async/await, and c) not want a build process in 2016, when literally everything has a build process already? i think the answer is, incredibly few.

[fl0w]

@ljharb, @PlasmaPower: understood.

I remember when koa released while generators only ran on 0.11 (unstable), behind a flag. I've always associated koa with edge, so releasing koa@2 as stable feels natural as a consumer.

[ronkorving]

@ljharb You just described me. We exist :)

[tejasmanohar]

i like async function but await only works for serial code

I find myself doing await Promise.all([...]) quite often :)

[felixfbecker]

@tejasmanohar

i like async function but await only works for serial code

I find myself doing await Promise.all([...]) quite often :)

Especially with destructuring.

const [result1, result2] = await Promise.all([getResult(1), getResult(2)])

[tejasmanohar]

How complex would it be to make Koa 2 backwards compatible and output warnings when generators are used?

@timjacobi I can't personally suggest going down that path. Allowing various input types (generators, Promise-returning functions, etc.) increases complexity, and IMO that outlook holds the project back from other potentially breaking changes like passing ctx around as arguments in Koa v2.

UPDATE: Nevermind. Looks like the OP's comment was removed. ¯_(ツ)_/¯

[timjacobi]

Yeah, realised that wasn't really feasible after having a closer look.

[PlasmaPower]

Couldn't it be done with minimal effort in koa-compose? We could even add koa-convert as an optional dependency if we want. I'm not sure that this is a good idea in the long run, but it would help smooth the transition. Maybe make koa-convert an optional dependency, and deprecate generators?

[PlasmaPower]

When I mean optional dependency, I mean don't require it until it is needed, and output an error if it doesn't exist. That might mess up deployments though. Given that koa-convert isn't that large, maybe we should just put it as a dependency, if we go down this route.

[fl0w]

This would be pleasant, e.g: Convert all generator functions by default using koa-convert and deprecate warn for generators. Step 2 would be to remove support generator functions all together.

Edit; rephrased

[PlasmaPower]

@fl0w you can do let middleware = middleware.constructor.name === 'GeneratorFunction' ? convert(middleware) : middleware.

[fl0w]

@PlasmaPower how would you feel then to add that as a dependency to koa@2, but with an added deprecation warning to koa-convert? (I think this is what your previous comment suggested, I guess this summarises it).

This would allow for a koa@2 release, without leaving ecosystem behind. Though removing koa-convert dependency (generator support) would require a semver-major bump. Thus koa@2 would mainy be a warm-up version for an eventual koa@3 which could be planned to release once async/await is fully available.

[PlasmaPower]

@fl0w Sounds good to me! koa-convert is very small anyway. I can make a PR in a couple hours and then we can further the discussion there.

[PlasmaPower]

Are you proposing the deprecation notice be builtin to koa-convert or koa-compose? I was assuming the latter, since if koa-convert is used manually then it's more obvious that it's deprecated in the code.

[fl0w]

@PlasmaPower aye, I was about to do a PR for convert and realised this as well.

[fl0w]

@PlasmaPower what if there was a deprecation warning on Application.use instead?

Essentially switching out application.js#L103 with said suggested line wrapped in a util.deprecated?

Edit I'm new so I might be missing something fundamental here ..
Edit 2 PR inc. to illustrate

[tejasmanohar]

@ScottKaye that's windows-only. plus, even with CI, using a different JS implementation in development and production server-side is less than ideal IMO.

[ide]

@fl0w's suggestion to use Koa 2 as a stepping stone to Koa 3 could be a good idea. React and React Router take a similar approach where v{n+1} deprecates, but does not remove, features in v{n}, and then removes those features in v{n+2}. So the workflow is: upgrade from v{n} to v{n+1}, fix all the deprecation warnings, and then in the future when v{n+2} is released, you should be able to do so easily.

[ghost]

Here we are, still no stage-4 eh?

[ljharb]

@hyperbrave this week's TC39 meeting isn't complete yet. Have patience, young padowan

[chovy]

Is there any documentation on using babel with koa2 and how to deploy to production?

[ScottKaye]

@chovy I'm not sure about official documentation, but it can work on regular node using babel-register and babel-polyfill. Here's a simple application that showcases this. Run node dev in dev, and webpack && node bin/prod in production.

[mapmeld]

@chovy I'm putting together a wiki guide to creating a Koa + Mongo + Passport server. This page covers Koa v2 and BabelJS to support async and await

[jonathanong]

@chovy i personally use babel-register everywhere but production, then just babel all my files on postinstall in production. this way, all of babel isn't require()ed in production. i've found that using babel-register in production unnecessarily increases memory usage and slows down boot up time

[chovy]

Is there an example of a postinstall babification for production use?

edit: for anyone else interested I found this which looks to be exactly what I'm looking for:
https://github.com/babel/example-node-server

[iliakan]

Why is using yield* considered bad? We can refactor it to async/await as easy as yield.

[tejasmanohar]

seems fine to me. yield* [...] becomes await Promise.all([...])

[sibelius]

@chovy you could take a look on this repo - https://github.com/sibeliusseraphini/koa-passport-mongoose-graphql

[eonezhang]

how about the performance of using babel.

[ljharb]

@eonezhang new syntax is always slower than old syntax (or at best, the same), because it hasn't had time to be optimized. babel performance is likely to be much faster than native.

[ghost]

I have a really newbie question.
I don't know if this is the right place to ask this, if it isn't please apologize me.

In short, when should I use async middleware. What is the difference between this:

app.use(async (ctx, next) => {
  // do something
  await next();
  // maybe do something more
});

and this:

app.use((ctx, next) => {
  // do something
  next();
  // maybe do something more
});

[PlasmaPower]

@vtfn the second one wouldn't work if next() needs to modify the response or if you need to modify the response synchronously, you'd need to do return next(); or if you wanted to do something more return next().then(...).

[ghost]

@PlasmaPower Sorry, could you please give me an example?
Or just tell me this. Would I have some kind of trouble by always using the async/await version? Would, in some case, one be better then the other?

[marvinhagemeister]

@vtfn No, it has nothing to do with being better or not. It is about synchronous vs asynchronous basically. The await keyword makes sure that the code after that won't be executed until the awaited function has finished. Always using awaitwould not make sense.

[ghost]

Ok, I think I understand it now. Thanks @PlasmaPower and @marvinhagemeister.
I was also afraid that with some of the aproches the thread could block, but it not seens to be the the case.

[EvanCarroll]

As an update: here is the link that tests whether ESNEXT features in Chrome Canary (an indicator of what is to come for Node, and more that ES7 draft from February 2016 has landed in V8 though it doesn't seem to have async/await,

The V8 team is already working to bring upcoming features such as async / await keywords, Object.prototype.values() / Object.prototype.entries(), String.prototype.padStart() / String.prototype.padEnd() and RegExp lookbehind to the runtime. Check back for more updates on our ESnext implementation progress and performance optimizations for existing ES6 and ES7 features.

Seems we're getting close though.

[jonathanong]

https://news.ycombinator.com/item?id=11710613
https://chromium.googlesource.com/v8/v8.git/+/d08c0304c5779223d6c468373af4815ec3ccdb84

[alexander-shestmintsev]

Waiting for node.js@7 with async/await support

[idchlife]

If I'm not mistaken node 7 with async/await will be available in October, 2016

[dominhhai]

@idchlife where did you find this info?

[mistadikay]

@dominhhai https://github.com/nodejs/LTS + https://news.ycombinator.com/item?id=11710613

[idchlife]

@dominhhai - mistadikay was first. Exactly. Lts roadmap

[idchlife]

Guys, may I ask, why the all hype about async/await and why there is such need to move to it from generators? Are generators that bad in speed and memory consumption?

[fl0w]

@idchlife the bet is that it becomes the idiomatic syntax for handling async responses.

As far as performance, we'll have to see I guess as it's not yet implemented in v8. My understanding was that generators was leading up to an async/await implementation thus I would assume generators is the underlaying tech anyway - but I could be wrong (my C++ aren't strong enough). The implementation started here.

[therealkenc]

async/await is already in node-chakracore, which has been available since January 2016. You can also use traceur/babel/typescript to get async/await in vanilla nodejs 4/5/6.

Like @jonathanong said Koa isn't declaring v2 stable until after async/await hits vanilla node 7. But that doesn't stop you from using it now. The reason this has taken so long is that the standards committee people, if asked to make a cheese sandwich, would spend six months arguing over the definition of 'cow'. Google delayed implementing async/await because the standards people were still haggling over generators edge cases no one except for them care about. Someone actually implemented node async/yield in 2013. You can track the chrome async/await implementation at issue 4483, which will eventually find its way into node.

[ljharb]

@therealkenc that's both untrue and unfair. The edge cases always matter, and there's far more reasons that the implementations and the standardization of async/await were delayed.

Your analogy is apt, though, because there are many kinds of cheese, and only one comes from a cow. Imperfect specs kill features.

[EvanCarroll]

node-chakracore isn't Node. They submitted a pull request to node. It was denied. Chakra doesn't even run on Linux yet. It's not cross platform. And, when it is cross-platform it won't have JIT. source. They pull from node that is all (afaik).

[EvanCarroll]

There is a bug in nodejs (the project is on github) that tracks v8 progress, tagging that for github reasons..

https://github.com/nodejs/promises/issues/4

[DJviolin]

Can you provide an example how to setup Babel for Koa? I never used Babel before and I try to shift from Express to Koa.

In my package.json:

  "dependencies": {
    "koa": ">= 2.0.0",
    "babel-core": ">= 6.10.4",
    "babel-register": ">= 6.9.0",
    "babel-plugin-transform-async-to-generator": ">= 6.8.0"
  },

start.js

// start.js
require('babel-core').transform('code', {
  plugins: ['transform-async-to-generator']
});

require('./app.js');

app.js

'use strict';

const Koa = require('koa');
const app = new Koa();

// x-response-time

app.use(async function (ctx, next) {
  const start = new Date();
  await next();
  const ms = new Date() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

// logger

app.use(async function (ctx, next) {
  const start = new Date();
  await next();
  const ms = new Date() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}`);
});

// response

app.use(ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000);

I'm getting the following error message:

$ npm run koa

> [email protected] koa C:\...\app
> node --harmony --trace-deprecation --trace-sync-io ./start

C:\...\app\app.js:8
app.use(async function (ctx, next) {
        ^^^^^
SyntaxError: missing ) after argument list
    at Object.exports.runInThisContext (vm.js:76:16)
    at Module._compile (module.js:513:28)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)
    at Module.require (module.js:468:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (C:\...\app\start.js:6:1)
    at Module._compile (module.js:541:32)

Also, with this Babel plugin (transform-async-to-generator), only my async/await code will be transformed back to legacy JS, or any ES5/6 code, that already implemented into Node v6.3.0?

Thank You for your help!

[mapmeld]

@DJviolin I recommend the setup in my demo repo, 1batch

You don't mention having a .babelrc file. This lets BabelJS know what kind of code to expect. It might look like this:

{
  "env": {
    "development": {
      "presets": ["es2015-node5"],
      "plugins": ["transform-async-to-generator"]
    }
  }
}

The only other BabelJS module that I install is babel-preset-es2015-node5

[DJviolin]

@mapmeld Thank You! It' solved by placing a .babelrc file into my /app dir with:

{
  "presets": ["node6"],
  "plugins": ["transform-async-to-generator"]
}

In the past I tried .babelrc, but looks like it didn't worked because I placed in the root / folder.

I also had to re-write start.js like this:

require('babel-register');
require('./app.js');

I also installed babel-preset-node6 which I think more suited for Node v6.

With this setup, only the async/await functions fill be transformed back to legacy JS, or any other ES5/6 features, like arrow functions, etc.? Since I'm using Node v6.3.0, I want the already supported ECMAscript functions natively compiled.

[purezen]

Ditto!

Using a similar setup. I am also eliminating .babelrc using,

require('babel-register')({
  presets: ['es2015-node5', 'stage-3']
})
require('./server.js')

[EvanCarroll]

Guys, come on. This is totally of topic. This is about the release of Koa v2. Not how to configure Babel for Koa v2. There are a hundred ways you could about getting/sharing that information, start with Stack Overflow or a separate bug report for docs. We have 58 people following this issue that are just concerned with the release of Koa v2, and the status of async/await in Node.

[callumlocke]

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 think you might have chosen the worse of two evils here. Letting this project exist in a confusing state for months, during which time it requires constant diligence (to check you're not reading the wrong branch of documentation or installing the wrong version of a plugin), is a worse developer experience in my opinion, and is generating permanent baggage. I might be wrong, but I would guess that the Koa project would be stronger in the long term if it refocused its pitch now: deprecate v1 to shut down the constant source of confusion and gotchas (accepting that this temporarily limits the potential market to those devs who are comfortable with build systems). Then take advantage of the inevitable surge in interest when async/await hits Node stable and everyone's looking for clearly pitched tools that take advantage of it.

[DJviolin]

@EvanCarroll StackOverflow Koa community is basically dead.

389 questions vs 24553 questions.

I think an unified documentation (with the most popular middlewares, even if they maintained by outsiders!) will help to get some popularity. It should be at least as robust as the Node and Express API documentation. As @callumlocke said, try to find the correct documentation for the correct repo in github wikis is suck! Until than, only those developers interested in Koa who really want to build a fully async app from the ground up. They are not very much. Maybe you have to "re-invent the wheel" every time with Express, but at least those wheels are very well documented.

[EvanCarroll]

@DJviolin it's not dead because it has fewer questions than Express. It does massively less than express and it's a newer framework. It clearly has less adoption too. Regardless of your silly definition of "dead" this isn't the place to ask questions. This is a bug report and questions about Gulp have nothing to do with it. Let's not simply pester a community because people are waiting here for updates. End of story.

[tj]

The number of questions on SO is not a good indicator of the popularity or state of any project IMO.

People are free to use whichever version they're comfortable with, 2.x doesn't make sense "officially" when compilation of SS code is required. If anything we can clarify in the state in the Readme a bit more.

A big reason for not going ahead with 2.x until then is precisely because Babel is really confusing to get started with, especially if you haven't used it on FE codebases. It's the choice between some confusion now for having what is effectively an RC, or having even more confusion from using Babel _and_ forcing people to compile on the server, which many people do not want, myself included.

[fl0w]

@tj To be fair, 2.x only requires compilation if the consumer opts for the sugar (async/await) - that's not a requirement by the library to work. Some simply wants their library to handle "promises natively", and even patch express to work as such - e.g. express-promise or express-promise-router.

What's your take on having 2.x being a promise-oriented solution (which also supports deprecated generator based middleware), and 3.x intended for use with async/await (with deprecated middleware removed)?

Edit changed a word s/framework/library.

[chovy]

I'm waiting for async/await support. I heard node/v8 will have it in October.

[dead-horse]

What's your take on having 2.x being a promise-oriented solution (which also supports deprecated generator based middleware)

I don't think this isn't what we want. We migrate to v2.x for _asyn await_, and I think we should not recommend people to use koa as a promise-oriented solution, which lose lots of readability. Before async await being native in node, generator based middleware is still the best choice for now(shouldn't warning people it is deprecated).

[magicdawn]

co.wrap acts almost same to async, so:

• if you think it's ok to use babel, just use it
• if you don't wanna compile server code, just use co.wrap / bluebird.coroutine ...

i.e: I add impress-router@next to support koa@next with co.wrap

[rattrayalex]

There's going to be a lot of excitement in the community when async/await hits. It may be the biggest thing to happen to server-side JavaScript since the merger of iojs and the node foundation.

The degree to which koa captures this excitement is likely to be dictated by the level of preparation within the koa community. Potential new adopters will want to see a wide array of battle-tested libraries that have already been working with async/await in production for a while.

If koa doesn't capture this momentum, I personally would be very concerned about a Python 2 / Python 3 situation, where most people stay on express even though koa is clearly better. Let alone the version split pain within the koa world itself.

Please take my thoughts with a grain of salt, as I don't currently have the good fortune of being able to write backend JavaScript professionally. I'm hoping against hope that the node world rallies around terrific paradigms and technologies (eg, koa with async/await) so that it makes more and more business sense to switch from Ruby/Python/etc to Node.

[rattrayalex]

@tj your concerns about confusion and compilation make a lot of sense.

Would you be open to a PR that:

1. Turns the readme into a concise rundown of the difference between versions 1 and 2, with prominent links to the documentation for each, and a clear how-to for setting up server-side babel and a word on the caveats.
2. Encourages package maintainers to support v2
3. Clarifies that 1.x series will continue to be supported until after async/await is released.
4. Sets a tentative "major version bump" date (eg; Sept 1). If uptake of v2 and a/a goes smoothly, the default version can become v2. Since it's a major bump, nobody should be adversely affected or forced to use compilation. The official momentum should help the community rally & prepare.

Needless to say, I would work with you on the specifics 😁

EDIT: I meant docs/website, not readme.

[yanickrochon]

I, for one, have personally manifested in interest in programming with promises and don't mind at all what others call "mess". I believe that I am not the only one. Waiting for async/await is fine, but Koa 2 is alright at the moment, and middleware maintainers can just refactor to be compliant. Once async/await is fully integrated into Node without requiring compilation, refactoring from Promise (or co.wrap, etc.) to async/await is quite trivial, if not required at all!

My 2 cents.

[tj]

@rattrayalex sounds great to me! My main issue is that I think we _really_ need the async/await syntax, otherwise people will start writing middleware with promises directly which to me is a step backwards I think in non-trivial cases. That said I saw the V8 news as well so it shouldn't be too far off! Especially now that Node is moving at a faster pace.

[rattrayalex]

Excellent! Hope to get to work on that soon. Thanks so much @tj !

[wlingke]

I'm a newcomer to Koa and am building a new application in the next couple of months (ie most likely before node releases async/await). Would you recommend using 1.x or 2.0 with promise syntax? It sounds like using babel to transpile async/await is very buggy. Which would be easiest for converting my application over to await/async when it becomes available?

[chanlito]

Been using koa with babel, all running fine. No point using koa1

On Aug 2, 2016 7:38 AM, "Lingke Wang" [email protected] wrote:

I'm a newcomer to Koa and am building a new application in the next couple
of months (ie most likely before node releases async/await). Would you
recommend using 1.x or 2.0 with promise syntax? It sounds like using babel
to transpile async/await is very buggy. Which would be easiest for
converting my application over to await/async when it becomes available?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/koajs/koa/issues/533#issuecomment-236754598, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AO8QO1G7jJ2NBp21HoLaUWLLX1z4htTYks5qbpGYgaJpZM4GP5wF
.

[ranisalt]

If anyone wants to write benchmarks for Koa 2, you can use my package sandra, it is promise-only and very clean as you can see here :) I'd happily help anytime.

[HriBB]

Is it possible to detect koa version from the running app?

[dominhhai]

@HriBB you can get from package.json

[slaskis]

Anyone tried async-to-gen?

With that instead of babel getting started with koa 2 can be as easy as:

{
  "name": "koa-example",
  "version": "2.0.0",
  "scripts": {
    "start": "node -r async-to-gen/register server.js"
  },
  "dependencies": {
    "async-to-gen": "^1.0.5",
    "koa": "next"
  }
}

Sure, it only provides the async part but a lot of the other es6+ features are already in node so...

[PlasmaPower]

@slaskis At that point I don't see an advantage over babel.

[slaskis]

The advantage I see is that it's way faster and easier to get going, with much less configuration and thus potentially less "scary" for new users.

[wlingke]

I've just been using babel-node. This is okay even in production for small/medium apps from what I have read and what others have tried.

[rattrayalex]

Hmm, that looks quite interesting. Though I imagine most people would want to use it by putting

require('async-to-gen/register')

at the top of their files.

Seems simpler than doing the same with babel and multiple plugins. Also claims to be faster.

[ilkkao]

The current plan is that node v7 will ship with V8 5.4 (There's a node PR already open that will integrate an early version of V8 5.4 branch to node master.)

At least in the current V8 5.4 branch, --harmony flag is needed to use the native async/await. As mentioned in previous comments that's not optimal for Koa. I'm wondering if any of these other options realistic?

1) Ask V8 people to ship async/await enabled by default in V5.4.
2) Ask Node.js people to patch V8 to have async/await enabled by default.
3) Wait 6 months for node v8 and hope V8 has enabled async/await at that time

My own thoughts:

1) Very likely can't be influenced.
2) I think node has a policy not to modify V8 feature configuration, for good reasons.
3) Many, including me, have waited this for a long time. Waiting another 6 or 12 months is not so nice.

Koa documentation already says "To use Koa with 0.11.x you must use the --harmony or --harmony-generators flag.". Maybe the least bad option still is to change that to: "To use Koa 2.0 you must use node v7 and the --harmony flag"

[rattrayalex]

@ilkkao appears to be referring to https://github.com/nodejs/node/pull/8317
(just wanted to include it for ease of reference)

[fl0w]

Koa 0.x was released with --harmony requirements back in the day.

I don't see the problem of just having Koa 2 under npm i koa@next until node (probably v8) releases with async/await out of the box.

[felixfbecker]

I would vote for requiring --harmony in Node 7. I mean, no user is forced to upgrade to Koa 2.

[aheckmann]

If Node 7 includes a version of V8 which has async/await behind a flag,
releasing Koa 2 with a Node 7 + --harmony requirement sounds like a good
path forward. However, I think it should not be released as "latest" on npm
until the --harmony requirement is removed from V8.

On Mon, Aug 29, 2016, 7:31 AM Felix Becker [email protected] wrote:

I would vote for requiring --harmony in Node 7. I mean, no user is forced
to upgrade to Koa 2.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/koajs/koa/issues/533#issuecomment-243141048, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAKLstU4VzM5Ov_DVhkr8O0zGEXeWjvhks5qku0ngaJpZM4GP5wF
.

[ljharb]

--harmony was a horrible idea then, and would be a horrible idea now. https://github.com/koajs/koa/issues/533#issuecomment-243146037, at the least, stems the bleeding somewhat.

[EvanCarroll]

I'm for dropping it as official (removing _alpha) when --harmony is available. At that point, I wouldn't have a problem talking about a fall-back to gulp/babel in the docs if you were averse to --harmony. Quite frankly, if you're not using the newest stable version of node, this project has never yet been for you. And, if you are there is no reason /not/ to use harmony and enable those features. I remember doing it for generators. There was no problem back then with it.

[EduardoRFS]

Targos, is working on Node V8 5.4 https://github.com/targos/node/tree/v8-5.4
I'm using and is "perfect" to use in Koa, async await behind --harmony

[chovy]

--harmony is fine imo, that's what its there for -- for cases like this. Obviously we'd all want everything in stable, but its either wait another year or hopefully in October with --harmony

[ljharb]

--harmony is there for people testing for bugs in v8. It's absolutely not there for people to use features in production before they are ready. If it was production-ready, it wouldn't be behind a flag.

It was never OK to advocate using --harmony in production - it caused immeasurable harm to the community - and doing it again will be nothing short of a disaster.

[rattrayalex]

@ljharb I find your assertions surprising. Can you provide some links for context?

[fundon]

https://github.com/targos/node/blob/v8-5.4/deps/v8/BUILD.gn#L430

Maybe the flag is --harmony_async_await or --harmony-async-await.

[EvanCarroll]

For summary, we have two options now with the upcoming release Node v7,

1. release and require --harmony until Node v8. Alternatively require build system like Gulp/Babel.
2. wait for a stable release at a much later point in time when --harmony isn't required.

Maybe we should get @tj in on this,

For what it's worth, I plan to start developing with --harmony asap, and will run in production if need be. I'd rather have code future-safe and not bother with babel. I don't believe the async/await part of the spec is that mutable at this point. For instance, the last change was five months ago and it was about debugging the source text for the async function.. Most of the spec is years old.

[ljharb]

@rattrayalex https://nodejs.org/en/docs/es6/ says:

All shipping features, which V8 considers stable, are turned on by default on Node.js and do NOT require any kind of runtime flag.
Staged features, which are almost-completed features that are not considered stable by the V8 team, require a runtime flag: --harmony.
In progress features can be activated individually by their respective harmony flag, although this is highly discouraged unless for testing purposes. Note: these flags are exposed by V8 and will potentially change without any deprecation notice.

This has always been the case, and is not new information.

[tj]

I think going with --harmony is fine personally, I have yet to use a harmony feature that wasn't already pretty stable, plus we can just clearly document that it could potentially be sketchy. That said I think we'll know verrrry quickly if it is going to cause problems or not, it shouldn't be tricky to find out.

Plenty of people used Node itself in production long before 1.0, what really matters is if servers running with this WIP feature are stable (enough) or not. I recall zero problems with generators for Koa 1.x when it was behind --harmony.

Either way, if it's well-documented (or left as alpha), it's up to the developer(s) to decide. I would leave it as alpha/beta personally, that actually represents the state, versioning is not important, what's important is we don't have to use babel!

[felixfbecker]

I would say we do it like NPM and TypeScript and put 1.x under latest and 2.0 under next dist tag

[EduardoRFS]

I'm using targos v8 5.4 on production ten day ago and for me is fine, 70k views per day, with "complex" async await usage. Only fun without babel

[renesamaral]

@EduardoRFS Which version of node.js do you used? I installed the last nightly version of node, v7.0.0-nightly20160831266270e618, and it comes with v8 v5.1.281.81! How can i use the v8 5.4 of targos?

[EduardoRFS]

@renesamaral git clone and build, i have edited a package of nodejs-git from archlinux aur. To make more easy.

[ranisalt]

@EduardoRFS I have interest in that pkgbuild, care to share?

[PlasmaPower]

@ranisalt I think just remove the #branch=5.x from the source line, but I haven't tried building it yet.

[EduardoRFS]

@PlasmaPower @ranisalt just changed the repository and enabled npm compilation https://gist.github.com/EduardoRFS/dcc742d79a1b974171ef526806a0e711

[soft-labs]

@EduardoRFS can you point me to any docs on how to use your pkgbuild file? I'm on OSX and trying to make it work but with no success. Thank you.

[EduardoRFS]

@soft-labs man is just to ArchLinux but essentially is easy to compile, clone targos repo and read https://github.com/nodejs/node/blob/master/BUILDING.md

Native async functions have one problem, performance(2x speed of new Promise and 1/2 speed of Promise.resolve), bluebird not work, AsyncFunction ever use internal PromiseThen function and GlobalPromise(es6 native) and apparently native is just a wrapper to generators, im trying to hack using C++ node addon but no works ;-; addon not give access to v8::internal

[soft-labs]

@EduardoRFS Thks friend. I was able to build it by following the steps on the script by hand. But I had no success to put async / await to work even with --harmony flag on.

[EduardoRFS]

@soft-labs compile this branch https://github.com/targos/node/tree/v8-5.4

[soft-labs]

@EduardoRFS Thanks. Working fine now.

[ilkkao]

Things are progressing nicely. v8-5.4 was merged to node master. Node v7 in late October will have it. Meanwhile async/await has been already enabled by default without any flags in upstream https://codereview.chromium.org/2356943002/

[saadq]

So just for clarification, is async/await going to be under a flag in Node v7 or not?

[fl0w]

@saadq no Promises yet _(pun intended)_.

[EduardoRFS]

@saadq yep, in node 7 async/await is under flag(--harmony-async-await), node 7 is v8 5.4, probably in node 8 or a minor update. Only a miracle(or cherry pick), make async await run without flag in node 7

[gerardmrk]

Async await is out babyyy!
https://twitter.com/malyw/status/780453672153124864

[ruimarinho]

It works great on the nightlies (it will still require --harmony or --harmony_async_await on the stable version).

One thing that set me off is that [email protected] is from March, while [email protected] (@next) is from September. I think that [email protected] should be unpublished to avoid confusion.

[ljharb]

It could be deprecated, but thankfully you can't unpublish things anymore.

[ruimarinho]

If anyone wants to give this a try and is using docker, we've put some node v7 (nightly) alpine-based docker images at seegno/node for testing (e.g. seegno/node:7).

[ShimShamSam]

With V8 now supporting async/await, if you use the Node nightly build (v7.x) with the --harmony flag, you don't have to transpile your server code.

[pesho]

Regarding the --harmony flag, I was just bitten by this V8 bug: https://bugs.chromium.org/p/v8/issues/detail?id=5322 - which affects Node 6.x only when started with --harmony.

Until a few hours ago I was in the camp that thought --harmony is fine for the Koa 2.0 release. Now I'm not so sure.

[ljharb]

The harmony flag's all fun and games until somebody gets a silent runtime bug

[iyobo]

Well....someone has to use it otherwise how do we know the bugs that need to be fixed to get it to full release mode?

--harmony onwards folks :D

[EduardoRFS]

@pesho if use only --harmony-async-await is fine no? Guys async / await is not more on flag in chrome canary, see changes in v8 code and if no have changes on async / await area, the current version in node 7 is stable

[fl0w]

@EduardoRFS that's looking at things simplistically. There might be other parts of v8 source code that's indirectly affecting how async/await works, I think what you said is wrong and misleading.

However, there's talk about perhaps bumping node v7 from v8 5.4 (--harmony-async-await) to v8 5.5 (async/await native without flag) when it's due in december, i.e. bumping v8 mid node v7 unstable release (which happened once, if memory serves me right 5.1 to 5.2).

CTC member Targos has (had?) an experimental branch using v8 5.5 and expressed no initial worries about upgrading, though nobody will know for sure until it actually hits the shelves in December.

I think it's unfair to do Koa release comparison between --harmony in node v0.11 and todays situation. This was a different era when node was perhaps a year behind v8 stable (guesstimate). Today, node is chasing edge v8 releases - caution has to be considered, especially when LTS and maintenance is a real concern.

An interesting point; if all goes against everyones wishes/efforts, we won't be seeing async await without a flag until node v8 which is due in april 2017 according to previous timeline.

[EduardoRFS]

@fl0w true, but async functions in v8 is just a wrapper to generators, generators with co is faster than async functions. If generators is fine, async functions too. And generators have years.

On actual node 7.x(with --harmony) this issue not occurred https://bugs.chromium.org/p/v8/issues/detail?id=5322 is fixed on this patch https://codereview.chromium.org/2278413003 and his in node 7

[pesho]

@pesho if use only --harmony-async-await is fine no?

I haven't tried the nightlies, but should be fine. The actual trigger for the bug was --harmony-tailcalls (which is included in --harmony). Besides, the bug should be fixed already in the nightlies' V8.

If Koa 2 is released before async/await is enabled without a flag, we should definitely recommend only --harmony-async-await instead of the more risky --harmony.

[joshmanders]

I talked to @jasnell on twitter regarding this, and he suspects that v7.x release later could have async/await landed if no ABI breakages.

https://twitter.com/jasnell/status/782612553218138112

[EduardoRFS]

@joshmanders but node v7 is already in beta, async/await is landed but with --harmony-async-await flag,

@pesho The actual trigger for the bug was --harmony-tailcalls

This issue is already fixed on node 7. With --harmony, but is really better recommend only --harmony-async-await

[joshmanders]

@EduardoRFS if you read the tweet, you'll see as long as there is no ABI breakage, you can see async/await removed from --harmony flag in a later release. Could be 7.1, could be 7.9 No idea. All I know is we might not have to wait until v8.

[ilkkao]

In any case async/await will be available without a flag in six months or sooner. I'd personally like to see koa to promote async/await immediately when node v7 is released.

[fundon]

https://github.com/pauliusuza/node-v7-async-await-demo

[callumlocke]

Replying to @tj's comment:

People are free to use whichever version they're comfortable with, 2.x doesn't make sense "officially" when compilation of SS code is required. If anything we can clarify in the state in the Readme a bit more.

Awareness of the distinction between Koa v1 and v2 is not the problem. The problem is the painful development experience. Even today I still frequently find myself looking at docs/code for the wrong Koa branch, or the wrong branch of a plugin, or a Stack Overflow answer or blog post about the wrong version.

These problems get worse when you're trying to introduce Koa to a team. Whenever I have to explain anything Koa-related to a new developer, half of what I say seems to be caveats about checking which version a plugin supports. Koa comes across as a minefield.

I understand your misgivings about requiring compilation for the stable branch. I agree that's a bad thing in principle. But it would only be a temporary measure until async/await arrives, and imo the alternative (continuing the painful developer experience, and continuing to generate FUD) is worse in this case.

[DJviolin]

In my upper posts I talked about the lack of comprehensive documentation. In contrast, It's just joy to read the Express API docs. No need for hunting in github wikis (and switching between trees), everything in one place, every scenerio well documented. One of the reasons why people still using Express, not Koa. What worked for Express, even made by the same guy, why not just copy-paste the Express api docs template? The styling, content organization of the Express doc is just so joy to read, nothing can come close, even Go Iris or any Python framework's docs can't offer this visual joy and well organized structure.

Ok, Koa v2 officially not released, so the lack of documentation is not the case (yet). But do it will change on the release date?

Another problem with Koa v2 is that there's no proper plugin support for handlebars with partials, which for me (was) a deal breaker. Of course, that's not Koa team's fault, they won't developing these plugins, because Koa is not a "kitchen sink". Express is a "kitchen sink" and like a fully functional kitchen sink, it has a proper & unified routing documentation.

Now there is Nunjucks, which is similar to Handlebars and the layouts, partials support handled in templates. So the missing Handlebars partial support for Koa v2 is not a miss anymore (not for me, but for other people maybe).

[tj]

It's just a tool, no one is forcing you to adopt it :p, do what you like, if you find the docs inadequate that's understandable but they're only a pull-request away.

The Express docs are only good because of the "sale" to StrongLoop that I got bashed for, so you can thank that for happening I guess haha. The Koa team is tiny, I'm not sure anyone has time to completely rewrite docs, but we're definitely open to contributions!

[danneu]

I agree with @ljharb, who pointed the following comment out to me made by a Chromium developer yesterday:

https://github.com/nodejs/promises/issues/4#issuecomment-254159118

I'm glad to hear so much excitement about async/await. However, Node v7 is based on V8 54, whose async/await implementation has some bugs in it (including a nasty memory leak). I would not recommend using --harmony-async-await in production until upgrading to V8 55; the easiest way to achieve that would be to wait for Node 8. A backport of everything to Node v6 would be non-trivial; there would be a lot of merge conflicts. Until Node 8 comes out, I'd recommend using a transpiler.

It seems best to keep holding out on the Koa 2 stable release.

[nickmccurdy]

I agree with waiting for a stable release, but maybe there could be a beta or RC when Node 7 comes out.

[tj]

We have one :D next: '2.0.0-alpha.7', and anyone interested can already transpile, the arguing here is kind of pointless.

[chovy]

@tj are you saying the 2.0.0-alpha.7 works with the harmony-async-await flag in node 7?
If so then I don't know what we are arguing about either.

[saadq]

Node v7.0.0 released! :o

[motss]

Start upgrading to Node v7.0.0 now~ 😸

[ncwhale]

7.0.0 is here!

[yeliex]

Node 7.0.0 now ~

[chanlito]

Installed 7.0.0

[jonathanong]

I agree with waiting for a stable release, but maybe there could be a beta or RC when Node 7 comes out.

next is already RC :) there's no plans for any other changes

[AntSworD]

waiting for v2.x release..

[nickmccurdy]

@AntSworD Have you tried installing next?

[sulliwane]

Node 7.1.0 is out
but v8 version is not 5.5 yet:

process.versions.v8:
'5.4.500.36'

Maybe more chance with the next version

[fl0w]

@sulliwane a v8 version bump may or may not happen, it all depends on breakage. Compatibility comes first, and by default a v8 bump should (though not exclusively) require a node major semver bump as well. v8 v5.5 is scheduled for release in december.

[marvinhagemeister]

@sulliwane as @fl0w already said. At the time node 7.0.0 was branched, v8 5.5 was not stable.

[ilkkao]

https://github.com/nodejs/node/pull/9618 v8 5.5 may happen soon afterall

[stephank]

So definitely in Node.js 8.x in April, but a backport PR for Node.js 7.x also exists: https://github.com/nodejs/node/pull/11029

Maybe in Node.js 7.5.0? There's currently a proposal PR (without V8 5.5), slated for release February 1st, which is a bit soon: https://github.com/nodejs/node/pull/11062

[pi0]

@stephank It seems we have to wait for another 7.x release. 7.5 was released without that... But nodejs/node#11029 is still open :)

[qoh]

There's a test build of v7.5.0 with V8 5.5 here

https://github.com/nodejs/node/pull/11062#issuecomment-276585315

[saadq]

According to this tweet, v7.6 might have async/await available without a flag :o

[italoacasas]

Hi everyone. I'm going to be releasing Node.js 7.6.0 RC next week, with v8 5.5 (async/await)...

[pe8ter]

Node.js 7.6 is out.

Edit: Blog post.

[arden]

when koa2.0 release?
seems, use async/await in 7.6.0, must be open --harmony also. so disappointed.

[ljharb]

@arden --harmony is absolutely not required; node in v7.6.0 allows async function foo() {} ; foo; to work just fine.

[PlasmaPower]

Sounds like it's time to make v2 default then. Anything else blocking?

[dead-horse]

personally, I tend to

1. Release 2.0.0 in npm officially now, so people can use koa@2 follow the semver.
2. Keep latest tag point to 1.x, because most people will stick on node LTS(6.x) for now.
3. Make 2.x default(master in github and latest in npm) when LTS support async fuction.

[fengmk2]

cc @jonathanong Going to release the 2.0.0 version to npm?

[jaydenseric]

IMHO if the latest is v2.0.0, tag it so. Semver indicates breaking changes just fine and package.json has engines. Anything else punishes up-to-date node users and creates confusion in docs, etc.

[Talento90]

Everyone is waiting for the same! Release the BEAST aka (koa v2.0.0)!

[pesho]

Everyone is waiting for the same! Release the BEAST aka (koa v2.0.0)!

Release the Koaken :octopus:

[hulkish]

i can't await

[DJviolin]

I'm happy if I can use Koa v2 today under the @next flag, have it in the master not changes anything for our projects, just have a good feeling that Koa v2 is "out". We shouldn't expect a full release without an updated documentation, which looks like no one doing at the moment. But at this stage, I compromised myself with the markdown docs in the repo. ctx.state yet alone worth the hassle.

Of course, I'm awaiting too!

[benseitz]

The documentation is automatically imported from the docs in the master branch (except the introduction and the links)

But since on our official homepage the first sentence is

Koa - next generation web framework for node.js

I believe its save to update to Koa 2.0.0. We are the next generation, not the legacy generation :)

[ilkkao]

It also feels that some middleware authors struggle to maintain support for 2.0 as a separate non-default branch. It would simplify things if middlewares could just do a new major release and make 2.0 branch as the default.

[jonathanong]

https://github.com/koajs/koa/commit/6c6aa4dab41bd3d11a62afe5de9fc144f9b2add3 :)