@byungi/p-cancel-saga

A cancelable promise with saga.

Example

1import pCancelSaga, { IS_CANCELED } from '@byungi/p-cancel-saga'
2
3const promise = pCancelSaga(function * () {
4    try {
5        const result1 = yield async100msTask()
6        console.log('The 1st task is done.')
7
8        const result2 = yield async100msTask()
9        console.log('The 2nd task is done.')
10
11        return result2
12    } finally {
13        if (yield IS_CANCELED) {
14            console.log('Canceled!')
15        }
16    }
17})
18
19delay(150).then(() => {
20    promise.cancel()
21    // => "The 1st task is done."
22    // => "Canceled!"
23    // (`The 2nd task is done.` is not print.)
24})

API

pCancelSaga(saga)

Create a cancelable promise using a saga(generator). Similar to p-cancel but without the hassle of checking to cancel after asynchronous task.

Example

Before

1const promise = new PCancel((resolve, reject, onCancel) => {
2    onCancel(() => console.log('Canceled!'))
3
4    async100msTask().then(result1 => {
5        if (!promise.isCanceled) {
6            console.log('The 1st task is done.')
7
8            async100msTask().then(result2 => {
9                if (!promise.isCanceled) {
10                    console.log('The 2nd task is done.')
11                    resolve(result2)
12                }
13
14            }).catch(reject)
15        }
16    }).catch(reject)
17})

After

1const promise = pCancelSaga(function * () {
2    try {
3        const result1 = yield async100msTask()
4        console.log('The 1st task is done.')
5
6        const result2 = yield async100msTask()
7        console.log('The 2nd task is done.')
8
9        return result2
10    } finally {
11        if (yield IS_CANCELED) {
12            console.log('Canceled!')
13        }
14    }
15})

Cancel propagation

1const parentPromise = new PCancel((resolve, reject, onCancel) => {
2    onCancel(() => {
3        console.log('Cancel parent')
4    })
5    /* ... */
6})
7
8const childPromise = pCancelSaga(function * () {
9    try {
10        const result = yield parentPromise
11        /* ... */
12    } finally {
13        if (yield IS_CANCELED) {
14            console.log('Cancel child')
15        }
16    }
17})
18
19childPromise.cancel()
20// => Cancel child
21// => Cancel parent

promise.cancel([reason])

Stop the flow in saga and throw a CancelError to promise.

promise.isCanceled

Returns whether the promise is canceled.

promise.pipe(onFulfilled, onRejected)

Similar to then but can propagate cancel to the upper promise.

IS_CANCELED

yield this symbol in saga, it returns whether the promise is canceled.

factory(saga)

Returns a reusable function using saga with arguments.

1import { factory, IS_CANCELED } from '@byungi/p-cancel-saga'
2
3const asyncTaskFunction = factory(function * (url, params) {
4    try {
5        const result = yield apiGet(url, params)
6        return result
7    } finally {
8        if (yield IS_CANCELED) {
9            /* ... */
10        }
11    }
12})
13
14const promise = asyncTaskFunction('/data', { id: 1 })

silent(saga)

If it's just a cancelable task (not a promise), CancelError is bothersome. This function does not propagate an error.

1import { silent, IS_CANCELED } from '@byungi/p-cancel-saga'
2
3const task = silent(function * () {
4    while (true) {
5        yield delay(1000)
6        yield asyncTask()
7    }
8})
9
10task.cancel() // => No `unhandledRejection` occurs.

Tips

Type inference of yield promise in saga

1const promise = pCancelSaga(function * () {
2    const data = yield getDataAsync() // => "data" type is `any` or `unknown`.
3    /* ... */
4})

In TypeScript, type inference of yield promise in generator functions is difficult. Specify the type or use the provided helper type(AsyncResult<F>).

1import pCancelSaga, { AsyncResult } from '@byungi/p-cancel-saga'
2
3const promise = pCancelSaga(function * () {
4    const data = (yield getDataAsync()) as {value: string}
5
6    // or
7    const data = (yield getDataAsync()) as AsyncResult<typeof getDataAsync>
8
9    /* ... */
10})

License

MIT