@node-red/util.util

cloneMessage(msg) → {Object}

Safely clones a message object. This handles msg.req/msg.res objects that must not be cloned.

Parameters:
Name Type Description
msg any

the message object to clone

Returns:
Type:
Object

the cloned message

compareObjects(obj1, obj2) → {boolean}

Compares two objects, handling various JavaScript types.

Parameters:
Name Type Description
obj1 any
obj2 any
Returns:
Type:
boolean

whether the two objects are the same

encodeObject(msg, opts) → {Object}

Encode an object to JSON without losing information about non-JSON types such as Buffer and Function.

This function is closely tied to its reverse within the editor

Parameters:
Name Type Description
msg Object
opts Object
Returns:
Type:
Object

the encoded object

ensureBuffer(o) → {String}

Converts the provided argument to a Buffer, using type-dependent methods.

Parameters:
Name Type Description
o any

the property to convert to a Buffer

Returns:
Type:
String

the Buffer version

ensureString(o) → {String}

Converts the provided argument to a String, using type-dependent methods.

Parameters:
Name Type Description
o any

the property to convert to a String

Returns:
Type:
String

the stringified version

evaluateEnvProperty(value, node) → {String}

Checks if a String contains any Environment Variable specifiers and returns it with their values substituted in place.

For example, if the env var WHO is set to Joe, the string Hello ${WHO}! will return Hello Joe!.

Parameters:
Name Type Description
value String

the string to parse

node Node

the node evaluating the property

Returns:
Type:
String

The parsed string

evaluateJSONataExpression(expr, msg, callback) → {any}

Evaluates a JSONata expression. The expression must have been prepared with @node-red/util-util.prepareJSONataExpression before passing to this function.

Parameters:
Name Type Description
expr Object

the prepared JSONata expression

msg Object

the message object to evaluate against

callback function

(optional) called when the expression is evaluated

Returns:
Type:
any

If no callback was provided, the result of the expression

evaluateNodeProperty(value, type, node, msg, callback) → {any}

Evaluates a property value according to its type.

Parameters:
Name Type Description
value String

the raw value

type String

the type of the value

node Node

the node evaluating the property

msg Object

the message object to evaluate against

callback function

(optional) called when the property is evaluated

Returns:
Type:
any

The evaluted property, if no callback is provided

generateId() → {String}

Generates a psuedo-unique-random id.

Returns:
Type:
String

a random-ish id

getMessageProperty(msg, expr) → {any}

Gets a property of a message object.

Unlike @node-red/util-util.getObjectProperty, this function will strip msg. from the front of the property expression if present.

Parameters:
Name Type Description
msg Object

the message object

expr String

the property expression

Throws:

Will throw an error if the parent of the property does not exist

Returns:
Type:
any

the message property, or undefined if it does not exist

getObjectProperty(msg, expr) → {any}

Gets a property of an object.

Given the object:

{
  "pet": {
      "type": "cat"
  }
}
  • pet.type will return "cat".
  • pet.name will return undefined
  • car will return undefined
  • car.type will throw an Error (as car does not exist)
Parameters:
Name Type Description
msg Object

the object

expr String

the property expression

Throws:

Will throw an error if the parent of the property does not exist

Returns:
Type:
any

the object property, or undefined if it does not exist

normaliseNodeTypeName(name) → {String}

Normalise a node type name to camel case.

For example: a-random node type will normalise to aRandomNodeType

Parameters:
Name Type Description
name String

the node type

Returns:
Type:
String

The normalised name

normalisePropertyExpression(str) → {Array}

Parses a property expression, such as msg.foo.bar[3] to validate it and convert it to a canonical version expressed as an Array of property names.

For example, a["b"].c returns ['a','b','c']

If msg is provided, any internal cross-references will be evaluated against that object. Otherwise, it will return a nested set of properties

For example, without msg set, 'a[msg.foo]' returns ['a', [ 'msg', 'foo'] ] But if msg is set to '{"foo": "bar"}', 'a[msg.foo]' returns ['a', 'bar' ]

Parameters:
Name Type Description
str String

the property expression

Returns:
Type:
Array

the normalised expression

parseContextStore(key) → {Object}

Parses a context property string, as generated by the TypedInput, to extract the store name if present.

For example, #:(file)::foo results in { store: "file", key: "foo" }.

Parameters:
Name Type Description
key String

the context property string to parse

Returns:
Type:
Object

The parsed property

prepareJSONataExpression(value, node) → {Object}

Prepares a JSONata expression for evaluation. This attaches Node-RED specific functions to the expression.

Parameters:
Name Type Description
value String

the JSONata expression

node Node

the node evaluating the property

Returns:
Type:
Object

The JSONata expression that can be evaluated

setMessageProperty(msg, prop, value, createMissing)

Sets a property of a message object.

Unlike @node-red/util-util.setObjectProperty, this function will strip msg. from the front of the property expression if present.

Parameters:
Name Type Description
msg Object

the message object

prop String

the property expression

value any

the value to set

createMissing boolean

whether to create missing parent properties

setObjectProperty(msg, prop, value, createMissing)

Sets a property of an object.

Parameters:
Name Type Description
msg Object

the object

prop String

the property expression

value any

the value to set

createMissing boolean

whether to create missing parent properties