Reactor Extensions Spec

The EVRYTHNG Reactor is a powerful programmatic feature allowing projects to contain JavaScript scripts that react to events in the Platform, such as property updates or created actions. This part of implementing an EVRYTHNG integration is usually up to the developer to design and write and provides the most flexibility.

Sometimes, modular parts of a project can be generalized and easily re-used in another project or by another developer. We call these Reactor Extensions, and there are many advantages to creating and sharing them:

• Enable sharing of reusable Reactor scripts by following a common specification.
• Allow the quick creation of more modular projects in the EVRYTHNG Platform.
• Benefit from the shared work of other developers in the ecosystem.
• Easily add existing Reactor Extensions to a project to get add modular features with minimal effort and configuration.

With this possibility in mind, the following specification for Reactor Extensions is described and serves as a guideline to be used when there is potential for a useful Reactor script to be re-used and shared to speed up development.

Specification

Requirements

A "Reactor Extension" script must:

• Live inside a public GitHub repository.
• Contain in the root directory:
  • package.json - npm-compatible JSON file containing at least evrythng-extended in dependencies.
  • main.js - source file including at least one Reactor event handler.
• Require no further code changes to deploy except:
  • Setting of preferences/configuration values as constants at the top of main.js.
  • Setting of secret credentials or third-party API keys as constants at the top of main.js.

Recommendations

We recommend you:

• Take advantage of built-in EVRYTHNG Platform features, such as action or Thng customFields to deliver parameters and other data to the script at runtime.
• Stay within your account usage limits by using Reactor filters as much as is reasonable to minimize the impact.
• Use the recommended single promise chain pattern to guarantee that done() is called, all errors are caught, logs aren't lost, and retries (which could produce side-effects) are avoided.
• Include further dependencies that are required:
  • In package.json - if they are npm modules.
  • In local subdirectories to adjacent main.js - if they are local files or libraries.

📘

Note

If more than one source file aside from main.js exists, the ‘bundle upload’ method must be used to deploy it.

A Reactor Extension script MUST NOT

• Require custom code changes beyond previously discussed configuration or secret constant values.
• Cause itself to run or be invoked indefinitely or break any of the other limits on Reactor scripts.

Examples

See the Reactor Scripts page for a list of example Reactor scripts that meet and implement this specification and can be classed as Reactor Extensions.