koa 3.0 roadmap

[dead-horse]

There are lots of PRs are blocked due to breaking change, and maybe it's time to make a plan for koa 3.0 now, if anyone has other suggestion, please post in this issue. :)

• don't set header when respond=false and header sent #1044
• req.origin should display the origin header if it exists, not the current hostname #1008
• Empty response if result is null #998
• Drop special 'back' case from response.redirect? #904
• application: removed koa-convert (v3) #1011

[fl0w]

Is it to early to create a v3 branch? I have some spare time coming up and wouldn’t mind doing some work.

[dead-horse]

All these pending PRs are not so emergency to me, so if anyone has any thoughts or some feature / refactor required, post in the issue to help us decide when to start create v3 branch. :)

[fl0w]

How about officially dropping support for < node.js 8?

[iyuq]

koa-compose could rewrite using async/await

[iyuq]

totally rewrite using TypeScript

[fl0w]

I'm personally against introducing TypeScript, adding external typings should be easy enough for those in need.

[marswong]

How about officially dropping support for < node.js 8?

koa-compose could rewrite using async/await

@fl0w @iyuq according to community practice, engines support should always follow the Node.js release schedule :)

[marswong]

totally rewrite using TypeScript

like what @fl0w said above, just one more thing:
koa is quite vary from egg、express and any other framework. It's just a pure http request middleware close to Node.js as you can see. So we can just feel free to write in pure JavaScript, follow the traditional convention and trust Node.js :)

[jonathanong]

if you have any breaking changes you'd like to introduce, please state them now :)

[fl0w]

Let's announce EOL for Koa v1.

[zhangxiang958]

How about support HTTP/2 ? https://nodejs.org/api/http2.html

[marswong]

@zhangxiang958 koa already support it since 2.3.0, u can simply setup a koa app over HTTP/2 like this:

const fs = require('fs');
const http2 = require('http2');
const Koa = require('koa');

const app = new Koa();

app.use(ctx => {
  ctx.body = 'Hello Koa'; // or any other stream
});

const options = {
  key: fs.readFileSync('xxx.key'),
  cert: fs.readFileSync('xxx.crt'),
};
const server = http2.createSecureServer(options, app.callback());

server.listen(443);

[hiroqn]

How about publish koa and official middleware module under @koajs/ ?

[urugator]

Adjust naming to follow WHATWG URL Standard.
Eg: request.path should be request.pathname etc

[likegun]

I think #1044 has already been solved by this commit

[tiendq]

I think context.res and context.req are not good names and they make people confused with context.response and context.request. Is it better if we can name them behind NodeJS names, so context.res becomes context.serverResponse and context.req becomes context.incomingRequest?

[ng-]

@tiendq I completely agree! I keep mixing up req/request and res/response. I vote for something like

{
req:<koa request>,
res:<koa response>:,
raw:{
   req:<node request>,
   res:<node response>
}}

[damianobarbati]

How to access the http2 stream on ctx object to push assets to client using koa? It this supported right now?

[mike-tobia]

I second @damianobarbati , would be great to get an implementation snippet that displays the compatibility and its usage. For example, would the stream be accessible through ctx.res.stream?

I've been seeing a bit of chatter on HTTP/2 support for Koa - I agree that we don't need to define config just to "enable" out of the box. What we do need however, is an interface to utilize HTTP/2, let's say if the request type is HTTP/2, maybe context could be formed at this stage.

I believe that the moment the Koa community takes a stance on HTTP/2, this would promote its usage for the next generation of servers built using Koa. To me, this is a great step forward.

What I envision, as a mode of compatibility and usage, is to add ctx.stream if the request is in an HTTP/2 context. As a start, we could yield the benefits of pushing from the stream and get a grip on how to manage push streams without ending the connection prematurely.

[tajnymag]

How about publish koa and official middleware module under @koajs/ ?

Why not simply @koa/?

[Hiswe]

Here is my little suggestions

• don't set header when respond=false and header sent #1044 because more and more people are using next/nuxt applications (or maybe not by I am…)
• and as said by @tajnymag a @koa namespace can be useful:
  • @koa/cors is already namespaced
  • it will be clearer what are the official middleware
  • for new adopter, it makes more easy what to safely start with.
    IMO “official” guaranties that it plays nicely with the framework and will be maintained over time
• optional some typescript types if needed as this language is getting more and more traction

[EDIT]

In fact everything's working perfectly.
The application doesn't crash and we have a warn.
Up to us to fix that by sending the headers before next/nuxt rendering.

