cp-koa

CP-Koa ⭐

CPKoa is an enhanced version of Koa with the support of cancellable middleware, that can be automatically canceled when client disconnecting. The package internally uses CPromise (provided by c-promise2) instead of the native to bring the cancellation and progress capturing to the CPKoa.

See the Codesandbox demo

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);

First middleware [/]
Progress: 25.0%
Progress: 50.0%
Second middleware
Progress: 100.0%

You can still use ECMA async function as middlewares:

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.

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:

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.

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.

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:

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 - promise with cancellation and progress capturing support
• use-async-effect2 - cancel async code in functional React components
• cp-axios - a simple axios wrapper that provides an advanced cancellation api
• 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 ⇐ Koa
  • .use(middleware, [options]) ⇒ CPKoaApplication
  • .close([timeout]) ⇒ CPromise

cpKoaApplication.use(middleware, [options]) ⇒ CPKoaApplication

Add middleware to the app

Kind: instance method of CPKoaApplication

Param	Type	Description
middleware	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

Param	Type	Default
[timeout]	number	10000

E_CLIENT_DISCONNECTED : string

Request cancellation reason for cases when the user was disconnected

Kind: global variable

E_SERVER_CLOSED : string

Request cancellation reason for cases when the server is closing

Kind: global variable

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
next	function

License

The MIT License Copyright (c) 2021 Dmitriy Mozgovoy [e-mail]

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.