Nodejs22

This feature is only enabled on certain environments and tenants. Please contact Support for more information about this feature.

With the Transforms API we are able to support many types of transform definitions. This document describes the transform type Nodejs22.

This transform type offers the ability for increased customization by giving access to Node.js v22 to program actions for each call to the transform endpoint in JavaScript.

We recommend this transform type if you have complex requirements involving multiple API calls. Some examples of how this could be used include:

• Combine multiple Execute API calls together.

• Apply JSONtransforms for multiple API calls.

• Orchestrate other Spark APIs to facilitate data transformation and processing.

For this particular transform type, the npm packages for fast-xml-parser or JSONata are also included allow for enhanced capabilities to parse JSON and XML content.

Build transforms

To build transforms you can follow the instructions for the specific transform on this page. For JavaScript developers there is also the Node Transform Document Builder that can be used to assist with the development.

Transform document

Transform documents are used to define the code relating to a transform. For Nodejs22, the transform document is a JSON document defined by the following objects:

Key	Value
transform_type	Nodejs22_v1.0.0
transform_code	Single string containing the code for the transform code. The code must contain the function async function handler(event) {}. When the transform is invoked, this function is called. Parameters from the transform request are passed into the event parameter as an object. This function should return: http_status_code for the HTTP status code. headers for response headers. body for the response body. This design pattern follows the AWS Lambda Define Lambda function handler in Node.js. See the Examples for more details.
transform_log_level	Optional parameter. This controls the level of logging that will be recorded during the execution. This can take the values of TRACE|DEBUG|INFO|WARN|ERROR. TRACE is the most verbose and ERROR is the least verbose. INFO is needed to return console.info() and console.log() statements. If omitted, the default is INFO.
transform_log_visible	NOTE: This configuration is not available yet. Optional parameter. This controls whether the execution logs will be made available in the response headers. These can be used for reviewing the execution and debugging. If omitted, the default is false.
transform_allowed_external_domains	Optional parameter. Array containing a list of external domains that the transform is allowed to access during the course of execution. These domains must be resolvable using NsLookup.

Create the transform document

The transform document can be manually created and uploaded to Spark using the New transforms feature.

1. The transform_type is Nodejs22_v1.0.0.

2. The transform_code must be a single string containing the code for the transform.

   1. If you are using either fast-xml-parser or JSONata, make sure to include the require() statements to import the modules for either fast-xml-parser or jsonata.

   2. Remove any lines containing comments.

   3. Any double quotation marks " need to be escaped, i.e. " is replaced with \".

      • Note that JavaScript allows for single quotation marks ' to be interchanged with double quotation marks ". If ' are used exclusively in lieu or ", then the escape character is not needed.

   4. If you are using Visual Studio Code, you can use the Join lines feature to make it easy to combine multiple lines into a single string.

      1. Select the transform text that you would like to combine onto a single line.

         1. Access the Command Palette F1 or Ctrl+Shift+P on Windows or Shift+⌘+P on Mac.

         2. Type in the command Join lines and select it.

   5. As an alternative to Join lines, line breaks Ctrl+Enter can be replaced with the new line character \n.

3. Follow the instructions on Transform documents to upload the transform document to Spark.

Transforms API

These details are specific to this transform in addition to information in Transforms API.

Request headers

Key	Value
x-meta or x-request-meta	Optional parameter. This can be used to introduce key-value pairs into the event.context parameter object. See Examine the event parameter objectfor more details. Example: "{\"call_purpose\":\"Transform mainframe request\"}"
Content-Type	application/json, application/xml, or text/xml
+ any other request headers...	These will be passed into event.request.headers as key-value pairs. See Examine the event parameter objectfor more details.

Limitations

• The API call has a maximum lifetime of 120 s.

• API calls can only be made to the coherent.global domain only unless defined by transform_allowed_external_domains.

• Not all built-in Node.js v22 modules are accessible.

Restricted Node.js v22 modules

Restricted module	Restricted functionality
fs	Read/write access to the file system.
child_process	Run arbitrary system commands (exec, spawn, etc.).
net / dgram	Create raw TCP/UDP sockets.
http, https	Make network requests. Use fetch instead.
vm	Create a nested sandbox.
process	Access environment variables or exit the process.
os	Access system information.
cluster	Fork additional worker processes.
worker_threads	Run threads that outside of the memory or sandbox space.
require (general)	Loading of unsupported modules.

HTTP status code

This is determined by the handler() function return{} of http_status_code object.

This can also be invoked with a response header x-spark-transform-response-httpstatuscode .

Response headers

This is determined by the handler() function return{} of headers(). object. We would suggest at the minimum to return the appropriate Content-Type for your response data.

Response body

This is determined by the handler() function return{} of the body() object.

Examples

Start with a Hello, World! transform

The aim of this transform is to demonstrate a simple standalone application. When called, the response will include a custom header and response body with the message Hello, World!.

JavaScript

async function handler(event) {
    return {
        http_status_code: 200,
        headers: {
            "Content-Type": "application/json",
            myresponseheader: "Hello, World!",
        },
        body:
            {
                myresponsebody: "Hello, World!",
            },
    }
}

