= javascript
:type: processor
:status: experimental
:categories: ["Mapping"]



////
     THIS FILE IS AUTOGENERATED!

     To make changes, edit the corresponding source file under:

     https://github.com/redpanda-data/connect/tree/main/internal/impl/<provider>.

     And:

     https://github.com/redpanda-data/connect/tree/main/cmd/tools/docs_gen/templates/plugin.adoc.tmpl
////

// © 2024 Redpanda Data Inc.


component_type_dropdown::[]


Executes a provided JavaScript code block or file for each message.

Introduced in version 4.14.0.

```yml
# Config fields, showing default values
label: ""
javascript:
  code: "" # No default (optional)
  file: "" # No default (optional)
  global_folders: []
```

The https://github.com/dop251/goja[execution engine^] behind this processor provides full ECMAScript 5.1 support (including regex and strict mode). Most of the ECMAScript 6 spec is implemented but this is a work in progress.

Imports via `require` should work similarly to NodeJS, and access to the console is supported which will print via the Benthos logger. More caveats can be found on https://github.com/dop251/goja#known-incompatibilities-and-caveats[GitHub^].

This processor is implemented using the https://github.com/dop251/goja[github.com/dop251/goja^] library.

== Fields

=== `code`

An inline JavaScript program to run. One of `code` or `file` must be defined.
This field supports xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions].


*Type*: `string`


=== `file`

A file containing a JavaScript program to run. One of `code` or `file` must be defined.
This field supports xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions].


*Type*: `string`


=== `global_folders`

List of folders that will be used to load modules from if the requested JS module is not found elsewhere.


*Type*: `array`

*Default*: `[]`

== Examples

[tabs]
======
Simple mutation::
+
--

In this example we define a simple function that performs a basic mutation against messages, treating their contents as raw strings.

```yaml
pipeline:
  processors:
    - javascript:
        code: 'benthos.v0_msg_set_string(benthos.v0_msg_as_string() + "hello world");'
```

--
Structured mutation::
+
--

In this example we define a function that performs basic mutations against a structured message. Note that we encapsulate the logic within an anonymous function that is called for each invocation, this is required in order to avoid duplicate variable declarations in the global state.

```yaml
pipeline:
  processors:
    - javascript:
        code: |
          (() => {
            let thing = benthos.v0_msg_as_structured();
            thing.num_keys = Object.keys(thing).length;
            delete thing["b"];
            benthos.v0_msg_set_structured(thing);
          })();
```

--
======

== Runtime

In order to optimize code execution JS runtimes are created on demand (in order to support parallel execution) and are reused across invocations. Therefore, it is important to understand that global state created by your programs will outlive individual invocations. In order for your programs to avoid failing after the first invocation ensure that you do not define variables at the global scope.

Although technically possible, it is recommended that you do not rely on the global state for maintaining state across invocations as the pooling nature of the runtimes will prevent deterministic behavior. We aim to support deterministic strategies for mutating global state in the future.

== Functions

### `benthos.v0_fetch`

Executes an HTTP request synchronously and returns the result as an object of the form `{"status":200,"body":"foo"}`.

#### Parameters

**`url`** &lt;string&gt; The URL to fetch  
**`headers`** &lt;object(string,string)&gt; An object of string/string key/value pairs to add the request as headers.  
**`method`** &lt;string&gt; The method of the request.  
**`body`** &lt;(optional) string&gt; A body to send.  

#### Examples

```javascript
let result = benthos.v0_fetch("http://example.com", {}, "GET", "")
benthos.v0_msg_set_structured(result);
```

### `benthos.v0_msg_as_string`

Obtain the raw contents of the processed message as a string.

#### Examples

```javascript
let contents = benthos.v0_msg_as_string();
```

### `benthos.v0_msg_as_structured`

Obtain the root of the processed message as a structured value. If the message is not valid JSON or has not already been expanded into a structured form this function will throw an error.

#### Examples

```javascript
let foo = benthos.v0_msg_as_structured().foo;
```

### `benthos.v0_msg_exists_meta`

Check that a metadata key exists.

#### Parameters

**`name`** &lt;string&gt; The metadata key to search for.  

#### Examples

```javascript
if (benthos.v0_msg_exists_meta("kafka_key")) {}
```

### `benthos.v0_msg_get_meta`

Get the value of a metadata key from the processed message.

#### Parameters

**`name`** &lt;string&gt; The metadata key to search for.  

#### Examples

```javascript
let key = benthos.v0_msg_get_meta("kafka_key");
```

### `benthos.v0_msg_set_meta`

Set a metadata key on the processed message to a value.

#### Parameters

**`name`** &lt;string&gt; The metadata key to set.  
**`value`** &lt;anything&gt; The value to set it to.  

#### Examples

```javascript
benthos.v0_msg_set_meta("thing", "hello world");
```

### `benthos.v0_msg_set_string`

Set the contents of the processed message to a given string.

#### Parameters

**`value`** &lt;string&gt; The value to set it to.  

#### Examples

```javascript
benthos.v0_msg_set_string("hello world");
```

### `benthos.v0_msg_set_structured`

Set the root of the processed message to a given value of any type.

#### Parameters

**`value`** &lt;anything&gt; The value to set it to.  

#### Examples

```javascript
benthos.v0_msg_set_structured({
  "foo": "a thing",
  "bar": "something else",
  "baz": 1234
});
```