Package Exports

chrome-extension-async

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (chrome-extension-async) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Chrome Extension Async

Promise wrapper for the Chrome extension API so that it can be used with async/await rather than callbacks

The Extension API provided by Chrome uses callbacks. However, Chrome now supports async and await keywords.

This library wraps Chrome extension API callback methods in promises, so that they can be called with async and await.

Once activated against the Chrome API each callback function gets a Promise version.

Chrome supports ES2017 syntax, so in extensions we can take full advantage of it.

Examples

For instance, to get the current active tab:

function startDoSomething(callback) {
    chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
        
        // Check API for any errors thrown
        if (chrome.runtime.lastError) {
            // Handle errors from chrome.tabs.query
        }
        else {
            try {
                var activeTab = tabs[0];

                // Do stuff with activeTab...

                callback(activeTab);
            }
            catch(err) {
                // Handle errors from my code
            }
        }
    });
}

Instead use await:

async function doSomething() {
    try {
        const tabs = await chrome.tabs.query({ active: true, currentWindow: true });
        const activeTab = tabs[0];

        // Do stuff with activeTab...

        return activeTab;
    }
    catch(err) {
        // Handle errors from chrome.tabs.query or my code
    }
}

Some callbacks take multiple parameters - in these cases the Promise will be a combined object:

async function checkUpdate() {
    try {
        // API is chrome.runtime.requestUpdateCheck(function (status, details) { ... });
        // Instead we use deconstruction-assignment and await
        const { status, details } = await chrome.runtime.requestUpdateCheck();
        alert(`Status: ${status}\nDetails: ${JSON.stringify(details)}`);
    }
    catch(err) {
        // Handle errors from chrome.runtime.requestUpdateCheck or my code
    }
}

Installation

Use bower

bower install chrome-extension-async

Or npm

npm i chrome-extension-async

Or download chrome-extension-async.js file and include it directly:

<script type="text/javascript" src="chrome-extension-async.js"></script>

TypeScript definitions for the altered API are in chrome-extension-async.d.ts

Release Notes

This only 'promisifies' API functions that use callbacks and are not marked as deprecated. No backwards compatibility is attempted.

Each API is added manually as JS can't spot deprecated or functions with no callbacks itself.

Supported API:

Pull requests with additional API gratefully received.

3.0.0

3.0.0 is a breaking change from v1 and v2: now the original API is wrapped by an identical method that can be called with either old or new syntax. Callbacks can still be used on the same methods, and will fire before the promise resolves. Any error thrown inside the callback function will cause the promise to reject.

You can use both a callback and await if you want to work with existing API code, but also want the try-catch support:

async function startDoSomethingHybrid(callback) {
    try{
        // Using await means any exception is passed to the catch, even from the callback
        await chrome.tabs.query({ active: true, currentWindow: true }, tabs => callback(tabs[0]));
    }
    catch(err) {
        // Handle errors thrown by the API or by the callback
    }
}

Older versions added a ...Async suffix to either the function (2.0.0) or the API class (1.0.0).