Transform document

Sample request

Sample response

Examine the event parameter object

When the handler() function is invoked, the event parameter is used to provide information about the request details. These can be used as inputs for the program.

We can create a transform specifically to help us to better understand the event parameter object.

JavaScript

async function handler(event) {
    return {
        http_status_code: 200,
        headers: { "Content-Type": "application/json" },
        body: { event }
    };
}

Transform document

Sample request

Sample response

Emulate a passthrough to the Execute API (v3)

In this example, the transform endpoint acts as a passthrough to send inputs to the Execute API (v3). This example is useful for building up transforms that make API calls to Spark.

JavaScript

• Note the encodeURI() function that is used in the fetchResource declaration. This is needed because folders or services that contain a space in the name need to be encoded to %20 in order for fetch() to work.

• The Authorization to the /execute API call is handled by using the token available in event.secrets.authorization.

• Trying to return all of the headers from the /execute call may lead to errors. See Known errors.

async function handler(event) {

    const fetchResource = `${event.context.spark_url}/${event.context.tenant}/api/v3${encodeURI(event.context.service_uri)}/execute`;

    const fetchOptions = {
        method: "POST",
        headers: {
            Authorization: event.secrets.authorization,
            "Content-Type": "application/json",
            "x-tenant-name": event.context.tenant,
        },
        body: JSON.stringify(event.request.body),
    };

    const response = await fetch(fetchResource, fetchOptions);
    const responseBody = await response.json();

    return {
        http_status_code: response.status,
        headers: { "Content-Type": response.headers.get("content-type") },
        body: responseBody,
    };
}

Transform document

Sample request

Sample response

Transform JSON with JSONata

JSONata is a "lightweight query and transformation language for JSON data". You can test your JSONata transforms in the JSONata Exerciser. The version of JSONata bundled is 2.1.0.

Including JSONata in this transform provides more flexibility than what can be done in JSONtransforms.

This example is based on Example nodejs application.

JavaScript

const jsonata = require("jsonata");

async function handler(event) {
    const data = {
        example: [
            { value: 4 },
            { value: 7 },
            { value: 13 }
        ]
    };
    const expression = jsonata("$sum(example.value)");
    const result = await expression.evaluate(data);
    return { http_status_code: 200, headers: { "Content-Type": "application/json" }, body: { sum: result } };
}

Transform document

Sample request

Sample response

Transform XML with fast-xml-parser

fast-xml-parser is the most popular package to manipulate XML in JavaScript. This package has been included with the Nodejs22 transform to empower XML parsing capabilities. The version of fast-xml-parser bundled is 5.2.5.

This example is based on 3.XMLBuilder.md.

JavaScript

const fastXmlParser = require("fast-xml-parser");

async function handler(event) {
    const { XMLBuilder } = require("fast-xml-parser");

    const XmlBuilderOptions = {
        ignoreAttributes: false,
        format: true,
        arrayNodeName: "car"
    };

    const cars = [
        {
            "color": "purple",
            "type": "minivan",
            "registration": "2020-02-03",
            "capacity": 7
        },
        {
            "color": "orange",
            "type": "SUV",
            "registration": "2021-05-17",
            "capacity": 4
        },
    ];

    const builder = new XMLBuilder(XmlBuilderOptions);
    const output = builder.build(cars);

    return {
        http_status_code: 200,
        headers: {
            'Content-Type': 'application/xml'
        },
        body: output,
    };
}

Transform document

Sample request

Sample response

Make an external API call

In this example, we exctract the contents from the www.google.com homepage.

JavaScript

async function handler(event) {

    const fetchResource = "https://www.google.com";
    const fetchOptions = {method: "GET"};

    const response = await fetch(fetchResource, fetchOptions);
    const responseText = await response.text();
    const responseBody = {outputs: { page_content: responseText } };
    return {
        http_status_code: response.status,
        headers: { "content-type": "application/json" },
        body: responseBody,
    };
}

Transform document

Sample request

Sample response

Recommended development process

To run this locally, you will need to have Node.js v22 installed. This process is not dissimilar to Building Lambda functions with Node.js.

1. Decide how you would like to construct the request to the /transforms endpoint, including the structure of the request line, as well as request and response headers and body.

2. Create the transform described in Examine the event parameter object. Run the proposed /transforms request against it and from the response copy the event object.

3. Test your script locally using the runHandler.js script below.

   1. Paste in the event object from above into TEST_EVENT of runHandler.js.

   2. Work on the handler() function in runHandler.js.

   3. If your script calls other Spark APIs, your Authorization may expire as you develop the program. You may need to update your event object periodically with a new bearer token.

   4. Test your script in your terminal using the command node runHandler.js. It will print the handler() function return.

4. Compose and upload the transform document using the directions in Transform document.

5. Test API calls against the /transforms endpoint to make sure you are getting the same result as the runHander.js script.

1KB

runHandler.zip

archive

Open

Known errors

Sometimes code will work locally but fail to run on Spark. Some examples where this may occur:

• Trying to return all of the headers from the /execute API call in Emulate a passthrough to the Execute API (v3) to the /transforms response headers may fail due to content encoding discrepancies.