JavaScript API Reference

This page documents the global objects available in the JavaScript environment shared by the nodered_js and tag_processor processors. The engine is goja (ES5.1 with some ES6 features) — no Node.js APIs are available.

msg

The message object. Contains the payload and metadata of the current message.

msg.payload    // The message content (any JSON type)
msg.meta       // Metadata key-value pairs (strings)

Return behavior:

• return msg; — pass the message through (modified or not)
• return null; or return undefined; — drop the message
• return { payload: ..., meta: ... }; — create a new message

Example:

msg.payload = msg.payload * 2;
msg.meta.processed = "true";
return msg;

console

Logging functions that write to the Benthos logger.

console.debug(...)  // DEBUG level
console.log(...)    // INFO level
console.info(...)   // INFO level
console.warn(...)   // WARN level
console.error(...)  // ERROR level

Accepts multiple arguments: console.log("value is", msg.payload.value)

cache

Key-value store for maintaining state across messages. Persists across all messages for the lifetime of the Benthos process. In-memory only, lost on restart. Supports any JSON-compatible type: strings, numbers, booleans, objects, arrays.

The cache is automatic and requires no configuration.

cache.set(key, value)    // Store a value under key (string)
cache.get(key)           // Retrieve a value, logs error if key not found
cache.exists(key)        // Returns true if key exists, false otherwise
cache.delete(key)        // Remove a key

Always use cache.exists(key) before cache.get(key) to avoid error logs on missing keys.

if (cache.exists("counter")) {
  var count = cache.get("counter");
} else {
  var count = 0;
}

Counter

var count = 0;
if (cache.exists("count")) { count = cache.get("count"); }
count++;
cache.set("count", count);
msg.payload = count;
return msg;

Previous value comparison

var prev = null;
if (cache.exists("last_value")) {
  prev = cache.get("last_value");
}
var delta = 0;
if (prev !== null) {
  delta = msg.payload.value - prev;
}
cache.set("last_value", msg.payload.value);
msg.payload.delta = delta;
return msg;

History (last N values)

var history = [];
if (cache.exists("history")) {
  history = cache.get("history");
}
history.push(msg.payload.value);
if (history.length > 10) history.shift();
cache.set("history", history);
return msg;

Alarm state tracking

var alarmed = false;
if (cache.exists("alarm_active")) {
  alarmed = cache.get("alarm_active");
}
if (msg.payload.value > 100 && !alarmed) {
  cache.set("alarm_active", true);
  msg.meta.alarm = "triggered";
  return msg;
}
if (msg.payload.value <= 100 && alarmed) {
  cache.set("alarm_active", false);
  msg.meta.alarm = "cleared";
  return msg;
}
return msg;

Cycle time between events

var lastMs = null;
if (cache.exists("last_event_ms")) {
  lastMs = cache.get("last_event_ms");
}
if (lastMs !== null) {
  msg.payload.cycle_time_ms = Date.now() - lastMs;
}
cache.set("last_event_ms", Date.now());
return msg;

Limitations

• In-memory only — state is lost when the Benthos process restarts. A persistent backend is planned.
• No size limits — the cache grows unboundedly if keys are never deleted. Use cache.delete to clean up unused keys. A memory safeguard (threshold, eviction) is planned.
• Cache scope in tag_processor — the cache is shared across all stages (defaults, conditions, advancedProcessing). A value set in defaults is visible in advancedProcessing within the same message.

protobuf

Decode and encode protobuf messages inline, against a schema passed as a base64-encoded FileDescriptorSet (no files on disk). Useful for reading data the standard inputs don't decode — for example the raw Sparkplug B metric bytes attached by the sparkplug_b input's passthrough_raw_metric flag, including proto2 extension fields.

protobuf.decode(dataB64, descriptorSetB64, msgName)  // base64 proto bytes -> object
protobuf.encode(obj, descriptorSetB64, msgName)      // object -> base64 proto bytes

• descriptorSetB64 — base64 of a self-contained FileDescriptorSet. Compile it once with protoc --include_imports --descriptor_set_out=schema.pb your.proto, then base64-encode schema.pb and paste the string into your script.
• msgName — fully-qualified message name, e.g. com.example.Payload.Metric (no leading dot).
• The decoded object follows protojson conventions: int64/uint64 and bytes come back as strings, enums as their names, and proto2 extensions appear as [package.extension] keys. For encode, pass 64-bit integers as strings.
• Both functions throw on error (invalid base64, unknown message, malformed descriptor set); wrap calls in try/catch to handle failures in script.

// Decode the raw Sparkplug metric attached by passthrough_raw_metric, reading an extension field.
var DESC = "CtIB..."; // base64 FileDescriptorSet, compiled once
var metric = protobuf.decode(msg.meta.spb_metric_raw, DESC, "com.example.Payload.Metric");
msg.payload = { value: metric.value, extra: metric["[com.example.my_extension]"] };
return msg;

Available in both nodered_js and tag_processor — they share the same JavaScript environment.