\n \n A Koa middleware to handle\n timeouts correctly\n \n
\n\n\n How it works\n |\n Usage\n
\n\n[](#contributors)\n[]()\n\n\n[](https://facebook.github.io/jest/)\n[](https://standardjs.com)\n\n## How it works\n\n`koa-timeout` uses\n[`Promise.race`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race)\nto race a `setTimeout` against your **Koa** middlewares/response.\n\n#### Timeout example\n```\nMiddlewares\n A 1s B 2s C 3s D 4s\n ╭─────┴────────┴─────╳╌╌╌╌┴╌╌╌╌╌╌╌╌╌┴╌╌╌╌╌\nReq ─────┤\n ╰────────────────────┬──→ 408 - 2500ms\n Timeout\n 2.5s\n```\nIn this example, a request has come in and the timeout is racing\nmiddlewares, `A`, `B`, `C` & `D`. However, the timeout is triggered\ncausing a `408` response after `2500ms`.\n\nThe `╳` signifys a **short circuit** and prevents middlewares `C` &\n`D` from running.\n\n\n#### Successful example\n```\nMiddlewares\n A 1s B 2s C 3s D 4s\n ╭─────┴────────┴─────────┴─────────┴──────╮\n │ │\nReq ─────┤ ╰──→ 200 - 4500ms\n │\n ╰─────────────────────────────────────────╳╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮\n Timeout\n 5s\n```\nIn this example, all 4 middlewares - `A`, `B`, `C` & `D` - have\nfinished, resulting in a `200` response after ~`4500ms`. The timeout\nis then cleared, signified by the `╳`.\n\n## Usage\n\nThe middleware can be configured with a _custom_ timeout time and\nstatus code.\n\n```js\nimport Koa from 'koa'\nimport timeout from '@uswitch/koa-timeout'\n\nconst app = new Koa()\n\napp.use(timeout(1000)) // 1s timeout\napp.use(timeout(1000, { status: 499 })) // 1s timeout with 499 status\n```\n\n### Short circuiting\n\n**N.B.** _By default_, `koa-timeout` does **not** short circuit the\nother middlewares. This means that the in-flight request will _continue_ to be\nprocessed even though a response has already been sent.\n\nThis behaviour can be useful in **development** to see where the slow\nparts of the request are, however, in **production** you probably want\nto kill the request as soon as possible.\n\n##### **To enable short circuiting**\n\nThis will prevent the _next_ middleware after a timeout from\ntriggering.\n\n```js\nimport { shortCircuit } from '@uswitch/koa-timeout'\n\napp.use(timeout(5000))\n\napp.get('*', shortCircuit(handleInitialState))\napp.get('*', shortCircuit(handleRendering))\napp.get('*', shortCircuit(handleReturn))\n\n// Or\n\napp.get('*', ...shortCircuit(handleInitialState, handleRendering, handleReturn))\n```\n\n\n\n N.B. when calling with multiple middlewares, make sure\n to spread the result!\n \n i.e. ...shortCircuit(a, b, c)\n\n