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.