node-red-dxp

Appearance

Utils for Controllers ​

This package contains a set of utilities that can be used on controllers.

Usage ​

All functions can be imported from the package like this for example:

typescript
import { splitBooleanOutputs } from '@keload/node-red-dxp/utils/controller';

And you benefit from tree-shaking in the final bundle 🚀

INFO

This documentation is automatically generated from the source code.

Functions ​

evaluateNodeProperty() ​

evaluateNodeProperty(params): Promise<[Error | undefined, any | undefined]>

Evaluates a node property in the Node-RED environment. This function wraps the evaluateNodeProperty utility from RED.util and returns a Promise. It resolves with a tuple containing an Error (if any) and the evaluation result.

The evaluation is performed asynchronously, and the function never rejects. The result will always be a tuple where:

  • The first element is an Error if one occurs during the evaluation, or undefined if no error occurs.
  • The second element is the result of the property evaluation, or undefined if no result is produced.

Note: This function is designed to be used in the context of Node-RED node development. It requires access to the RED object and the necessary node properties.

Parameters ​

params ​

EvaluateNodePropertyParams

The parameters needed to evaluate the node property.

Returns ​

Promise<[Error | undefined, any | undefined]>

  • A promise that resolves with a tuple containing:
  • The error (if any) or undefined if no error occurs.
  • The result of the evaluation or undefined if no result is produced.

Examples ​

ts
// Example usage of evaluateNodeProperty with async/await
async function processNodeProperty() {
  const params: EvaluateNodePropertyParams = {
    value: "msg.payload",
    type: "jsonata",
    node: myNode,  // assuming myNode is a valid Node object
    msg: myMsg,    // assuming myMsg is a valid NodeMessage object
  };

  const [err, result] = await evaluateNodeProperty(params);

  if (err) {
    console.error("Error:", err);
  } else {
    console.log("Evaluation Result:", result);
  }
}
ts
// Handling the result when using the promise directly
evaluateNodeProperty({
  value: "msg.payload.someProperty",
  type: "str",
  node: myNode,  // assuming myNode is a valid Node object
  msg: myMsg,    // assuming myMsg is a valid NodeMessage object
})
.then(([err, result]) => {
  if (err) {
    console.error("Error:", err);
  } else {
    console.log("Result:", result);
  }
});

getREDNode() ​

getREDNode<TFields, TCreds>(idNode): Node<TCreds> & TFields

Retrieves a node by its ID from the RED.nodes collection. This function returns the node object, which includes any custom fields and credentials associated with it. If the node with the specified ID doesn't exist, the function returns null.

Type Parameters ​

• TFields extends object = Record<any, any>

A generic type that extends an object, representing the additional fields associated with the node. This allows the caller to extend the node with custom fields.

• TCreds extends object = Record<any, any>

A generic type that extends an object, representing the credentials associated with the node. This allows the caller to extend the node with custom credentials.

Parameters ​

idNode ​

string

The unique identifier of the node to be retrieved.

Returns ​

Node<TCreds> & TFields

The node object with credentials and additional fields, or null if the node cannot be found.

Example ​

ts
// Example usage of the getREDNode function
const nodeId = 'node123';
const node = getREDNode<{customField: string}, {apiKey: string}>(nodeId);
if (node) {
  console.log(node.customField);  // Accessing custom field
  console.log(node.apiKey);       // Accessing node credentials
} else {
  console.log('Node not found');
}

// In this example:
// - We retrieve the node with ID 'node123'.
// - The node is expected to have a custom field called 'customField' and credentials including 'apiKey'.

Throws ​

Throws an error if the idNode is invalid or if there are issues retrieving the node.

splitBooleanOutputs() ​

splitBooleanOutputs(conditionTerm, msg): unknown[]

Splits a message into two outputs based on a boolean condition.

Parameters ​

conditionTerm ​

boolean

The condition to evaluate. Expected to be a boolean (true or false).

msg ​

unknown

The message object to route based on the condition.

Returns ​

unknown[]

An array of two elements:

  • The first element contains the message if conditionTerm is true, otherwise null.
  • The second element contains the message if conditionTerm is false, otherwise null.

Example ​

ts
const msg = { payload: 'Hello, world!' };
const result = splitBooleanOutputs(true, msg);
console.log(result); // Output: [{ payload: 'Hello, world!' }, null]

useControllerNode() ​

useControllerNode(node, msg, opts?): object

A hook-like function that provides utilities for evaluating Node-RED properties within a custom node. It includes property evaluation with default values and quick property evaluation with type enforcement.

Parameters ​

node ​

Node

The Node-RED node instance.

msg ​

NodeMessage

The message object passing through the node.

opts? ​

Optional configuration for property evaluation.

typedSuffix ​

string = 'Type'

The suffix used to determine the type of a property.

Returns ​

object

An object containing utility functions for evaluating node properties.

evaluateNodeProperty() ​

evaluateNodeProperty: (value, type) => Promise<[Error | undefined, any | undefined]> = evaluateNodePropertyWithDefaults

Evaluates a Node-RED property, resolving its value and type while ensuring defaults are handled correctly.

Parameters ​
value ​

string

The property value to evaluate.

type ​

string

The type of the property.

Returns ​

Promise<[Error | undefined, any | undefined]>

A promise resolving to a tuple where the first element is an error (if any) and the second is the evaluated property value.

quickNodePropertyEval() ​

quickNodePropertyEval: <T>(bag, term, quickOpts?) => Promise<any>

Evaluates a property within an object (bag), resolving its value and applying a strict default if the resolved value is empty.

Type Parameters ​

• T extends object

The type of the bag object.

Parameters ​
bag ​

T

The object containing the property to evaluate.

term ​

keyof T

The key of the property to evaluate.

quickOpts? ​

Additional options for evaluation.

strictDefaultValue ​

any = undefined

A fallback value if the evaluated property is empty.

Returns ​

Promise<any>

A promise resolving to the evaluated value, or the strict default value if applicable.

Example ​

ts
const controller = useControllerNode(node, msg);

// Evaluate a property
const [error, value] = await controller.evaluateNodeProperty('someValue', 'msg');

// Quickly evaluate a property from an object
const result = await controller.quickNodePropertyEval({ foo: 'bar' }, 'foo');