Function Extensions

Function Extensions are powerful tools that you attach directly to a function's output to provide additional, often simpler, capabilities for on-the-fly data processing. They allow you to modify, filter, record, or handle errors without needing a separate function block.

Working with Extensions

The following actions apply to all extension types, allowing you to build complex processing pipelines directly on a function's output.

Adding an Extension: To add an extension, click the + icon on a function's output and select the desired type from the menu. You can add multiple parallel extensions to the same output to perform independent actions on the same data.
Chaining Extensions: To create a multi-step process, you can add an extension to the output of another extension. This allows you to, for example, filter data first and then modify the result.
Deleting an Extension: To remove an extension, right-click on it and select Delete from the context menu.

Modifier

The Modifier is a simple but powerful tool for on-the-fly data modification and transformation. It takes the output from a function and allows you to apply a JSONata or JavaScript expression to change its structure or value before passing it to the next step in your flow.

A Modifier can use either JSONata or a JavaScript expression to perform transformations. By default, it is set to JSONata. You can switch between types at any time by right-clicking the modifier and selecting Jsonata or Expression.

When you switch the modifier type, any existing code within it will be deleted.

JSONata Modifier

JSONata is a lightweight query and transformation language designed for JSON data.

To refer to the value from the preceding output, use the $ sign.
For JSONata functions, however, the previous value is automatically considered as an argument, eliminating the need to explicitly fill it into the brackets.
For a complete guide, refer to the official JSONata documentation.

Examples

1. Wrap a value in an object: This expression takes the incoming value ($) and wraps it inside a JSON object with a key named payload.

{ "payload": $ }

2. Select a nested value: This expression selects the location value from a nested incoming object. If the input is an object like { "user": { "name": "John", "location": "Berlin" } }, this expression will output the string "Berlin".

user.location

Visual Examples

JavaScript Expression Modifier

This allows you to use any standard JavaScript expression that evaluates to a new value.

The variable x is reserved and always contains the value from the preceding output.
For more information, refer to the MDN documentation for JavaScript Expressions and Operators.

Examples

1. Concatenate a string: This expression takes the incoming string (x) and adds a prefix to it.

`Hello, ${x}`

2. Perform a conditional check: This ternary expression checks if the incoming number (x) is greater than 100 and returns a corresponding string.

x > 100 ? 'High' : 'Normal'

Visual Examples

Patterns of common usage

Changing the all objects within an array at once For that the map function comes in handy. Say your x represented data in the form:
```
[ { a: 1, b: 1, c: 1 }, { a: 2, b: 2, c: 2 } ]
```
And you wanted to remove c from every entry and add a d property instead, you could write:
```
x.map(y => ({
...y, // this reproduces the existing entry (puts { a, b, c })
c: undefined, // this removes c
d: 'cool' // this adds d with value 'cool'
}))
```
This would result in the following output:
```
[ { a: 1, b: 1, d: 'cool' }, { a: 2, b: 2, d: 'cool' } ]
```
Implementing full Javascript, including variables While the modifier supports only Javascript expressions, you can work around this using the IIFE pattern
```
(() ⇒ {
   // put your javascript code here
   // Note: you must provide a return statement
})()
```
This pattern is useful if you need to do something more elaborate and need a temporary variable. In case of the combine function this gets quickly useful.
```
(() ⇒ {
  const result = []
  const users = x[0]
  const assets = x[1]
  // compute the result here
  return result
})()
```
Computing with dates While the regulate Date object from Javascript is available, we also provide support for the extra-ordinary Luxon library which provides the DateTime object. With that you can do things like:
```
x.map(y => ({
   ...y,
   dueDate: DateTime.fromISO(y.startDate).plus({ days: y.days })
}))
```

Filter

The Filter acts as a conditional gate for your data flow, allowing you to branch logic based on conditions. It is the primary method for implementing if/else scenarios in your flows.

The Filter evaluates a JavaScript expression you provide, which must return true or false. The input value from the previous output is available as the variable x. If the result is true, the data is passed on; if false, the data flow is halted at this point. At the same time, the true and false states of the filter can be used to trigger separate logic paths.

A filter condition that evaluate to a "falsy" value (i.e. false 0, null, "") stops the execution of the flow. This is the only way to interrupt a flow and can be essential when building complex backend logic.

Examples

1. Check a numeric value This expression checks if the temperature value in an incoming object (x) exceeds a threshold of 90.

x.temperature > 90

2. Check text content This expression checks if an incoming message (x) contains the word "Error".

x.includes('Error')

Visual Example

Recorder

The Recorder captures a function's output and stores it as time-series data in the internal InfluxDB. This allows you to store a data stream, visualize it within your applications, or analyze it as required. It records data during both build-time (in test mode) and the app's runtime.

The Recorder has two settings:

Measurement Name: You must provide a unique name for the measurement in the recorder's text box.
Retention Policy: Right-click the circle icon (which defaults to 'F' for Forever) to set how long the recorded data should be stored. Options range from one hour to a year, or forever.

Error Handler

The Error Handler allows you to gracefully manage potential errors thrown by a function. It provides a separate output that will only activate if the function it's attached to fails or throws an exception.

This enables you to build a safe, separate logic path to handle error conditions, such as logging the error details to a database or displaying a user-friendly error message on the UI.

Last updated 1 month ago