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;orreturn undefined;— drop the messagereturn { 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 levelAccepts 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.
Always use cache.exists(key) before cache.get(key) to avoid error logs on missing keys.
Counter
Previous value comparison
History (last N values)
Alarm state tracking
Cycle time between events
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.deleteto 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 indefaultsis visible inadvancedProcessingwithin 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.
descriptorSetB64— base64 of a self-containedFileDescriptorSet. Compile it once withprotoc --include_imports --descriptor_set_out=schema.pb your.proto, then base64-encodeschema.pband 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/uint64andbytescome back as strings, enums as their names, and proto2 extensions appear as[package.extension]keys. Forencode, pass 64-bit integers as strings.Both functions throw on error (invalid base64, unknown message, malformed descriptor set); wrap calls in
try/catchto handle failures in script.
Available in both nodered_js and tag_processor — they share the same JavaScript environment.
Last updated

