CloudEvents SDK for JavaScript

The CloudEvents SDK requires a current LTS version of Node.js (e.g., Node.js 16.x or 18.x). Install it in your Node.js project using npm:

npm install cloudevents

To run the MQTT example, you must first install dependencies and compile the project. You also need a running MQTT broker (such as Eclipse Mosquitto) available on port 1883.

Prerequisites

• Node.js and npm
• Docker (to run the broker)

Steps

1. Install and compile the project:

   npm install
   npm run compile

2. Start an MQTT broker using Docker: Run the following command to start an unauthenticated Mosquitto broker:

   docker run -it -d -p 1883:1883 eclipse-mosquitto:2.0 mosquitto -c /mosquitto-no-auth.conf

3. Start the application:

   npm start

To run the Express example provided in this repository, navigate to the examples/express-ex directory and use the following command:

npm start

After setting up Kafka, you can run the example CLI application which demonstrates sending user input as a CloudEvent through a Kafka producer and handling/deserializing it with a consumer in a consumer group.

Prerequisites:

• NodeJS (>18)
• A running Kafka broker

Start the Producer

Run the following command to start the producer CLI:

npm run start:producer

Start the Consumer

Run the following command to start the consumer, providing a ${groupId} as an argument:

npm run start:consumer ${groupId}

# Start the producer
npm run start:producer

# Start the consumer (replace ${groupId} with your desired group ID)
npm run start:consumer my-consumer-group

The Emit.send method has been removed. You must now manually handle the transport protocol (e.g., using axios) by first converting your CloudEvent into a transportable message using either HTTP.binary (for binary events) or HTTP.structured (for structured events).

const axios = require('axios').default;
const { HTTP } = require("cloudevents");

const ce = new CloudEvent({ type, source, data });
const message = HTTP.binary(ce); // Or HTTP.structured(ce)

axios({
  method: 'post',
  url: '...',
  data: message.body,
  headers: message.headers,
});

The Receiver class has been removed in version 4.0.0. To convert incoming HTTP requests into CloudEvent objects, use the HTTP.toEvent method. This method accepts an object containing headers and body extracted from your HTTP framework (e.g., Express.js).

const app = require("express")();
const { HTTP } = require("cloudevents");

app.post("/", (req, res) => {
  // body and headers come from an incoming HTTP request, e.g. express.js
  const receivedEvent = HTTP.toEvent({ headers: req.headers, body: req.body });
  console.log(receivedEvent);
});

The SDK provides interfaces for converting between CloudEventV1 objects and Message objects:

• Serializer<M>: A function that takes a CloudEventV1<T> and returns a Message of type M.
• Deserializer: A function that takes a Message and returns either a single CloudEventV1<T> or an array of events CloudEventV1<T>[] (for batch modes).
• Detector: A predicate function used to check if a Message contains a valid CloudEvent.

JavaScript's Number type loses precision for very large integers (e.g., Twitter IDs). To prevent this when parsing CloudEvents, set the environment variable CE_USE_BIG_INT to "true". This enables the json-bigint package. Note that this may slow down parsing speed by approximately 7x.

export CE_USE_BIG_INT=true