@shivams136/advanced-promise

    2.1.1 • Public • Published

    advanced-promise

    A simple extension to the native Promise API

    Overview

    This simple library provides you some handy extensions to the native Promise API like below:

    • Make the promise/fetch abortable
    • Get status of the promise at any stage
    • Bind some data to the promise and get that
    • Resolve/Reject the promise from outside
    • Auto Timeout for aborting the promise after particular time in microseconds

    How to install

    Simply run below:

    npm install @shivams136/advanced-promise

    How to use

    Signature

    AdvancedPromise(([resolve] [, reject] [, signal])=>{
        // ...
    } [,timeoutInMs][,data]): AdvancedPromise

    Creating

    There are below 2 ways to create an AdvancedPromise:

    1. Constructor

    const advPromise = new AdvancedPromise(
    	(resolve, reject, signal) => {
    		//....
    	},
    	timeout,
    	data
    );

    2. Existing Promise

    // Pass existing promise to the static `from` method
    const advPromise = AdvancedPromise.from(promise);

    Abort

    // Abort with default reason - Aborted
    advPromise.abort();
    
    // Abort with custom reason
    advPromise.abort("I just want to abort");
    
    // cancel is alias of abort so you can use that too
    advPromise.cancel();

    Getters

    Abort Reason

    This will provide you the abort reason for the promise. Its value will be undefined if the proise is not aborted yet, so you can use is to check if the promise is aborted or not.

    advPromise.abortReason; // default: Aborted

    Status Methods

    isFulfilled

    Check whether the promise is fulfilled or not

    advPromise.isFulfilled; // true/false

    isSettled

    Check whether the promise is settled/resolved or not

    advPromise.isSettled; // true/false

    isRejected

    Check whether the promise is rejected or not

    advPromise.isRejected; // true/false

    isTimedout

    Check whether the promise is aborted due to timeout or not

    advPromise.isTimedout; // true/false

    status

    This will provide you the current status of the promise

    advPromise.status; // "pending" | "resolved" | "rejected"

    More features

    Resolve/Reject from outside

    You can easily resolve/reject the promise from outside by just calling resolve() or reject() methods from outside.

    advPromise.resolve("Test Data");
    advPromise.reject("Test Error");

    Examples:

    Use with Fetch and a timeout value

    const loadData = (id) => {
    	return new AdvancedPromise((resolve, reject, abortSignal) => {
    		fetch(url, { signal: abortSignal })
    			.then((response) => response.json())
    			.then(parsedData)
    			.then(resolve)
    			.catch(reject);
    	}, 5000); // 5000ms timeout
    };
    
    const advPromise = loadData(id);
    advPromise.abort(); // For manual abort

    Hook the abort

    You can add event listener on Abort action and do anything on abort of the error

    const advPromise = new AdvancedPromise((resolve, reject, abortSignal) => {
    	abortSignal.addEventListener("abort", () => {
    		// Do something when abort happens
    	});
    	// ...
    });

    Use status

    const advPromise = new AdvancedPromise((resolve, reject, abortSignal) => {
    	// ...
    });
    //...
    //...
    //...
    const iconColor = advPromise.isFulfilled ? (advPromise.isSettled ? "green" : "red") : "orange";

    Use Data

    const advPromise = new AdvancedPromise(
    	(resolve, reject, abortSignal) => {
    		// ...
    	},
    	5000, // 5 second timeout
    	{ name: "Shivam", age: 25 } // Data bound with promise
    );
    //...
    //...
    //...
    const promiseData = advPromise.data; // {name:"Shivam",age:25}

    Working Example with plain JS

    You can find the code sandbox here.

    import AdvancedPromise from "@shivams136/advanced-promise";
    
    const loadData = (id) => {
    	return new AdvancedPromise((resolve, reject, abortSignal) => {
    		fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
    			signal: abortSignal,
    		})
    			.then((response) => response.json())
    			.then(resolve)
    			.catch(reject);
    	});
    };
    
    const id = 1;
    const advPromise = loadData(id);
    advPromise
    	.then((myData) => {
    		console.log(myData);
    	})
    	.catch((err) => console.log("My Error:\n", err));
    advPromise.abort();

    A working example on node

    You can find the code sandbox here.

    const fetch = require("node-fetch");
    const AdvancedPromise = require("@shivams136/advanced-promise");
    
    const loadData = (id) => {
    	return new AdvancedPromise((resolve, reject, abortSignal) => {
    		fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, { signal: abortSignal })
    			.then((response) => response.json())
    			.then(resolve)
    			.catch(reject);
    	});
    };
    
    const id = 1;
    const advPromise = loadData(id);
    advPromise
    	.then((myData) => {
    		console.log(myData);
    	})
    	.catch((err) => console.log("My Error:\n", err));
    advPromise.abort();

    Contact

    You can contact me on github anytime.

    This package is inspired by this package from Thor(Shenghan) Chen.

    Install

    npm i @shivams136/advanced-promise

    DownloadsWeekly Downloads

    17

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    10.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • shivams136