Negligible Participation Metric
    Have ideas to improve npm?Join in the discussion! »

    cancellable-coroutine
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.8 • Public • Published

    Cancellable-Coroutine

    GitHub Workflow Status npm (tag) npm bundle size

    Cancellable-coroutine is a wrapper for function generators that runs them as async functions and adds cancellation support.

    Usage

    // Take a generator function
    const myFn = function*(url) {
      // Maybe you want some API data
      const response = yield fetchSomething(url);
      // Maybe you want to delay for some ms
      yield delay(500);
      console.log(response);
      return response;
    };
     
    // Wrap the generator in Cancellable.create(...)
    const cancellableFn = Cancellable.create(myFn);
     
    // Run the wrapped function, which runs like a function using `async/await`.
    // The function returns a promise, which resolves on complete, or rejects on uncaught exception or cancellation.
    cancellableFn('https://my-api.com').then(onComplete, onFailureOrCancel);
     
    // Now we can halt the execution of our generator function whenever we want! We use Cancellable.cancel(..) to cancel.
    setTimeout(() => {
      Cancellable.cancel(cancellableFn);
    }, 200);

    API

    create(generatorFn)

    Returns a CancellableTask.

    When calling this CancellableTask, generatorFn will run like an async/await function (all yield expressions will resolve in sequence).

    const task = Cancellable.create(function*(arg: string) {
      const result1 = yield doAThing(arg);
      const result2 = yield doAnAsyncThing(result1);
      return yield doAThirdThing(result2);
    };
     
    /*
      this task will run like:
      async function(arg: string) {
        const result1 = await doAThing(arg);
        const result2 = await doAnAsyncThing(result1);
        return await doAThirdThing(result2);
      }
    */
    task('hello');

    cancel(cancellableTask)

    Cancels cancellableTask.

    If cancellableTask is running, a CancelError will be thrown in the wrapped generator function. If the task is not running, nothing will happen.

    const task = Cancellable.create(function*() {
      try {
        yield doAThingThatTakes5Seconds();
        // We want to cancel before this line.
        console.log("We did it!");
      } catch (error) {
        if (Cancellable.isCancelError(error)) {
          console.log("We cancelled!");
        } else {
          console.log("We failed!");
        }
      }
    };
     
    task();
     
    setTimeout(() => {
      Cancellable.cancel(task);
    }, 1000);
     
    // Only "We cancelled!" will output to the console.

    CancelError

    Extends Error. A CancelError will be thrown into the generator function if it is cancelled while running.

    isCancelError(error)

    Returns true if the passed error is a CancelError, false otherwise. This can be used in a catch(error) block to check whether error was caused by cancellation or not.

    try {
    ...
    } catch (error) {
      if (isCancelError(error)) {
        // We cancelled!
      } else {
        // Something else failed!
      }
    }

    isCancelled(cancellableTask)

    Returns true if the passed task has been cancelled. This can be used in a calling function to check whether a called task ran successfully or was cancelled.

    const task = Cancellable.create(function*() {
      ...
    });
     
    task();
     
    Cancellable.cancel(task);
     
    if (Cancellable.isCancelled(task)) {
      // task was cancelled!
    }

    Install

    npm i cancellable-coroutine

    DownloadsWeekly Downloads

    0

    Version

    1.0.8

    License

    MIT

    Unpacked Size

    112 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar