Weer API Documentation

This file describes Weer API, for an introduction into Weer and for the most fresh API see GitHub repository.

Weer.Utils

File: weer-repo/src/src/utils.js
Objectives:

1. Help in catching errors with weer.
2. Help to write more robust code.

Utils.mandatory()

const foo = function foo(one = 'one', two = Utils.mandatory()) {
  /*...*/
};
foo('one'); // Throws error.
foo('one', 'two'); // No error.
foo('one', null); // No error.
foo('one', undefined); // Throws error (surprise).

Utils.throwIfError(error)

Throws first argument if it is == true.

const foo = function foo(cb) {
  /*...*/
  const error = new Error('oops');
  cb(error, result);
};
foo(Utils.throwIfError); // Throws Error('oops').

Utils.checkChromeError()

Checks chrome.runtime.lastError and returns new Error(message) or nothing.

chrome.runtime.openOptionsPage(
  () => {
    const err = Utils.checkChromeError(); // Error if no options page in `manifest.json`.
    /*...*/
  }
);

Utils.timeouted((...args) => {/*...*/})

Fixes context for thrown errors to that, which allows catching on global window.

chrome.runtime.openOptionsPage(Utils.timeouted((/*arg1, arg2, ...*/) => {

  throw new Error('I am catchable!');

}))

Utils.chromified((error, ...args) => {/*...*/})

Allows to use error-first callbacks with chrome apis. Also Utils.timeouts callback.

chrome.runtime.openOptionsPage(Utils.chromified((err, res1, res2) => {

  if (err) {
    throw err;
  }
  throw new Error('I am catchable!');

}))

Utils.getOrDie((...args) => {/*...*/})

Gets result of chrome API, throws error in case of error, passes result to callback otherwise.

chrome.runtime.openOptionsPage(Utils.getOrDie((res1, res2) => {

  throw new Error('I am catchable!');

}))

Utils.assert(valueToTest, errorMessage)

Poor man's assert.

Weer.ErrorCatchers

installListenersOn(configs, cb)

Installs error and unhandled rejections catchers on hostWindow object, in case of error calls handleErrorMessage({ to: 'error-reporter', payload: plainErrorEventObject }).

Configs

{
  hostWindow = window,
  nameForDebug = 'BG',
  handleErrorMessage,
};

Returns

uninstallListeners

Weer.GetNotifiersSingleton(configs)

Configs

{
 sendReports: {
    toEmail = '[email protected]',
    // In what language to display a template for the error reporting form.
    // Use only those languages that your support team may understand.
    inLanguages = ['en'],
  },
  onNotificationClick = defaultClickHandler,
  // Icons:
  extErrorIconUrl = 'https://rebrand.ly/ext-error',
  pacErrorIconUrl = 'https://rebrand.ly/pac-error',
  maskIconUrl = false,
};

onNotificationClick is a function (errorMessage, report) => {...}. Report looks like:

{
  payload: {
    filename: "chrome-extension://mddbgiefhigdgkeggceilkaoamkbnajl/pages/popup/dist/bundle.js",  
    colno: 13,
    lineno: 373,
    error: {
      message: "I'm a type error!",
      name: "TypeError",
      stack: "...",
    },
    message: "Uncaught TypeError: I'm a type error!",
    path: "[[object Window]]",
    type: "error",
  },
  errorType: "ext-error",
  extName: "PAC Kitchen",
  version: "0.0.0.1",
  userAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36",
  platform: "Linux x86_64",
}

Return Type

const noty = Weer.GetNotifiersSingleton(configs);
noty.switch('off'); // Switches off notifications.
noty.switch('off', 'pac-error'); // Switches off notifications for pac-errors.
noty.isOn('pac-error');
// To get a Map of `{ error-type: "description" }`:
noty.getErrorTypeToLabelMap();

Weer.install(configs)

configs are passed to Weer.GetNotifiersSingleton, see above.