chrome-promise

Chrome API using promises.

Note: I'm no longer adding features to this library (only bug fixing). You can check other alternative libraries at the end of this file.

Installation

Use npm

npm install chrome-promise

Or yarn

yarn add chrome-promise

Or download chrome-promise.js file.

You can include it in your HTML like this:

<script src="chrome-promise.js" data-instance="chromep"></script>

Or you can use ES2015 import statement:

import chromep from 'chrome-promise';

Compatibility

It supports Chrome 34 or higher, but it should work in older versions. Create an issue if it doesn't work for your version.

Examples

Use local storage.

chromep.storage.local.set({foo: 'bar'}).then(function() {
  alert('foo set');
  return chromep.storage.local.get('foo');
}).then(function(items) {
  alert(JSON.stringify(items)); // => {"foo":"bar"}
});

Detect languages of all tabs.

chromep.tabs.query({}).then((tabs) => {
  const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
  return Promise.all(promises);
}).then((languages) => {
  alert('Languages: ' + languages.join(', '));
}).catch((err) => {
  alert(err.message);
});

Options

If you are testing with node, you can provide a mock for the chrome API (sinon-chrome is a good choice) using the constructor.

const ChromePromise = require('chrome-promise/constructor');
const chrome = require('sinon-chrome');

const chromep = new ChromePromise({ chrome });

The constructor accepts an options parameter with the following properties:

chrome: the chrome API object. By default (or when null or undefined are used), it is the 'chrome' global property.
Promise: the object used to create promises. By default, it is the 'Promise' global property.

Notes

This library is not a replacement of the chrome api. It should be used only for functions that have a callback.

// this returns a rejected promise (because a callback is added to getManifest)
chromep.runtime.getManifest();

// this works
chrome.runtime.getManifest();

When there's a callback with multiple parameters, the promise will return an array with the callback arguments.

chromep.hid.receive(4).then(function(args) {
  const reportId = args[0];
  const data = args[1];
  console.log(reportId, data);
});

// Using babel or chrome >= 49
chromep.hid.receive(4).then(([reportId, data]) => {
  console.log(reportId, data);
});

Only APIs that are enabled in the manifest will be available in the ChromePromise instance. If the API is undefined, first check the permissions in the manifest.json of your project.

// manifest.json
{
  "permissions": [
    "tabs"
  ]
}

// main.js
console.log(typeof chromep.tabs)  // "object"
console.log(typeof chromep.bookmarks)  // "undefined"

Synchronous-looking code

If you are using babel or chrome ≥ 55, you can use async/await to achieve this.

async function main() {
  await chromep.storage.local.set({foo: 'bar'});
  alert('foo set');
  const items = await chromep.storage.local.get('foo');
  alert(JSON.stringify(items));
}
main();

// try...catch
async function main2() {
  try {
    const tabs = await chromep.tabs.query({});
    const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
    const languages = await Promise.all(promises);
    alert('Languages: ' + languages.join(', '));
  } catch(err) {
    alert(err);
  }
}
main2();

If you are not using babel and you need to support chrome ≥ 39, it can be done with generator functions. Using the methods Q.async and Q.spawn from the Q library, the previous examples can be rewritten as:

Q.spawn(function* () {
  yield chromep.storage.local.set({foo: 'bar'});
  alert('foo set');
  const items = yield chromep.storage.local.get('foo');
  alert(JSON.stringify(items));
});

// try...catch
Q.spawn(function* () {
  try {
    const tabs = yield chromep.tabs.query({});
    const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
    const languages = yield Promise.all(promises);
    alert('Languages: ' + languages.join(', '));
  } catch(err) {
    alert(err);
  }
});

// promise.catch
Q.async(function* () {
  const tabs = yield chromep.tabs.query({});
  const languages = yield Promise.all(tabs.map((tab) => (
    chromep.tabs.detectLanguage(tab.id);
  )));
  alert('Languages: ' + languages.join(', '));
})().catch(function(err) {
  alert(err);
});

You can also use the co library instead of Q.

mjorritsma/chrome-promise