[fl0w]

Note, I am not privileged to make this decision. This is my personal opinion.

I'd like to chime in that I agree that namespace:ing npm-releases under npm:@koa is a good idea.

One or two caveats thought.

1. Only for packages that reside in github:@koajs
2. Don't namespace Koa core, i.e. npm i koa still resolves as expected.

Bug reports for 3rd party packages often end up in @koajs/koa#issues, which is burdensome for both maintainers and the user. This might clear things up a bit.

I also haven't considered possible implications of moving the packages (e.g. does npm have tooling for moving origins?).

[maticrivo]

+1 on #1044

[mytecor]

Please do normal error handling. The ability to set content type

[catsalive]

+1 on #998

[lagden]

I think superset is bad!
Many projects move to TypeScript and appears a lot of "type issues".

But I agree make a TS version to run on Deno in another repository.

[crazybber]

I think superset is bad!
Many projects move to TypeScript and appears a lot of "type issues".

But I agree make a TS version to run on Deno in another repository.

type issue is one of basic and necessary cost to move to TS, but i think benefit is more than cost especially in code quality.

[codingnan]

how about base on uWebSocket.js. it's so fast.

[LeonnardoVerol]

Definitely #1326

[X-neuron]

How about support HTTP/3 https://nodejs.org/dist/latest-v15.x/docs/api/quic.html

[draconteus]

I'm personally against introducing TypeScript, adding external typings should be easy enough for those in need.

Downside of this that external type declarations can be easily broken or lagging the koa releases.
E.g.: current version of @types/koa at 2.13.1 has breaking typing for context.response.body, no version of 2.12.x was ever released...

[iyobo]

What drew me to koa back then was that it was using generators from the core while others were still using nasty callbacks. Koa was technologically ahead. Now async/await is everywhere, but I stuck with koa because I had already built quite a few frameworks on it... Even though Koa isn't the most economically viable space to invest in right now as far as popularity.

Now I see koa kinda lagging behind in a lot of things. And I believe it's partly because TJ and other OGs have moved on to other things. But that's good for them.

I will say that if koa 3 does not come inbuilt with typescript, that will be the final nail in the coffin for koa for me. That will keep it in the land of hobby/amateur/not-professional-use... Which does none of us koa "investors" any favors. Types are a thing now and are invaluable when working with huge teams, whether anyone likes it or not.

[iyobo]

I think superset is bad!
Many projects move to TypeScript and appears a lot of "type issues".

But I agree make a TS version to run on Deno in another repository.

Type issues can be solved by simply understanding typescript. You can make typescript as strict or as lax as you want. At the end of the day, there is value in even the most lax typescript implementation when it comes to keeping typings automatically up to date.

A TS version can also serve normal JS users as well as TS users, with the TS users getting a better dev experience right out the back. There would be no need to keep 2 versions.

Also not a fan of external typings as they go out of sync.

[lagden]

@iyobo

It doesn't make sense to me!
Won't keep 2 versions.
Will be the another project with same concept.

Deno runs native TS (as another language).
It's much better than "superset project"!

I keep my opinion.

[nickserv]

If we migrate the project to TS, that single version can be used in both TS and JS. I'd personally recommend that based on the future needs of Koa and the community moving toward strong TS support. I can probably help with migration, but I don't think I'd have time to do all of it on my own.

[kubejm]

@nickmccurdy I'd be willing to help if there is desire to migrate. I took at stab at rewriting koa in TS the middle of last year and opened an issue (#1475), but it did not seem pressing to make the transition at the time and was closed. However, if there is renewed interest, then https://github.com/kubejm/koa-ts might be a reasonable jumping off point. It's likely a little stale, because I have not kept up with changes since the issue was closed in June of 2020.

[jimmywarting]

I don't think there is a reason to migrate to TS, jsdoc works just as well with typing support.
My personal experiences working with TypeScript and ESM-only in some projects is a total nightmare with the extensions .ts, .mts, .cts, .mjs, .cjs and no extension at all. Remote path resolver is a total mess when it comes to Typescript when it dose not have direct access to the filesystem

Deno requires explicit path with .ts extension, nodejs don't support .ts extension in relative imports, to make a esm project in node/npm you basically have to add .js even doe there isn't any file with that .js extension it's just a total mess at the moment

TypeScript have never worked in the Browser and it never will. All it is is a uncessary JIT compiler that adds a unnecessary extra step that makes it take longer to load

