Filters

A filter is an account that sends messages that reference messages from causes. Effects can use these messages to selectively react to causes by using a _refs property in the pattern used to match messages.

A filter may simply be an effect that sends a message depending on some condition. For example, an effect that makes an HTTP request and that can be configured to send specific messages depending on the HTTP status code can be set up to act as a filter. A filter may also be something that implements more complicated logic depending on the history of messages that it has seen so far, and/or depending on other conditions. For example, a filter may flag a message if it as the third one in a row that matches a certain condition, or the first message of the day, or if it shows the maximum value for a measurement that has been seen so far.

This allows effects to react to arbitrarily complex conditions, without the effects themselves needing to be developed with these conditions in mind.

In general, filters check events that match a pattern (called “candidate events”), and of those candidate events, decide which events pass and which events do not. Filters will usually use reactions to mark which events pass and (optionally) which events do not.

Configuration

The configuration for a filter is similar to the configuration for an effect. It will have an actions field whose value will be an array of objects. Each object in this array will have an on field whose value will be a pattern that matches the candidate events, as well as any other parameters that are needed to define which of the candidate events the filter should pass. In addition, it will have a send field, which may be an array of one or two strings. The first item is a reaction to send to messages that pass the filter, and the second item (if present) is a reaction to send to candidate events that do not pass the filter. A filter may accept other formats for the send field, but should at least accept this format for consistency.