diff options
Diffstat (limited to 'includes/external/school/node_modules/polka/readme.md')
| -rw-r--r-- | includes/external/school/node_modules/polka/readme.md | 643 |
1 files changed, 0 insertions, 643 deletions
diff --git a/includes/external/school/node_modules/polka/readme.md b/includes/external/school/node_modules/polka/readme.md deleted file mode 100644 index 8c137fc..0000000 --- a/includes/external/school/node_modules/polka/readme.md +++ /dev/null @@ -1,643 +0,0 @@ -<div align="center"> - <img src="https://github.com/lukeed/polka/raw/master/polka.png" alt="Polka" width="400" height="300" /> -</div> - -<h1 align="center">Polka</h1> - -<div align="center"> - <a href="https://npmjs.org/package/polka"> - <img src="https://badgen.now.sh/npm/v/polka" alt="version" /> - </a> - <a href="https://travis-ci.org/lukeed/polka"> - <img src="https://badgen.now.sh/travis/lukeed/polka" alt="travis" /> - </a> - <a href="https://codecov.io/gh/lukeed/polka"> - <img src="https://badgen.now.sh/codecov/c/github/lukeed/polka" alt="codecov" /> - </a> - <a href="https://npmjs.org/package/polka"> - <img src="https://badgen.now.sh/npm/dm/polka" alt="downloads" /> - </a> - <a href="https://packagephobia.now.sh/result?p=polka"> - <img src="https://packagephobia.now.sh/badge?p=polka" alt="install size" /> - </a> -</div> - -<div align="center">A micro web server so fast, it'll make you dance! :dancers:</div> - -<br /> - -Polka is an extremely minimal, highly performant Express.js alternative. Yes, you're right, Express is _already_ super fast & not _that_ big :thinking: — but Polka shows that there was (somehow) room for improvement! - -Essentially, Polka is just a [native HTTP server](https://nodejs.org/dist/latest-v9.x/docs/api/http.html#http_class_http_server) with added support for routing, middleware, and sub-applications. That's it! :tada: - -And, of course, in mandatory bullet-point format: - -* 33-50% faster than Express for simple applications -* Middleware support, including Express middleware you already know & love -* Nearly identical application API & route pattern definitions -* ~90 LOC for Polka, 120 including [its router](https://github.com/lukeed/trouter) - - -## Install - -``` -$ npm install --save polka -``` - -## Usage - -```js -const polka = require('polka'); - -function one(req, res, next) { - req.hello = 'world'; - next(); -} - -function two(req, res, next) { - req.foo = '...needs better demo 😔'; - next(); -} - -polka() - .use(one, two) - .get('/users/:id', (req, res) => { - console.log(`~> Hello, ${req.hello}`); - res.end(`User: ${req.params.id}`); - }) - .listen(3000, err => { - if (err) throw err; - console.log(`> Running on localhost:3000`); - }); -``` - -## API - -Polka extends [Trouter](https://github.com/lukeed/trouter) which means it inherits its API, too! - -### polka(options) - -Returns an instance of Polka~! - -#### options.server -Type: `Server`<br> - -A custom, instantiated server that the Polka instance should attach its [`handler`](#handlerreq-res-parsed) to. This is useful if you have initialized a server elsewhere in your application and want Polka to use _it_ instead of creating a new `http.Server`. - -Polka _only_ updates the server when [`polka.listen`](#listen) is called. At this time, Polka will create a [`http.Server`](https://nodejs.org/api/http.html#http_class_http_server) if a server was not already provided via `options.server`. - -> **Important:** The `server` key will be `undefined` until `polka.listen` is invoked, unless a server was provided. - -#### options.onError -Type: `Function` - -A catch-all error handler; executed whenever a middleware throws an error. Change this if you don't like default behavior. - -Its signature is `(err, req, res, next)`, where `err` is the `String` or `Error` thrown by your middleware. - -> **Caution:** Use `next()` to bypass certain errors **at your own risk!** <br>You must be certain that the exception will be handled elsewhere or _can_ be safely ignored. <br>Otherwise your response will never terminate! - -#### options.onNoMatch -Type: `Function` - -A handler when no route definitions were matched. Change this if you don't like default behavior, which sends a `404` status & `Not found` response. - -Its signature is `(req, res)` and requires that you terminate the response. - - -### use(base, ...fn) - -Attach [middleware(s)](#middleware) and/or sub-application(s) to the server. These will execute _before_ your routes' [handlers](#handlers). - -**Important:** If a `base` pathname is provided, all functions within the same `use()` block will _only_ execute when the `req.path` matches the `base` path. - -#### base -Type: `String`<br> -Default: `undefined` - -The base path on which the following middleware(s) or sub-application should be mounted. - -#### fn -Type: `Function|Array` - -You may pass one or more functions at a time. Each function must have the standardized `(req, res, next)` signature. - -You may also pass a sub-application, which _must_ be accompanied by a `base` pathname. - -Please see [`Middleware`](#middleware) and [Express' middleware examples](http://expressjs.com/en/4x/api.html#middleware-callback-function-examples) for more info. - - -### parse(req) - -Returns: `Object` or `undefined` - -As of `v0.5.0`, this is an alias of the [`@polka/url`](/packages/url) module. For nearly all cases, you'll notice no changes. - -But, for whatever reason, you can quickly swap in [`parseurl`](https://github.com/pillarjs/parseurl) again: - -```js -const app = polka(); -app.parse = require('parseurl'); -//=> Done! -``` - -### listen() - -Returns: `Polka` - -Boots (or creates) the underlying [`http.Server`](https://nodejs.org/dist/latest-v9.x/docs/api/http.html#http_class_http_server) for the first time. All arguments are passed to [`server.listen`](https://nodejs.org/dist/latest-v9.x/docs/api/net.html#net_server_listen) directly with no changes. - -As of `v0.5.0`, this method no longer returns a Promise. Instead, the current Polka instance is returned directly, allowing for chained operations. - -```js -// Could not do this before 0.5.0 -const { server, handler } = polka().listen(); - -// Or this! -const app = polka().listen(PORT, onAppStart); - -app.use('users', require('./users')) - .get('/', (req, res) => { - res.end('Pretty cool!'); - }); -``` - -### handler(req, res, parsed) - -The main Polka [`IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage) handler. It receives all requests and tries to match the incoming URL against known routes. - -If the `req.url` is not immediately matched, Polka will look for sub-applications or middleware groups matching the `req.url`'s [`base`](#base) path. If any are found, they are appended to the loop, running _after_ any global middleware. - -> **Note:** Any middleware defined within a sub-application is run _after_ the main app's (aka, global) middleware and _before_ the sub-application's route handler. - -At the end of the loop, if a middleware hasn't yet terminated the response (or thrown an error), the route handler will be executed, if found — otherwise a `(404) Not found` response is returned, configurable via [`options.onNoMatch`](#optionsonnomatch). - -#### req -Type: `IncomingMessage` - -#### res -Type: `ServerResponse` - -#### parsed -Type: `Object` - -Optionally provide a parsed [URL](https://nodejs.org/dist/latest-v9.x/docs/api/url.html#url_class_url) object. Useful if you've already parsed the incoming path. Otherwise, [`app.parse`](#parsereq) (aka [`parseurl`](https://github.com/pillarjs/parseurl)) will run by default. - - -## Routing - -Routes are used to define how an application responds to varying HTTP methods and endpoints. - -> If you're coming from Express, there's nothing new here!<br> However, do check out [Comparisons](#comparisons) for some pattern changes. - -### Basics - -Each route is comprised of a [path pattern](#patterns), a [HTTP method](#methods), and a [handler](#handlers) (aka, what you want to do). - -In code, this looks like: - -```js -app.METHOD(pattern, handler); -``` - -wherein: - -* `app` is an instance of `polka` -* [`METHOD`](#methods) is any valid HTTP/1.1 method, lowercased -* [`pattern`](#patterns) is a routing pattern (string) -* [`handler`](#handlers) is the function to execute when `pattern` is matched - -Also, a single pathname (or `pattern`) may be reused with multiple METHODs. - -The following example demonstrates some simple routes. - -```js -const app = polka(); - -app.get('/', (req, res) => { - res.end('Hello world!'); -}); - -app.get('/users', (req, res) => { - res.end('Get all users!'); -}); - -app.post('/users', (req, res) => { - res.end('Create a new User!'); -}); - -app.put('/users/:id', (req, res) => { - res.end(`Update User with ID of ${req.params.id}`); -}); - -app.delete('/users/:id', (req, res) => { - res.end(`CY@ User ${req.params.id}!`); -}); -``` - -### Patterns - -Unlike the very popular [`path-to-regexp`](https://github.com/pillarjs/path-to-regexp), Polka uses string comparison to locate route matches. While [faster](https://github.com/lukeed/matchit#benchmarks) & more memory efficient, this does also prevent complex pattern matching. - -However, have no fear! :boom: All the basic and most commonly used patterns are supported. You probably only ever used these patterns in the first place. :wink: - -> See [Comparisons](#comparisons) for the list of `RegExp`-based patterns that Polka does not support. - -The supported pattern types are: - -* static (`/users`) -* named parameters (`/users/:id`) -* nested parameters (`/users/:id/books/:title`) -* optional parameters (`/users/:id?/books/:title?`) -* any match / wildcards (`/users/*`) - -### Parameters - -Any named parameters included within your route [`pattern`](#patterns) will be automatically added to your incoming `req` object. All parameters will be found within `req.params` under the same name they were given. - -> **Important:** Your parameter names should be unique, as shared names will overwrite each other! - -```js -app.get('/users/:id/books/:title', (req, res) => { - let { id, title } = req.params; - res.end(`User: ${id} && Book: ${title}`); -}); -``` - -```sh -$ curl /users/123/books/Narnia -#=> User: 123 && Book: Narnia -``` - -### Methods - -Any valid HTTP/1.1 method is supported! However, only the most common methods are used throughout this documentation for demo purposes. - -> **Note:** For a full list of valid METHODs, please see [this list](https://github.com/lukeed/trouter#method). - -### Handlers - -Request handlers accept the incoming [`IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage) and the formulating [`ServerResponse`](https://nodejs.org/dist/latest-v9.x/docs/api/http.html#http_class_http_serverresponse). - -Every route definition must contain a valid `handler` function, or else an error will be thrown at runtime. - -> **Important:** You must _always_ terminate a `ServerResponse`! - -It's a **very good** practice to _always_ terminate your response ([`res.end`](https://nodejs.org/api/http.html#http_request_end_data_encoding_callback)) inside a handler, even if you expect a [middleware](#middleware) to do it for you. In the event a response is/was not terminated, the server will hang & eventually exit with a `TIMEOUT` error. - -> **Note:** This is a native `http` behavior. - -#### Async Handlers - -If using Node 7.4 or later, you may leverage native `async` and `await` syntax! :heart_eyes_cat: - -No special preparation is needed — simply add the appropriate keywords. - -```js -const app = polka(); - -const sleep = ms => new Promise(r => setTimeout(r, ms)); - -async function authenticate(req, res, next) { - let token = req.headers['authorization']; - if (!token) return (res.statusCode=401,res.end('No token!')); - req.user = await Users.find(token); // <== fake - next(); // done, woot! -} - -app - .use(authenticate) - .get('/', async (req, res) => { - // log middleware's findings - console.log('~> current user', req.user); - // force sleep, because we can~! - await sleep(500); - // send greeting - res.end(`Hello, ${req.user.name}`); - }); -``` - - -## Middleware - -Middleware are functions that run in between (hence "middle") receiving the request & executing your route's [`handler`](#handlers) response. - -> Coming from Express? Use any middleware you already know & love! :tada: - -The middleware signature receives the request (`req`), the response (`res`), and a callback (`next`). - -These can apply mutations to the `req` and `res` objects, and unlike Express, have access to `req.params`, `req.path`, `req.search`, and `req.query`! - -Most importantly, a middleware ***must*** either call `next()` or terminate the response (`res.end`). Failure to do this will result in a never-ending response, which will eventually crash the `http.Server`. - -```js -// Log every request -function logger(req, res, next) { - console.log(`~> Received ${req.method} on ${req.url}`); - next(); // move on -} - -function authorize(req, res, next) { - // mutate req; available later - req.token = req.headers['authorization']; - req.token ? next() : ((res.statusCode=401) && res.end('No token!')); -} - -polka().use(logger, authorize).get('*', (req, res) => { - console.log(`~> user token: ${req.token}`); - res.end('Hello, valid user'); -}); -``` - -```sh -$ curl / -# ~> Received GET on / -#=> (401) No token! - -$ curl -H "authorization: secret" /foobar -# ~> Received GET on /foobar -# ~> user token: secret -#=> (200) Hello, valid user -``` - -### Middleware Sequence - -In Polka, middleware functions are organized into tiers. - -Unlike Express, Polka middleware are tiered into "global", "filtered", and "route-specific" groups. - -* Global middleware are defined via `.use('/', ...fn)` or `.use(...fn)`, which are synonymous.<br>_Because_ every request's `pathname` begins with a `/`, this tier is always triggered. - -* Sub-group or "filtered" middleware are defined with a base `pathname` that's more specific than `'/'`. For example, defining `.use('/users', ...fn)` will run on any `/users/**/*` request.<br>These functions will execute _after_ "global" middleware but before the route-specific handler. - -* Route handlers match specific paths and execute last in the chain. They must also match the `method` action. - -Once the chain of middleware handler(s) has been composed, Polka will iterate through them sequentially until all functions have run, until a chain member has terminated the response early, or until a chain member has thrown an error. - -Contrast this with Express, which does not tier your middleware and instead iterates through your entire application in the sequence that you composed it. - -```js -// Express -express() - .get('/', get) - .use(foo) - .get('/users/123', user) - .use('/users', users) - -// Polka -Polka() - .get('/', get) - .use(foo) - .get('/users/123', user) - .use('/users', users) -``` - -```sh -$ curl {APP}/ -# Express :: [get] -# Polka :: [foo, get] - -$ curl {APP}/users/123 -# Express :: [foo, user] -# Polka :: [foo, users, user] -``` - - -### Middleware Errors - -If an error arises within a middleware, the loop will be exited. This means that no other middleware will execute & neither will the route handler. - -Similarly, regardless of `statusCode`, an early response termination will also exit the loop & prevent the route handler from running. - -There are three ways to "throw" an error from within a middleware function. - -> **Hint:** None of them use `throw` :joy_cat: - -1. **Pass any string to `next()`** - - This will exit the loop & send a `500` status code, with your error string as the response body. - - ```js - polka() - .use((req, res, next) => next('💩')) - .get('*', (req, res) => res.end('wont run')); - ``` - - ```sh - $ curl / - #=> (500) 💩 - ``` - -2. **Pass an `Error` to `next()`** - - This is similar to the above option, but gives you a window in changing the `statusCode` to something other than the `500` default. - - ```js - function oopsies(req, res, next) { - let err = new Error('Try again'); - err.code = 422; - next(err); - } - ``` - - ```sh - $ curl / - #=> (422) Try again - ``` - -3. **Terminate the response early** - - Once the response has been ended, there's no reason to continue the loop! - - This approach is the most versatile as it allows to control every aspect of the outgoing `res`. - - ```js - function oopsies(req, res, next) { - if (true) { - // something bad happened~ - res.writeHead(400, { - 'Content-Type': 'application/json', - 'X-Error-Code': 'Please dont do this IRL' - }); - let json = JSON.stringify({ error:'Missing CSRF token' }); - res.end(json); - } else { - next(); // never called FYI - } - } - ``` - - ```sh - $ curl / - #=> (400) {"error":"Missing CSRF token"} - ``` - - -## Benchmarks - -Quick comparison between various frameworks using [`wrk`](https://github.com/wg/wrk) on `Node v10.4.0`.<br> Results are taken with the following command, after one warm-up run: - -``` -$ wrk -t4 -c4 -d10s http://localhost:3000/users/123 -``` - -Additional benchmarks between Polka and Express (using various Node versions) can be [found here](/bench). - -> **Important:** Time is mostly spent in _your application code_ rather than Express or Polka code!<br> Switching from Express to Polka will (likely) not show such drastic performance gains. - -``` -Native - Thread Stats Avg Stdev Max +/- Stdev - Latency 1.96ms 119.06us 5.33ms 92.57% - Req/Sec 12.78k 287.46 13.13k 90.00% - 508694 requests in 10.00s, 50.45MB read - Requests/sec: 50867.22 - Transfer/sec: 5.05MB - -Polka - Thread Stats Avg Stdev Max +/- Stdev - Latency 1.98ms 119.26us 4.45ms 92.87% - Req/Sec 12.68k 287.74 13.05k 94.06% - 509817 requests in 10.10s, 50.56MB read - Requests/sec: 50475.67 - Transfer/sec: 5.01MB - -Rayo - Thread Stats Avg Stdev Max +/- Stdev - Latency 2.02ms 116.55us 6.66ms 92.55% - Req/Sec 12.43k 262.32 12.81k 91.58% - 499795 requests in 10.10s, 49.57MB read - Requests/sec: 49481.55 - Transfer/sec: 4.91MB - -Fastify - Thread Stats Avg Stdev Max +/- Stdev - Latency 2.10ms 138.04us 5.46ms 91.50% - Req/Sec 11.96k 414.14 15.82k 95.04% - 479518 requests in 10.10s, 66.31MB read - Requests/sec: 47476.75 - Transfer/sec: 6.57MB - -Koa - Thread Stats Avg Stdev Max +/- Stdev - Latency 2.95ms 247.10us 6.91ms 72.18% - Req/Sec 8.52k 277.12 9.09k 70.30% - 342518 requests in 10.10s, 47.36MB read - Requests/sec: 33909.82 - Transfer/sec: 4.69MB - -Express - Thread Stats Avg Stdev Max +/- Stdev - Latency 4.91ms 484.52us 10.65ms 89.71% - Req/Sec 5.11k 350.75 9.69k 98.51% - 204520 requests in 10.10s, 40.57MB read - Requests/sec: 20249.80 - Transfer/sec: 4.02MB -``` - - -## Comparisons - -Polka's API aims to be _very_ similar to Express since most Node.js developers are already familiar with it. If you know Express, you already know Polka! :dancer: - -There are, however, a few main differences. Polka does not support or offer: - -1) **Polka uses a tiered middleware system.** - - Express maintains the sequence of your route & middleware declarations during its runtime, which can pose a problem when composing sub-applications. Typically, this forces you to duplicate groups of logic. - - Please see [Middleware Sequence](#middleware-sequence) for an example and additional details. - -2) **Any built-in view/rendering engines.** - - Most templating engines can be incorporated into middleware functions or used directly within a route handler. - -3) **The ability to `throw` from within middleware.** - - However, all other forms of middleware-errors are supported. (See [Middleware Errors](#middleware-errors).) - - ```js - function middleware(res, res, next) { - // pass an error message to next() - next('uh oh'); - - // pass an Error to next() - next(new Error('🙀')); - - // send an early, customized error response - res.statusCode = 401; - res.end('Who are you?'); - } - ``` - -4) **Express-like response helpers... yet! (#14)** - - Express has a nice set of [response helpers](http://expressjs.com/en/4x/api.html#res.append). While Polka relies on the [native Node.js response methods](https://nodejs.org/dist/latest-v9.x/docs/api/http.html#http_class_http_serverresponse), it would be very easy/possible to attach a global middleware that contained a similar set of helpers. (_TODO_) - -5) **`RegExp`-based route patterns.** - - Polka's router uses string comparison to match paths against patterns. It's a lot quicker & more efficient. - - The following routing patterns **are not** supported: - - ```js - app.get('/ab?cd', _ => {}); - app.get('/ab+cd', _ => {}); - app.get('/ab*cd', _ => {}); - app.get('/ab(cd)?e', _ => {}); - app.get(/a/, _ => {}); - app.get(/.*fly$/, _ => {}); - ``` - - The following routing patterns **are** supported: - - ```js - app.get('/users', _ => {}); - app.get('/users/:id', _ => {}); - app.get('/users/:id?', _ => {}); - app.get('/users/:id/books/:title', _ => {}); - app.get('/users/*', _ => {}); - ``` - -6) **Polka instances are not (directly) the request handler.** - - Most packages in the Express ecosystem expect you to pass your `app` directly into the package. This is because `express()` returns a middleware signature directly. - - In the Polka-sphere, this functionality lives in your application's [`handler`](#handlerreq-res-parsed) instead. - - Here's an example with [`supertest`](https://github.com/visionmedia/supertest), a popular testing utility for Express apps. - - ```js - const request = require('supertest'); - const send = require('@polka/send-type'); - - const express = require('express')(); - const polka = require('polka')(); - - express.get('/user', (req, res) => { - res.status(200).json({ name: 'john' }); - }); - - polka.get('/user', (req, res) => { - send(res, 200, { name: 'john' }); - }); - - function isExpected(app) { - request(app) - .get('/user') - .expect('Content-Type', /json/) - .expect('Content-Length', '15') - .expect(200); - } - - // Express: Pass in the entire application directly - isExpected(express); - - // Polka: Pass in the application `handler` instead - isExpected(polka.handler); - ``` - - -## License - -MIT © [Luke Edwards](https://lukeed.com) |