diff --git a/docs/koa-vs-express.md b/docs/koa-vs-express.md new file mode 100644 index 0000000..5b3f8e2 --- /dev/null +++ b/docs/koa-vs-express.md @@ -0,0 +1,128 @@ + +THIS DOCUMENT IS IN PROGRESS. THIS PARAGRAPH SHALL BE REMOVED WHEN THIS DOCUMENT IS DONE. + +TO DO: + +- Remove benchmark from readme + +# Koa vs Express + +## Does Koa replace Express? + + It's more like Connect, but a lot of the Express goodies + were moved to the middleware level in Koa to help form + a stronger foundation. This makes middleware more enjoyable + and less error-prone to write, for the entire stack, not + just the end application code. + + Typically many middleware would + re-implement similar features, or even worse incorrectly implement them, + when features like signed cookie secrets among others are typically application-specific, + not middleware specific. + +## Does Koa replace Connect? + + No, just a different take on similar functionality + now that generators allow us to write code with less + callbacks. Connect is equally capable, and some may still prefer it, + it's up to what you prefer. + +## Why isn't Koa just Express 4.0? + + Koa is a pretty large departure from what people know about Express, + the design is fundamentally much different, so the migration from + Express 3.0 to this Express 4.0 would effectively mean rewriting + the entire application, so we thought it would be more appropriate + to create a new library. + +## Is Koa faster than Express? + + To our amazement, yes, but only if you use [`yield *next`](http://wiki.ecmascript.org/doku.php?id=harmony%3agenerators#delegating_yield). We do not provide examples of using delegated yields as we find it confusing as well as unnecessary for most people. Here are Koa's benchmarks when using delegated yields: + +``` + 1 middleware + 8849.36 + + 5 middleware + 8685.74 + + 10 middleware + 8511.08 + + 15 middleware + 8456.86 + + 20 middleware + 8211.93 + + 30 middleware + 8102.98 + + 50 middleware + 7617.67 + + 100 middleware + 6899.45 +``` + + Here are the benchmarks for Express: + +``` + 1 middleware + 7805.19 + + 5 middleware + 7707.15 + + 10 middleware + 7475.08 + + 15 middleware + 7261.73 + + 20 middleware + 7012.07 + + 30 middleware + 6672.76 + + 50 middleware + 6255.92 + + 100 middleware + 5000.98 +``` + + Also note that Express uses many more middleware than Koa, so these benchmarks are largely in Koa's favor. + +## How is Koa different than Connect/Express? + +### Generated-based control flow + + Thanks to co. + + No callback hell. + + Better error handling through try/catch. + + No need for domains. + +### Koa is barebone + + Unlike both Connect and Express, Koa does not include any middleware. + + Unlike Express, routing is not provided. + + Unlike Express, many convenience utilities are not provided. For example, sending files. + + More modular. + +### Koa relies less middleware + + For example, instead of a "body parsing" middleware, you would instead use a body parsing function. + +### Koa abstracts node's request/response + + Less hackery. + + Proper stream handling.