Wondering what’s next for npm?Check out our public roadmap! »

    chrome-promise
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.5 • Public • Published

    chrome-promise

    npm version build status

    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.

    Alternative libraries

    Install

    npm i chrome-promise

    DownloadsWeekly Downloads

    96

    Version

    3.0.5

    License

    MIT

    Unpacked Size

    214 kB

    Total Files

    24

    Last publish

    Collaborators

    • avatar