Skip to content

Automatically invalidate async listeners and promises in one place. Lightweight zero dependent library for browsers.

License

Notifications You must be signed in to change notification settings

KromDaniel/browser-cancelable-events

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Browser Cancelable Events

Automatically invalidate async listeners and promises in one place.
Lightweight zero dependent library for browsers.

Motivation

Libraries like React, should invalidate all async tasks once component is unmounted, using isMounted is anti pattern.

Table of Contents

  1. Quick start
  2. API
  3. Testing
  4. License

Quick start

Install

npm i --save browser-cancelable-events

Typescript

The project is written with typescript and comes with a built-in index.d.ts

Import

import { CancelableEvents, isCancelledPromiseError } from "browser-cancelable-events";

Require

const { CancelableEvents, isCancelledPromiseError } = require("browser-cancelable-events");

Usage

Usage example using react component

import { Component } from 'react'
import { CancelableEvents, isCancelledPromiseError } from "browser-cancelable-events";

class MyComponent extends Component {
    constructor(props) {
        super(props);
        this.cancelable = new CancelableEvents();
    }

    componentDidMount() {
        this.cancelable.addWindowEventListener("resize", this.onWindowResize.bind(this));
        this.cancelable.addDocumentEventListener("keydown", (e) => {
            if (e.shiftKey) {
                // shift clicked
            }
        });
        this.updateEverySecond();
        this.fetchDataFromApi();
    }

    // invalidate all events
    componentWillUnmount() {
        this.cancelable.cancelAll(); // this is the magic line
    }

    render() {
        return (
            <div> ... </div>
        );
    }

    // interval that updates every second
    updateEverySecond() {
        this.cancelable.setInterval(() => {
            this.setState({
                counter: this.state.counter + 1,
            })
        }, 1000);
    }

    // do task with timeout
    doSomeAnimation() {
        this.setState({
            isInAnimation: true,
        }, () => {
            this.cancelable.setTimeout(() => {
                this.setState({
                    isInAnimation: false,
                });
            }, 500);
        })
    }

    // use invalidated promise
    async fetchDataFromApi() {
        try {
            const apiResult = await this.cancelable.promise(() => {
                return APIService.fetchSomeData();
            });

            const someVeryLongPromise = this.cancelable.promise(() => {
                return APIService.fetchSomeReallyLongTask();
            });

            this.cancelable.setTimeout(() => {
                // 1 second is too much, let's cancel
                someVeryLongPromise.cancel();
            }, 1000);

            await someVeryLongPromise;
        } catch (err) {
            if (isCancelledPromiseError(err)) {
                // all good, component is not mounted or promise is cancelled
                return;
            }

            // it's real error, should handle
        }
    }

    // callback for window.addEventListener
    onWindowResize(e) {
        // do something with resize event
    }
}

API

Cancelable object

Each one of the cancelable methods returns object with cancel method

{
    cancel: Function
}
const timer = cancelable.setInterval(intervalCallback, 100);
timer.cancel();

Cancel All

Cancel all listeners method, invalidated everything immediately. Adding new listeners on cancelled event will throw exception

cancelable.cancelAll();

Timeout

cancelable.setTimeout(callback, time, ...args[]) -> CancelableObject

Interval

cancelable.setInterval(callback, time, ...args[]) -> CancelableObject

Promise

cancelable.promise(functionThatReturnsPromise, ...args[]) -> Promise & CancelableObject
cancelable.promise(promise) -> Promise<T> & CancelableObject
Promise example
const cancelable = new CancelableEvents();

cancelable.promise(new Promise((resolve, reject) => {
    resolve("foo");
})).then((res) => {
    console.log(res); // foo
});

let cancelTimer;
// invalidate promise after 1 second
const promise = cancelable.promise(() => API.fetchSomeLongData());

promise.then((data) => {
    if(cancelTimer){
        cancelTimer.cancel();
    }
}).catch((err) => {
    if(isCancelledPromiseError(err)){
        // timeout, took too long
        return;
    };
    // real error
});

// if promise.cancel() called after fulfilled, nothing will happen
cancelTimer = cancelable.setTimeout(() => {
    promise.cancel();
}, 1000);

Document event listener

Observes document.addEventListener

cancelable.addDocumentEventListener(eventKey, callback) -> CancelableObject

Window event listener

Observes window.addEventListener

cancelable.addWindowEventListener(eventKey, callback) -> CancelableObject
Event listeners example
const cancelable = new CancelableEvents();

cancelable.addDocumentEventListener("mousewheel", (e) => {
   // do something with event 
});
cancelable.addWindowEventListener("submit", (e) => {
    // do something with event
});

// remove all cancelable listeners
cancelable.cancelAll();

Custom event emitter

You can use custom event emitter with cancelable events.

cancelable.addCustomCancelable(subscription, removeKey) -> CancelableObject
Custom event emitter example
const { EventEmitter } = require("fbemitter");

const emitter = new EventEmitter();
// key "remove" because emitter.addListener(...).remove()
cancelable.addCustomCancelable(emitter.addListener("myCustomEvent", callback), "remove");

Testing

npm run tests

License

MIT

About

Automatically invalidate async listeners and promises in one place. Lightweight zero dependent library for browsers.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published