There is many things Typescript gets wrong, it have no understanding of Symbol.toPrimitive and classes that has things like toString() so most often it complains on things like fetch(new URL(...)) which is totally valid to do, but something TS complains about. I don't think typescript fits in a loosed typed language. It's like trying to put a square into a circle.

It's just lagging behind in many areas so it will always stand in the shadow of javascript, when something new comes out then typescript will take for ages to adapt to new changes. one such recent change is having signal in addEventListener

I have written a vanilla javascript project for both Deno and NodeJS with jsdoc and love and behold you get typing/IDE support from both worlds using npm and http-import using the Deno plugin for vscode and without any d.ts or ts files

Typescript just adds complexity to a project, i have worked with it JS in 12 years, two of those years i have activlly used TS back and forth, i don't think it adds any real marginal productivity, you will spend lots of time just making some simple JS function compliant to the TS rules. I don't think the bug density is lower just b/c you use TypeScript, you just spend it just upfront more early
it also adds lots of wasteful compile time and unnecessary dependencies. Deno stop using Typescript for a couple of reasons which i can only agree upon

Its very much possible to have typing and esm code without using Typescript syntax and having it work for both Deno and Node

One day we could have optional static typing, and when that day comes TS will be totally unnecessary and everyone would refactor back to vanilla javascript

[alanpurple]

@jimmywarting
what on earth does the Browser issue come to server-framework matter?

[jimmywarting]

@alanpurple my point is that TypeScript will never be a first class language in browser or nodejs - https://stackoverflow.com/a/8947021/1008999
it's just one of many languages that needs to compile to javascript.
The idea of having a multiple vms platform support for many languages is not desirable

I just created this page to prove my point that you don't actually need typescript

[draconteus]

I just created this page to prove my point that you don't actually need typescript

@jimmywarting Although there are some valid points in your writing, most of them are just straight bad.
The community needs strong Typescript support, because even if you can do this: 1 + true is vanilla JS, doesn't mean you wanted to do so. Typescript is exactly made for to avoid the bad practices can be done in vanilla JS.

[jimmywarting]

There is a beautie in a dynamic loosed type system too and there is nothing wrong with it that needs to be fixed, there have been one time where i actually wanted to do += boolean instead of += boolean ? 1 : 0

js have very many toPrimitive (or rather webidl conversion) hacks in a lot of the builtin web api's that typescript don't understand, one very common such thing is casting anything to string. anywhere where a web api expect a byteString, number or a boolean there is a webidl converter that is suppose to cast whatever argument you gave it into the correct type.

i don't think the community needs stronger typescript support, i think it needs optional static typing instead builtin instead.

and if you feel so strongly about types (and possible coming from a other typed language) why not just stick to it and compile to WebAssembly instead?

[iyobo]

There is a beautie in a dynamic loosed type system too and there is nothing wrong with it that needs to be fixed, there have been one time where i actually wanted to do += boolean instead of += boolean ? 1 : 0

js have very many toPrimitive (or rather webidl conversion) hacks in a lot of the builtin web api's that typescript don't understand, one very common such thing is casting anything to string. anywhere where a web api expect a byteString, number or a boolean there is a webidl converter that is suppose to cast whatever argument you gave it into the correct type.

i don't think the community needs stronger typescript support, i think it needs optional static typing instead builtin instead.

and if you feel so strongly about types (and possible coming from a other typed language) why not just stick to it and compile to WebAssembly instead?

You do realize Typescript allows for "Optional static typing" right?
Would it not then be best to support Typescript so those who want static typing can use it and the lovers of amorphous blobs can carry on with their implicit anys?

IF you simply must 1 + boolean, then you can @ts-ignore .... hopefully with an explanation comment as to why this bad practice is crucial to the functionality of your application, for the ever-loving sake of whoever is unfortunate enough to inherit the maintenance of said application.

This is about moving Koa forward for all, not an argument of personal preferences and hacks.
I can authoritatively say that very weak typing is also one of the reasons Koa is still a hard sell to enterprise and highly regulated spaces right now.
We cannot continue to remain in the past. Koa needs to mature past these limiting beliefs as quoted above.

BTW: If anyone wants a tool to define Koa endpoints+input validation using Typescript annotations and classes, check out https://www.npmjs.com/package/amala

[jimmywarting]

You do realize Typescript allows for "Optional static typing" right?

optional static typing proposal !== TypeScript

[iyobo]

You do realize Typescript allows for "Optional static typing" right?

optional static typing proposal !== TypeScript

The decision we make about this will determine how attractive the Koa ecosystem will be to end-users.
Particularly enterprise end-users, who tend to bring job listings and financial support to ecosystems they rely on...2 things this community desperately needs.

Typescript will not only allow for what you are proposing, but also open the gates to more serious engagement in this ecosystem by providing end-users with the types they need to enforce their code structure based on their industry compliance needs, etc. Actual Types and Interfaces, not just relying on comment-based intelli-sence that can easily become obsolete and/or wrong.

We have to mature Koa past these personal hack/blob preferences.

[libook]

For me, Typescript is just a tool for ECMAScript. Well, there is not only one tool for such purpose.

Flexibility can be exchanged for team-work efficiency. That is what employers need.
So of course, there should be declaration files for koa; for teams who use Typescript. (There already were.)

But it doesn't mean that koa should be writen with Typescript.
In one hand, koa project don't need to use flexibility to exchange team-work efficiency.
In other hand, there is not enough benefit for the developing work of this project.
In fact, users(who use koa for developing) need not to care about the detial of koa. High quality API and document are enough.
Koa is good, people konw. They don't need Typescript to be the reason.

If koa switch to Typescirpt, there would also be a voice from people who don't want to include Typescript compiler in their projects.

Typescript is not a silver bullet. I don't want to argue much about it. I just share my opinion as a heavy user of koa. And wish we don't spend too much time on this.

[fgarcia]

If koa switch to Typescirpt, there would also be a voice from people who don't want to include Typescript compiler in their projects.

Actually, a Typescript compiler was never necessary to consume Typescript packages. Typescript projects export plain JS along type definition files.

Moving the source code to Typescript should mostly be made if it brings value to the maintainers working on the code, and I do believe Typescript lowers the difficulty for beginners to make code contributions. Also to refactor and clean up code.

Given the low API surface, I would be surprised if a plain Koa user/consumer could gain any benefit beyond what the @types/koa already gives.

Maybe a whole different thing is wanting to send the signal that Typescript is taken seriously. When comparing packages I do favor the ones with clear TS support. Just this month the node-redis package was updated to officially support promises, because you know, callbacks were always enough.

[FossPrime]

I'm personally against introducing TypeScript, adding external typings should be easy enough for those in need.

Middle ground that will probably appease the TypeScript and the anti-bundler crowd...
https://github.com/typicode/lowdb

They build their extremely popular library on pure ES Modules... no bundlers needed... Node LTS as of 16, aka the current LTS release as of two years ago has stable support for ES Modules.

Personally I just want the official typed examples... seriously what's the type of the response object! ... I'm sure I'll figure it out eventually, I may have to read the DT source code. I'm talking about docs like the one pictured below... absolutely no one in 2022 should ever type the word require(

bonus: here's a koa sandbox with Typescript powered by vite... vavite's server side HSR wasn't a thing when I made this. https://stackblitz.com/edit/vitejs-vite-asva6y?file=src/app.ts

Typescript could be one of the ways to really say, we are better than Express. Their upcoming 5.0 version won't be in typescript, but 6.0 is looking positive expressjs/express#4756 (comment)

If I don't see a blue TS logo on the repo, I will immediately think less of the package and look for alternatives.

[rotkiw]

Is this a dead horse? 'cos it looks like a dead horse. 💀 🐴

[imaksp]

Is this a dead horse? 'cos it looks like a dead horse. 💀

It looks like this is not well maintained, for new TS based projects users can consider libs like tinyhttp. but it might be slower than koa, users can also consider hyper express if req/sec is very important.
See this for comparison:
https://web-frameworks-benchmark.netlify.app/result?f=tinyhttp,express,hyper-express,koa

[talentlessguy]

Is this a dead horse? 'cos it looks like a dead horse. 💀

It looks like this is not well maintained, for new TS based projects users can consider libs like tinyhttp. but it might be slower than koa, users can also consider hyper express if req/sec is very important. See this for comparison: https://web-frameworks-benchmark.netlify.app/result?f=tinyhttp,express,hyper-express,koa

huge thanks for spreading the word about the project! Agree on the performance side, but the benefit is better compatibility with middleware / smoother transition from express

[jonathanong]

moving the tracker to here: https://github.com/koajs/koa/issues/new?assignees=&labels=enhancement&projects=&template=---feature-request.md&title=%5Bfeat%5D+DESCRIPTIVE+TITLE