https://github.com/digitalbrainjs/cp-koa
Koa with cancellable middlewares support
https://github.com/digitalbrainjs/cp-koa
Last synced: about 1 year ago
JSON representation
Koa with cancellable middlewares support
- Host: GitHub
- URL: https://github.com/digitalbrainjs/cp-koa
- Owner: DigitalBrainJS
- License: mit
- Created: 2021-04-22T14:54:06.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-02-01T18:08:04.000Z (over 4 years ago)
- Last Synced: 2025-03-24T00:41:38.112Z (about 1 year ago)
- Language: JavaScript
- Size: 557 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://travis-ci.com/DigitalBrainJS/cp-koa)
[](https://coveralls.io/github/DigitalBrainJS/cp-koa?branch=master)
[](https://github.com/DigitalBrainJS/cp-koa/stargazers)
## CP-Koa :star:
`CPKoa` is an enhanced version of [Koa](https://www.npmjs.com/package/koa) with the support of cancellable middleware,
that can be automatically canceled when client disconnecting.
The package internally uses `CPromise` (provided by [c-promise2](https://www.npmjs.com/package/c-promise2))
instead of the native to bring the cancellation and progress capturing to the `CPKoa`.
See the [Codesandbox demo](https://codesandbox.io/s/cp-koa-readme-basic-xr2fi)
````javascript
const CPKoa = require('cp-koa');
const {CPromise} = require('c-promise2');
const app = new CPKoa();
app.use(function*(ctx, next){
console.log(`First middleware [${ctx.url}]`);
yield CPromise.delay(2000);
ctx.body= `Hello! [${yield next()}]`
}).use(function*(){
console.log(`Second middleware`);
yield CPromise.delay(500);
return new Date().toLocaleTimeString();
}).on('progress', (ctx, score)=>{
console.log(`Progress: ${(score*100).toFixed(1)}%`)
}).listen(3000);
````
````output
First middleware [/]
Progress: 25.0%
Progress: 50.0%
Second middleware
Progress: 100.0%
````
You can still use ECMA async function as middlewares:
````javascript
app.use(function* (ctx, next) {
console.log(`First middleware [${ctx.url}]`);
yield CPromise.delay(2000);
ctx.body = `Hello! [${yield next()}]`
})
.use(async (ctx) => {
console.log(`Second ECMA async middleware`);
await CPromise.delay(1000);
return new Date().toLocaleTimeString();
})
.on('progress', (ctx, score) => {
console.log(`Progress: ${(score * 100).toFixed(1)}%`)
}).listen(3000);
````
CPKoa's `ctx` has a `scope` property that refers to the relative `CPromise` instance.
Since every CPromise has a `signal` property that provides `AbortController` signal (controllers creating on demand),
you can use it to cancel your async routines, when the parent scope cancels.
This allowing you to use async middlewares and functions that do not support `CPromise` out of the box.
````javascript
app.use(async (ctx) => {
console.log(`Second ECMA async middleware`);
await CPromise.run(function* () {
yield CPromise.delay(1000);
console.log('stage 4');
yield CPromise.delay(1000);
console.log('stage 5');
}).listen(ctx.scope.signal);
})
````
CPKoa's ctx object has a shortcut to do this easier:
````javascript
app.use(async (ctx) => {
await ctx.run(function* () { // this async routine will be cancelled when the client disconnecting
yield CPromise.delay(1000);
console.log('stage 4');
yield CPromise.delay(1000);
console.log('stage 5');
});
ctx.body= 'Done!';
})
````
CPromise provides `timeout` method, so you able to set a timeout for each middleware separately if you need to.
````javascript
const app = new CPKoa();
app.use(function* (ctx, next) {
console.log(`Start [${ctx.url}]`);
this.timeout(2000);
const response = yield cpAxios(`https://run.mocky.io/v3/7b038025-fc5f-4564-90eb-4373f0721822?mocky-delay=5s`);
ctx.body = `Hello! Response : [${JSON.stringify(response.data)}]`
}).listen(3000);
````
The `CPromise` chain can be marked as `atomic` - the execution of such a chain cannot be interrupted from the upper chains.
By default, the top chain will wait for the atomic chain to complete, or if the `detached` option has been set,
it will continue canceling the top chain while the atomic chain continues in the background.
````javascript
app.use(function*(ctx, next){
this.atomic();// The request promise chain can not be interrupted while this sub-chain is not completed.
yield CPromise.delay(100);
console.log('stage 1');
yield CPromise.delay(1000);
console.log('stage 2');
yield CPromise.delay(1000);
console.log('stage 3');
ctx.body = new Date().toLocaleTimeString();
})
````
Since koa-router currently do not support `CPromise` features, you have to use a workaround with `ctx.run`
inside your routes:
````javascript
const app = new CPKoa();
const router = new Router();
router.get('/', async(ctx, next)=>{
await ctx.run(function*(){
this.innerWeight(3); // total progress score
yield CPromise.delay(1000);
console.log('stage 1');
yield CPromise.delay(1000);
console.log('stage 2');
yield CPromise.delay(1000);
console.log('stage 3');
ctx.body= "Root page"
});
})
app
.use(router.routes())
.use(router.allowedMethods())
.on('progress', (ctx, score) => {
console.log(`Progress: ${(score * 100).toFixed(1)}%`)
}).listen(3000);
````
## Related projects
- [c-promise2](https://www.npmjs.com/package/c-promise2) - promise with cancellation and progress capturing support
- [use-async-effect2](https://www.npmjs.com/package/use-async-effect2) - cancel async code in functional React components
- [cp-axios](https://www.npmjs.com/package/cp-axios) - a simple axios wrapper that provides an advanced cancellation api
- [cp-fetch](https://www.npmjs.com/package/cp-fetch) - fetch with timeouts and request cancellation
## API Reference
## Classes
-
CPKoaApplication ⇐Koa
## Members
-
E_CLIENT_DISCONNECTED :string -
Request cancellation reason for cases when the user was disconnected
-
E_SERVER_CLOSED :string -
Request cancellation reason for cases when the server is closing
## Functions
-
isCanceledError(thing) ⇒boolean -
Check whether the object is an CanceledError instance
## CPKoaApplication ⇐ Koa
**Kind**: global class
**Extends**: Koa
**Api**: public
* [CPKoaApplication](#CPKoaApplication) ⇐ Koa
* [.use(middleware, [options])](#CPKoaApplication+use) ⇒ [CPKoaApplication](#CPKoaApplication)
* [.close([timeout])](#CPKoaApplication+close) ⇒ CPromise
### cpKoaApplication.use(middleware, [options]) ⇒ [CPKoaApplication](#CPKoaApplication)
Add middleware to the app
**Kind**: instance method of [CPKoaApplication](#CPKoaApplication)
| Param | Type | Description |
| --- | --- | --- |
| middleware | [CPKoaMiddleware](#CPKoaMiddleware) | |
| [options] | Object | |
| [options.scopeArg] | Boolean | pass the relative CPromise scope to the middleware as the first argument |
### cpKoaApplication.close([timeout]) ⇒ CPromise
Cancel all requests with timeout and close running http server
**Kind**: instance method of [CPKoaApplication](#CPKoaApplication)
| Param | Type | Default |
| --- | --- | --- |
| [timeout] | number | 10000 |
## E\_CLIENT\_DISCONNECTED : string
Request cancellation reason for cases when the user was disconnected
## E\_SERVER\_CLOSED : string
Request cancellation reason for cases when the server is closing
## isCanceledError(thing) ⇒ boolean
Check whether the object is an CanceledError instance
**Kind**: global function
| Param | Type |
| --- | --- |
| thing | \* |
## ~CPKoaCtx : Object
**Kind**: inner typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| run | function | promisify and run async function (ECMA async function, generator or callback-styled function) |
| scope | CPromise | ref to the relative CPromise scope |
## ~CPKoaMiddleware : GeneratorFunction \| function
**Kind**: inner typedef
| Param | Type |
| --- | --- |
| ctx | [CPKoaCtx](#CPKoaCtx) |
| next | function |
## License
The MIT License Copyright (c) 2021 Dmitriy Mozgovoy robotshara@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.